gmx.valuation

Documentation for eth_defi.gmx.valuation Python module.

GMX account valuation.

Calculate the total equity of a GMX trading account at a specific block, combining wallet token reserves (including native ETH) with the net value of open perpetual positions.

  • Reserves are read onchain at the requested block_identifier. Stablecoin reserve tokens (checked via is_stablecoin_like()) are summed at face value. Any other reserve token – and native ETH, when include_native_eth is set – is converted to USD via the live GMX oracle mark price. This is not limited to USDC-collateralised accounts: a Safe that has accumulated WETH/WBTC (e.g. from a GMX long position paying out PnL in the market’s long token) or native ETH is priced rather than rejected.

  • Position data is read onchain at the requested block_identifier via Reader.getAccountPositionInfoList(). Its positionValueInUsd is already net of borrowing fees, funding fees, position fees and price impact – it is not a hand-rolled collateral + naive PnL figure.

  • Oracle prices use the live GMX signed-prices API and therefore reflect current market prices, not prices at the historical block. This applies equally to reserve and position pricing, and is a known limitation for historical valuation – see GMX oracle documentation.

import os
from eth_defi.provider.multi_provider import create_multi_provider_web3
from eth_defi.token import fetch_erc20_details
from eth_defi.gmx.valuation import fetch_gmx_total_equity

web3 = create_multi_provider_web3(os.environ["JSON_RPC_ARBITRUM"])
usdc = fetch_erc20_details(web3, "0xaf88d065e77c8cC2239327C5EDb3A432268e5831")

# Account 0x1640... holds USDC reserves and several GMX positions
# (mixed long/short) at block 401_729_535.
result = fetch_gmx_total_equity(
    web3=web3,
    account="0x1640e916e10610Ba39aAC5Cd8a08acF3cCae1A4c",
    reserve_tokens=[usdc],
    block_identifier=401_729_535,
)
# result.stable_reserves     = USDC only, deterministic at this block
# result.non_stable_reserves = the account's native ETH balance, priced live
#                               (include_native_eth defaults to True)
# result.reserves            = result.stable_reserves + result.non_stable_reserves
# result.positions           = net of fees, oracle-price dependent
# result.get_total() = result.reserves + result.positions

Functions

fetch_gmx_total_equity(web3, account, ...[, ...])

Calculate the total equity of a GMX trading account.

Classes

GMXEquity

Equity breakdown for a GMX trading account.
class GMXEquity

Bases: object

Equity breakdown for a GMX trading account.

See fetch_gmx_total_equity().

reserves: decimal.Decimal

Sum of all reserves in USD – stable_reserves + non_stable_reserves.

positions: decimal.Decimal

Sum of open GMX position values in USD, net of borrowing fees, funding fees, position fees and price impact.

stable_reserves: decimal.Decimal

Portion of reserves summed at face value because the token looks like a USD-pegged stablecoin. Defaults to Decimal(0) for backward-compatible direct construction (fetch_gmx_total_equity() always sets this explicitly and correctly).

non_stable_reserves: decimal.Decimal

Portion of reserves converted to USD via the GMX oracle mark price – non-stablecoin reserve tokens, plus native ETH when include_native_eth was set. Defaults to Decimal(0) for backward-compatible direct construction.

get_total()

Total equity = reserves + positions.

Return type

decimal.Decimal

__init__(reserves, positions, stable_reserves=Decimal('0'), non_stable_reserves=Decimal('0'))
Parameters
Return type

None

fetch_gmx_total_equity(web3, account, reserve_tokens, block_identifier='latest', chain='arbitrum', include_native_eth=True)

Calculate the total equity of a GMX trading account.

Returns a GMXEquity dataclass with separate reserves and positions subtotals (and a stable/non-stable breakdown of reserves for observability). Call GMXEquity.get_total() for the combined figure.

Reserve token balances are summed directly – the caller controls which tokens to include. Stablecoin reserves are summed at face value; any other reserve token, and native ETH when include_native_eth is set, is converted to USD via the live GMX oracle mark price (see the module docstring).

  • Reserve balances and position data are read onchain at the given block_identifier (requires an archive node for historical blocks).

  • Oracle prices are fetched from the live GMX signed-prices API and therefore reflect current market prices, not prices at the historical block.

Parameters

  • web3 (web3.main.Web3) – Web3 connection. Must point to an archive node when querying historical blocks.

  • account (Union[eth_typing.evm.HexAddress, str]) – Wallet address that holds the reserves and GMX positions.

  • reserve_tokens (list[eth_defi.token.TokenDetails]) – List of TokenDetails whose balanceOf(account) should be included in the reserve total. Any ERC-20 is accepted. Stablecoins (checked via is_stablecoin_like()) are summed at face value; other tokens are converted to USD via the live GMX oracle mark price, and a ValueError is raised if the oracle has no price for one – an unpriceable reserve must not silently contribute zero.

  • block_identifier (Union[Literal['latest', 'earliest', 'pending', 'safe', 'finalized'], eth_typing.evm.BlockNumber, eth_typing.evm.Hash32, eth_typing.encoding.HexStr, int]) – Block number (or "latest") at which to read onchain state.

  • chain (str) – GMX chain name. Reserve valuation works on any chain GMX supports. Position valuation additionally requires a known GMX ReferralStorage address – currently only "arbitrum" is confirmed (see _REFERRAL_STORAGE_ADDRESSES); an account with open positions on an unconfirmed chain raises ValueError.

  • include_native_eth (bool) – If True (the default), add the account’s native ETH balance to the reserve total, priced via the chain’s wrapped-native-token oracle price. Native ETH is not an ERC-20, so it cannot be passed via reserve_tokens. The balance is counted in full – callers that need to reserve part of it as a gas float must account for that themselves; this function does not guess a gas reserve.

Returns

GMXEquity with reserves and positions subtotals.

Return type

eth_defi.gmx.valuation.GMXEquity