> ## Documentation Index
> Fetch the complete documentation index at: https://seilabs-docs-bridge-release-v6-6-3.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# x402 Protocol on Sei

> Implement HTTP micropayments on Sei using x402 v2 for API monetization and digital services.

x402 is an open protocol for HTTP-native payments. It lets clients pay for APIs, data, content, and other web resources through the standard `402 Payment Required` flow. A service can charge for a single request without requiring the buyer to create an account, manage a subscription, or negotiate a separate billing integration.

When a client requests a paid resource, the server responds with the price and payment terms. The client signs a payment authorization and retries the same request. The server verifies and settles the payment before returning the resource.

## Why x402 on Sei?

x402 payments sit in the request path. The client receives the protected response only after the payment has been authorized and settled. Sei's fast finality reduces this wait, while its low transaction costs make small per-request payments practical.

Sei EVM also lets you use the upstream `@x402` packages and standard EVM wallet tooling. Native USDC is already included in the x402 default asset registry for Pacific-1 and Atlantic-2, so dollar-denominated route pricing works without a custom token mapping.

<Info>
  When you configure x402 on Sei:

  * Pacific-1 uses the CAIP-2 network identifier `eip155:1329`.
  * Atlantic-2 uses the CAIP-2 network identifier `eip155:1328`.
  * `@x402/evm` provides the EVM payment scheme implementation.
</Info>

## How x402 works

Three components take part in an x402 payment:

* The **client** requests a resource and signs a payment authorization. It can be a user-facing dApp, an autonomous agent, or another service.
* The **resource server** defines the price, validates payment, and returns the protected resource.
* A **facilitator** can verify the authorization, submit the payment onchain, and return the settlement result. You can use a facilitator service, run your own, or settle payments directly.

<Steps>
  <Step title="Request the resource">
    The client sends a normal HTTP request to the paid endpoint.
  </Step>

  <Step title="Receive the payment requirements">
    The server returns `402 Payment Required`. Its `PAYMENT-REQUIRED` header describes the accepted scheme, amount, asset, network, recipient, and resource.
  </Step>

  <Step title="Authorize payment">
    The client selects an accepted payment option and signs the payment payload with its wallet.
  </Step>

  <Step title="Retry the request">
    The client sends the request again with the signed payload in the `PAYMENT-SIGNATURE` header. The x402 Fetch and Axios adapters automate this retry.
  </Step>

  <Step title="Verify and settle">
    The resource server verifies the payload against its payment requirements. It then settles directly or asks a facilitator to submit the payment onchain.
  </Step>

  <Step title="Return the resource">
    After successful settlement, the server returns the requested data and includes settlement details in the `PAYMENT-RESPONSE` header.
  </Step>
</Steps>

### Payment headers

| Header              | Direction        | Purpose                                                 |
| ------------------- | ---------------- | ------------------------------------------------------- |
| `PAYMENT-REQUIRED`  | Server to client | Describes the payment options accepted for the resource |
| `PAYMENT-SIGNATURE` | Client to server | Carries the signed payment payload                      |
| `PAYMENT-RESPONSE`  | Server to client | Reports the settlement result                           |

The header values contain Base64-encoded JSON. The x402 SDK encodes and decodes them for you.

### Payment schemes

x402 v2 supports different settlement models:

