nautechsystems/nautilus_trader · error · anyhow::Error

BUY quote amount {} exceeds the configured quote-spend maxim

Error message

BUY quote amount {} exceeds the configured quote-spend maximum {} for {} -> {}

What it means

In `verified_swap_amounts` (crates/adapters/blockchain/src/execution/client.rs:4100), once a BUY order's quote spend ceiling is present, the independently quoted amount of the quote token to spend must not exceed `ceiling.max_amount`. This is a risk control: it prevents the engine from spending more quote token than the configured maximum to fill a BUY.

Source

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

        "Independent swap quote returned zero"
    );
    let base_amount =
        quantity_to_raw_amount(plan.order.quantity(), plan.pool.get_base_token().decimals)?;
    let slippage_bps = plan.slippage_bps;
    match plan.order.order_side() {
        OrderSide::Sell => Ok((
            base_amount,
            derive_min_amount_out(quote.amount, slippage_bps)?,
        )),
        OrderSide::Buy => {
            let ceiling = plan.quote_spend_ceiling.ok_or_else(|| {
                anyhow::anyhow!(
                    "No quote spend ceiling for BUY token pair {} -> {}",
                    plan.token_in,
                    plan.token_out
                )
            })?;
            anyhow::ensure!(
                quote.amount <= ceiling.max_amount,
                "BUY quote amount {} exceeds the configured quote-spend maximum {} for {} -> {}",
                quote.amount,
                ceiling.max_amount,
                plan.token_in,
                plan.token_out
            );
            Ok((
                quote.amount,
                derive_min_amount_out(base_amount, slippage_bps)?,
            ))
        }
    }
}

fn validate_manifest_pool(
    plan: &SwapPlan,
    manifest: &BlockchainDeploymentManifest,

View on GitHub (pinned to 18893faf8b)

Solutions

1. Raise quote_spend_ceiling.max_amount to cover realistic quoted costs for the order size, then retry.
2. Reduce the BUY order quantity so its quoted spend fits within the existing cap.
3. Recheck quote-token decimals: max_amount is in raw (smallest) units; a decimal misconfiguration makes the cap appear exceeded.
4. Verify the quote is taken at the current block; a stale block can inflate the quoted amount.

Example fix

// before: cap too small for the order (6-decimal USDC, raw units)
quote_spend_ceiling: Some(QuoteSpendCeiling { max_amount: U256::from(100_000_000u64) }), // 100 raw units
// after: cap sized correctly in raw quote-token units
quote_spend_ceiling: Some(QuoteSpendCeiling { max_amount: U256::from(500_000_000_000u64) }), // 500k USDC raw

let estimate = client.quote(plan).await?;
if estimate.amount > ceiling.max_amount {
    return Err("order spend exceeds configured quote-spend maximum");
}

fn within_ceiling(q: &UniswapV3Quote, c: &QuoteSpendCeiling) -> bool {
    q.amount <= c.max_amount
}

match client.execute_swap(plan).await {
    Err(e) if e.to_string().contains("exceeds the configured quote-spend maximum") => {
        // shrink the order or raise the cap, then retry
    }
    other => other?,
}

When it happens

Trigger: An independent QuoterV2 quote for an ExactOutput BUY returns quote.amount greater than the configured quote_spend_ceiling.max_amount — the desired base quantity is expensive relative to the cap, price moved, or the ceiling was configured too low for the order size.

Common situations: Operator configured a spend cap sized for small orders but submits a large BUY; volatile market makes the same base quantity cost more quote token than the cap; a stale ceiling reused from another network/token pair; decimal mistakes making max_amount far smaller than intended.

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

• Slippage {slippage_bps} bps exceeds the configured `max_slip
• BUY quote amount {amount_in} exceeds the configured `quote_s
• No quote spend ceiling for BUY token pair {} -> {}
• Token pair {token_in} -> {token_out} is not in the `allowed_
• Order amount {base_amount} exceeds the configured `max_order

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