nautechsystems/nautilus_trader · error

Native currency balance

Error message

Native currency balance {native_balance} wei is below maximum transaction cost {max_transaction_cost} wei

What it means

Pre-sign, the client verifies the wallet's native currency balance (in wei) and bails if it is below the maximum estimated transaction cost. This guard prevents broadcasting a transaction that cannot pay its gas, which would either fail at inclusion or waste an in-flight slot.

Solutions

  1. Fund the signer address with enough native currency to cover max cost plus headroom
  2. Lower the transaction's value or gas limit if possible
  3. Re-check the current gas price and resubmit when fees drop
  4. Confirm the correct chain and wallet address are configured

Example fix

// before
client.submit_order(order).await?;
// after
let balance = client.native_balance(signer_address).await?;
let max_cost = client.max_transaction_cost(&order).await?;
anyhow::ensure!(balance > max_cost, "fund wallet: need {max_cost} wei, have {balance}");
client.submit_order(order).await?;
Defensive patterns

Strategy: validation

Validate before calling

let balance = client.native_balance(signer_address).await?;
let cost = client.max_transaction_cost(&tx).await?;
anyhow::ensure!(balance > cost + headroom, "need {} wei, have {}", cost, balance);

Prevention

When it happens

Trigger: Submitting a transaction when the signer address's native balance (ETH etc.) is less than the computed max cost (gas limit × max fee per gas + value). The balance check itself is verified via the pre-sign native balance verification.

Common situations: Wallet drained or funds still bridging; gas price spiked so max cost exceeds balance; using the wrong chain/wallet with low balance; value transfer included on top of gas making total cost exceed balance.

Understand the failure class

Background: "value must be between 0 and 1" / "out of range" / "must not be negative" errors: fixing range-validation failures across open-source libraries — this error's family across 42 libraries.

Related errors


AI-assisted analysis of nautechsystems/nautilus_trader@18893faf8b (2026-09-08). Data as JSON: /api/errors/4865d1b28f0a6623. Report an issue: GitHub.

Appendix: source

Thrown at crates/adapters/blockchain/src/execution/client.rs:2387

        )?;
        let gas_estimate = gas_estimate_verification.value;
        let gas_limit = derive_gas_limit(gas_estimate, self.gas_buffer_bps, self.gas_limit)?;
        let max_gas_cost = U256::from(gas_limit)
            .checked_mul(U256::from(max_fee_per_gas))
            .ok_or_else(|| anyhow::anyhow!("Maximum gas cost overflow"))?;
        let max_transaction_cost = value
            .checked_add(max_gas_cost)
            .ok_or_else(|| anyhow::anyhow!("Maximum transaction cost overflow"))?;
        let native_balance_verification = required_verification(
            self.verification
                .verify_balance(&self.wallet_address, decision_header.number)
                .await,
            "pre-sign native balance",
        )?;
        let native_balance = native_balance_verification.value;

        if native_balance < max_transaction_cost {
            anyhow::bail!(
                "Native currency balance {native_balance} wei is below maximum transaction cost {max_transaction_cost} wei"
            );
        }
        let decision_height = Some(decision_header.number);
        let mut decisions = vec![
            verification_decision(&chain_id_verification, None, None),
            verification_decision(
                &decision_header_verification,
                decision_height,
                decision_height,
            ),
            verification_decision(&deployment_verification, decision_height, decision_height),
            verification_decision(&priority_fee_verification, None, None),
            verification_decision(&gas_estimate_verification, decision_height, decision_height),
            verification_decision(
                &native_balance_verification,
                decision_height,
                decision_height,

View on GitHub (pinned to 18893faf8b)