gmx.lagoon

Documentation for eth_defi.gmx.lagoon Python module.

GMX trading integration for Lagoon vaults.

This module provides a LagoonGMXTradingWallet class that implements the BaseWallet interface, enabling the standard GMX CCXT adapter to trade through a Lagoon vault without any modifications.

Example usage:

from eth_defi.gmx.ccxt import GMX
from eth_defi.gmx.lagoon import LagoonGMXTradingWallet
from eth_defi.erc_4626.vault_protocol.lagoon import LagoonVault
from eth_defi.hotwallet import HotWallet

# Set up vault and asset manager
vault = LagoonVault(web3, vault_address)
asset_manager = HotWallet.from_private_key("0x...")

# Create vault wallet
wallet = LagoonGMXTradingWallet(vault, asset_manager)

# Use standard GMX adapter with vault wallet
gmx = GMX(params={"rpcUrl": rpc_url}, wallet=wallet)
gmx.load_markets()

# Trade through vault - standard GMX API
order = gmx.create_order(
    symbol="ETH/USD",
    type="market",
    side="buy",
    amount=0,
    params={"size_usd": 1000, "leverage": 2.0},
)
class LagoonGMXTradingWallet

Bases: eth_defi.basewallet.BaseWallet

Wallet implementation that routes transactions through a Lagoon vault.

This wallet wraps all transactions through the vault’s TradingStrategyModuleV0.performCall() method, enabling vault-based trading with protocols like GMX.

The wallet implements the full BaseWallet interface, making it a drop-in replacement for HotWallet when used with the GMX CCXT adapter.

Architecture:

GMX CCXT Adapter
└── wallet: LagoonGMXTradingWallet
    ├── vault: LagoonVault (holds assets in Safe multisig)
    ├── asset_manager: HotWallet (signs wrapped transactions)
    └── sign_transaction_with_new_nonce():
        1. Wrap tx in performCall(to, data, value)
        2. Sign with asset_manager
        3. Return SignedTransactionWithNonce

The Safe address is used as the trading account, meaning: - Positions are owned by the Safe, not the asset manager - Collateral tokens must be in the Safe - Token approvals are done from the Safe via performCall()

Example:

vault = LagoonVault(web3, vault_address)
asset_manager = HotWallet.from_private_key("0x...")

wallet = LagoonGMXTradingWallet(vault, asset_manager)

# Use with GMX
gmx = GMX(params={"rpcUrl": rpc_url}, wallet=wallet)
order = gmx.create_order("ETH/USD", "market", "buy", 0, params={"size_usd": 1000})

Initialise the Lagoon wallet.

Parameters

  • vault – Lagoon vault with TradingStrategyModuleV0 configured. The vault’s Safe address will be used as the trading account.

  • asset_manager – Hot wallet of the asset manager who will sign transactions. Must have the asset manager role on the vault.

  • gas_buffer – Additional gas to add for performCall overhead. Default is 200,000 gas.

__init__(vault, asset_manager, gas_buffer=200000)

Initialise the Lagoon wallet.

Parameters

  • vault – Lagoon vault with TradingStrategyModuleV0 configured. The vault’s Safe address will be used as the trading account.

  • asset_manager (eth_defi.hotwallet.HotWallet) – Hot wallet of the asset manager who will sign transactions. Must have the asset manager role on the vault.

  • gas_buffer (int) – Additional gas to add for performCall overhead. Default is 200,000 gas.

property address: eth_typing.evm.HexAddress

Get the wallet’s Ethereum address.

Returns the vault’s Safe address, as this is the account that owns positions and holds collateral.

get_main_address()

Get the main Ethereum address for this wallet.

Returns the vault’s Safe address.

Return type

eth_typing.evm.HexAddress

sync_nonce(web3)

Synchronise the nonce with the blockchain.

Delegates to the asset manager’s nonce, as the asset manager is the one signing and broadcasting transactions.

Parameters

web3 (web3.main.Web3) –

Return type

None

allocate_nonce()

Get the next available nonce.

Delegates to the asset manager.

Return type

int

sign_transaction_with_new_nonce(tx)

Sign a transaction with a new nonce.

This is the key method that wraps the transaction through the vault’s performCall() before signing.

Parameters

tx (dict) – Transaction dict with ‘to’, ‘data’, and optionally ‘value’ and ‘gas’.

Returns

Signed transaction ready for broadcasting.

Return type

eth_defi.hotwallet.SignedTransactionWithNonce

sign_bound_call_with_new_nonce(func, tx_params=None, web3=None, fill_gas_price=False, value=None)

Sign a contract function call with a new nonce.

Wraps the function call through performCall before signing.

Parameters

  • func (web3.contract.contract.ContractFunction) – Contract function to call.

  • tx_params (Optional[dict]) – Additional transaction parameters.

  • web3 (Optional[web3.main.Web3]) – Web3 instance (uses self.web3 if not provided).

  • fill_gas_price (bool) – Whether to fill in gas price from network.

  • value (Optional[int]) – ETH value to send with transaction.

Returns

Signed transaction ready for broadcasting.

Return type

eth_defi.hotwallet.SignedTransactionWithNonce

get_native_currency_balance(web3)

Get the wallet’s native currency balance.

Returns the Safe’s ETH balance, as this is where trading funds are held.

Parameters

web3 (web3.main.Web3) –

Return type

decimal.Decimal

static fill_in_gas_price(web3, tx)

Fill in gas price details for a transaction.

Delegates to HotWallet’s implementation.

Parameters

  • web3 (web3.main.Web3) –

  • tx (dict) –

Return type

dict

approve_gmx_collateral_via_vault(vault, asset_manager, collateral_token, amount, broadcast_callback=None)

Approve GMX SyntheticsRouter to spend collateral from the vault’s Safe.

This wraps a token approval through the vault’s TradingStrategyModuleV0, allowing the Safe to approve the GMX SyntheticsRouter to spend tokens.

Parameters
Returns

Transaction hash

Return type

hexbytes.main.HexBytes

Example:

from eth_defi.gmx.lagoon.approvals import approve_gmx_collateral_via_vault

tx_hash = approve_gmx_collateral_via_vault(
    vault=vault,
    asset_manager=asset_manager,
    collateral_token=usdc,
    amount=Decimal("10000"),
)
approve_gmx_execution_fee_via_vault(vault, asset_manager, weth_token, amount, broadcast_callback=None)

Approve GMX ExchangeRouter to spend WETH for execution fees from the vault’s Safe.

GMX orders require execution fees paid in ETH/WETH. This approves the ExchangeRouter to spend WETH from the Safe for these fees.

Parameters
Returns

Transaction hash

Return type

hexbytes.main.HexBytes

Modules

eth_defi.gmx.lagoon.approvals

Token approval functions for GMX trading through Lagoon vaults.

eth_defi.gmx.lagoon.wallet

Lagoon vault wallet for GMX trading.