Skip to main content
The gateway speaks standard x402 over HTTP. This page lists every header it reads from clients and returns in responses, along with the status codes clients should expect.

​
Request headers

​
PAYMENT-SIGNATURE (aka X-PAYMENT)

Used by paid routes (accessMode: "exact").
  • Base64-encoded x402 exact payment payload.
  • Must match the maxAmountRequired, network, and payTo fields from the route’s 402 Payment Required challenge envelope.
  • The gateway accepts either PAYMENT-SIGNATURE or X-PAYMENT.
  • Each payment can authorize exactly one call; reusing the same header returns 400.

​
SIGN-IN-WITH-X

Used by auth-only routes (accessMode: "siwx").
  • Base64-encoded SIWX payload.
  • Must be signed by a Solana wallet and target one of the authNetworks from the challenge envelope.
  • Must be used within expirationSeconds (300s) of being signed.
  • Each signature can only authorize one request. Replays are rejected.

​
X-Ryvo-Request-Id

Used by channel-backed routes (accessMode: "ryvo-channel").
  • Stable idempotency key for one gateway request.
  • Required with RYVO-COMMITMENT.
  • The gateway atomically reserves the request ID before upstream execution so concurrent calls on one channel cannot overspend.

​
RYVO-COMMITMENT

Used by channel-backed routes (accessMode: "ryvo-channel").
  • Base64 JSON envelope containing the signed Ryvo cumulative commitment payload.
  • Must target the live devnet program, gateway merchant participant, correct cluster, correct message domain, and official devnet USDC token.
  • The new cumulative amount must equal the latest accepted commitment plus the route’s priceTokenAmount.

​
Content-Type

  • application/json for any request with a body.
  • Required for paid Solana routes. Rejected with 415 for any other content type on body routes.

​
Response headers

​
WWW-Authenticate

Emitted on 402 Payment Required responses. Describes the accepted scheme(s), either exact with a Solana network or sign-in-with-x with one or more networks.

​
X-PAYMENT-RESPONSE (aka PAYMENT-RESPONSE)

Emitted on successful paid responses (accessMode: "exact"). Contains the Solana settlement transaction hash and payer address. Clients should read this to get a proof of settlement. Example shape after decoding: 
{
  "success": true,
  "network": "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp",
  "transaction": "<tx hash>",
  "payer": "<payer pubkey>",
  "settledAt": "2026-04-18T11:32:00Z"
}
SIWX routes never return this header. Channel-backed routes do not return X-PAYMENT-RESPONSE per request. Accepted commitments are settled later through Ryvo Protocol bundle settlement.

​
access-control-*

Full CORS preflight is supported. See Endpoints for the exact allowlist.

​
Status codes

StatusMeaningBody
200 OKSuccessful upstream response.{ ok: true, ..., result: {...} }
204 No ContentPreflight OPTIONS response.empty
400 Bad RequestInput failed validation, reused payment, or invalid provider filter.{ ok: false, error, ... }
402 Payment Requiredx402 exact or SIWX challenge. Retry with the matching header.{ x402Version: 2, accepts: [...] }
404 Not FoundUnknown route path.{ ok: false, error: "not_found" }
405 Method Not AllowedWrong HTTP method for the route.{ ok: false, error: "method_not_allowed" }
415 Unsupported Media TypeNon-JSON body on a JSON route.{ ok: false, error: "unsupported_media_type" }
422 Unprocessable EntityPayment verification failed after a valid challenge.{ ok: false, error: "payment_verification_failed" }
429 Too Many RequestsRate limit hit.{ ok: false, error: "rate_limited", retryAfterMs }
5xxUpstream or facilitator failure. No settlement occurs.{ ok: false, error, detail }

​
Challenge envelope

402 responses always include a JSON body with a standard x402 envelope: 
{
  "x402Version": 2,
  "accepts": [
    {
      "scheme": "exact" | "sign-in-with-x",
      "network": "<CAIP-2 or array>",
      "maxAmountRequired": "<micro-USDC>",       // exact only
      "statement": "...",                          // siwx only
      "expirationSeconds": 300,                    // siwx only
      "resource": "<full URL>",
      "description": "...",
      "mimeType": "application/json",
      "payTo": "<address>",                        // exact only
      "asset": { "address": "...", "symbol": "USDC", "decimals": 6 },
      "facilitator": { "url": "<facilitator url>" },
      "extensions": { /* discovery + siwx */ }
    }
  ]
}
Clients should not rely on the ordering of fields. Treat accepts as a list of possible authorization strategies.

​
See also