gmx.whitelist

Documentation for eth_defi.gmx.whitelist Python module.

GMX market whitelisting for Lagoon vaults.

This module provides utilities for fetching and whitelisting GMX markets in Lagoon vault Guard contracts. It enables programmatic management of which GMX perpetual markets are allowed for trading through a Lagoon vault.

Getting a list of GMX markets

To fetch all available GMX markets on a chain:

from web3 import Web3
from eth_defi.gmx.whitelist import fetch_all_gmx_markets

web3 = Web3(Web3.HTTPProvider("https://arb1.arbitrum.io/rpc"))
markets = fetch_all_gmx_markets(web3)

for address, info in markets.items():
    print(f"{info.market_symbol}: {address}")

Using the CLI script:

export JSON_RPC_ARBITRUM="https://..."
python scripts/gmx/list-gmx-markets.py

# For Python-pasteable output
python scripts/gmx/list-gmx-markets.py --python

Whitelisting markets in Guard contract

Markets must be whitelisted individually by the vault owner (Safe). After vault deployment, impersonate or execute through the Safe to whitelist:

# Direct call (only works if caller is Guard owner)
guard.functions.whitelistGMXMarket(
    "0x70d95587d40A2caf56bd97485aB3Eec10Bee6336",  # ETH/USD market
    "ETH/USD perpetuals",
).transact({"from": safe_address})

Or use the helper function for batch whitelisting:

from eth_defi.gmx.whitelist import whitelist_gmx_markets

tx_hashes = whitelist_gmx_markets(
    guard=guard_contract,
    markets=[ETH_USD_MARKET, BTC_USD_MARKET],
    owner=safe_address,
)

GMX deployment configuration

When deploying a new Lagoon vault with GMX support, use the GMXDeployment dataclass to configure all GMX-related whitelisting:

from eth_defi.gmx.whitelist import GMXDeployment

# create_arbitrum() dynamically fetches the latest GMX contract addresses
gmx_deployment = GMXDeployment.create_arbitrum(
    markets=[
        "0x70d95587d40A2caf56bd97485aB3Eec10Bee6336",  # ETH/USD
        "0x47c031236e19d024b42f8AE6780E44A573170703",  # BTC/USD
    ],
)

# Pass to deployment function
deployment = deploy_automated_lagoon_vault(
    ...
    gmx_deployment=gmx_deployment,
)

Security considerations

  • Never use anyAsset=True in production: This bypasses all market checks

  • Whitelist specific markets only: Restrict trading to known, liquid markets

  • Review markets before whitelisting: Verify the market address on Arbiscan

  • Markets can be removed: Use removeGMXMarket() to revoke access

  • Receiver must be whitelisted: The Safe must be whitelisted as a receiver before GMX trading will work

See also

Module Attributes

GMX_ARBITRUM_ADDRESSES

GMX contract addresses on Arbitrum mainnet.

GMX_POPULAR_MARKETS

Popular GMX markets on Arbitrum with human-readable names

Functions

fetch_all_gmx_markets(web3)

Fetch all available GMX markets from the blockchain.

get_gmx_arbitrum_addresses()

Fetch current GMX contract addresses for Arbitrum mainnet.

get_gmx_market_addresses(web3)

Get iterator of all GMX market addresses for a chain.

remove_gmx_markets(guard, markets, owner[, ...])

Remove GMX markets from Guard whitelist.

setup_gmx_whitelisting(guard, ...)

Set up complete GMX whitelisting on a Guard contract.

whitelist_gmx_markets(guard, markets, owner)

Whitelist multiple GMX markets in a Guard contract.

Classes

GMXDeployment

GMX deployment configuration for Guard whitelisting.
GMX_ARBITRUM_ADDRESSES: dict[str, eth_typing.evm.HexAddress] = {'exchange_router': '0x7C68C7866A64FA2160F78EEaE12217FFbf871fa8', 'order_vault': '0x31eF83a530Fde1B38EE9A18093A333D8Bbbc40D5', 'synthetics_router': '0x7452c558d45f8afC8c83dAe62C3f8A5BE19c71f6'}

GMX contract addresses on Arbitrum mainnet.

Warning

These addresses may become stale when GMX upgrades contracts. Prefer using get_gmx_arbitrum_addresses() or GMXDeployment.create_arbitrum() which fetch addresses dynamically from the GMX contracts registry.

These are the official GMX V2 contract addresses required for whitelisting GMX trading in a Guard contract.

get_gmx_arbitrum_addresses()

Fetch current GMX contract addresses for Arbitrum mainnet.

Unlike GMX_ARBITRUM_ADDRESSES which may become stale, this function dynamically fetches the latest addresses from the GMX contracts registry on GitHub.

Returns

Dictionary with keys exchange_router, synthetics_router, order_vault.

Raises

ValueError – If addresses cannot be fetched from the GMX API.

Return type

dict[str, eth_typing.evm.HexAddress]

Popular GMX markets on Arbitrum with human-readable names

Use these addresses when whitelisting specific markets. For a full list, use fetch_all_gmx_markets().

class GMXDeployment

Bases: object

GMX deployment configuration for Guard whitelisting.

This dataclass encapsulates all GMX-related configuration needed when deploying a Lagoon vault with GMX perpetuals trading support. Pass an instance to deploy_automated_lagoon_vault() to automatically whitelist GMX contracts and markets during deployment.

Example:

