gmx.contracts

Documentation for eth_defi.gmx.contracts Python module.

GMX Protocol Contract Infrastructure

This module provides contract addresses, ABIs, and utility functions for interacting with GMX protocol contracts across supported networks.

Functions

`get_contract_addresses`(chain)	Get GMX contract addresses for a specific network.
`get_datastore_contract`(web3, chain)	Get DataStore contract instance for a specific network.
`get_exchange_router_contract`(web3, chain)	Get ExchangeRouter contract instance for a specific network.
`get_glv_reader_contract`(web3, chain)	Get GLV Reader contract instance for a specific network.
`get_oracle_contract`(web3, chain)	Get Oracle contract instance for a specific network.
`get_reader_contract`(web3, chain)	Get SyntheticsReader contract instance for a specific network.
`get_token_address`(chain, symbol[, web3])	Get address for a specific token on a network.
`get_token_address_normalized`(chain, symbol)	Get address for a specific token on a network, with proper normalization for GMX.
`get_token_balance_contract`(web3, ...)
`get_token_metadata`(chain, address)	Get metadata for a specific token on a network.
`get_tokens_address_dict`(chain)	Get token address mapping for a specific network from GMX API.
`get_tokens_metadata_dict`(chain)	Get full token metadata for a specific network from GMX API.
`normalize_gmx_token_symbol`(chain, token_symbol)	Normalize token symbol to the canonical form used by GMX API for a given chain.

Classes

ContractAddresses

GMX contract addresses for a specific network.

class ContractAddresses

Bases: object

GMX contract addresses for a specific network.

datastore: eth_typing.evm.HexAddress: DataStore contract address for on-chain data storage

eventemitter: eth_typing.evm.HexAddress: EventEmitter contract address for protocol event logging

exchangerouter: eth_typing.evm.HexAddress: ExchangeRouter contract address for trading operations

depositvault: eth_typing.evm.HexAddress: DepositVault contract address for deposit operations

withdrawalvault: eth_typing.evm.HexAddress: WithdrawalVault contract address for withdrawal operations

ordervault: eth_typing.evm.HexAddress: OrderVault contract address for order management

syntheticsreader: eth_typing.evm.HexAddress: SyntheticsReader contract address for efficient data queries

syntheticsrouter: eth_typing.evm.HexAddress: SyntheticsRouter contract address for synthetic asset routing

glvreader: eth_typing.evm.HexAddress: GLVReader contract address for GLV token queries

chainlinkpricefeedprovider: Optional[eth_typing.evm.HexAddress]: ChainlinkPriceFeedProvider contract address (optional)

chainlinkdatastreamprovider: Optional[eth_typing.evm.HexAddress]: ChainlinkDataStreamProvider contract address (optional)

gmoracleprovider: Optional[eth_typing.evm.HexAddress]: GMOracleProvider contract address (optional)

orderhandler: Optional[eth_typing.evm.HexAddress]: OrderHandler contract address (optional)

oracle: Optional[eth_typing.evm.HexAddress]: Oracle contract address (optional)

__init__(datastore, eventemitter, exchangerouter, depositvault, withdrawalvault, ordervault, syntheticsreader, syntheticsrouter, glvreader, chainlinkpricefeedprovider=None, chainlinkdatastreamprovider=None, gmoracleprovider=None, orderhandler=None, oracle=None)

Parameters

datastore (eth_typing.evm.HexAddress) –
eventemitter (eth_typing.evm.HexAddress) –
exchangerouter (eth_typing.evm.HexAddress) –
depositvault (eth_typing.evm.HexAddress) –
withdrawalvault (eth_typing.evm.HexAddress) –
ordervault (eth_typing.evm.HexAddress) –
syntheticsreader (eth_typing.evm.HexAddress) –
syntheticsrouter (eth_typing.evm.HexAddress) –
glvreader (eth_typing.evm.HexAddress) –
chainlinkpricefeedprovider (Optional[eth_typing.evm.HexAddress]) –
chainlinkdatastreamprovider (Optional[eth_typing.evm.HexAddress]) –
gmoracleprovider (Optional[eth_typing.evm.HexAddress]) –
orderhandler (Optional[eth_typing.evm.HexAddress]) –
oracle (Optional[eth_typing.evm.HexAddress]) –

