Skip to main content

tokens

This module provides comprehensive token configuration and utilities for the GMX protocol across different blockchain networks. It includes token definitions, mappings, and helper functions for working with tokens in both V1 and V2 versions of the protocol.

Constants​

The constants section covers three categories: special stub addresses, pre-built token data maps, and color mappings. Import any constant directly from @gmx-io/sdk/configs/tokens.

Special addresses​

  • NATIVE_TOKEN_ADDRESS: string — The zero address ("0x0000000000000000000000000000000000000000") used to represent native tokens (ETH, AVAX, etc.).
  • GM_STUB_ADDRESS: string — Stub address used internally to represent GM (liquidity pool) tokens: "<GM-ADDRESS>".
  • GLV_STUB_ADDRESS: string — Stub address used internally to represent GLV (liquidity vault) tokens: "<GLV-ADDRESS>".
import { NATIVE_TOKEN_ADDRESS } from "@gmx-io/sdk/configs/tokens";

console.log(NATIVE_TOKEN_ADDRESS); // "0x0000000000000000000000000000000000000000"

Token data maps (pre-built)​

These objects are populated at module initialization time from the static TOKENS array. Prefer the getter functions below over accessing these maps directly.

  • TOKENS: { [chainId: number]: Token[] } — Raw token array for each chain, used as the source of truth.
  • TOKENS_MAP: { [chainId: number]: { [address: string]: Token } } — Tokens keyed by address per chain.
  • V1_TOKENS: { [chainId: number]: Token[] } — V1-available tokens per chain.
  • V2_TOKENS: { [chainId: number]: Token[] } — V2-available tokens per chain.
  • SYNTHETIC_TOKENS: { [chainId: number]: Token[] } — Synthetic tokens per chain.
  • TOKENS_BY_SYMBOL_MAP: { [chainId: number]: { [symbol: string]: Token } } — Tokens keyed by symbol per chain.
  • WRAPPED_TOKENS_MAP: { [chainId: number]: Token } — The wrapped native token per chain.
  • NATIVE_TOKENS_MAP: { [chainId: number]: Token } — The native token per chain.
import { TOKENS } from "@gmx-io/sdk/configs/tokens";
import { ARBITRUM } from "@gmx-io/sdk/configs/chains";

const arbitrumTokens = TOKENS[ARBITRUM];
console.log(arbitrumTokens[0].symbol); // "ETH"

TOKEN_COLOR_MAP​

TOKEN_COLOR_MAP: { [symbol: string]: string }

Color mappings for token symbols used in UI components. Includes a default fallback color.

import { TOKEN_COLOR_MAP } from "@gmx-io/sdk/configs/tokens";

console.log(TOKEN_COLOR_MAP.ETH); // "#6062a6"
console.log(TOKEN_COLOR_MAP.BTC); // "#F7931A"
console.log(TOKEN_COLOR_MAP.default); // "#6062a6"

Methods​

The tokens config module exports functions organized into two groups: lookup and validation helpers for retrieving token objects, and display/conversion utilities. Import any function directly from @gmx-io/sdk/configs/tokens. Chain ID constants (such as ARBITRUM) must be imported from @gmx-io/sdk/configs/chains.

getSyntheticTokens​

getSyntheticTokens(chainId: number): Token[]

Returns all synthetic tokens available on the specified chain.

import { getSyntheticTokens } from "@gmx-io/sdk/configs/tokens";
import { ARBITRUM } from "@gmx-io/sdk/configs/chains";

const syntheticTokens = getSyntheticTokens(ARBITRUM);
console.log(syntheticTokens.map((token) => token.symbol));

getWrappedToken​

getWrappedToken(chainId: number): Token

Returns the wrapped native token for the specified chain (for example, WETH on Arbitrum, WAVAX on Avalanche).

import { getWrappedToken } from "@gmx-io/sdk/configs/tokens";
import { ARBITRUM } from "@gmx-io/sdk/configs/chains";

const wrappedToken = getWrappedToken(ARBITRUM);
console.log(wrappedToken.symbol); // "WETH"

getNativeToken​

getNativeToken(chainId: number): Token

Returns the native token for the specified chain.

