# x402

x402 is an open payment protocol developed by Coinbase that uses the HTTP 402 status code to embed blockchain payments directly in HTTP request/response cycles. RailProtocol supports x402 natively and uses it as the default protocol when a service supports both x402 and MPP.

***

## Background

The HTTP 402 status code ("Payment Required") was reserved in the original HTTP specification in 1997 but was never formally standardized. x402 gives it a real implementation: when a server responds with 402, it includes a structured payment requirement, and the client fulfills it on-chain before retrying the request.

***

## How x402 works

The x402 flow has three parties: the **client** (your agent), the **resource server** (the API you are paying), and the **facilitator** (routes and verifies on-chain settlement).

```
1. Agent sends request to resource server
        GET https://api.service.com/data

2. Server responds with 402 + payment requirements
        HTTP/1.1 402 Payment Required
        Content-Type: application/json

        {
          "scheme": "exact",
          "network": "solana-mainnet",
          "token": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",  // USDC
          "amount": "2000",    // 0.002 USDC (6 decimal places)
          "payTo": "7xKXtg...",
          "resource": "https://api.service.com/data"
        }

3. RailProtocol constructs and signs a PaymentPayload
        {
          "scheme": "exact",
          "network": "solana-mainnet",
          "payload": {
            "from": "<agent wallet address>",
            "to": "7xKXtg...",
            "amount": "2000",
            "token": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
            "nonce": "01j9x4k2m3n5p6q7"
          },
          "signature": "<ed25519 signature>"
        }

4. Agent retransmits original request with payment header
        GET https://api.service.com/data
        X-PAYMENT: <base64-encoded PaymentPayload>
        X-PAYMENT-SIGNATURE: <signature>

5. Server verifies payment via facilitator and returns data
        HTTP/1.1 200 OK
        ...response body...
```

Settlement on Solana takes less than 400ms. With the Alpenglow upgrade, finality targets below 150ms.

***

## Key properties

| Property         | Value                                      |
| ---------------- | ------------------------------------------ |
| Settlement layer | Solana (primary), Base, other EVM networks |
| Settlement token | USDC (primary), USDT                       |
| Protocol fee     | None                                       |
| KYC required     | No                                         |
| Account required | No                                         |
| Session support  | Yes (v2, wallet-based)                     |
| Finality         | Under 400ms on Solana                      |

***

## x402 on Solana

Solana is the fastest and cheapest settlement layer for x402 payments:

* Average transaction fee: under $0.001
* Confirmed transactions: 143 million per day (as of May 2026)
* Stablecoin volume: $2 trillion per quarter

RailProtocol uses Solana as the default x402 settlement network. USDC is transferred via the SPL Token program. Every transaction is publicly visible on Solana Explorer.

***

## x402 sessions

x402 v2 introduced session support, allowing a wallet to pre-authorize a spending allowance for a service. This eliminates per-request overhead for high-frequency calls to the same endpoint.

RailProtocol manages x402 sessions automatically. When a session is established with a service, subsequent calls reuse it without renegotiating the full payment handshake.

***

## How RailProtocol handles x402

When `rail.pay()` is called:

1. RailProtocol sends the original request to the target endpoint
2. If the response is 402, RailProtocol reads the `PaymentRequired` object
3. The spend policy is checked against the required amount and domain
4. If the policy passes, RailProtocol constructs a signed `PaymentPayload` using the agent's wallet keypair
5. The original request is retransmitted with the `X-PAYMENT` and `X-PAYMENT-SIGNATURE` headers
6. The server verifies the payment via the x402 facilitator and returns the response
7. RailProtocol records the transaction to the on-chain ledger

The developer calls `rail.pay()` and receives the API response. The x402 handshake is invisible.

***

## Accepting x402 payments (server side)

If you want your own API to accept x402 payments from agents, RailProtocol provides server-side middleware:

```typescript
import { x402Middleware } from "@railprotocol/sdk/server";
import express from "express";

const app = express();

app.use("/api/data", x402Middleware({
  amount: "2000",        // 0.002 USDC
  token: "usdc",
  network: "solana-mainnet",
  payTo: process.env.PAYMENT_WALLET_ADDRESS,
}));

app.get("/api/data", (req, res) => {
  res.json({ result: "..." });
});
```

Payments are automatically verified before your handler is called. USDC arrives in your wallet on Solana within 400ms of the agent's request.

***

## Further reading

* [x402 specification](https://x402.org)
* [MPP protocol](/protocols/mpp.md) — the alternative agent payment protocol
* [Payment Router](/features/payment-router.md) — how RailProtocol chooses between x402 and MPP


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.railprotocol.org/protocols/x402.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.