wait_for_vault_deposit_confirmation

Documentation for eth_defi.hyperliquid.api.wait_for_vault_deposit_confirmation function.

wait_for_vault_deposit_confirmation(session, user, vault_address, expected_deposit, existing_equity=None, timeout=60.0, poll_interval=2.0, tolerance=Decimal('0.01'), relative_tolerance=Decimal('0.05'), first_deposit_relative_tolerance=Decimal('0.01'))

Observe vault equity until its deposit threshold is reached or time runs out.

After a CoreWriter vaultTransfer action succeeds on HyperEVM, HyperCore may take several seconds to process the deposit. This function polls userVaultEquities until the expected equity appears or increases.

The deadline includes network reads and poll sleeps. Strict callers still receive HypercoreDepositVerificationError if the threshold is not reached. A live executor may deliberately treat that exception as a warning: an existing holding’s trading PnL can conceal a small successful top-up, so equity growth cannot establish the amount actually deposited. Market gains can also reach the threshold without a successful deposit. The historical function name is retained for existing callers.

Handles two cases:

• New position: existing_equity is None. Requires equity near the expected amount, so old dust cannot satisfy a strict caller’s first-deposit check.

• Existing position: existing_equity is provided. Waits for equity to increase by at least expected_deposit - max(tolerance, expected_deposit * relative_tolerance).

Parameters

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

• user (Union[eth_typing.evm.HexAddress, str]) – On-chain address (the Safe address for Lagoon vaults).

• vault_address (Union[eth_typing.evm.HexAddress, str]) – Hypercore vault address.

• expected_deposit (decimal.Decimal) – Expected deposit amount in USDC (human-readable, not raw).

• existing_equity (Optional[decimal.Decimal]) – User’s vault equity before the deposit, or None if this is the first deposit (no existing position).

• timeout (float) – Total observation budget, including requests and sleeps. Read errors end the observation immediately; this is a maximum, not a minimum wait.

• poll_interval (float) – Seconds between API polls.

• tolerance (decimal.Decimal) – Acceptable difference between expected and actual equity increase (to account for rounding, fees, vault PnL during the wait). Defaults to 0.01 USDC.

• relative_tolerance (decimal.Decimal) – Acceptable relative difference for deposits into an existing vault position. The larger of tolerance and expected_deposit * relative_tolerance is used, because live vault equity can drift during confirmation. Defaults to 5% (see DEFAULT_VAULT_DEPOSIT_RELATIVE_TOLERANCE for why).

• first_deposit_relative_tolerance (decimal.Decimal) – Acceptable relative difference for a first deposit (no existing position). Kept tighter than relative_tolerance because there is no pre-existing position to mark-to-market against a stale baseline. Defaults to 1% (see DEFAULT_FIRST_VAULT_DEPOSIT_RELATIVE_TOLERANCE).

Returns

The observed UserVaultEquity that reached the threshold.

Raises

• HypercoreDepositVerificationError – If equity does not reach the threshold within the timeout.

• requests.RequestException – If the bounded API read fails. No hidden transport retries are made.

Return type

eth_defi.hyperliquid.api.UserVaultEquity