gmx.events

Documentation for eth_defi.gmx.events Python module.

GMX event log decoding and parsing.

This module provides utilities for decoding GMX protocol events from transaction receipts. GMX emits all events through a centralised EventEmitter contract using EventLog, EventLog1, and EventLog2 event types.

Key features:

• Decode complex EventLogData structure from transaction logs

• Extract order execution results (success/failure/frozen)

• Parse position increase/decrease events with execution prices, PnL, and fees

• Decode error reasons from failed orders

Example usage:

from web3 import Web3
from eth_defi.gmx.events import (
    decode_gmx_events,
    extract_order_execution_result,
)

# Get transaction receipt
receipt = web3.eth.get_transaction_receipt(tx_hash)

# Decode all GMX events from receipt
events = list(decode_gmx_events(web3, receipt))

# Extract order execution result
result = extract_order_execution_result(web3, receipt)
if result:
    print(f"Order status: {result.status}")
    print(f"Execution price: {result.execution_price}")

For more information on GMX events, see: https://docs.gmx.io/docs/api/contracts#event-monitoring

Functions

decode_error_reason(reason_bytes)	Decode GMX error reason from reasonBytes.
decode_gmx_event(web3, log[, ...])	Decode a single GMX EventLog from a transaction log entry.
decode_gmx_events(web3, receipt)	Decode all GMX events from a transaction receipt.
extract_order_execution_result(web3, receipt)	Extract order execution result from a keeper transaction receipt.
extract_order_key_from_receipt(web3, receipt)	Extract order key from OrderCreated or OrderExecuted event in receipt.
find_events_by_name(web3, receipt, event_name)	Find all events with a specific name from a transaction receipt.
get_event_name_hash(event_name)	Compute the keccak256 hash of an event name.

Classes

GMXEventData	Parsed GMX event data from EventLogData structure.
OrderExecutionResult	Result of GMX order execution.
OrderFees	Fees from GMX order execution.

class GMXEventData

Bases: object

Parsed GMX event data from EventLogData structure.

GMX events contain structured data in the following categories:

• Address items: Contract addresses (account, market, tokens)

• Uint items: Unsigned integers (sizes, prices, fees)

• Int items: Signed integers (PnL, price impact)

• Bool items: Boolean flags (isLong, etc.)

• Bytes32 items: Order/position keys

• Bytes items: Raw byte data (error reasons)

• String items: String data (reasons)

Each category has both single items and array items.

__init__(event_name, msg_sender=None, topic1=None, topic2=None, address_items=<factory>, address_array_items=<factory>, uint_items=<factory>, uint_array_items=<factory>, int_items=<factory>, int_array_items=<factory>, bool_items=<factory>, bool_array_items=<factory>, bytes32_items=<factory>, bytes32_array_items=<factory>, bytes_items=<factory>, bytes_array_items=<factory>, string_items=<factory>, string_array_items=<factory>)

Parameters

• event_name (str) –

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

• topic1 (Optional[bytes]) –

• topic2 (Optional[bytes]) –

• address_items (dict[str, eth_typing.evm.HexAddress]) –

• address_array_items (dict[str, list[eth_typing.evm.HexAddress]]) –

• uint_items (dict[str, int]) –

• uint_array_items (dict[str, list[int]]) –

• int_items (dict[str, int]) –

• int_array_items (dict[str, list[int]]) –

• bool_items (dict[str, bool]) –

• bool_array_items (dict[str, list[bool]]) –

• bytes32_items (dict[str, bytes]) –

• bytes32_array_items (dict[str, list[bytes]]) –

• bytes_items (dict[str, bytes]) –

• bytes_array_items (dict[str, list[bytes]]) –

• string_items (dict[str, str]) –

• string_array_items (dict[str, list[str]]) –

Return type

None

get_address(key, default=None)

Get an address item by key.

Parameters

• key (str) –

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

Return type

Optional[eth_typing.evm.HexAddress]

get_bool(key, default=None)

Get a bool item by key.

Parameters

• key (str) –

• default (Optional[bool]) –

Return type

Optional[bool]

get_bytes(key, default=None)

Get a bytes item by key.

Parameters

• key (str) –

• default (Optional[bytes]) –

Return type

Optional[bytes]

get_bytes32(key, default=None)

Get a bytes32 item by key.

Parameters

• key (str) –

• default (Optional[bytes]) –

Return type

Optional[bytes]

get_int(key, default=None)

Get an int item by key.

Parameters

• key (str) –

• default (Optional[int]) –

Return type

Optional[int]

get_string(key, default=None)

Get a string item by key.

Parameters

• key (str) –

• default (Optional[str]) –

Return type

Optional[str]

