The upto scheme — worked example

Every paid call settles at:

settleAtomic = max(units × pricePerUnit, minCharge)

where minCharge is the per-call settlement floor — 100000 atomic units ($0.10). The floor is advertised in the 402 advertisement as accepts[0].extra.minCharge (an atomic-unit string, "100000"), so agents can discover it programmatically alongside pricePerUnit and maxUnits.

A small call — floored to $0.10

Suppose you call:

GET https://api.bazaar.tools/v1/flights/search?origin=SFO&destination=JFK&maxResults=5

with an upto authorisation for $0.10 (the per-call ceiling).

The server does this calculation:

authorizedAtomic = 100_000n       (your signed cap, 6-decimal USDC)
pricePerUnit     =   1_000n       ($0.001 per itinerary)
maxUnits         = 100             (the spec's hard cap)
maxResults       =   5             (your query)
minCharge        = 100_000n       ($0.10 per-call floor)

authorizedUnits = floor(authorizedAtomic / pricePerUnit) = 100
units           = min(maxResults, maxUnits, authorizedUnits) = 5
rawAtomic       = units * pricePerUnit = 5_000n            ($0.005)
settleAtomic    = max(rawAtomic, minCharge) = 100_000n     ($0.10)

The server then calls setSettlementOverrides({ amount: "100000" }). The facilitator settles for $0.10 — the floor, because 5 itineraries at $0.001 come to only $0.005 raw. Your PAYMENT-RESPONSE shows amount: "100000".

Practical corollary: on this endpoint a 1-row call and a 100-row call both settle $0.10, so ask for the full 100.

A larger call — settles above the floor

GET https://api.bazaar.tools/v1/stocks/fundamentals?symbols=AAPL,MSFT,NVDA,GOOGL,AMZN,META

with an upto authorisation for $0.95 (the per-call ceiling):

authorizedAtomic = 950_000n       ($0.95)
pricePerUnit     =  50_000n       ($0.05 per symbol)
units            =   6             (one row per symbol)
rawAtomic        = 6 * 50_000n = 300_000n                  ($0.30)
settleAtomic     = max(300_000n, 100_000n) = 300_000n      ($0.30)

Above the floor you pay exactly units × pricePerUnit — never the ceiling you authorised. The facilitator settles for $0.30, not $0.95.

When you pay nothing

amount: "0" — no on-chain transaction — happens only on errors: input-validation 400s, 404s where your query matched zero rows in every freshness tier, and thrown server errors. A 2xx that returns rows always settles at least the $0.10 floor, on every freshness tier including cold. To inspect the response shape for free, read the schema and example in the unpaid 402 body (or the Bazaar listing) — see Test data.