Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs-test.rye.com/docs/llms.txt

Use this file to discover all available pages before exploring further.

← 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

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

{
  "error": "payment_required",
  "paymentRequired": {
    "scheme": "exact",
    "network": "eip155:8453",
    "maxAmountRequired": "0.02",
    "currency": "USDC",
    "recipient": "0x…",
    "expiresAt": "2026-04-27T20:45:00Z"
  }
}

​
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": { ... } }

​
Success

HTTP/1.1 201 Created

{
  "id": "ci_abc123",
  "state": "retrieving_offer"
}

​
GET /v1/checkout-intents/: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/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/:id/confirm

Confirms the intent and starts order placement. Fee: purchase total + $0.03 USDC, bundled into a single signed transfer.

​
Request body

FieldTypeDescription
paymentMethod.typestringMust be "x402"
paymentMethod.networkstringOne of "base", "solana", "tempo"

​
First call — no signature

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

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

​
402 response

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

{
  "error": "payment_required",
  "paymentRequired": {
    "scheme": "exact",
    "network": "eip155:8453",
    "maxAmountRequired": "<purchase total + $0.03>",
    "currency": "USDC",
    "recipient": "0x…",
    "expiresAt": "2026-04-27T20:50:00Z"
  }
}

​
Retry — with signature

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

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

​
Success

HTTP/1.1 200 OK

{
  "id": "ci_abc123",
  "state": "placing_order"
}
Once state is placing_order, poll GET /v1/checkout-intents/: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