The router

The router is the product edge. It runs on every POST /v1/chat/completions and turns a buyer's request into a cleared trade.

One completion maps to one offer, one upstream forward, and one clear.

What it does, in order

1. Resolve the Bearer key to a wallet and its max price.
2. Acquire the per-wallet lock: one in-flight completion per wallet (429 if busy).
3. Pre-check the confirmed USDC balance against the estimated gross.
4. Select supply: the cheapest eligible offer whose posted price is at or below the buyer's max and whose routable capacity is sufficient.
5. Acquire the per-key lock; fall through to the next eligible key or wait FIFO if busy.
6. Forward once to the supplier's upstream key.
7. Meter the real capacity burn from the response.
8. Settle in a single transaction and write audit rows.

Selection rules

• Cheapest eligible wins. Among offers at or below the buyer's max, the lowest posted price clears first.
• The clearing price is the posted ask. The buyer's max only filters; it never sets the price.
• No browsing. Buyers never see or choose individual sellers.

Serialization and limits

• One in-flight completion per wallet across all its API keys (429 buyer_concurrency_limit).
• One in-flight forward per supplier key; the router falls through or waits.
• Streaming is not supported in v1.

When nothing clears

If no eligible supply exists, the router returns 503 with one of no_eligible_supply, insufficient_routable_at_price, or pool_empty, plus headers indicating the cheapest posted price and routable capacity above your max. See Errors & limits.