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:

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

success: bool

Whether the order executed successfully

order_key: bytes | None

The order key (32-byte identifier)

status: Optional[Literal['executed', 'cancelled', 'frozen']]

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

account: Optional[eth_typing.evm.HexAddress]

Account address that owns the order

execution_price: float | None

Execution price (converted to float USD)

size_delta_usd: float | None

Size delta in USD (converted to float)

size_delta_in_tokens: int | None

Size delta in tokens (raw value)

collateral_delta: int | None

Collateral delta amount (can be negative)

pnl_usd: float | None

Realised PnL in USD (converted to float)

price_impact_usd: float | None

Price impact in USD (converted to float)

is_long: bool | None

Whether the position is long

position_key: bytes | None

Position key (if position was modified)

fees: eth_defi.gmx.events.OrderFees | None

Execution fees

reason: str | None

Error reason string (for failed orders)

reason_bytes: bytes | None

Raw error reason bytes

decoded_error: str | None

Decoded error message

error_selector: str | None

Error selector (4-byte hex string)

event_count: int

Number of GMX events in the transaction

event_names: list[str]

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, fees=None, reason=None, reason_bytes=None, decoded_error=None, error_selector=None, event_count=0, event_names=<factory>)
Parameters
Return type

None

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 (bytes | None) – 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,
    )
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 (bytes | None) – 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}")