Skip to content
Sign in
Menu

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

A paid call through NODRA
  1. Client → Gateway Request, no payment
  2. Gateway → Payment core Issue a quote (60 s)
  3. Gateway → Client 402 + PAYMENT-REQUIRED
  4. Client Build and sign the transfer
  5. Client → Gateway Same request + PAYMENT-SIGNATURE
  6. Gateway → Payment core Accept payment for the quote
  7. Payment core → Solana Simulate the transaction
  8. Payment core → Gateway Reserved
  9. Gateway → Provider Forward the request
  10. Provider → Gateway Answer
  11. Gateway → Payment core Billable: settle
  12. Payment core → Solana Co-sign as fee payer and submit
  13. Solana → Payment core Confirmed
  14. 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

OutcomeStatusBodyPAYMENT-RESPONSE
SettledThe provider'sThe provider'ssuccess: true with the transaction
Not confirmed within 5 sThe provider'sThe provider'ssuccess: false, errorReason: "settlement_pending"
Settlement failed502{"error":"settlement_failed"}success: false with the reason
Not billable / provider failed502 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 amount of asset into the associated token account of payTo. 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

StateMeaning
receivedThe payment arrived and was recorded.
validatedThe transaction passed the checks.
reservedAccepted, within the payer's exposure limit, ready to serve.
calling_upstreamThe provider is being called.
upstream_succeededThe provider answered billably; settlement is next.
submittedSent to Solana, awaiting confirmation.
settledConfirmed on Solana. The only state that counts as paid.
rejectedFailed verification. Never submitted.
expiredThe quote expired before the payment was used. Never submitted.
upstream_failedThe provider failed or wasn't billable. Never submitted.
settlement_failedThe provider answered but the transfer couldn't be settled. The caller isn't charged.