Generation runbook
The challenge is the locked quote.
With x402 enabled, a generation that would fail for insufficient credits returns PAYMENT-REQUIRED priced from the same signed quote the AI router locked. After USDC settlement, exactly those credits are granted and the job starts on the locked route.
- Price source
- Signed quote
- CLI behavior
- Transparent retry
- Failure after pay
- Credits stay
Settle the quote, then generate
Follow the sequence in order. Each step is a bounded operator action—not a promise that every deployment has x402 enabled.
- 01
Lock a quote first
Use quote_generation or the CLI quote command for the exact model and options. Keep the lockedQuoteToken for submit.
- 02
Submit generate
Pass quoteToken on generate. If balance is short and x402 is enabled, the response is an x402 challenge instead of a dead-end insufficient-credits error.
- 03
Sign under the spend cap
A configured wallet signs locally and retries with PAYMENT-SIGNATURE. Over-cap challenges are refused before signing.
- 04
Reuse the locked token
The challenge body includes quote.lockedQuoteToken. Pass it again on the paid retry so the price cannot drift. If generation fails after settlement, reserved credits remain available for a free retry of that work.
- Price sourceSigned quote
The x402 challenge amount comes from the router-locked credit charge, not a separate agent price.
- CLI behaviorTransparent retry
With a wallet configured, generate can cover pay-as-you-go 402s automatically.
- Failure after payCredits stay
If the generation fails after settlement, credits remain on the balance for retry.
Runbook FAQ
Can settlement change my locked generation price?
No. The challenge is priced from the signed quote. Settlement grants exactly those credits and the generation runs on the locked route.
What if I have no wallet?
You get the legacy insufficient-credits path. Top up with Stripe or Studio, then submit again with the same quote token while it remains valid.
Keep payment decisions explicit.
Humans stay on Stripe. Agents settle only with a local wallet and a spend cap. When the shape is unclear, start with the PAYMENT-REQUIRED diagnosis runbook.