* [`exact`](https://docs.x402.org/schemes/exact) charges a fixed amount for each request.
* [`upto`](https://docs.x402.org/schemes/upto) lets the client authorize a maximum amount while the seller settles the actual usage.
* [`batch-settlement`](https://docs.x402.org/schemes/batch-settlement) uses an escrow deposit and signed vouchers so high-volume services can settle multiple payments together.

For a fixed-price API or paywall, start with the `exact` scheme.

## Use cases on Sei

* Charge per request for AI inference, image generation, data feeds, or other APIs.
* Gate individual articles, media files, and downloads without requiring a subscription.
* Let agents and backend services pay for machine-to-machine resources.
* Bill for measured infrastructure, storage, or bandwidth usage.

## Use upstream x402 v2

<Danger>
  The `@sei-js/x402`, `@sei-js/x402-fetch`, `@sei-js/x402-axios`, `@sei-js/x402-express`, `@sei-js/x402-hono`, and `@sei-js/x402-next` packages are deprecated and no longer maintained.

  Do not use them for new integrations. Migrate existing integrations to the upstream x402 v2 packages under the `@x402` npm scope.
</Danger>

x402 v2 separates the protocol core, network mechanisms, and HTTP framework adapters into modular packages.

| Deprecated package     | Upstream replacement                           |
| ---------------------- | ---------------------------------------------- |
| `@sei-js/x402`         | `@x402/core` and `@x402/evm`                   |
| `@sei-js/x402-fetch`   | `@x402/fetch` and `@x402/evm`                  |
| `@sei-js/x402-axios`   | `@x402/axios` and `@x402/evm`                  |
| `@sei-js/x402-express` | `@x402/express`, `@x402/core`, and `@x402/evm` |
| `@sei-js/x402-hono`    | `@x402/hono`, `@x402/core`, and `@x402/evm`    |
| `@sei-js/x402-next`    | `@x402/next`, `@x402/core`, and `@x402/evm`    |

## Install x402 v2

Install the EVM mechanism package together with the adapter for your client or server.

<Tabs>
  <Tab title="Fetch client">
    ```bash theme={null}
    npm install @x402/core @x402/evm @x402/fetch viem
    ```
  </Tab>

  <Tab title="Axios client">
    ```bash theme={null}
    npm install @x402/core @x402/evm @x402/axios viem
    ```
  </Tab>

  <Tab title="Express server">
    ```bash theme={null}
    npm install @x402/core @x402/evm @x402/express
    ```
  </Tab>

  <Tab title="Hono server">
    ```bash theme={null}
    npm install @x402/core @x402/evm @x402/hono
    ```
  </Tab>

  <Tab title="Next.js server">
    ```bash theme={null}
    npm install @x402/core @x402/evm @x402/next
    ```
  </Tab>
</Tabs>

Follow the upstream [seller quickstart](https://docs.x402.org/getting-started/quickstart-for-sellers) or [buyer quickstart](https://docs.x402.org/getting-started/quickstart-for-buyers) for the current API.

## Configure Sei

Use the CAIP-2 identifier for your target network when you configure a route:

| Network    | CAIP-2 identifier | Default USDC                                 |
| ---------- | ----------------- | -------------------------------------------- |
| Pacific-1  | `eip155:1329`     | `0xe15fC38F6D8c56aF07bbCBe3BAf5708A2Bf42392` |
| Atlantic-2 | `eip155:1328`     | `0x4fCF1784B31630811181f670Aea7A7bEF803eaED` |

Because x402 registers these assets as the defaults for Sei, a price such as `"$0.001"` resolves to the USDC address for the selected network. To accept another ERC-20 token, configure an explicit token amount and its EIP-712 metadata instead.

<Warning>
  x402 can express and sign payments for any EVM network, but your facilitator must also support the selected Sei network. Confirm network support with your facilitator before deployment, or run your own facilitator.
</Warning>

See the upstream [network and token support](https://docs.x402.org/core-concepts/network-and-token-support) reference for current asset and facilitator details.

### What the facilitator does

A facilitator handles the blockchain-specific work on behalf of your resource server. It checks that the signed payload satisfies the advertised payment requirements, submits the authorized transfer, waits for the settlement result, and returns that result to your server.

Native USDC on Sei supports EIP-3009. With the `exact` EVM scheme, the buyer signs a transfer authorization instead of submitting the transfer transaction itself. The facilitator submits the transaction and pays the required gas.

## Protect an Express route

The following x402 v2 example charges `0.001` USDC for `GET /weather` on Atlantic-2. Set `X402_FACILITATOR_URL` to a facilitator that supports `eip155:1328`.

```typescript theme={null}
import express from "express";
import { HTTPFacilitatorClient } from "@x402/core/server";
import { ExactEvmScheme } from "@x402/evm/exact/server";
import { paymentMiddleware, x402ResourceServer } from "@x402/express";

const facilitatorUrl = process.env.X402_FACILITATOR_URL;
const payTo = process.env.PAY_TO_ADDRESS as `0x${string}` | undefined;

if (!facilitatorUrl || !payTo) {
  throw new Error("Set X402_FACILITATOR_URL and PAY_TO_ADDRESS");
}

const app = express();
const network = "eip155:1328";
const facilitator = new HTTPFacilitatorClient({ url: facilitatorUrl });
const resourceServer = new x402ResourceServer(facilitator).register(
  network,
  new ExactEvmScheme(),
);

app.use(
  paymentMiddleware(
    {
      "GET /weather": {
        accepts: [
          {
            scheme: "exact",
            price: "$0.001",
            network,
            payTo,
          },
        ],
        description: "Current weather data",
        mimeType: "application/json",
      },
    },
    resourceServer,
  ),
);

app.get("/weather", (_request, response) => {
  response.json({
    location: "Sei",
    conditions: "sunny",
  });
});

app.listen(4021);
```

The middleware handles the initial `402` response, payment verification, and settlement. Your route handler runs after verification. The middleware buffers its response and sends it to the client only if settlement succeeds.

## Make a paid request

The Fetch adapter handles the client side of the flow. It makes the initial request, reads the `402` response, signs an accepted payment option, and retries with `PAYMENT-SIGNATURE`.

```typescript theme={null}
import { x402Client } from "@x402/core/client";
import { ExactEvmScheme } from "@x402/evm/exact/client";
import { wrapFetchWithPayment } from "@x402/fetch";
import { privateKeyToAccount } from "viem/accounts";

const privateKey = process.env.EVM_PRIVATE_KEY as `0x${string}` | undefined;

if (!privateKey) {
  throw new Error("Set EVM_PRIVATE_KEY");
}

const signer = privateKeyToAccount(privateKey);
const client = new x402Client();
client.register("eip155:*", new ExactEvmScheme(signer));

const fetchWithPayment = wrapFetchWithPayment(fetch, client);
const response = await fetchWithPayment("https://api.example.com/weather");

if (!response.ok) {
  throw new Error(`Request failed with status ${response.status}`);
}

console.log(await response.json());
```

<Warning>
  Do not treat a successful transaction receipt by itself as proof that a request was paid. Verification must bind the signed payload to the required network, asset, amount, recipient, resource, and validity window. Use the x402 middleware and a compatible facilitator, or implement the complete verification and settlement rules when you self-facilitate.
</Warning>

## Production checks

* Use HTTPS so intermediaries cannot read or replace payment headers.
* Keep buyer wallet keys in a secret manager or another server-side secret store. Do not ship a private key in browser code.
* Confirm facilitator support for Pacific-1 or Atlantic-2 before you deploy.
* Test rejected signatures, expired authorizations, failed settlement, and insufficient balances.
* Fulfill the protected request only after x402 reports a valid payment.

## Migrate from v1

The deprecated `@sei-js/x402*` packages implement the v1 protocol. Migrating requires more than changing package names.

| v1                                   | v2                                       |
| ------------------------------------ | ---------------------------------------- |
| `X-PAYMENT` request header           | `PAYMENT-SIGNATURE`                      |
| `X-PAYMENT-RESPONSE` response header | `PAYMENT-RESPONSE`                       |
| Network names such as `sei-testnet`  | CAIP-2 identifiers such as `eip155:1328` |
| `x402Version: 1`                     | `x402Version: 2`                         |

Use the official [x402 v1-to-v2 migration guide](https://docs.x402.org/guides/migration-v1-to-v2) to update client construction, server middleware, payment schemes, headers, and network identifiers.

## Resources

<CardGroup cols={2}>
  <Card title="x402 documentation" icon="book" href="https://docs.x402.org">
    Read the upstream protocol and SDK documentation.
  </Card>

  <Card title="x402 GitHub repository" icon="github" href="https://github.com/x402-foundation/x402">
    Review source code, examples, and releases.
  </Card>

  <Card title="Seller quickstart" icon="store" href="https://docs.x402.org/getting-started/quickstart-for-sellers">
    Protect an API or web resource with x402.
  </Card>

  <Card title="Buyer quickstart" icon="wallet" href="https://docs.x402.org/getting-started/quickstart-for-buyers">
    Add automatic payment handling to a client.
  </Card>

  <Card title="Client and server roles" icon="arrows-left-right" href="https://docs.x402.org/core-concepts/client-server">
    Follow the complete request and payment lifecycle.
  </Card>

  <Card title="Facilitators" icon="server" href="https://docs.x402.org/core-concepts/facilitator">
    Learn how verification and settlement services work.
  </Card>
</CardGroup>