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

eth_defi.gmx.core.markets - Low-level market data fetching
eth_defi.erc_4626.vault_protocol.lagoon.deployment.deploy_automated_lagoon_vault() - Vault deployment with GMX support
eth_defi.gmx.lagoon.wallet - GMX trading through Lagoon wallet

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.
`resolve_gmx_market_labels`(web3)	Build address-to-label mapping for GMX markets by querying on-chain data.
`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.

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
    ],
)

__init__(exchange_router, synthetics_router, order_vault, markets=<factory>, tokens=None)

Parameters

exchange_router (eth_typing.evm.HexAddress) –
synthetics_router (eth_typing.evm.HexAddress) –
order_vault (eth_typing.evm.HexAddress) –
markets (list[eth_typing.evm.HexAddress]) –
tokens (Optional[list[eth_typing.evm.HexAddress]]) –

Return type

None

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

markets (Optional[list[eth_typing.evm.HexAddress]]) – List of market addresses to whitelist. If None, no markets are whitelisted.
tokens (Optional[list[eth_typing.evm.HexAddress]]) – List of token addresses to whitelist as collateral.

Returns

GMXDeployment configured for Arbitrum mainnet.

Raises

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

Return type

eth_defi.gmx.whitelist.GMXDeployment

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_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]

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]

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]

resolve_gmx_market_labels(web3)

Build address-to-label mapping for GMX markets by querying on-chain data.

Fetches all available GMX markets and builds a dictionary mapping each market address to a human-readable label like "GMX ETH/USD".

This is useful for display purposes, e.g. passing the result as known_labels to format_guard_config_report().

Example:

from eth_defi.gmx.whitelist import resolve_gmx_market_labels

labels = resolve_gmx_market_labels(web3)
# {"0x70d95587d40A2caf56bd97485aB3Eec10Bee6336": "GMX ETH/USD", ...}

Parameters: web3 (web3.main.Web3) – Web3 instance connected to Arbitrum or another GMX-supported chain.
Returns: Dictionary mapping checksummed market addresses to labels.
Return type: dict[eth_typing.evm.HexAddress, str]

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:

Whitelist GMX router contracts (ExchangeRouter, SyntheticsRouter, OrderVault)
Whitelist the Safe as a receiver
Whitelist all specified markets
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

guard (web3.contract.contract.Contract) – Guard contract instance (GuardV0).
gmx_deployment (eth_defi.gmx.whitelist.GMXDeployment) – GMX deployment configuration with router and market addresses.
owner (eth_typing.evm.HexAddress) – Address of the Guard owner (must have permission to whitelist).
safe_address (eth_typing.evm.HexAddress) – Safe address to whitelist as receiver.

Returns

Dictionary with transaction hashes grouped by operation type.

Return type

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

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]