Getting Started
Use SDK v2 when you want HTTP-backed GMX data or API-relayed order workflows without wiring RPC, oracle, or Subsquid connections yourself.
Install the shared SDK package first:
npm install @gmx-io/sdk
Then import the client from the v2 subpath:
import { GmxApiSdk } from "@gmx-io/sdk/v2";
const apiSdk = new GmxApiSdk({ chainId: 42161 }); // Arbitrum
const markets = await apiSdk.fetchMarkets();
const marketsInfo = await apiSdk.fetchMarketsInfo();
const marketsConfig = await apiSdk.fetchMarketsConfig();
const marketsValues = await apiSdk.fetchMarketsValues();
const tickers = await apiSdk.fetchMarketsTickers({
symbols: ["BTC/USD"],
});
const tokens = await apiSdk.fetchTokens();
const tokensData = await apiSdk.fetchTokensData();
const pairs = await apiSdk.fetchPairs();
const rates = await apiSdk.fetchRates({ period: "7d" });
const apy = await apiSdk.fetchApy({ period: "7d" });
const annualized = await apiSdk.fetchPerformanceAnnualized({
period: "30d",
});
const snapshots = await apiSdk.fetchPerformanceSnapshots({
period: "30d",
});
const positions = await apiSdk.fetchPositionsInfo({
address: "0x9f7198eb1b9Ccc0Eb7A07eD228d8FbC12963ea33",
includeRelatedOrders: true,
});
const orders = await apiSdk.fetchOrders({
address: "0x9f7198eb1b9Ccc0Eb7A07eD228d8FbC12963ea33",
});
const trades = await apiSdk.fetchTrades({
address: "0x9f7198eb1b9Ccc0Eb7A07eD228d8FbC12963ea33",
limit: 20,
});
const jitLiquidity = await apiSdk.fetchJitLiquidityInfo();
const candles = await apiSdk.fetchOhlcv({
symbol: "BTC/USD",
timeframe: "1h",
limit: 100,
});
GmxApiSdk calls the GMX API directly — no RPC endpoint, oracle URL, or Subsquid URL required. It supports active mainnet integrations on Arbitrum, Avalanche, and MegaETH, plus Arbitrum Sepolia for testing. The constructor throws for unsupported chains.
If your app switches chains dynamically, prefer isApiSupported(chainId), getApiUrl(chainId), and getApiFallbackUrls(chainId) from @gmx-io/sdk/configs/api instead of hardcoding API hosts.
GMX API deployment
The GMX API deployment exposes independent peer base URLs such as https://{chain}.gmxapi.io/v1 and https://{chain}.gmxapi.ai/v1. GmxApiSdk builds an HttpClientWithFallback from the primary URL returned by getApiUrl(chainId) and any peers configured by getApiFallbackUrls(chainId).
Fallback lists are configuration, not a fixed SDK guarantee. In 1.6.4 the packaged list is empty for every chain, so HttpClientWithFallback runs against a single host unless you supply the peer. If your integration requires peer failover, pass the second host explicitly and monitor both in your own HTTP layer.
Arbitrum Sepolia uses a separate test host returned by getApiUrl(421614). Test hosts can change, so use the exported helper instead of hardcoding the URL.
@gmx-io/sdk/v2 is an import path inside the @gmx-io/sdk package, not a separate npm package.
If you're using CommonJS, require the v2 client from the v2 subpath:
const { GmxApiSdk } = require("@gmx-io/sdk/v2");
const apiSdk = new GmxApiSdk({ chainId: 42161 });
TypeScript subpath resolution is supported for @gmx-io/sdk/v2 and the SDK's utility, config, ABI, and type-only entrypoints.
What SDK v2 covers today
| Workflow | Status | Notes |
|---|---|---|
| Read market catalogs, configuration, values, tickers, and token data over HTTP | ✅ | Available through fetchMarkets(), fetchMarketsInfo(), fetchMarketsConfig(), fetchMarketsValues(), fetchMarketsTickers(), fetchTokens(), and fetchTokensData() |
| Read pairs, rates, APY, and performance analytics over HTTP | ✅ | Available through fetchPairs(), fetchRates(), fetchApy(), fetchPerformanceAnnualized(), and fetchPerformanceSnapshots() |
| Read one account's positions and orders over HTTP | ✅ | Available through fetchPositionsInfo() and fetchOrders() |
| Read trade history over HTTP | ✅ | Available through fetchTrades() and searchTrades() |
| Read OHLCV candles over HTTP | ✅ | Available through fetchOhlcv() |
| Read protocol buyback stats over HTTP | ✅ | Available through fetchBuybackWeeklyStats() |
| Read JIT liquidity over HTTP | ✅ | Available through fetchJitLiquidityInfo() |
| Read staking power over HTTP | ✅ | Available through fetchStakingPower() |
| Read wallet balances and allowances over HTTP | ✅ | Available through fetchWalletBalances() and fetchAllowances() |
| Build approval transaction calldata | ✅ | Available through buildApproveTransaction(), buildErc20ApproveTxn(), and executeErc20Approve() |
| GMX Account deposits and withdrawals | ✅ | Available through same-chain deposit/withdraw helpers and cross-chain deposit/withdraw helpers |
| Submit, edit, cancel, or track orders | ✅ | Signed order intents are posted to the GMX API, which relays express orders via Gelato. SDK v1 and direct contracts remain available for integrations that prefer RPC. |
| One-click-trading subaccount helpers | ✅ | Available through generateSubaccount(), activateSubaccount(), refreshSubaccountState(), clearSubaccount(), fetchSubaccountStatus(), prepareSubaccountApproval(), and signSubaccountApproval() |
See Order Examples for runnable code showing how to open, close, edit, cancel, and track orders, including TP/SL, TWAP, classic mode, and one-click trading flows.
Use SDK Overview if you want a quick capability comparison before wiring an integration.
Methods
GmxApiSdk exposes the following methods. All of them call the GMX API directly -- no RPC, oracle, or Subsquid connection is required.
| Method | Parameters | Returns | Notes |
|---|---|---|---|
fetchMarkets() | -- | MarketWithTiers[] | Market catalog data from /markets |
fetchMarketsInfo() | -- | RawMarketInfo[] | Market definitions and pricing from /markets/info |
fetchMarketsConfig() | -- | RawMarketConfig[] | Slower-changing market configuration from /markets/config |
fetchMarketsValues() | -- | RawMarketValues[] | Frequently changing market state from /markets/values; each row includes its least-recent component timestamp in updatedAt |
fetchMarketsTickers(params?) | addresses?: string[], symbols?: string[] | MarketTicker[] | Filterable market tickers from /markets/tickers |
fetchTokens() | -- | Token[] | Static token catalog from /tokens |
fetchTokensData() | -- | TokenData[] | Token metadata and current prices from /tokens/info |
fetchPairs() | -- | Pair[] | Pair-level summary data from /pairs |
fetchRates(params?) | period?: ApiParameterPeriod, `averageBy?: "1d" | "7d" | "30d", address?: string` |
fetchApy(params?) | period?: ApiParameterPeriod | ApyResponse | Market and GLV APY data from /apy |
fetchPerformanceAnnualized(params?) | period?: ApiParameterPeriod, address?: string | PerformanceAnnualized[] | Annualized performance summaries from /performance/annualized |
fetchPerformanceSnapshots(params?) | period?: ApiParameterPeriod, address?: string | PerformanceSnapshots[] | Historical performance snapshot series from /performance/snapshots |
fetchPositionsInfo(params) | address: string, includeRelatedOrders?: boolean | ApiPositionInfo[] | Position objects for an address; optionally includes related orders |
fetchOrders(params) | address: string | ApiOrderInfo[] | Active order objects for an address |
fetchTrades(params) | address: string, symbol?: string, marketAddress?: string, since?: number, until?: number, actions?: TradeEventName[], limit?: number, cursor?: string | TradesListResponse | Account trade history from /trades |
searchTrades(params) | address?: string, forAllAccounts?: boolean, fromTimestamp?: number, toTimestamp?: number, marketsDirections?: MarketDirectionFilter[], orderEventCombinations?: OrderEventCombination[], showDebugValues?: boolean, limit?: number, cursor?: string | TradesListResponse | Advanced trade-history search from /trades/search |
fetchOhlcv(params) | symbol: string, timeframe: string, limit?: number, since?: number | OhlcvCandle[] | OHLCV candle data from /prices/ohlcv |
fetchBuybackWeeklyStats() | -- | BuybackWeeklyStatsResponse | Weekly buyback accrual data and cumulative summary from /buyback/weekly-stats |
fetchJitLiquidityInfo(params?) | apiVersion?: "v1" | "v2" | JitLiquidityMap | JIT liquidity map from /jit/liquidity_info |
fetchStakingPower(params) | address: string | StakingPowerResponse | Staking power, loyalty ratio, and reward share data for an address from /staking/power |
Account and order methods
These methods cover wallet data, approval calldata, API-relayed order workflows, and one-click-trading subaccounts.
fetchWalletBalances({ address })returns wallet balances from/balances/wallet.fetchAllowances({ address, spender })returns token allowances from/allowances.spenderis"router".buildApproveTransaction(params)builds ERC-20 approval calldata for the selected chain.buildErc20ApproveTxn(params)builds ERC-20 approval calldata for any caller-supplied spender address, andexecuteErc20Approve(signer, params)sends that approval through a signer that supportssendTransaction.buildSameChainDepositTxn(params),buildSameChainWithdrawTxn(params),executeSameChainDeposit(signer, params), andexecuteSameChainWithdraw(signer, params)cover GMX Account funding on the settlement chain.buildSameChainWithdrawBridgeOutParams(params)andbuildCrossChainWithdrawBridgeOutParams(params)build bridge-out params used by GMX Account withdrawals.prepareCrossChainDeposit(request)andexecuteCrossChainDeposit(signer, request)cover cross-chain GMX Account deposits.prepareCrossChainWithdraw(request),signCrossChainWithdraw(prepared, signer),submitCrossChainWithdraw(request),executeCrossChainWithdraw(signer, request), andgetCrossChainWithdrawStatus(requestId)cover cross-chain GMX Account withdrawals.prepareOrder(request)prepares a swap, increase, or decrease order and returns either typed data for express mode or transaction calldata for classic mode. See Order Examples for full usage.signOrder(prepared, signer)signs a prepared express order with anIAbstractSigner.submitOrder(request)submits a signed express order intent to/orders/txns/submit.executeExpressOrder(request, signer)runs the common prepare, sign, and submit flow in one call.fetchOrderStatus({ requestId })returns relay, creation, execution, cancellation, and error state for an API-relayed order request.prepareEditOrder(request),prepareCancelOrder(request), andprepareCollateral(request)prepare edit, cancel, collateral deposit, or collateral withdrawal order intents.fetchSubaccountStatus(request),prepareSubaccountApproval(request), andsignSubaccountApproval(prepared, signer)support one-click-trading authorization flows.generateSubaccount(mainSigner),activateSubaccount(mainSigner, options?),refreshSubaccountState(account), andclearSubaccount()manage the SDK's local subaccount state.subaccountAddress,subaccountStatus,hasActiveSubaccount, andsubaccountApprovalMessageexpose the current state.- When an active subaccount exists,
prepareOrder(),prepareEditOrder(),prepareCancelOrder(),prepareCollateral(), andexecuteExpressOrder()attach the current subaccount approval automatically.signOrder()signs prepared subaccount orders with the generated subaccount key. - Use the
subaccountStatusgetter to read the parsed on-chain status afterrefreshSubaccountState(account).
PrivateKeySigner and the IAbstractSigner type are exported from @gmx-io/sdk/v2. Lower-level signer helpers are also available from @gmx-io/sdk/utils/signer.
One-click trading lifecycle
One-click trading uses three signing steps:
| Signature | Signer | When it is needed |
|---|---|---|
| Subaccount key derivation | Main wallet | When generateSubaccount() or activateSubaccount() creates the local subaccount signer |
| Subaccount approval | Main wallet | Only when the subaccount is not active on-chain, or when the requested expiry/action limit needs to be extended |
| Order signature | Subaccount signer | For each prepared subaccount order |
activateSubaccount(mainSigner, options?) refreshes the current on-chain subaccount status, generates the local subaccount signer if needed, and signs a new approval only when the existing on-chain authorization is not enough for the requested expiry and maxAllowedCount. The signed approval is kept in SDK memory and submitted with the next subaccount order.
After an approval-bearing order is created or executed and the on-chain status is usable, refreshSubaccountState(account) updates subaccountStatus and subaccountApprovalMessage becomes an empty approval whose signature is "0x". The empty approval tells the relay to use the already-active on-chain authorization, so the main wallet does not sign every trade. Per-order signatures are produced by the generated subaccount key.
Use one GmxApiSdk instance per active wallet account, or call clearSubaccount() when the wallet account changes. The SDK rejects subaccount order preparation if the stored subaccount belongs to a different account.
Staking power timestamps
StakingPowerResponse includes two protocol-level timestamps that are constant across all addresses:
| Field | Type | Description |
|---|---|---|
powerAccrualStart | unix seconds | The moment power began accumulating for staked GMX. Set to 1772582400 (March 4, 2026 00:00:00 UTC). |
loyaltyTrackingStart | unix seconds | The moment loyalty tracking became active. Before this time, unstaking did not affect the historical peak used for loyalty enforcement. Set to 1774396800 (March 25, 2026 00:00:00 UTC). |
After loyaltyTrackingStart, if an account's staked balance drops below 80% of its historical peak, accumulated power resets to zero. See Rewards for the user-facing description of how the loyalty threshold works.
When to use SDK v2
Use GmxApiSdk for API integrations that need market configuration and values, tickers, token, pair, rate, APY, performance, position, order, trade-history, JIT-liquidity, OHLCV, wallet-balance, allowance, buyback, or staking-power data, or API-relayed order submission, edit, cancellation, GMX Account, and subaccount flows. Use the full GmxSdk (SDK v1) when you need direct RPC-backed transaction ownership.
GmxApiSdk is under active development and covers an expanding share of the full SDK surface, replacing the need for direct RPC, oracle, and Subsquid connections. Order submission runs via the GMX API's Gelato relay. The GMX API OpenAPI Reference documents the underlying HTTP endpoints, while this page documents the typed SDK method names and signing helpers.