Skip to content
Sign in
Menu

Gateway

The paid request endpoint: call a launched API through NODRA and pay with x402.

  • x402 v2
On this page

Call a paid API

GET/v1/{slug}/{path}x402 payment

Also POST, PUT, PATCH and DELETE, unless the API narrows its methods. Forwards the request to the provider's upstream URL with {path} and the query string appended, once a valid payment is attached. Without one, answers 402 with a quote.

Path parameters

NameTypeDescription
slugstringThe API's slug, 3 to 40 characters. Must be a live API.
pathstring, optionalThe provider's path. Segments . and .. are refused.

Query parameters

Passed to the provider unchanged. NODRA defines none.

Request headers

All other request headers are dropped before forwarding.
HeaderRequiredDescription
PAYMENT-SIGNATUREOn the paid attemptBase64 JSON: { x402Version, resource, accepted, payload: { transaction } }. NODRA reads accepted.extra.memo (the quote id) and payload.transaction (the base64 signed transaction).
Content-TypeWith a bodyForwarded to the provider.
AcceptNoForwarded to the provider.

Request body

Forwarded to the provider as raw bytes, up to 1 MiB. Not sent for GET. Send the same body on the paid attempt as on the first.

Example

ShellRequest a quoteIllustrative values
curl -i 'https://gateway.example.com/v1/weather-forecasts/forecast?city=Lisbon'
HTTP402 responseIllustrative values
HTTP/1.1 402 Payment Required
Content-Type: application/json
Cache-Control: no-store
PAYMENT-REQUIRED: eyJ4NDAyVmVyc2lvbiI6Mi…

{ "error": "payment_required", "quoteId": "q_3f9c2a7b8e1d4c6a9b0e2f4d6c8a1b3e" }
ShellPaid attemptIllustrative values
curl -i 'https://gateway.example.com/v1/weather-forecasts/forecast?city=Lisbon' \
  -H "PAYMENT-SIGNATURE: $PAYMENT"
HTTPPaid responseIllustrative values
HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store
PAYMENT-RESPONSE: eyJzdWNjZXNzIjp0cnVlLC…

{ "city": "Lisbon", "forecast": "…" }

Responses

StatusMeaning
Provider's statusPaid and billable. Provider's body and Content-Type/Content-Language, plus PAYMENT-RESPONSE.
402No payment, or a rejected one. PAYMENT-REQUIRED holds a fresh quote; the body is { error, quoteId }.
400 404 405 409 413 429 500 502 503 504Errors. See Error handling for every code.

PAYMENT-REQUIRED

FieldDescription
x402Version2.
errorPresent only on a 402 after a rejected payment: the reason.
resource.urlThe URL you requested.
resource.descriptionPaid API {slug}.
resource.mimeTypeapplication/json.
accepts[]Exactly one requirement:
accepts[].schemeexact.
accepts[].networkCAIP-2 Solana network id.
accepts[].amountBase units to pay: the agent price.
accepts[].assetUSDC mint address.
accepts[].payToThe API's vault address. Pay its associated token account for asset.
accepts[].maxTimeoutSeconds60.
accepts[].extra.feePayerNODRA's fee payer. Must be the transaction's fee payer.
accepts[].extra.memoThe quote id. Must be the transaction's memo.
accepts[].extra.successPolicyThe billing rule for this call: { mode }, and jsonPointer for json_field.
accepts[].extra.priceBreakdown{ providerPrice, platformFee }, base-unit strings that add up to amount.

PAYMENT-RESPONSE

FieldDescription
successtrue when the payment is settled.
transactionThe Solana transaction signature.
networkCAIP-2 network id.
payerThe wallet that paid (the owner of the source token account).
errorReasonWhen success is false: settlement_pending, settlement_failed or the payment's final state.