Integration guide

Use this page when you want exact integration steps. The hand-written API pages explain which surfaces exist and how they behave operationally. The API v2 OpenAPI reference is generated and is best used for endpoint schemas and response fields, not for workflow guidance. Use Troubleshooting when reads do not match expected state.

Choose the right integration surface

Start by choosing the narrowest surface that solves your problem.

Need	Recommended surface	Notes
Live oracle prices, market snapshots, liquidity, and APY	API v1 REST pages	Stable public HTTP endpoints on gmxinfra.io
Read markets, tickers, tokens, pairs, rates, APY, performance, positions, orders, or OHLCV over HTTP from TypeScript	SDK v2 or the generated API v2 reference	Read-only and expanding
Historical trade and order activity	GraphQL	Indexed data, not write-path state
Submit, cancel, or simulate orders	SDK v1 or direct contract calls	Use the SDK or contracts, not the public read-only API guides

What is available now

The current hand-written docs and checked-out code support the following split:

Surface	Read	Write	Description
API v1 REST (gmxinfra.io)	✅	❌	Public market, price, liquidity, APY, and performance reads. Manual docs cover the stable public HTTP endpoints.
API v2 HTTP reference	✅	❌	Generated schema reference for current API v2 reads. Covers markets, tokens, positions, orders, rates, APY, and performance. API v2 is in active development and is expected to become the primary API in the coming weeks, expanding to support read and write operations for virtually any action.
GraphQL	✅	❌	Historical indexed activity. Best for history, not write-path confirmation.
SDK v1 (GmxSdk)	✅	✅	Full TypeScript integration with reads and writes. Uses RPC, oracle, and Subsquid connections directly.
SDK v2 (GmxApiSdk)	✅	❌	Read-only TypeScript integration over HTTP. SDK v2 is in active development alongside API v2 and is expected to become the primary SDK in the coming weeks, expanding to support read and write operations for virtually any action.
Direct contracts	✅	✅	Lowest-level integration and custom transaction flows. Highest control and highest implementation burden.

The generated API v2 reference does not currently list every helper surfaced by SDK v2. Use the SDK v2 docs for the typed client surface, including fetchPairs() and fetchOhlcv().

Build a live market overview

Use API v1 when you need public market snapshots and fallback URLs. Use /markets for a slower-changing market list, and /markets/info for a near-live market state snapshot.

const endpoints = [
  "https://arbitrum-api.gmxinfra.io/markets/info",
  "https://arbitrum-api-fallback.gmxinfra.io/markets/info",
  "https://arbitrum-api-fallback.gmxinfra2.io/markets/info",
];

async function fetchMarketsInfo() {
  let lastError: Error | undefined;

  for (const endpoint of endpoints) {
    try {
      const response = await fetch(endpoint, {
        headers: { Accept: "application/json" },
      });

      if (!response.ok) {
        throw new Error(`HTTP ${response.status}`);
      }

      return await response.json();
    } catch (error) {
      lastError = error as Error;
    }
  }

  throw lastError ?? new Error("All market endpoints failed");
}

const markets = await fetchMarketsInfo();
console.log("Loaded markets:", markets.length);

Use this refresh strategy:

1. Call /markets when you need the market catalog and can tolerate a 60 second cache window.
2. Call /markets/info when you need liquidity, open interest, funding, borrowing, token amounts, and isDisabled. This is also the correct endpoint for near-live funding rates.
3. Treat /markets/info as a snapshot, not a guarantee of the latest block. The current implementation caches the route for 1 second and refreshes market values on a 5000 ms pull interval, so build for near-live rather than same-block state.
4. Use /rates for historical funding and borrowing rate data. This endpoint returns hourly snapshots from the Squid indexer, not realtime values. Use it for rate averages, trends, and historical analysis.

Read positions and related orders for one account

Use SDK v2 if you are already in TypeScript and want bigint-aware responses. Use the generated API v2 reference if you need raw HTTP schemas.

Install @gmx-io/sdk, then import GmxApiSdk from @gmx-io/sdk/v2. The v2 path is a subpath export, not a separate package.

import { GmxApiSdk } from "@gmx-io/sdk/v2";

const apiSdk = new GmxApiSdk({ chainId: 42161 });

const positions = await apiSdk.fetchPositionsInfo({
  address: "0x9f7198eb1b9Ccc0Eb7A07eD228d8FbC12963ea33",
  includeRelatedOrders: true,
});

const orders = await apiSdk.fetchOrders({
  address: "0x9f7198eb1b9Ccc0Eb7A07eD228d8FbC12963ea33",
});

console.log({
  positions,
  orders,
});

Use this flow when you render account state:

1. Fetch positions with includeRelatedOrders: true if your page shows open positions and their linked orders together.
2. Fetch standalone orders only if you also need an account-wide orders view.
3. After submitting a write through SDK v1 or direct contracts, poll these read endpoints until the expected state appears instead of assuming immediate consistency.

Read historical trade activity

Use GraphQL for historical, indexed activity. Do not try to reconstruct history from live REST snapshots.

query RecentTrades($account: String!) {
  tradeActions(where: { account_eq: $account }, limit: 50, orderBy: timestamp_DESC) {
    eventName
    account
    timestamp
    transactionHash
    sizeDeltaUsd
    collateralDeltaAmount
  }
}

The current GraphQL schema exposes transactionHash and top-level timestamp. See GraphQL for schema usage notes and migration context.

Operational notes

Freshness and caching

• GET /markets uses a 60 second HTTP cache in the current implementation.
• GET /markets/info uses a 1 second HTTP cache in the current implementation.
• The backend currently caches prices, tokensData, and marketsInfo for 1 second, userReferralInfo for 5 seconds, and onchainSettings for 60 seconds.
• Avoid joining data from unrelated polls when you need one coherent snapshot. Prefer composite endpoints such as /markets/info or fetchPositionsInfo({ includeRelatedOrders: true }).

Retries, timeouts, and fallback URLs

• The current API server timeout is 60000 ms.
• SDK v2 uses a simple HTTP client and does not add retry or fallback logic for you.
• Use the Fallback URLs page for API v1 market and oracle reads.
• If you receive a timeout, network error, 429, or 5xx, retry with backoff and fail over where you have fallback endpoints.

Surface-specific operational model

• API v1 REST uses endpoint-specific cache windows, and fallback URLs are documented for some public reads.
• API v2 reference documents read-only HTTP endpoints, but the generated reference does not define your retry policy.
• GraphQL is indexed data. Expect lag relative to live chain state.
• SDK v1 mixes live RPC, oracle, and indexed reads. Default SDK-created HTTP transports disable retries.
• SDK v2 is a read-only HTTP client and does not add fallback or retry logic for you.
• Direct contracts give you the most control, but your app owns retry, nonce, gas, and receipt strategy.

Idempotency and race conditions

• These public API docs cover read paths. They do not provide idempotency keys for writes.
• After a write, do not assume your first follow-up read will reflect final state. Submission, indexing, and keeper execution can land at different times.
• If you need "position plus linked orders" on one screen, prefer a single positions call with includeRelatedOrders: true over stitching data from independent polls.

Next steps

• Use API Overview to decide between REST, GraphQL, contracts, and the SDK.
• Use API v1 REST API for public market, price, and liquidity endpoints.
• Use the generated API v2 OpenAPI Reference for endpoint-level request and response schemas.
• Use Troubleshooting if your reads look stale, a query fails validation, or a write does not show up yet.
• Use SDK v1 when your application needs write flows such as creating or canceling orders.