SDK Overview
The GMX SDK (@gmx-io/sdk) is a TypeScript library for integrating GMX perpetuals and spot trading into your application. It wraps the GMX smart contracts and data APIs into a typed interface, letting you read market data, compute fees, and submit orders without managing low-level contract calls directly.
The SDK runs in Node.js (>=18) and browser environments.
SDK v1 and v2
The SDK ships two clients. Choose based on your integration needs:
Install both clients from the same package: npm install @gmx-io/sdk. The SDK v2 import path is @gmx-io/sdk/v2, but @gmx-io/sdk/v2 is not a separate npm package.
SDK v1 — GmxSdk | SDK v2 — GmxApiSdk | |
|---|---|---|
| Import | import { GmxSdk } from "@gmx-io/sdk" | import { GmxApiSdk } from "@gmx-io/sdk/v2" |
| Requires | RPC + Oracle URL + Subsquid URL | Chain ID only |
| Capabilities | Full direct client (read + write) | HTTP client for reads, wallet helpers, subaccounts, and API-relayed order workflows |
| Status | Maintenance only: no new features; to be removed in a future major version | Recommended for new integrations; expanding to cover the full SDK surface |
SDK v2 (GmxApiSdk) is under active development and will expand over time, replacing the need for direct RPC, oracle, and Subsquid connections. It wraps the GMX API OpenAPI Reference.
SDK v1 (GmxSdk) is being sunset. It receives no new features, and new capabilities such as JIT-aware trading capacity ship only in SDK v2. It will be removed in a future major version, so plan to migrate existing SDK v1 integrations to SDK v2.
- SDK v1 — Getting Started — Full client for read and write operations
- SDK v1 — Integration guide — End-to-end workflows and operational guidance
- SDK v1 — Troubleshooting — Receipt handling, duplicate-submit protection, stale reads, and simulation caveats
- SDK v2 — Getting Started — HTTP API client for TypeScript integrations
- SDK v2 — Order Examples — Creating, editing, cancelling, and tracking orders
If you are starting a new integration, read the workflow page before the reference pages and build on SDK v2: HTTP-backed reads, wallet helpers, subaccount helpers, and API-relayed order submission. SDK v1 remains available for direct RPC-backed reads or writes until it is removed.
Operational differences
| Topic | SDK v1 — GmxSdk | SDK v2 — GmxApiSdk |
|---|---|---|
| Data sources | RPC, oracle, and Subsquid | GMX API |
| Trade history | ✅ | ✅ |
| Order submission, edit, and cancellation | ✅ Direct wallet transactions | ✅ Signed intents posted to the GMX API and submitted through GMX Relay for express orders |
| Built-in HTTP peer failover | ❌ Default viem transports use retryCount: 0 | ✅ HttpClientWithFallback tries configured API peer hosts for server and network errors |
| Built-in transaction receipt waiting | ❌ | Not applicable for API-relayed order submission; poll order status with the returned requestId |
Available now
- SDK v1 is in maintenance: it receives no new features and will be removed in a future major version.
- SDK v2 exposes read methods such as
fetchMarketsInfo,fetchMarketsConfig,fetchMarketsValues,fetchMarkets,fetchMarketsTickers,getTradingCapacity,fetchTokensData,fetchTokens,fetchPairs,fetchRates,fetchApy,fetchPerformanceAnnualized,fetchPerformanceSnapshots,fetchGmPoolYieldPnl,fetchPositionsInfo,fetchOrders,fetchTrades,searchTrades,fetchOhlcv,fetchBuybackWeeklyStats,fetchJitLiquidityInfo,fetchStakingPower,fetchWalletBalances, andfetchAllowances. - SDK v2 also exposes approval helpers, order prepare/sign/submit/status methods, edit/cancel/collateral prepare methods, GMX Account deposit and withdrawal helpers, and subaccount helpers for one-click trading flows.
- Use SDK v1 only if your integration needs direct RPC ownership or lower-level contract composition today, and plan its migration to SDK v2.
Supported networks
The SDK supports the following production networks:
| Network | Chain ID | Status |
|---|---|---|
| Arbitrum | 42161 | Active |
| Avalanche | 43114 | Active |
| MegaETH | 4326 | Active |
Repository: github.com/gmx-io/gmx-interface/sdk
Installation
Install the SDK using your preferred package manager:
# npm
npm install @gmx-io/sdk
# yarn
yarn add @gmx-io/sdk
Both SDK clients ship in this package. Import GmxSdk from @gmx-io/sdk and GmxApiSdk from @gmx-io/sdk/v2.
The package supports both ESM and CommonJS. CommonJS consumers can use require("@gmx-io/sdk") for v1 and require("@gmx-io/sdk/v2") for v2. TypeScript subpath resolution is supported for the SDK's root, client, utility, config, ABI, and type-only entrypoints.
Use the SDK changelog to review package-level changes before upgrading.
The SDK requires Node.js 18 or later.