import { getNativeToken } from "@gmx-io/sdk/configs/tokens";
import { ARBITRUM } from "@gmx-io/sdk/configs/chains";

const nativeToken = getNativeToken(ARBITRUM);
console.log(nativeToken.symbol); // "ETH"

getTokens​

getTokens(chainId: number): Token[]

Returns all tokens available on the specified chain.

import { getTokens } from "@gmx-io/sdk/configs/tokens";
import { ARBITRUM } from "@gmx-io/sdk/configs/chains";

const allTokens = getTokens(ARBITRUM);

getV1Tokens​

getV1Tokens(chainId: number): Token[]

Returns tokens available in GMX V1 on the specified chain.

getV2Tokens​

getV2Tokens(chainId: number): Token[]

Returns tokens available in GMX V2 on the specified chain.

getTokensMap​

getTokensMap(chainId: number): { [address: string]: Token }

Returns a mapping of token addresses to token objects for the specified chain.

import { getTokensMap } from "@gmx-io/sdk/configs/tokens";
import { ARBITRUM } from "@gmx-io/sdk/configs/chains";

const tokensMap = getTokensMap(ARBITRUM);
const ethToken = tokensMap["0x0000000000000000000000000000000000000000"];
console.log(ethToken.symbol); // "ETH"

getWhitelistedV1Tokens​

getWhitelistedV1Tokens(chainId: number): Token[]

Returns whitelisted tokens for GMX V1 on the specified chain. Equivalent to getV1Tokens.

getVisibleV1Tokens​

getVisibleV1Tokens(chainId: number): Token[]

Returns visible V1 tokens (excluding wrapped tokens) for the specified chain.

isValidToken​

isValidToken(chainId: number, address: string): boolean

Returns true if the token address exists on the specified chain. Throws if the chain ID is not recognized.

import { isValidToken } from "@gmx-io/sdk/configs/tokens";
import { ARBITRUM } from "@gmx-io/sdk/configs/chains";

const isValid = isValidToken(ARBITRUM, "0x82aF49447D8a07e3bd95BD0d56f35241523fBab1");
console.log(isValid); // true

isValidTokenSafe​

isValidTokenSafe(chainId: number, address: string): boolean

Safely checks if a token address exists on the specified chain without throwing.

import { isValidTokenSafe } from "@gmx-io/sdk/configs/tokens";
import { ARBITRUM } from "@gmx-io/sdk/configs/chains";

isValidTokenSafe(ARBITRUM, "0x82aF49447D8a07e3bd95BD0d56f35241523fBab1"); // true
isValidTokenSafe(ARBITRUM, "0xinvalidaddress"); // false

getToken​

getToken(chainId: number, address: string): Token

Returns the token object for the specified address. Throws if the chain or address is not recognized.

import { getToken } from "@gmx-io/sdk/configs/tokens";
import { ARBITRUM } from "@gmx-io/sdk/configs/chains";

const wethToken = getToken(ARBITRUM, "0x82aF49447D8a07e3bd95BD0d56f35241523fBab1");
console.log(wethToken.symbol); // "WETH"

getTokenBySymbol​

getTokenBySymbol(chainId: number, symbol: string, options?: { isSynthetic?: boolean; version?: "v1" | "v2"; symbolType?: "symbol" | "baseSymbol" }): Token

Returns the token object for the specified symbol. Throws if not found.

import { getTokenBySymbol } from "@gmx-io/sdk/configs/tokens";
import { ARBITRUM } from "@gmx-io/sdk/configs/chains";

const ethToken = getTokenBySymbol(ARBITRUM, "ETH");
const syntheticBTC = getTokenBySymbol(ARBITRUM, "BTC", { isSynthetic: true });

getTokenBySymbolSafe​

getTokenBySymbolSafe(chainId: number, symbol: string, options?: { isSynthetic?: boolean; version?: "v1" | "v2"; symbolType?: "symbol" | "baseSymbol" }): Token | undefined

Like getTokenBySymbol but returns undefined instead of throwing when the token is not found.

import { getTokenBySymbolSafe } from "@gmx-io/sdk/configs/tokens";
import { ARBITRUM } from "@gmx-io/sdk/configs/chains";

