Endpoint Reference

← 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

Field	Type	Description
`productUrl`	string	URL of the product to purchase
`quantity`	integer	Quantity to purchase
`buyer`	object	Buyer 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

Field	Type	Description
`id`	string	Checkout intent id (e.g., `ci_abc123`)
`paymentMethod.type`	string	Must be `"x402"`
`paymentMethod.network`	string	One 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:

Value	Chain ID (CAIP-2)
`base`	`eip155:8453`
`solana`	`solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp`
`tempo`	`eip155: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.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

Universal Checkout API

Tools

Testing

Webhooks

API Reference

Help

Endpoint Reference

← x402

Authentication

`POST /v1/checkout-intents`

Request body

First call — no signature

`402` response

Retry — with signature

Success

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

`POST /v1/checkout-intents/confirm`

Request body

First call — no signature

`402` response

Retry — with signature

Success

Networks

Refunds

Discovery

← x402

​Authentication

​POST /v1/checkout-intents

​Request body

​First call — no signature

​402 response

​Retry — with signature

​Success

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

​POST /v1/checkout-intents/confirm

​Request body

​First call — no signature

​402 response

​Retry — with signature

​Success

​Networks

​Refunds

​Discovery

Authentication

`POST /v1/checkout-intents`

Request body

First call — no signature

`402` response

Retry — with signature

Success

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

`POST /v1/checkout-intents/confirm`

Request body

First call — no signature

`402` response

Retry — with signature

Success

Networks

Refunds

Discovery