wait_for_evm_escrow_clear

Documentation for eth_defi.hyperliquid.evm_escrow.wait_for_evm_escrow_clear function.

wait_for_evm_escrow_clear(session, user, timeout=60.0, poll_interval=2.0, expected_usdc=None)

Wait until the user’s EVM escrow is empty (all bridged funds have cleared).

Waits one poll_interval before the first check to give HyperCore time to register the escrow entry (the API can lag behind the EVM tx). Then polls spotClearinghouseState until evmEscrows is empty, indicating that all CoreDepositWallet.deposit() actions have been processed and funds are available in the user’s spot account.

P15: When expected_usdc is provided, also verifies that the user’s HyperCore spot USDC balance increased by at least the expected amount. This provides a dual check: escrow empty and USDC arrived in spot. Without this, a race condition where the escrow entry disappears but USDC is lost (e.g. burned by a failed bridge action) would go undetected.

Example:

from eth_defi.hyperliquid.evm_escrow import wait_for_evm_escrow_clear
from eth_defi.hyperliquid.session import create_hyperliquid_session

session = create_hyperliquid_session()
wait_for_evm_escrow_clear(session, user="0xAbc...", expected_usdc=Decimal("100"))
# Now safe to proceed with CoreWriter actions that need spot balance
Parameters

  • session (HyperliquidSession) – Session from create_hyperliquid_session().

  • user (str) – On-chain address whose escrow to monitor (the Safe address for Lagoon vaults).

  • timeout (float) – Maximum seconds to wait before raising TimeoutError. Defaults to 60 seconds which is conservative for typical 2-10 s latency.

  • poll_interval (float) – Seconds between API polls. Defaults to 2 seconds.

  • expected_usdc (Decimal | None) – Optional expected USDC increase in the spot balance (human units, e.g. Decimal("50") for 50 USDC). When provided, the function captures the pre-existing USDC spot balance and verifies that the balance increased by at least this amount after escrows clear.

Raises

TimeoutError – If the escrow does not clear within the timeout period.

Return type

None