Native currency balance {native_balance} wei is below maximu

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.

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)

Solutions

Fund the signer address with enough native currency to cover max cost plus headroom
Lower the transaction's value or gas limit if possible
Re-check the current gas price and resubmit when fees drop
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

Monitor signer wallet balance and alert below a threshold
Recompute max cost from live gas prices before each submission
Keep a funding buffer above expected worst-case gas
Confirm chain id so you check the right network's balance

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.