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 | Current full client | 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 — 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. Use SDK v1 when you need direct RPC-backed reads or writes. Use SDK v2 when you want HTTP-backed reads, wallet helpers, subaccount helpers, or API-relayed order submission.
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 relayed through Gelato 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 the current full client.
- SDK v2 exposes read methods such as
fetchMarketsInfo,fetchMarkets,fetchMarketsTickers,fetchTokensData,fetchTokens,fetchPairs,fetchRates,fetchApy,fetchPerformanceAnnualized,fetchPerformanceSnapshots,fetchPositionsInfo,fetchOrders,fetchOhlcv,fetchBuybackWeeklyStats,fetchStakingPower,fetchWalletBalances, andfetchAllowances. - SDK v2 also exposes
buildApproveTransaction, order prepare/sign/submit/status methods, edit/cancel/collateral prepare methods, and subaccount helpers for one-click trading flows. - Use SDK v1 if your integration needs direct RPC ownership or trade history today.
Supported networks
The SDK supports the following production networks:
| Network | Chain ID |
|---|---|
| Arbitrum | 42161 |
| Avalanche | 43114 |
| Botanix | 3637 |
| MegaETH | 4326 |
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.
The current npm release is 1.5.0-alpha-13. The API may change before a stable release.
The SDK requires Node.js 18 or later.