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.

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.

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.

1. Request the resource

   The client sends a normal HTTP request to the paid endpoint.

2. Receive the payment requirements

   The server returns 402 Payment Required. Its PAYMENT-REQUIRED header describes the accepted scheme, amount, asset, network, recipient, and resource.

3. Authorize payment

   The client selects an accepted payment option and signs the payment payload with its wallet.

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

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

6. Return the resource

   After successful settlement, the server returns the requested data and includes settlement details in the PAYMENT-RESPONSE header.

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 charges a fixed amount for each request.
• upto lets the client authorize a maximum amount while the seller settles the actual usage.
• 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

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.

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.

Fetch client

npm install @x402/core @x402/evm @x402/fetch viem

Axios client

npm install @x402/core @x402/evm @x402/axios viem

Express server

npm install @x402/core @x402/evm @x402/express

Hono server

npm install @x402/core @x402/evm @x402/hono

Next.js server

npm install @x402/core @x402/evm @x402/next

Follow the upstream seller quickstart or buyer quickstart 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.

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.

See the upstream 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.

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.

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());

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.

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 to update client construction, server middleware, payment schemes, headers, and network identifiers.

Resources

x402 documentation

Read the upstream protocol and SDK documentation.

x402 GitHub repository

Review source code, examples, and releases.

Seller quickstart

Protect an API or web resource with x402.

Buyer quickstart

Add automatic payment handling to a client.

Client and server roles

Follow the complete request and payment lifecycle.

Facilitators

Learn how verification and settlement services work.