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

assert_gmx_router_whitelisted(guard, ...[, ...])

Check a Guard allows the GMX ExchangeRouter before any order is sent.

fetch_all_gmx_markets(web3)

Fetch all available GMX markets from the blockchain.

get_gmx_arbitrum_addresses()

Resolve the 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.

Exceptions

GMXRouterNotWhitelisted

The GMX ExchangeRouter we would trade through is not allowed by the Guard.
GMX_ARBITRUM_ADDRESSES: dict[str, eth_typing.evm.HexAddress] = {'exchange_router': '0x7dE39FF2e232A2203196788d37e234cF8F1b83f1', 'order_vault': '0x31eF83a530Fde1B38EE9A18093A333D8Bbbc40D5', 'synthetics_router': '0x7452c558d45f8afC8c83dAe62C3f8A5BE19c71f6'}

GMX contract addresses on Arbitrum mainnet.

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

Warning

Duplicated as literals, so this can drift when GMX rotates contracts — it previously held an ExchangeRouter older than any supported release. Prefer get_gmx_arbitrum_addresses() or GMXDeployment.create_arbitrum(), which read eth_defi.gmx.contracts.PINNED_CONTRACTS directly and therefore cannot drift.

Kept in sync with the v2.2c entry of eth_defi.gmx.contracts.PINNED_CONTRACTS; the literals exist only to avoid a circular import between this module and eth_defi.gmx.contracts. test_whitelist_constants_track_the_pinned_release enforces the match.

get_gmx_arbitrum_addresses()

Resolve the GMX contract addresses for Arbitrum mainnet.

Unlike GMX_ARBITRUM_ADDRESSES, which duplicates the addresses as literals and can drift, this reads eth_defi.gmx.contracts.PINNED_CONTRACTS through eth_defi.gmx.contracts.get_contract_addresses(), honouring the GMX_CONTRACT_RELEASE pin.

Returns

Dictionary with keys exchange_router, synthetics_router, order_vault.

Raises

ValueError – If the configured release or chain is not supported.

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: Optional[list[eth_typing.evm.HexAddress]]

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]

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]

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

exception GMXRouterNotWhitelisted

Bases: Exception

The GMX ExchangeRouter we would trade through is not allowed by the Guard.

Raised by assert_gmx_router_whitelisted(). Every order created through this router would revert on-chain with Target not allowed, so this is a fatal startup condition rather than a per-order error.

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

Add a note to the exception

with_traceback(tb, /)

Set self.__traceback__ to tb and return self.

assert_gmx_router_whitelisted(guard, exchange_router, *, order_vault=None)

Check a Guard allows the GMX ExchangeRouter before any order is sent.

GMX rotates its ExchangeRouter between releases, while a Lagoon vault Guard enforces a fixed address allowlist. When the two disagree, every order-creating transaction reverts with Target not allowed — including exits, so the bot cannot flatten risk. The failure is otherwise only discovered by spending gas on a reverting transaction, once per order.

Call this at startup so the mismatch surfaces as one clear error instead.

Example:

from eth_defi.gmx.contracts import get_contract_addresses
from eth_defi.gmx.whitelist import assert_gmx_router_whitelisted

addresses = get_contract_addresses("arbitrum")
assert_gmx_router_whitelisted(
    guard,
    addresses.exchangerouter,
    order_vault=addresses.ordervault,
)
Parameters

  • guard (web3.contract.contract.Contract) – Guard contract instance (GuardV0), usually the Safe’s TradingStrategyModuleV0.

  • exchange_router (Union[eth_typing.evm.HexAddress, str]) – GMX ExchangeRouter address that orders would be routed through.

  • order_vault (Optional[Union[eth_typing.evm.HexAddress, str]]) – If given, also assert the Guard maps this router to this OrderVault. sendWnt/sendTokens receiver validation uses that mapping, so a stale value fails at order time even when the router itself is allowed.

Raises

GMXRouterNotWhitelisted – If the router is not whitelisted, or is mapped to a different OrderVault.

Return type

None