gmx.verification

Documentation for eth_defi.gmx.verification Python module.

GMX order execution verification.

This module provides verification utilities for GMX order executions. GMX keeper transactions can have receipt.status == 1 even when the order is cancelled or frozen at the protocol level. This module detects such failures by parsing GMX events.

Key functions:

• verify_gmx_order_execution(): Main verification function

• raise_if_order_failed(): Convenience wrapper that raises on failure

Example usage:

from eth_defi.gmx.verification import verify_gmx_order_execution, raise_if_order_failed

receipt = web3.eth.wait_for_transaction_receipt(tx_hash)

# Option 1: Check and raise if failed
result = raise_if_order_failed(web3, receipt, tx_hash)

# Option 2: Check without raising
result = verify_gmx_order_execution(web3, receipt)
if not result.success:
    print(f"Order failed: {result.decoded_error}")

Functions

raise_if_order_failed(web3, receipt, tx_hash)	Verify order execution and raise exception if failed.
verify_gmx_order_execution(web3, receipt[, ...])	Verify GMX order execution from transaction receipt.

Classes

GMXOrderVerificationResult

Result of GMX order execution verification.

class GMXOrderVerificationResult

Bases: object

Result of GMX order execution verification.

This dataclass contains the verification result and extracted execution details from GMX events.

Variables

• success – Whether the order executed successfully

• order_key – The order key (32-byte identifier)

• status – Order status: “executed”, “cancelled”, or “frozen”

• account – Account address that owns the order

• execution_price – Execution price (converted to float USD)

• size_delta_usd – Size delta in USD (converted to float)

• pnl_usd – Realised PnL in USD (converted to float)

• price_impact_usd – Price impact in USD (converted to float)

• fees – Execution fees from GMX

• reason – Error reason string (for failed orders)

• decoded_error – Decoded error message

• error_selector – 4-byte error selector hex string

• event_count – Number of GMX events in the transaction

• event_names – List of event names found

__init__(success, order_key=None, status=None, account=None, execution_price=None, size_delta_usd=None, size_delta_in_tokens=None, collateral_delta=None, pnl_usd=None, price_impact_usd=None, is_long=None, position_key=None, collateral_token=None, collateral_token_price=None, fees=None, reason=None, reason_bytes=None, decoded_error=None, error_selector=None, event_count=0, event_names=<factory>)

Parameters

• success (bool) –

• order_key (Optional[bytes]) –

• status (Optional[Literal['executed', 'cancelled', 'frozen']]) –

• account (Optional[eth_typing.evm.HexAddress]) –

• execution_price (Optional[float]) –

• size_delta_usd (Optional[float]) –

• size_delta_in_tokens (Optional[int]) –

• collateral_delta (Optional[int]) –

• pnl_usd (Optional[float]) –

• price_impact_usd (Optional[float]) –

• is_long (Optional[bool]) –

• position_key (Optional[bytes]) –

• collateral_token (Optional[eth_typing.evm.HexAddress]) –

• collateral_token_price (Optional[int]) –

• fees (Optional[eth_defi.gmx.events.OrderFees]) –

• reason (Optional[str]) –

• reason_bytes (Optional[bytes]) –

• decoded_error (Optional[str]) –

• error_selector (Optional[str]) –

• event_count (int) –

• event_names (list[str]) –

Return type

None

raise_if_order_failed(web3, receipt, tx_hash, order_key=None)

Verify order execution and raise exception if failed.

Convenience function that combines verification and exception raising. Use this in the CCXT exchange wrapper to ensure failed orders are not treated as successful.

Parameters

• web3 (web3.main.Web3) – Web3 instance

• receipt (dict) – Transaction receipt

• tx_hash (str) – Transaction hash (for error reporting)

• order_key (Optional[bytes]) – Optional order key to filter for

Returns

GMXOrderVerificationResult if order succeeded

Raises

GMXOrderFailedException – If order was cancelled or frozen

Return type

eth_defi.gmx.verification.GMXOrderVerificationResult

Example:

from eth_defi.gmx.verification import raise_if_order_failed
from eth_defi.gmx.ccxt.errors import GMXOrderFailedException

try:
    result = raise_if_order_failed(web3, receipt, tx_hash)
    # Order succeeded - use result.execution_price, result.size_delta_usd, etc.
except GMXOrderFailedException as e:
    # Order failed at GMX level despite tx success
    print(f"Order failed: {e.decoded_error}")

verify_gmx_order_execution(web3, receipt, order_key=None)

Verify GMX order execution from transaction receipt.

This function parses GMX events from the receipt to determine the true order execution status. A transaction can have receipt.status == 1 but still contain OrderCancelled or OrderFrozen events indicating failure.

Success pattern:

• Has OrderExecuted event

• Has PositionIncrease or PositionDecrease event

• Typically 20-32+ GMX events

Failure pattern:

• Has OrderCancelled or OrderFrozen event

• No OrderExecuted event

• Typically 6-10 GMX events

• Error reason in reasonBytes field

Parameters

• web3 (web3.main.Web3) – Web3 instance connected to the appropriate chain

• receipt (dict) – Transaction receipt from keeper execution

• order_key (Optional[bytes]) – Optional order key to filter for. If not provided, returns result for the first order event found.

Returns

GMXOrderVerificationResult with success flag and execution details

Return type

eth_defi.gmx.verification.GMXOrderVerificationResult

Example:

receipt = web3.eth.wait_for_transaction_receipt(tx_hash)
result = verify_gmx_order_execution(web3, receipt)

if not result.success:
    logger.error(
        "Order %s failed: %s",
        result.order_key.hex() if result.order_key else "unknown",
        result.decoded_error or result.reason,
    )