Skip to content

README.md

Latest commit

 

History

History
280 lines (217 loc) · 8.85 KB

README.md

File metadata and controls

280 lines (217 loc) · 8.85 KB
Raw

GMX SDK

Installation

yarn add @gmx-io/sdk # or
npm install --save @gmx-io/sdk

Getting Started

import { GmxSdk } from "@gmx-io/sdk";
import { useWallet } from "wagmi";

const sdk = new GmxSdk({
  chainId: 42161,
  rpcUrl: "https://arb1.arbitrum.io/rpc",
  oracleUrl: "https://arbitrum-api.gmxinfra.io",
  walletClient: useWallet().walletClient,
  subsquidUrl: "https://gmx.squids.live/gmx-synthetics-arbitrum@bac941/api/graphql",
});

const { marketsInfoData, tokensData } = await sdk.markets.getMarketsInfo();

sdk.setAccount("0x1234567890abcdef1234567890abcdef12345678");

sdk.positions
  .getPositions({
    marketsInfoData,
    tokensData,
    start: 0,
    end: 1000,
  })
  .then((positions) => {
    console.log(positions);
  });

API Reference

Read Methods

Markets

  • getMarkets(offset?: number, limit?: number): Promise<Market[]> - fetches a list of available markets
  • getMarketsInfo(): Promise<{ marketsInfoData: MarketInfoData[], tokensData: TokenData[] }> - retrieves detailed market information along with token data
  • getDailyVolumes(): Promise<{market: string; volume: bigint}[]> - gets daily trading volume for each market

Positions

  • getPositions(): Promise<Position[]> - retrieves all open positions

Tokens

  • getTokensData(): Promise<TokenData[]> - fetches data for all available tokens

Orders

  • getOrders(): Promise<Order[]> - retrieves all active orders

Trades

  • getTradeHistory(p: Parameters): Promise<TradeAction[]> - fetches historical trade data

Write Methods

Orders

Quick Methods:

  • long(p: Parameters) - opens a long position (see examples)
  • short(p: Parameters) - opens a short position (see examples)
  • swap(p: Parameters) - executes a token swap (see examples)

Full Methods:

  • cancelOrders(orderKeys: string[]) - cancels one or more orders using their keys
  • createIncreaseOrder(p: Parameters) - creates an order to increase position size (see examples)
  • createDecreaseOrder(p: Parameters) - creates an order to decrease position size (see examples)
  • createSwapOrder(p: Parameters) - creates a token swap order (see examples)

Configuration Options

interface GmxSdkConfig {
  chainId: number;
  rpcUrl: string;
  oracleUrl: string;
  subsquidUrl?: string;
  account?: string;
  publicClient: PublicClient;
  walletClient: WalletClient;
  tokens?: Record<string, Partial<Token>>;
  markets?: Record<
    string,
    {
      isListed: boolean;
    }
  >;
}

Setting Up Custom Viem Clients

When working with custom Viem clients, make sure to include the batching configuration:

import { BATCH_CONFIGS } from "@gmx-io/sdk/configs/batch";

const publicClient = createPublicClient({
  ...your_config,
  batch: BATCH_CONFIGS[chainId].client,
});

Network URLs

Customizing Token Data

You can override default token properties by passing an extension object in the SDK configuration:

const sdk = new GmxSdk({
  ...arbitrumSdkConfig,
  tokens: {
    "0x912CE59144191C1204E64559FE8253a0e49E6548": {
      name: "My Custom Name for ARB",
    },
  },
});

With this configuration, the name field for this token will use your custom value throughout the SDK.

Customizing Market Availability

To control which markets are available in the SDK, use the markets configuration field:

const sdk = new GmxSdk({
  ...arbitrumSdkConfig,
  markets: {
    "0x47c031236e19d024b42f8AE6780E44A573170703": {
      isListed: false,
    },
  },
});

Usage Examples

Opening a Long Position

import type { IncreasePositionAmounts } from "@gmx-io/sdk/types/orders";

const { marketsInfoData, tokensData } = await sdk.markets.getMarketsInfo();

if (!marketsInfoData || !tokensData) {
  throw new Error("No markets or tokens info data");
}

