Payment lifecycle
Every step of a paid call: the first request, the 402 quote, authorization, verification, the upstream call, settlement and the final response.
On this page
Sequence
- Client → Gateway Request, no payment
- Gateway → Payment core Issue a quote (60 s)
- Gateway → Client
402+PAYMENT-REQUIRED - Client Build and sign the transfer
- Client → Gateway Same request +
PAYMENT-SIGNATURE - Gateway → Payment core Accept payment for the quote
- Payment core → Solana Simulate the transaction
- Payment core → Gateway Reserved
- Gateway → Provider Forward the request
- Provider → Gateway Answer
- Gateway → Payment core Billable: settle
- Payment core → Solana Co-sign as fee payer and submit
- Solana → Payment core Confirmed
- Gateway → Client Answer +
PAYMENT-RESPONSE
Step by step
1. Initial request
The client calls the gateway URL with no PAYMENT-SIGNATURE header. The gateway checks the API is live and the method is allowed. If the provider is mid-way through a price change, it answers 503 price_change_in_progress instead of a quote. Quote requests are rate limited per client address.
2. HTTP 402 response
The gateway issues a quote for the API's current agent price and answers 402 with the body {"error":"payment_required","quoteId":"q_…"} and the quote in PAYMENT-REQUIRED. The quote lasts 60 seconds.
3. Payment requirements
The quote has one requirement in accepts: scheme exact, the network, the USDC mint (asset), the amount in base units, payTo (the API's vault), maxTimeoutSeconds: 60, and extra with the feePayer, the quote id as memo, the API's successPolicy and the priceBreakdown. See Understand an HTTP 402 response.
4. Payment authorization
The client builds a Solana transaction that pays the quote, signs it as the owner of the USDC (not as fee payer), and sends the same request again with PAYMENT-SIGNATURE. The rules are below in Authorization rules.
5. Verification
The payment core finds the quote by the memo, records the payment, and checks it: the quote exists, is unused and hasn't expired; the transaction follows the instruction rules; and a simulation on Solana shows it would succeed with exactly the quoted transfer. It also checks the paying wallet's exposure: how much it has in unsettled payments. A payment that passes is reserved.
A payment that fails is rejected: the gateway answers 402 again with the reason and a fresh quote. The rejected quote can't be reused.
6. Upstream API execution
The payment is verified again just before the provider is called, so an authorization that stopped being valid isn't served. Only one request can claim a payment. The gateway then forwards the request to the provider with the provider's key and waits up to 20 seconds.
7. Settlement
If the answer meets the billing rule that came with the quote, the payment core co-signs the transaction as fee payer, records its signature, and submits it to Solana. The gateway waits up to 5 seconds for confirmation at the configured commitment level (confirmed).
If the answer isn't billable, or the provider fails or times out, the payment becomes upstream failed and is never submitted.
8. Final response
| Outcome | Status | Body | PAYMENT-RESPONSE |
|---|---|---|---|
| Settled | The provider's | The provider's | success: true with the transaction |
| Not confirmed within 5 s | The provider's | The provider's | success: false, errorReason: "settlement_pending" |
| Settlement failed | 502 | {"error":"settlement_failed"} | success: false with the reason |
| Not billable / provider failed | 502 or 504 | {"error":"upstream_failed", …} | None |
Authorization rules
NODRA accepts a payment transaction only if it follows these rules. The fee payer's signing service re-checks them independently before it co-signs.
- A version 0 transaction (legacy transactions are accepted as version 0) with no address lookup tables.
- The fee payer is
extra.feePayer, it is the first account, and it appears in no instruction. The transaction has at most 2 signatures. - Instructions, in this order: set compute unit limit (at most 400,000), set compute unit price (at most 50,000 microlamports), exactly one `TransferChecked` and exactly one Memo. Lighthouse assertion instructions, which some wallets add, are allowed. Programs other than Compute Budget, Token, Token-2022, Memo and Lighthouse are refused.
- The transfer moves exactly
amountofassetinto the associated token account ofpayTo. The vault's token account already exists, so no account-creation instruction is needed or allowed. - The memo equals
extra.memo. - Smart-contract wallets (such as Squads or Swig) aren't supported.
Payment states
| State | Meaning |
|---|---|
received | The payment arrived and was recorded. |
validated | The transaction passed the checks. |
reserved | Accepted, within the payer's exposure limit, ready to serve. |
calling_upstream | The provider is being called. |
upstream_succeeded | The provider answered billably; settlement is next. |
submitted | Sent to Solana, awaiting confirmation. |
settled | Confirmed on Solana. The only state that counts as paid. |
rejected | Failed verification. Never submitted. |
expired | The quote expired before the payment was used. Never submitted. |
upstream_failed | The provider failed or wasn't billable. Never submitted. |
settlement_failed | The provider answered but the transfer couldn't be settled. The caller isn't charged. |