Skip to main content

tokens

This module provides utilities for token price conversions, amount calculations, and token relationship operations in the GMX protocol. It handles conversions between USD values and token amounts, price formatting for contracts, and various token comparison utilities.

Methods​

parseContractPrice​

  • parseContractPrice(price: bigint, tokenDecimals: number): bigint

Converts a contract price to a standard price format by adjusting for token decimals.

import { parseContractPrice } from "@gmx-ui/sdk/utils/tokens";

const contractPrice = 1000000n;
const decimals = 18;
const standardPrice = parseContractPrice(contractPrice, decimals);

convertToContractPrice​

  • convertToContractPrice(price: bigint, tokenDecimals: number): ContractPrice

Converts a standard price to contract price format by adjusting for token decimals.

import { convertToContractPrice } from "@gmx-ui/sdk/utils/tokens";

const standardPrice = 1000000000000000000000n;
const decimals = 18;
const contractPrice = convertToContractPrice(standardPrice, decimals);

convertToContractTokenPrices​

  • convertToContractTokenPrices(prices: TokenPrices, tokenDecimals: number): { min: ContractPrice; max: ContractPrice }

Parameters​

  • prices: TokenPrices - Object containing minPrice and maxPrice
  • tokenDecimals: number - Number of decimals for the token

Converts token prices to contract format for both min and max prices.

import { convertToContractTokenPrices } from "@gmx-ui/sdk/utils/tokens";

const prices = {
  minPrice: 1000000000000000000000n,
  maxPrice: 1100000000000000000000n
};
const contractPrices = convertToContractTokenPrices(prices, 18);

convertToTokenAmount​

  • convertToTokenAmount(usd: bigint | undefined, tokenDecimals: number | undefined, price: bigint | undefined): bigint | undefined

Converts a USD value to token amount using the given price and token decimals.

import { convertToTokenAmount } from "@gmx-ui/sdk/utils/tokens";

const usdValue = 1000000000000000000000n; // $1000 in wei
const tokenDecimals = 18;
const tokenPrice = 2000000000000000000000n; // $2000 per token
const tokenAmount = convertToTokenAmount(usdValue, tokenDecimals, tokenPrice);

convertToUsd​

  • convertToUsd(tokenAmount: bigint | undefined, tokenDecimals: number | undefined, price: bigint | undefined): bigint | undefined

Converts a token amount to USD value using the given price and token decimals.

import { convertToUsd } from "@gmx-ui/sdk/utils/tokens";

const tokenAmount = 500000000000000000n; // 0.5 tokens
const tokenDecimals = 18;
const tokenPrice = 2000000000000000000000n; // $2000 per token
const usdValue = convertToUsd(tokenAmount, tokenDecimals, tokenPrice);

convertBetweenTokens​

  • convertBetweenTokens(tokenAmount: bigint | undefined, fromToken: TokenData | undefined, toToken: TokenData | undefined, maximize: boolean): bigint | undefined

Parameters​

  • tokenAmount: bigint | undefined - Amount of the source token
  • fromToken: TokenData | undefined - Source token data including prices and decimals
  • toToken: TokenData | undefined - Target token data including prices and decimals
  • maximize: boolean - Whether to maximize the output amount

Converts an amount from one token to another using their respective prices.

import { convertBetweenTokens } from "@gmx-ui/sdk/utils/tokens";

const amount = 1000000000000000000n; // 1 token
const convertedAmount = convertBetweenTokens(amount, fromTokenData, toTokenData, true);

getMidPrice​

  • getMidPrice(prices: TokenPrices): bigint

Parameters​

  • prices: TokenPrices - Object containing minPrice and maxPrice

Calculates the mid price between min and max token prices.

import { getMidPrice } from "@gmx-ui/sdk/utils/tokens";

const prices = {
  minPrice: 1900000000000000000000n,
  maxPrice: 2100000000000000000000n
};
const midPrice = getMidPrice(prices);

getIsEquivalentTokens​

  • getIsEquivalentTokens(token1: Token, token2: Token): boolean

Parameters​

  • token1: Token - First token to compare
  • token2: Token - Second token to compare

Determines if two tokens are equivalent (same address, wrapped/native pair, or synthetic tokens with same symbol).

import { getIsEquivalentTokens } from "@gmx-ui/sdk/utils/tokens";

const isEquivalent = getIsEquivalentTokens(wethToken, ethToken);

getTokenData​

  • getTokenData(tokensData?: TokensData, address?: string, convertTo?: "wrapped" | "native"): TokenData | undefined

Parameters​

  • tokensData: TokensData | undefined - Map of token addresses to token data
  • address: string | undefined - Token address to look up
  • convertTo: "wrapped" | "native" | undefined - Optional conversion type

