Skip to main content

← x402

This page describes each x402 endpoint as it appears on the wire. If you are using the AgentCash SDK the 402 → sign → retry loop is handled for you — the request and response payloads below are still useful as a reference for the data your code receives. All endpoints are rooted at https://x402.rye.com.

​
Authentication

There is no Authorization header. Authentication is the signed PAYMENT-SIGNATURE payload — the wallet that signs the USDC transfer is the wallet of record for the request. Wallet identity resolves from authorization.from inside the payload.

​
POST /v1/checkout-intents

Creates a checkout intent and starts offer retrieval. Fee: $0.02 USDC

​
Request body

FieldTypeDescription
productUrlstringURL of the product to purchase
quantityintegerQuantity to purchase
buyerobjectBuyer name, email, phone, and shipping address
The buyer field follows the same schema as the standard Universal Checkout API.

​
First call — no signature

POST /v1/checkout-intents HTTP/1.1
Host: x402.rye.com
Content-Type: application/json

{
  "productUrl": "https://shop.example.com/running-shoes",
  "quantity": 1,
  "buyer": {
    "firstName": "Jane",
    "lastName": "Doe",
    "email": "jane@example.com",
    "phone": "+14155551234",
    "address1": "123 Market St",
    "city": "San Francisco",
    "province": "CA",
    "country": "US",
    "postalCode": "94103"
  }
}

​
402 response

The body is canonical x402 v2 PaymentRequired. The same JSON is base64-encoded into the PAYMENT-REQUIRED header. 
HTTP/1.1 402 Payment Required
PAYMENT-REQUIRED: <base64 JSON>

{
  "x402Version": 2,
  "resource": {
    "url": "https://x402.rye.com/v1/checkout-intents",
    "description": "x402 proxy access fee (2¢ USDC) for POST /v1/checkout-intents on base",
    "mimeType": "application/json"
  },
  "accepts": [
    {
      "scheme": "exact",
      "network": "eip155:8453",
      "amount": "20000",
      "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
      "payTo": "0x…",
      "maxTimeoutSeconds": 300,
      "extra": { "name": "USD Coin", "version": "2" }
    }
  ],
  "error": "PAYMENT-SIGNATURE header is required"
}
Field notes:
  • amount is in atomic units (USDC has 6 decimals — "20000" = $0.02).
  • asset is the USDC contract address on the named chain.
  • payTo is a freshly minted Stripe deposit address; it changes on every challenge.
  • extra.{name, version} are the EIP-712 domain parameters required to sign the TransferWithAuthorization message.

​
Retry — with signature

POST /v1/checkout-intents HTTP/1.1
Host: x402.rye.com
Content-Type: application/json
PAYMENT-SIGNATURE: <base64 JSON>

{ "productUrl": "...", "quantity": 1, "buyer": { ... } }
The PAYMENT-SIGNATURE header is a base64-encoded canonical x402 v2 PaymentPayload: 
{
  "x402Version": 2,
  "accepted": {
    "scheme": "exact",
    "network": "eip155:8453",
    "amount": "20000",
    "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    "payTo": "0x… (payTo from the challenge)",
    "maxTimeoutSeconds": 300
  },
  "payload": {
    "signature": "0x… (EIP-712 signature over authorization)",
    "authorization": {
      "from": "0x… (buyer's wallet)",
      "to": "0x… (payTo from the challenge)",
      "value": "20000",
      "validAfter": "1714000000",
      "validBefore": "1714003600",
      "nonce": "0x… (32 random bytes)"
    }
  }
}
The buyer signs an EIP-3009 authorization off-chain. The buyer never broadcasts — the proxy submits transferWithAuthorization on Base and pays the gas.

​
Success

The success response carries an X-PAYMENT-RESPONSE header containing a base64-encoded SettleResponse with the on-chain transaction hash. 
HTTP/1.1 201 Created
X-PAYMENT-RESPONSE: <base64 JSON>