get_uint(key, default=None)

Get a uint item by key.

Parameters

• key (str) –

• default (Optional[int]) –

Return type

Optional[int]

class OrderExecutionResult

Bases: object

Result of GMX order execution.

This dataclass aggregates information from order execution events (OrderExecuted, OrderFrozen, OrderCancelled) and position events (PositionIncrease, PositionDecrease).

__init__(order_key, status, account=None, execution_price=None, size_delta_usd=None, size_delta_in_tokens=None, collateral_delta=None, pnl_usd=None, price_impact_usd=None, fees=None, reason=None, reason_bytes=None, decoded_error=None, position_key=None, is_long=None, collateral_token=None, collateral_token_price=None)

Parameters

• order_key (bytes) –

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

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

• execution_price (Optional[int]) –

• size_delta_usd (Optional[int]) –

• size_delta_in_tokens (Optional[int]) –

• collateral_delta (Optional[int]) –

• pnl_usd (Optional[int]) –

• price_impact_usd (Optional[int]) –

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

• reason (Optional[str]) –

• reason_bytes (Optional[bytes]) –

• decoded_error (Optional[str]) –

• position_key (Optional[bytes]) –

• is_long (Optional[bool]) –

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

• collateral_token_price (Optional[int]) –

Return type

None

class OrderFees

Bases: object

Fees from GMX order execution.

All fee values are in token amounts (not USD).

__init__(position_fee=0, borrowing_fee=0, funding_fee=0, liquidation_fee=0)

Parameters

• position_fee (int) –

• borrowing_fee (int) –

• funding_fee (int) –

• liquidation_fee (int) –

Return type

None

decode_error_reason(reason_bytes)

Decode GMX error reason from reasonBytes.

GMX uses custom error selectors. This function attempts to decode common error types and their parameters.

Parameters

reason_bytes (bytes) – The raw reasonBytes from OrderFrozen/OrderCancelled events

Returns

Decoded error message with parameters, or None if cannot decode

Return type

Optional[str]

decode_gmx_event(web3, log, event_emitter_contract=None)

Decode a single GMX EventLog from a transaction log entry.

This function handles EventLog, EventLog1, and EventLog2 events emitted by the GMX EventEmitter contract.

Parameters

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

• log (dict) – A single log entry from transaction receipt

• event_emitter_contract (Optional[web3.contract.contract.Contract]) – Optional pre-built EventEmitter contract instance. When decoding many logs in a loop, passing a cached contract avoids repeated lookups.

Returns

Parsed GMXEventData or None if not a GMX event

Return type

Optional[eth_defi.gmx.events.GMXEventData]

decode_gmx_events(web3, receipt)

Decode all GMX events from a transaction receipt.

Parameters

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

• receipt (dict) – Transaction receipt dictionary

Yields

Parsed GMXEventData for each GMX event found

Return type

Iterator[eth_defi.gmx.events.GMXEventData]

extract_order_execution_result(web3, receipt, order_key=None)

Extract order execution result from a keeper transaction receipt.

This function looks for OrderExecuted, OrderFrozen, or OrderCancelled events and extracts the relevant execution data. For successful orders, it also extracts PositionIncrease/PositionDecrease data.

Parameters

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

• receipt (dict) – Transaction receipt from keeper execution

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

Returns

OrderExecutionResult or None if no order events found

Return type

Optional[eth_defi.gmx.events.OrderExecutionResult]

extract_order_key_from_receipt(web3, receipt)

Extract order key from OrderCreated or OrderExecuted event in receipt.

This function handles both GMX order execution models:

• Two-phase orders (limit orders): Look for OrderCreated event, order is pending until keeper executes it in a separate transaction.

• Single-phase orders (market orders): Look for OrderExecuted event, order is created and executed atomically in the same transaction.

Parameters

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

• receipt (dict) – Transaction receipt from order creation/execution

Returns

The 32-byte order key

Raises

ValueError – If no OrderCreated or OrderExecuted event found in receipt

Return type

bytes

find_events_by_name(web3, receipt, event_name)

Find all events with a specific name from a transaction receipt.

Parameters

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

• receipt (dict) – Transaction receipt dictionary

• event_name (str) – The event name to filter for (e.g., “OrderExecuted”)

Yields

Matching GMXEventData events

Return type

Iterator[eth_defi.gmx.events.GMXEventData]

get_event_name_hash(event_name)

Compute the keccak256 hash of an event name.

GMX uses the hash of event name strings as topic[1] in EventLog events for efficient filtering.

Parameters

event_name (str) – The event name (e.g., “OrderCreated”, “OrderExecuted”)

Returns

The keccak256 hash as hex string without 0x prefix

Return type

str