> ## 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.

# Endpoint Reference

> Request and response shapes for each x402 Agent API endpoint, with raw HTTP examples.

<Card title="← x402" href="/api-v2/x402/overview" />

This page describes each x402 endpoint as it appears on the wire. If you are using the [AgentCash SDK](/api-v2/x402/quickstart) 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](/api-v2/introduction).

### First call — no signature

```http theme={null}
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 theme={null}
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

```http theme={null}
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`:

```json theme={null}
{
  "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 theme={null}
HTTP/1.1 201 Created
X-PAYMENT-RESPONSE: <base64 JSON>

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

Decoded `X-PAYMENT-RESPONSE` body:

```json theme={null}
{
  "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`.

```http theme={null}
GET /v1/checkout-intents?id=ci_abc123 HTTP/1.1
Host: x402.rye.com
X-Wallet-Address: 0x…
```

```http theme={null}
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](/api-v2/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

```http theme={null}
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 theme={null}
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

```http theme={null}
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 theme={null}
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](https://agentcash.dev/docs/tools/check-endpoint-schema) to introspect prices and schemas:

```bash theme={null}
npx -y @agentcash/discovery@latest discover https://x402.rye.com
```