{
  "id": "ci_abc123",
  "state": "retrieving_offer"
}
Decoded X-PAYMENT-RESPONSE body: 
{
  "success": true,
  "transaction": "0x… (on-chain tx hash)",
  "network": "base",
  "payer": "0x… (buyer's wallet)"
}
Spec-compliant x402 SDKs read this header to confirm settlement and surface the tx hash to the caller.

​
GET /v1/checkout-intents?id=<intent-id>

Returns the current state of an intent. Free — no payment headers required. The call is scoped to the wallet that paid for the intent. Pass the wallet address in the X-Wallet-Address header. Other wallets receive 404. 
GET /v1/checkout-intents?id=ci_abc123 HTTP/1.1
Host: x402.rye.com
X-Wallet-Address: 0x…

HTTP/1.1 200 OK

{
  "id": "ci_abc123",
  "state": "awaiting_confirmation",
  "offer": {
    "cost": {
      "subtotal": { "amountSubunits": 11999, "currencyCode": "USD" },
      "shipping": { "amountSubunits": 599,   "currencyCode": "USD" },
      "tax":      { "amountSubunits": 988,   "currencyCode": "USD" },
      "total":    { "amountSubunits": 13586, "currencyCode": "USD" }
    },
    "shippingMethod": "Standard — 3–5 business days"
  }
}
For a complete list of states and the transitions between them, see Checkout Intent Lifecycle.

​
POST /v1/checkout-intents/confirm

Confirms the intent and starts order placement. The intent id goes in the request body, not the URL. Fee: purchase total + $0.03 USDC, bundled into a single signed authorization.

​
Request body

FieldTypeDescription
idstringCheckout intent id (e.g., ci_abc123)
paymentMethod.typestringMust be "x402"
paymentMethod.networkstringOne of "base", "solana", "tempo"

​
First call — no signature

POST /v1/checkout-intents/confirm HTTP/1.1
Host: x402.rye.com
Content-Type: application/json

{
  "id": "ci_abc123",
  "paymentMethod": { "type": "x402", "network": "base" }
}

​
402 response

HTTP/1.1 402 Payment Required
PAYMENT-REQUIRED: <base64 JSON>

{
  "x402Version": 2,
  "resource": {
    "url": "https://x402.rye.com/v1/checkout-intents/confirm",
    "description": "x402 confirm payment for intent ci_abc123 on base",
    "mimeType": "application/json"
  },
  "accepts": [
    {
      "scheme": "exact",
      "network": "eip155:8453",
      "amount": "<purchase total + $0.03 in atomic USDC units>",
      "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
      "payTo": "0x…",
      "maxTimeoutSeconds": 300,
      "extra": { "name": "USD Coin", "version": "2" }
    }
  ],
  "error": "PAYMENT-SIGNATURE header is required"
}

​
Retry — with signature

POST /v1/checkout-intents/confirm HTTP/1.1
Host: x402.rye.com
Content-Type: application/json
PAYMENT-SIGNATURE: <base64 JSON>

{
  "id": "ci_abc123",
  "paymentMethod": { "type": "x402", "network": "base" }
}

​
Success

The success response carries X-PAYMENT-RESPONSE with the settle envelope, same shape as the create gate. 
HTTP/1.1 200 OK
X-PAYMENT-RESPONSE: <base64 JSON>

{
  "id": "ci_abc123",
  "state": "placing_order"
}
Once state is placing_order, poll GET /v1/checkout-intents?id=<intent-id> until it reaches completed (with orderId) or failed.

​
Networks

Set the network field on paymentMethod for /confirm to one of:
ValueChain ID (CAIP-2)
baseeip155:8453
solanasolana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp
tempoeip155:4217
USDC is the only accepted token on every supported network.

​
Refunds

Order placement failures (out of stock, merchant rejection, etc.) are refunded automatically — Rye returns the purchase amount to the signing wallet on-chain. The 0.02and0.02 and 0.03 API access fees are non-refundable.

​
Discovery

GET /openapi.json returns an OpenAPI 3.1.0 document with x-payment-info annotations on each paid operation. Use it with AgentCash discovery to introspect prices and schemas: 
npx -y @agentcash/discovery@latest discover https://x402.rye.com