const marketInfo = marketsInfo["0x47c031236e19d024b42f8AE6780E44A573170703"];
const collateralToken = tokensData["0x912CE59144191C1204E64559FE8253a0e49E6548"];
sdk.orders.createIncreaseOrder({
  marketsInfoData: marketsInfoData!,
  tokensData,
  isLimit: false,
  isLong: true,
  marketAddress: marketInfo.marketTokenAddress,
  allowedSlippage: 50,
  collateralToken,
  collateralTokenAddress: collateralToken.address,
  receiveTokenAddress: collateralToken.address,
  fromToken: tokensData["0x912CE59144191C1204E64559FE8253a0e49E6548"],
  marketInfo,
  indexToken: marketInfo.indexToken,
  increaseAmounts: {
    initialCollateralAmount: 3000000n,
    initialCollateralUsd: 2999578868393486100000000000000n,
    collateralDeltaAmount: 2997003n,
    collateralDeltaUsd: 2996582289103961007386100000000n,
    indexTokenAmount: 1919549334876037n,
    sizeDeltaUsd: 5993158579050185227800000000000n,
    sizeDeltaInTokens: 1919536061202302n,
    estimatedLeverage: 20000n,
    indexPrice: 3122169600000000000000000000000000n,
    initialCollateralPrice: 999859622797828700000000000000n,
    collateralPrice: 999859622797828700000000000000n,
    triggerPrice: 0n,
    acceptablePrice: 3122191190655414690893787784152819n,
    acceptablePriceDeltaBps: 0n,
    positionFeeUsd: 2996579289525092613900000000n,
    swapPathStats: undefined,
    uiFeeUsd: 0n,
    swapUiFeeUsd: 0n,
    feeDiscountUsd: 0n,
    borrowingFeeUsd: 0n,
    fundingFeeUsd: 0n,
    positionPriceImpactDeltaUsd: 41444328240807630917223064n,
  },
});

Helpers

Helper functions simplify order creation by automatically calculating amounts, swap paths, and other parameters. By default, helpers fetch the latest data from the API, but you can optionally pass marketsInfoData and tokensData yourself to reduce API calls.

sdk.orders.long({
  payAmount: 100031302n,
  marketAddress: "0x70d95587d40A2caf56bd97485aB3Eec10Bee6336", // ETH/USD [WETH-USDC]
  payTokenAddress: "0x82aF49447D8a07e3bd95BD0d56f35241523fBab1", // WETH
  collateralTokenAddress: "0xaf88d065e77c8cC2239327C5EDb3A432268e5831", // USDC
  allowedSlippageBps: 125,
  leverage: 50000n,
});

sdk.orders.swap({
  fromAmount: 1000n,
  fromTokenAddress: "0x912CE59144191C1204E64559FE8253a0e49E6548", // ARB
  toTokenAddress: "0xf97f4df75117a78c1A5a0DBb814Af92458539FB4", // LINK
  allowedSlippageBps: 125,
});

Note the distinction between payTokenAddress and collateralTokenAddress. These represent the ERC20 token addresses for payment and collateral respectively. Some markets use synthetic tokens, so you'll need to provide the correct underlying token address. For example, the BTC/USD [WETH-USDC] market has a synthetic BTC token as its indexTokenAddress, so you should pass the WBTC address instead of BTC.

JIT-aware trading capacity

Use the v2 API client to get the current increase-order capacity for one market side:

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

const api = new GmxApiSdk({ chainId: 42161 });
const capacity = await api.getTradingCapacity({
  symbol: "ETH/USD [WETH-USDC]",
  direction: "long",
});

if (capacity.marketDataStatus !== "fresh") {
  throw new Error("Trading capacity is based on stale market data");
}

const safeAccountAgnosticSize = capacity.baseAvailableLiquidity;
const indicativeGlobalCapacity =
  capacity.jitDataStatus === "available" ? capacity.availableLiquidity : capacity.baseAvailableLiquidity;

availableLiquidity is the current global JIT-aware capacity and remains capped by max open interest. It is indicative because the keeper can restrict JIT by account. baseAvailableLiquidity is the native capacity without JIT, but it is still a market-level snapshot: a collateral swap or intervening market state can reduce the capacity available to a specific order. The keeper can use JIT for market, limit, stop-market, and TWAP increases, but availability is evaluated again when each order executes. Do not size an order while marketDataStatus is stale. Treat prepareOrder as the final request-aware validation; it returns a typed warning when capacity is not authoritative for the specific request.

Prepare failures can be narrowed to the typed API contract:

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

try {
  await api.prepareOrder(request);
} catch (error) {
  const prepareError = parsePrepareOrderError(error);
  if (prepareError?.code === "INSUFFICIENT_LIQUIDITY") {
    console.log(prepareError.details.availableLiquidity, prepareError.details.requestedSizeUsd);
  }
}

The helper uses the capacity returned by /v1/markets/trading-capacity. Existing raw JIT access through fetchJitLiquidityInfo() remains available for integrations that need shift data.