Return type

None

get_contract_addresses(chain)

Get GMX contract addresses for a specific network.

Parameters: chain (str) – Network name (“arbitrum”, “avalanche”, or “arbitrum_sepolia”)
Returns: Contract addresses for the network
Raises: ValueError – If chain is not supported
Return type: eth_defi.gmx.contracts.ContractAddresses

get_reader_contract(web3, chain)

Get SyntheticsReader contract instance for a specific network.

Parameters

web3 (web3.main.Web3) – Web3 connection instance
chain (str) – Network name

Returns

Web3 contract instance for SyntheticsReader

Return type

web3.contract.contract.Contract

get_datastore_contract(web3, chain)

Get DataStore contract instance for a specific network.

Parameters

web3 (web3.main.Web3) – Web3 connection instance
chain (str) – Network name

Returns

Web3 contract instance for DataStore

Return type

web3.contract.contract.Contract

get_tokens_metadata_dict(chain)

Get full token metadata for a specific network from GMX API.

Returns address -> {symbol, decimals, synthetic} mapping. This avoids expensive contract calls for each token.

Parameters: chain (str) – Network name
Returns: Dictionary mapping token addresses to metadata
Raises: ValueError – If chain is not supported or API request fails
Return type: dict[str, dict]

get_tokens_address_dict(chain)

Get token address mapping for a specific network from GMX API.

Returns symbol -> address mapping for backward compatibility.

Parameters: chain (str) – Network name
Returns: Dictionary mapping token symbols to addresses
Raises: ValueError – If chain is not supported or API request fails
Return type: dict[str, str]

get_token_address(chain, symbol, web3=None)

Get address for a specific token on a network.

Parameters

chain (str) – Network name
symbol (str) – Token symbol
web3 (Optional[web3.main.Web3]) – Web3 connection instance (optional, not required for API calls)

Returns

Token address or None if not found

Return type

Optional[str]

get_exchange_router_contract(web3, chain)

Get ExchangeRouter contract instance for a specific network.

Parameters

web3 (web3.main.Web3) – Web3 connection instance
chain (str) – Network name

Returns

Web3 contract instance for ExchangeRouter

Return type

web3.contract.contract.Contract

get_oracle_contract(web3, chain)

Get Oracle contract instance for a specific network.

Parameters

web3 (web3.main.Web3) – Web3 connection instance
chain (str) – Network name

Returns

Web3 contract instance for Oracle, or None if not available for the chain

Return type

Optional[web3.contract.contract.Contract]

get_glv_reader_contract(web3, chain)

Get GLV Reader contract instance for a specific network.

Parameters

web3 (web3.main.Web3) – Web3 connection instance
chain (str) – Network name

Returns

Web3 contract instance for GLV Reader

Return type

web3.contract.contract.Contract

get_token_metadata(chain, address)

Get metadata for a specific token on a network.

Parameters

chain (str) – Network name
address (str) – Token address

Returns

Token metadata dictionary or None if not found

Return type

Optional[dict]

normalize_gmx_token_symbol(chain, token_symbol)

Normalize token symbol to the canonical form used by GMX API for a given chain.

On GMX, ETH and WETH are treated as the same token, as are AVAX and WAVAX. This function returns the canonical symbol that GMX API uses.

Parameters

chain (str) – Network name
token_symbol (str) – Original token symbol (e.g., “ETH”, “WETH”)

Returns

Canonical token symbol (e.g., always “ETH” for ETH/WETH on Arbitrum)

Return type

str

get_token_address_normalized(chain, symbol, web3=None)

Get address for a specific token on a network, with proper normalization for GMX.

This function handles the special case where ETH and WETH are treated as the same token on GMX protocol, as well as AVAX and WAVAX on Avalanche.

Parameters

chain (str) – Network name
symbol (str) – Token symbol (ETH/WETH will be normalized)
web3 (Optional[web3.main.Web3]) – Web3 connection instance (optional, not required for API calls)

Returns

Token address or None if not found

Return type

Optional[str]