# Recommended: use factory method with dynamic address fetch
gmx_deployment = GMXDeployment.create_arbitrum(
    markets=[
        "0x70d95587d40A2caf56bd97485aB3Eec10Bee6336",  # ETH/USD
        "0x47c031236e19d024b42f8AE6780E44A573170703",  # BTC/USD
    ],
)
exchange_router: eth_typing.evm.HexAddress

GMX ExchangeRouter contract address

synthetics_router: eth_typing.evm.HexAddress

GMX SyntheticsRouter contract address

order_vault: eth_typing.evm.HexAddress

GMX OrderVault contract address

markets: list[eth_typing.evm.HexAddress]

List of GMX market addresses to whitelist for trading

tokens: list[eth_typing.evm.HexAddress] | None

Optional: specific tokens to whitelist as collateral If None, tokens are not explicitly whitelisted (use anyAsset or manual whitelisting)

classmethod create_arbitrum(markets=None, tokens=None)

Create a GMXDeployment for Arbitrum mainnet with dynamically fetched addresses.

Fetches the latest GMX contract addresses from the GMX contracts registry on GitHub, ensuring addresses are always up-to-date even after GMX upgrades.

Parameters
Returns

GMXDeployment configured for Arbitrum mainnet.

Raises

ValueError – If addresses cannot be fetched from the GMX API.

Return type

eth_defi.gmx.whitelist.GMXDeployment

__init__(exchange_router, synthetics_router, order_vault, markets=<factory>, tokens=None)
Parameters
Return type

None

fetch_all_gmx_markets(web3)

Fetch all available GMX markets from the blockchain.

This function queries the GMX Reader contract to get a complete list of all available perpetual markets with their metadata.

Example:

from web3 import Web3
from eth_defi.gmx.whitelist import fetch_all_gmx_markets

web3 = Web3(Web3.HTTPProvider("https://arb1.arbitrum.io/rpc"))
markets = fetch_all_gmx_markets(web3)

for address, info in markets.items():
    print(f"{info.market_symbol}: {address}")
Parameters

web3 (web3.main.Web3) – Web3 instance connected to Arbitrum or another GMX-supported chain.

Returns

Dictionary mapping market addresses to MarketInfo objects.

Return type

dict[eth_typing.evm.HexAddress, eth_defi.gmx.core.markets.MarketInfo]

get_gmx_market_addresses(web3)

Get iterator of all GMX market addresses for a chain.

Convenience function for scripting and batch operations.

Example:

from web3 import Web3
from eth_defi.gmx.whitelist import get_gmx_market_addresses

web3 = Web3(Web3.HTTPProvider("https://arb1.arbitrum.io/rpc"))

for market_address in get_gmx_market_addresses(web3):
    print(market_address)
Parameters

web3 (web3.main.Web3) – Web3 instance connected to Arbitrum or another GMX-supported chain.

Returns

Iterator of market addresses.

Return type

Iterator[eth_typing.evm.HexAddress]

whitelist_gmx_markets(guard, markets, owner, notes_prefix='GMX market')

Whitelist multiple GMX markets in a Guard contract.

This function whitelists each market individually by calling whitelistGMXMarket() on the Guard contract. The caller must be the Guard owner (typically the Safe).

Example:

from eth_defi.gmx.whitelist import whitelist_gmx_markets

tx_hashes = whitelist_gmx_markets(
    guard=guard_contract,
    markets=[
        "0x70d95587d40A2caf56bd97485aB3Eec10Bee6336",  # ETH/USD
        "0x47c031236e19d024b42f8AE6780E44A573170703",  # BTC/USD
    ],
    owner=safe_address,
)
Parameters

  • guard (web3.contract.contract.Contract) – Guard contract instance (GuardV0).

  • markets (list[eth_typing.evm.HexAddress]) – List of GMX market addresses to whitelist.

  • owner (eth_typing.evm.HexAddress) – Address of the Guard owner (must have permission to whitelist).

  • notes_prefix (str) – Prefix for the notes string in each whitelist call.

Returns

List of transaction hashes for each whitelist operation.

Return type

list[hexbytes.main.HexBytes]

remove_gmx_markets(guard, markets, owner, notes_prefix='Remove GMX market')

Remove GMX markets from Guard whitelist.

This function removes each market individually by calling removeGMXMarket() on the Guard contract.

Parameters

  • guard (web3.contract.contract.Contract) – Guard contract instance (GuardV0).

  • markets (list[eth_typing.evm.HexAddress]) – List of GMX market addresses to remove.

  • owner (eth_typing.evm.HexAddress) – Address of the Guard owner (must have permission).

  • notes_prefix (str) – Prefix for the notes string in each remove call.

Returns

List of transaction hashes for each remove operation.

Return type

list[hexbytes.main.HexBytes]

setup_gmx_whitelisting(guard, gmx_deployment, owner, safe_address)

Set up complete GMX whitelisting on a Guard contract.

This function performs all necessary whitelisting for GMX trading:

  1. Whitelist GMX router contracts (ExchangeRouter, SyntheticsRouter, OrderVault)

  2. Whitelist the Safe as a receiver

  3. Whitelist all specified markets

  4. Optionally whitelist collateral tokens

Example:

from eth_defi.gmx.whitelist import GMXDeployment, setup_gmx_whitelisting

gmx = GMXDeployment.create_arbitrum(
    markets=["0x70d95587d40A2caf56bd97485aB3Eec10Bee6336"],
)

tx_hashes = setup_gmx_whitelisting(
    guard=guard_contract,
    gmx_deployment=gmx,
    owner=safe_address,
    safe_address=safe_address,
)
Parameters
Returns

Dictionary with transaction hashes grouped by operation type.

Return type

dict[str, list[hexbytes.main.HexBytes]]