const token = getTokenBySymbolSafe(ARBITRUM, "ETH"); // Token
const missing = getTokenBySymbolSafe(ARBITRUM, "INVALID"); // undefined

convertTokenAddress​

convertTokenAddress(chainId: number, address: string, convertTo?: "wrapped" | "native"): string

Converts between native and wrapped token addresses.

import { convertTokenAddress, NATIVE_TOKEN_ADDRESS } from "@gmx-io/sdk/configs/tokens";
import { ARBITRUM } from "@gmx-io/sdk/configs/chains";

const wrappedAddress = convertTokenAddress(ARBITRUM, NATIVE_TOKEN_ADDRESS, "wrapped");
console.log(wrappedAddress); // "0x82aF49447D8a07e3bd95BD0d56f35241523fBab1"

const nativeAddress = convertTokenAddress(ARBITRUM, "0x82aF49447D8a07e3bd95BD0d56f35241523fBab1", "native");
console.log(nativeAddress); // "0x0000000000000000000000000000000000000000"

getNormalizedTokenSymbol​

getNormalizedTokenSymbol(tokenSymbol: string): string

Returns a normalized version of a token symbol by applying these rules in order:

  • WBTC, WETH, WAVAX → strip the leading W (for example, WETH → ETH)
  • PBTC, STBTC → return "BTC"
  • XAUT → return "XAUT.v2"
  • Symbols containing . → return the part before the dot (for example, USDC.E → USDC)
  • All other symbols → return as-is
import { getNormalizedTokenSymbol } from "@gmx-io/sdk/configs/tokens";

console.log(getNormalizedTokenSymbol("WETH")); // "ETH"
console.log(getNormalizedTokenSymbol("USDC.E")); // "USDC"
console.log(getNormalizedTokenSymbol("PBTC")); // "BTC"

isChartAvailableForToken​

isChartAvailableForToken(chainId: number, tokenSymbol: string): boolean

Returns true if chart data is available for the token on the specified chain.

getPriceDecimals​

getPriceDecimals(chainId: number, tokenSymbol?: string): number

Returns the number of decimal places to display for a token's price. Defaults to 2.

import { getPriceDecimals } from "@gmx-io/sdk/configs/tokens";
import { ARBITRUM } from "@gmx-io/sdk/configs/chains";

console.log(getPriceDecimals(ARBITRUM, "ETH")); // 2

isTokenInList​

isTokenInList(token: Token, tokenList: Token[]): boolean

Returns true if the token exists in the given list (matched by address).

isSimilarToken​

isSimilarToken(tokenA: Token, tokenB: Token): boolean

Returns true if two tokens are similar. Two tokens are considered similar when they share the same address, or when their symbol and baseSymbol fields overlap (for example, WETH with baseSymbol: "ETH" is similar to a token with symbol: "ETH").

getTokenVisualMultiplier​

getTokenVisualMultiplier(token: Token): string

Returns the visual multiplier string for a token, derived from token.visualPrefix or token.visualMultiplier. Returns an empty string if neither is set.

getStableTokens​

getStableTokens(chainId: number): Token[]

Returns all stable tokens on the specified chain (tokens with isStable: true).

getCategoryTokenAddresses​

getCategoryTokenAddresses(chainId: number, category: TokenCategory): string[]

Returns token addresses belonging to the specified category on a chain.

createTokensMap​

createTokensMap(tokens: Token[]): Record<string, Token>

Creates a token address-to-token map from an array of tokens.

import { createTokensMap, getV1Tokens } from "@gmx-io/sdk/configs/tokens";
import { ARBITRUM } from "@gmx-io/sdk/configs/chains";

const v1Tokens = getV1Tokens(ARBITRUM);
const tokensMap = createTokensMap(v1Tokens);

isUsdBasedStableToken​

isUsdBasedStableToken(token: Token): boolean

Returns true if the token is a USD-based stablecoin (USDC, USDC.E, USDT, DAI, USDC.SG).

import { isUsdBasedStableToken, getTokenBySymbol } from "@gmx-io/sdk/configs/tokens";
import { ARBITRUM } from "@gmx-io/sdk/configs/chains";

const usdc = getTokenBySymbol(ARBITRUM, "USDC");
console.log(isUsdBasedStableToken(usdc)); // true