Retrieves token data from the tokens map, optionally converting between wrapped and native versions.

import { getTokenData } from "@gmx-ui/sdk/utils/tokens";

const tokenData = getTokenData(tokensData, tokenAddress, "wrapped");

getTokensRatioByAmounts​

  • getTokensRatioByAmounts(p: { fromToken: Token; toToken: Token; fromTokenAmount: bigint; toTokenAmount: bigint }): TokensRatio

Parameters​

  • p: object - Parameters object containing fromToken, toToken, fromTokenAmount, and toTokenAmount

Calculates the ratio between two token amounts, identifying which token has the larger amount.

import { getTokensRatioByAmounts } from "@gmx-ui/sdk/utils/tokens";

const ratio = getTokensRatioByAmounts({
  fromToken: tokenA,
  toToken: tokenB,
  fromTokenAmount: 1000000000000000000n,
  toTokenAmount: 2000000000000000000n
});

getTokensRatioByMinOutputAmountAndTriggerPrice​

  • getTokensRatioByMinOutputAmountAndTriggerPrice(p: { fromToken: Token; toToken: Token; fromTokenAmount: bigint; toTokenAmount: bigint; triggerPrice: bigint; minOutputAmount: bigint }): TokensRatioAndSlippage

Parameters​

  • p: object - Parameters object containing token data, amounts, trigger price, and minimum output amount

Calculates token ratio and allowed slippage based on trigger price and minimum output requirements.

import { getTokensRatioByMinOutputAmountAndTriggerPrice } from "@gmx-ui/sdk/utils/tokens";

const ratioAndSlippage = getTokensRatioByMinOutputAmountAndTriggerPrice({
  fromToken: tokenA,
  toToken: tokenB,
  fromTokenAmount: 1000000000000000000n,
  toTokenAmount: 2000000000000000000n,
  triggerPrice: 1500000000000000000000n,
  minOutputAmount: 1900000000000000000n
});

getAmountByRatio​

  • getAmountByRatio(p: { fromToken: Token; toToken: Token; fromTokenAmount: bigint; ratio: bigint; shouldInvertRatio?: boolean; allowedSwapSlippageBps?: bigint }): bigint

Parameters​

  • p: object - Parameters object containing tokens, amount, ratio, and optional slippage settings

Calculates the output amount based on a given ratio, with optional slippage adjustment.

import { getAmountByRatio } from "@gmx-ui/sdk/utils/tokens";

const outputAmount = getAmountByRatio({
  fromToken: tokenA,
  toToken: tokenB,
  fromTokenAmount: 1000000000000000000n,
  ratio: 2000000000000000000000n,
  shouldInvertRatio: false,
  allowedSwapSlippageBps: 50n
});

getIsWrap​

  • getIsWrap(token1: Token, token2: Token): boolean

Parameters​

  • token1: Token - Source token
  • token2: Token - Target token

Determines if the operation is wrapping a native token to its wrapped version.

import { getIsWrap } from "@gmx-ui/sdk/utils/tokens";

const isWrapOperation = getIsWrap(ethToken, wethToken);

getIsUnwrap​

  • getIsUnwrap(token1: Token, token2: Token): boolean

Parameters​

  • token1: Token - Source token
  • token2: Token - Target token

Determines if the operation is unwrapping a wrapped token to its native version.

import { getIsUnwrap } from "@gmx-ui/sdk/utils/tokens";

const isUnwrapOperation = getIsUnwrap(wethToken, ethToken);

getIsStake​

  • getIsStake(token1: Token, token2: Token): boolean

Parameters​

  • token1: Token - Source token
  • token2: Token - Target token

Determines if the operation is staking a token (native or wrapped to staking token).

import { getIsStake } from "@gmx-ui/sdk/utils/tokens";

const isStakeOperation = getIsStake(wethToken, stakingToken);

getIsUnstake​

  • getIsUnstake(token1: Token, token2: Token): boolean

Parameters​

  • token1: Token - Source token
  • token2: Token - Target token

Determines if the operation is unstaking a token (staking token to wrapped token).

import { getIsUnstake } from "@gmx-ui/sdk/utils/tokens";

const isUnstakeOperation = getIsUnstake(stakingToken, wethToken);

getTokensRatioByPrice​

  • getTokensRatioByPrice(p: { fromToken: Token; toToken: Token; fromPrice: bigint; toPrice: bigint }): TokensRatio

Parameters​

  • p: object - Parameters object containing tokens and their respective prices

Calculates the ratio between two tokens based on their prices.

import { getTokensRatioByPrice } from "@gmx-ui/sdk/utils/tokens";

const ratio = getTokensRatioByPrice({
  fromToken: tokenA,
  toToken: tokenB,
  fromPrice: 2000000000000000000000n,
  toPrice: 1000000000000000000000n
});