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 (read + write) | Read-only HTTP client (markets, tickers, tokens, pairs, rates, APY, performance, positions, orders, OHLCV) |
| 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 API v2 (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 — Read-only API client for TypeScript integrations
If you are starting a new integration, read the workflow page before the reference pages. Use SDK v1 when you need writes or direct RPC-backed reads. Use SDK v2 when you only need read-only HTTP access.
Operational differences
| Topic | SDK v1 — GmxSdk | SDK v2 — GmxApiSdk |
|---|---|---|
| Data sources | RPC, oracle, and Subsquid | GMX HTTP API |
| Trade history | ✅ | ❌ |
| Order submission and cancellation | ✅ | ❌ |
| Built-in HTTP retries | ❌ Default viem transports use retryCount: 0 | ❌ Current HTTP client does not add retry or fallback logic |
| Built-in transaction receipt waiting | ❌ | Not applicable |
| Idempotency keys | ❌ | Not applicable |
Available now
- SDK v1 is the current full client.
- SDK v2 exposes
fetchMarketsInfo,fetchMarkets,fetchMarketsTickers,fetchTokensData,fetchTokens,fetchPairs,fetchRates,fetchApy,fetchPerformanceAnnualized,fetchPerformanceSnapshots,fetchPositionsInfo,fetchOrders, andfetchOhlcv. - Use SDK v1 if your integration needs writes or trade history today.
Supported networks
The SDK supports the following production networks:
| Network | Chain ID |
|---|---|
| Arbitrum | 42161 |
| Avalanche | 43114 |
| Botanix | 3637 |
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 release is 1.5.0-alpha-8. The API may change before a stable release.
The SDK requires Node.js 18 or later.