gmx.synthetic_tokens

Documentation for eth_defi.gmx.synthetic_tokens Python module.

GMX Synthetic token details fetching and caching.

Fetch GMX synthetic token data from APIs and cache results for efficient access.

Functions

fetch_gmx_synthetic_tokens(chain_id[, ...])

Fetch GMX synthetic token details from API with caching and retry logic.

get_gmx_synthetic_token_by_address(chain_id, ...)

Get a specific GMX token by address on a given chain.

get_gmx_synthetic_token_by_symbol(chain_id, ...)

Get a specific GMX token by symbol on a given chain.

get_supported_gmx_chains()

Get list of chain IDs that support GMX synthetic tokens.

reset_gmx_token_cache()

Reset the default GMX token cache.

Classes

GMXSyntheticTokenDetails

GMX Synthetic token Python representation.

Exceptions

GMXTokenFetchError

Exception raised when GMX token fetching fails.
DEFAULT_GMX_TOKEN_CACHE = LRUCache({}, maxsize=512, currsize=0)

Default cache for GMX token details

GMXTokenAddress

GMX token address type alias

class GMXSyntheticTokenDetails

Bases: object

GMX Synthetic token Python representation.

A helper class to work with GMX synthetic tokens from their API. Similar to TokenDetails but designed for GMX API data structure.

Example usage:

# Fetch all GMX tokens for Arbitrum
tokens = fetch_gmx_synthetic_tokens(chain_id=42161)
usdc_token = next(t for t in tokens if t.symbol == "USDC")
print(f"USDC address on Arbitrum: {usdc_token.address}")

Key differences from ERC-20 TokenDetails: - No web3 contract instance needed - Data comes from API, not blockchain calls - Simpler structure (no name or total_supply from API)

symbol: str

Token symbol e.g. “USDC”, “ETH”

address: eth_typing.evm.HexAddress

Token contract address

decimals: int

Number of decimals for the token

chain_id: int

Chain ID where this token exists

extra_data: dict[str, Any]

Extra metadata for caching and other purposes

property address_lower: str

Get the lowercase version of the address.

convert_to_decimals(raw_amount)

Convert raw token units to decimal representation.

Parameters

raw_amount (int) – Raw token amount as integer

Returns

Decimal representation of the amount

Return type

decimal.Decimal

Example:

If token has 6 decimals, converts 1000000 -> 1.0

convert_to_raw(decimal_amount)

Convert decimal token amount to raw integer units.

Parameters

decimal_amount (decimal.Decimal) – Decimal amount

Returns

Raw token amount as integer

Return type

int

Example:

If token has 6 decimals, converts 1.0 -> 1000000

static generate_cache_key(chain_id, symbol)

Generate cache key for GMX token.

We cache by (chain_id, symbol) since GMX API gives us symbol-based data. This is different from ERC-20 caching which uses address.

Parameters

  • chain_id (int) – Blockchain chain ID

  • symbol (str) – Token symbol

Returns

Cache key string in format “gmx-{chain_id}-{symbol_lower}”

Return type

str

export()

Export token details as serializable dictionary.

Useful for saving to disk cache or API responses.

Returns

dictionary with all token information

Return type

dict[str, Any]

__init__(symbol, address, decimals, chain_id, extra_data=<factory>)
Parameters
Return type

None

exception GMXTokenFetchError

Bases: Exception

Exception raised when GMX token fetching fails.

__init__(*args, **kwargs)
__new__(**kwargs)
add_note()

Exception.add_note(note) – add a note to the exception

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

fetch_gmx_synthetic_tokens(chain_id, cache=LRUCache({}, maxsize=512, currsize=0), timeout=10.0, force_refresh=False, max_retries=2, retry_delay=0.1)

Fetch GMX synthetic token details from API with caching and retry logic.

This function fetches all available GMX synthetic tokens for a given chain and caches the results to avoid repeated API calls. It implements retry logic with exponential backoff and automatic failover to backup API endpoints.

Parameters

  • chain_id (int) – Blockchain chain ID (42161 for Arbitrum, 43114 for Avalanche)

  • cache (Optional[cachetools.Cache]) – Cache instance to use. Set to None to disable caching

  • timeout (float) – HTTP request timeout in seconds

  • force_refresh (bool) – If True, bypass cache and fetch fresh data

  • max_retries (int) – Maximum number of retry attempts per endpoint (default: 2)

  • retry_delay (float) – Initial delay between retries in seconds with exponential backoff (default: 0.1s, resulting in 0.1s, 0.2s delays)

Returns

list of GMXSyntheticTokenDetails objects

Raises
Return type

list[eth_defi.gmx.synthetic_tokens.GMXSyntheticTokenDetails]

Example:

# Fetch Arbitrum GMX tokens with automatic retry and failover
tokens = fetch_gmx_synthetic_tokens(chain_id=42161)
get_gmx_synthetic_token_by_symbol(chain_id, symbol, cache=LRUCache({}, maxsize=512, currsize=0))

Get a specific GMX token by symbol on a given chain.

This is a convenience function that fetches all tokens and filters by symbol. More efficient than fetching tokens repeatedly when you need just one.

Parameters

  • chain_id (int) – Blockchain chain ID

  • symbol (str) – Token symbol to search for (case-insensitive)

  • cache (Optional[cachetools.Cache]) – Cache instance to use

Returns

GMXSyntheticTokenDetails if found, None otherwise

Return type

Optional[eth_defi.gmx.synthetic_tokens.GMXSyntheticTokenDetails]

Example:

# Get USDC token on Arbitrum
usdc = get_gmx_synthetic_token_by_symbol(42161, "USDC")
if usdc:
    print(f"USDC decimals: {usdc.decimals}")
get_gmx_synthetic_token_by_address(chain_id, address, cache=LRUCache({}, maxsize=512, currsize=0))

Get a specific GMX token by address on a given chain.

Parameters
Returns

GMXSyntheticTokenDetails if found, None otherwise

Return type

Optional[eth_defi.gmx.synthetic_tokens.GMXSyntheticTokenDetails]

reset_gmx_token_cache()

Reset the default GMX token cache.

Useful for testing or when you want to force fresh API calls.

get_supported_gmx_chains()

Get list of chain IDs that support GMX synthetic tokens.

Returns

list of supported chain IDs

Return type

list[int]