prices

This module provides utilities for calculating prices, price impacts, and acceptable price ranges for GMX trading operations. This page also covers the related OHLCV read surface exposed through GmxApiSdk, because the candle types live in the same source area.

Methods

The prices module exports utilities for two tasks: determining which side of the bid-ask spread to use for a given operation, and computing acceptable prices that encode a user's slippage tolerance into an on-chain parameter. The OHLCV section below is included because the public GmxApiSdk.fetchOhlcv() method uses the same source area, but @gmx-io/sdk/utils/prices does not export the fetch helper directly.

getMarkPrice

getMarkPrice(p: { prices: TokenPrices; isIncrease: boolean; isLong: boolean }): bigint

Returns the mark price for an operation. Long increases and short decreases use maxPrice; short increases and long decreases use minPrice. This matches the on-chain convention that the protocol uses the price least favorable to the trader.

import { getMarkPrice } from "@gmx-io/sdk/utils/prices";

const markPrice = getMarkPrice({
  prices: {
    minPrice: 1800n * 10n ** 30n,
    maxPrice: 1802n * 10n ** 30n,
  },
  isIncrease: true,
  isLong: true,
});
// Returns prices.maxPrice (worst price for a long increase)

getShouldUseMaxPrice

getShouldUseMaxPrice(isIncrease: boolean, isLong: boolean): boolean

Returns true when the operation should use maxPrice and false when it should use minPrice. The rule is: isIncrease ? isLong : !isLong.

import { getShouldUseMaxPrice } from "@gmx-io/sdk/utils/prices";

getShouldUseMaxPrice(true, true); // true  — long increase uses maxPrice
getShouldUseMaxPrice(true, false); // false — short increase uses minPrice
getShouldUseMaxPrice(false, true); // false — long decrease uses minPrice
getShouldUseMaxPrice(false, false); // true  — short decrease uses maxPrice

getOrderThresholdType

getOrderThresholdType(orderType: OrderType, isLong: boolean): TriggerThresholdType | undefined

Returns the TriggerThresholdType (Above or Below) for a trigger order. Returns undefined for order types that don't use a trigger price (for example, Market Increase).

Order type	Long	Short
Limit Increase (LimitIncrease)	Below	Above
Stop Market (StopIncrease)	Above	Below
Take-Profit (LimitDecrease)	Above	Below
Stop-Loss (StopLossDecrease)	Below	Above

import { getOrderThresholdType } from "@gmx-io/sdk/utils/prices";
import { OrderType } from "@gmx-io/sdk/utils/orders";
import { TriggerThresholdType } from "@gmx-io/sdk/utils/trade";

const thresholdType = getOrderThresholdType(OrderType.LimitIncrease, true);
// TriggerThresholdType.Below — trigger when price drops to or below target

getAcceptablePriceInfo

getAcceptablePriceInfo(p: {
  marketInfo: MarketInfo;
  isIncrease: boolean;
  isLimit: boolean;
  isLong: boolean;
  indexPrice: bigint;
  sizeDeltaUsd: bigint;
  maxNegativePriceImpactBps?: bigint;
}): {
  acceptablePrice: bigint;
  acceptablePriceDeltaBps: bigint;
  priceImpactDeltaAmount: bigint;
  priceImpactDeltaUsd: bigint;
  priceImpactDiffUsd: bigint;
  balanceWasImproved: boolean;
}

Computes the acceptable price and price impact for an order. There are two code paths:

• When maxNegativePriceImpactBps is provided (Limit and Trigger orders): the acceptable price is derived directly from the basis-points slippage tolerance, and price impact is back-calculated from that price.
• When maxNegativePriceImpactBps is omitted (Market orders): the on-chain pool price impact is computed via getCappedPositionImpactUsd and used to derive the acceptable price.

Returns zero values when sizeDeltaUsd is 0 or indexPrice is 0n.

import { getAcceptablePriceInfo } from "@gmx-io/sdk/utils/prices";

// Market order: derive acceptable price from live pool price impact
const result = getAcceptablePriceInfo({
  marketInfo,
  isIncrease: true,
  isLimit: false,
  isLong: true,
  indexPrice: 1800n * 10n ** 30n,
  sizeDeltaUsd: 10000n * 10n ** 30n, // $10,000 position
});

console.log("Acceptable price:", result.acceptablePrice);
console.log("Price impact USD:", result.priceImpactDeltaUsd);

// Limit order: pass explicit slippage tolerance (50 bps = 0.5%)
const limitResult = getAcceptablePriceInfo({
  marketInfo,
  isIncrease: true,
  isLimit: true,
  isLong: true,
  indexPrice: 1800n * 10n ** 30n,
  sizeDeltaUsd: 10000n * 10n ** 30n,
  maxNegativePriceImpactBps: 50n,
});

getAcceptablePriceByPriceImpact

getAcceptablePriceByPriceImpact(p: {
  isIncrease: boolean;
  isLong: boolean;
  indexPrice: bigint;
  sizeDeltaUsd: bigint;
  priceImpactDeltaUsd: bigint;
}): {
  acceptablePrice: bigint;
  acceptablePriceDeltaBps: bigint;
  priceDelta: bigint;
}

Converts a USD price impact into an acceptable price. The formula is:

acceptablePrice = indexPrice × (sizeDeltaUsd + adjustedImpact) / sizeDeltaUsd

where adjustedImpact flips the sign for longs versus shorts. Returns { acceptablePrice: indexPrice, acceptablePriceDeltaBps: 0n, priceDelta: 0n } when sizeDeltaUsd is 0 or indexPrice is 0n.

import { getAcceptablePriceByPriceImpact } from "@gmx-io/sdk/utils/prices";

const { acceptablePrice, acceptablePriceDeltaBps, priceDelta } = getAcceptablePriceByPriceImpact({
  isIncrease: true,
  isLong: true,
  indexPrice: 1800n * 10n ** 30n,
  sizeDeltaUsd: 10000n * 10n ** 30n,
  priceImpactDeltaUsd: -50n * 10n ** 30n, // -$50 price impact
});
// acceptablePrice is slightly below indexPrice (worse for a long)
// acceptablePriceDeltaBps is the basis-point deviation from indexPrice

getDefaultAcceptablePriceImpactBps

getDefaultAcceptablePriceImpactBps(p: {
  isIncrease: boolean;
  isLong: boolean;
  indexPrice: bigint;
  sizeDeltaUsd: bigint;
  priceImpactDeltaUsd: bigint;
  acceptablePriceImapctBuffer?: number;  // default: 30 (0.3%)
}): bigint

Returns the recommended acceptable price impact in basis points for a given trade, including a safety buffer. The default buffer is 30 basis points (0.3%).

When priceImpactDeltaUsd is positive (favorable price impact), the function returns only the buffer. When it's negative, the function converts the impact to basis points and adds the buffer on top.

note

The parameter name acceptablePriceImapctBuffer contains a typo (Imapct instead of Impact). This matches the source code exactly and must be used as-is.

import { getDefaultAcceptablePriceImpactBps } from "@gmx-io/sdk/utils/prices";

const acceptableBps = getDefaultAcceptablePriceImpactBps({
  isIncrease: true,
  isLong: true,
  indexPrice: 1800n * 10n ** 30n,
  sizeDeltaUsd: 10000n * 10n ** 30n,
  priceImpactDeltaUsd: -50n * 10n ** 30n,
  // acceptablePriceImapctBuffer: 30  // 30 bps buffer (default)
});
// Returns: |priceImpactBps| + 30

API data fetching

The prices module includes a utility for fetching OHLCV candle data from the GMX REST API. The public interface is the fetchOhlcv method on the GmxApiSdk V2 client.

fetchOhlcv via GmxApiSdk

import { GmxApiSdk } from "@gmx-io/sdk/v2";
import type { OhlcvCandle, OhlcvParams } from "@gmx-io/sdk/v2";

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

const candles: OhlcvCandle[] = await apiSdk.fetchOhlcv({
  symbol: "BTC/USD",
  timeframe: "1h",
  limit: 100,
});

The method sends a GET request to the /prices/ohlcv endpoint with the provided query parameters.

OhlcvParams

type OhlcvParams = {
  symbol: string;     // Trading pair, for example "BTC/USD"
  timeframe: string;  // Candle interval, for example "1h", "4h", "1d"
  limit?: number;     // Maximum number of candles to return
  since?: number;     // Unix timestamp to start from
};

OhlcvCandle

Each candle in the returned array has this shape:

type OhlcvCandle = {
  timestamp: number;
  open: string;
  high: string;
  low: string;
  close: string;
};

The open, high, low, and close values are returned as strings.

note

The underlying fetchApiOhlcv function in utils/prices/api is not re-exported from @gmx-io/sdk/utils/prices. Use GmxApiSdk.fetchOhlcv() instead. The OhlcvCandle and OhlcvParams types are also available from @gmx-io/sdk/types/prices.