x402

What Is x402?

x402 is an open payment protocol, originally developed by Coinbase, that gives the long-reserved HTTP 402 Payment Required status code a concrete, blockchain-native meaning: if you want this resource, pay for it. No accounts, API keys, or checkout flows. Just plain HTTP.

This matters for AI agents because they need to pay for resources programmatically. x402 makes payment a first-class part of the web stack, so an agent can discover a price, sign a payment, and retry the HTTP request automatically.

The Three Roles

How the Protocol Works

{
  "x402Version": 2,
  "resource": {
    "url": "https://api.example.com/data",
    "description": "Example data",
    "mimeType": "application/json"
  },
  "accepts": [{
    "scheme": "exact",
    "network": "eip155:9745",
    "amount": "1000000",
    "asset": "0xB8CE59FC3717ada4C02eaDF9682A9e934F625ebb",
    "payTo": "0x1111111111111111111111111111111111111111",
    "maxTimeoutSeconds": 60,
    "extra": { "name": "USDT0", "version": "1", "decimals": 6 }
  }],
  "extensions": {}
}

For the full protocol specification, see x402.org and the x402 GitHub repository.

How to Use x402 With WDK

WDK wallets work as drop-in client signers for the versions used below. WalletAccountEvm beta.19 satisfies the x402 2.26.0 client signer interface directly. Each integration still needs a configured RPC, a supported x402 scheme and network, and an asset contract that implements the selected authorization method.

This guide walks through three things:

1. Client (Buyer) - Pay for x402-protected resources using a WDK wallet
2. Server with Hosted Facilitator - Accept x402 payments by delegating verification and settlement to a third-party facilitator
3. Server with Self-Hosted Facilitator - Assess the current community adapter's version constraints before adopting it

Recommended Chains

The EVM exact scheme can be configured for a CAIP-2 EVM network when the chosen token implements EIP-3009 and the client, resource server, and facilitator all support that scheme and network. The examples use Plasma and Stable. Buyers sign an EIP-3009 authorization and do not submit an ERC-20 approval or pay settlement gas; they still need enough USD₮0, and the facilitator needs the chain's native gas token.

Client: Paying for Resources

npm install @tetherto/wdk-wallet-evm@1.0.0-beta.19 @x402/fetch@2.26.0 @x402/evm@2.26.0

import WalletManagerEvm from "@tetherto/wdk-wallet-evm";

const account = await new WalletManagerEvm(process.env.SEED_PHRASE, {
  provider: "https://rpc.plasma.to", // or "https://rpc.stable.xyz"
}).getAccount();

import { x402Client, wrapFetchWithPayment } from "@x402/fetch";
import { registerExactEvmScheme } from "@x402/evm/exact/client";

const client = new x402Client();
registerExactEvmScheme(client, { signer: account });

const fetchWithPayment = wrapFetchWithPayment(fetch, client);

const response = await fetchWithPayment("https://api.example.com/weather", {
  method: "GET",
});

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

const data = await response.json();
console.log("Response:", data);

Getting USD₮0 on Plasma or Stable

Before making a payment, fund the buyer with USD₮0 on the selected network. If you need to bridge a supported source token, follow the USD₮0 bridge guide for the current route, spender, bounded allowance, quote, and settlement steps.

Server: Accepting Payments (Hosted Facilitator)

Your server delegates verification and settlement to a hosted facilitator. You never interact with the chain directly.

Before enabling payments, request GET https://x402.semanticpay.io/supported as described in the facilitator API and confirm that the response advertises x402 v2, your payment scheme, and your network. If the request fails or that combination is absent, do not enable the hosted integration. Select a facilitator verified for the required x402 version, scheme, and network; also review the current self-hosting limitations.

npm install @tetherto/wdk-wallet-evm@1.0.0-beta.19 @x402/express@2.26.0 @x402/evm@2.26.0 @x402/core@2.26.0 express@5.2.1 dotenv@17.2.3

import WalletManagerEvm from "@tetherto/wdk-wallet-evm";

const account = await new WalletManagerEvm(process.env.SEED_PHRASE, {
  provider: "https://rpc.plasma.to", // or "https://rpc.stable.xyz"
}).getAccount();

const sellerAddress = await account.getAddress();

import { HTTPFacilitatorClient } from "@x402/core/server";

const facilitatorClient = new HTTPFacilitatorClient({
  url: "https://x402.semanticpay.io/",
});

import express from "express";
import { paymentMiddleware, x402ResourceServer } from "@x402/express";
import { ExactEvmScheme } from "@x402/evm/exact/server";

const PLASMA_NETWORK = "eip155:9745";   // or "eip155:988" for Stable
const USDT0_PLASMA = "0xB8CE59FC3717ada4C02eaDF9682A9e934F625ebb";   // or "0x779Ded0c9e1022225f8E0630b35a9b54bE713736" on Stable

const app = express();

app.use(
  paymentMiddleware(
    {
      "GET /weather": {
        accepts: [
          {
            scheme: "exact",
            network: PLASMA_NETWORK,
            price: {
              amount: "1000", // $0.001 (6 decimals)
              asset: USDT0_PLASMA,
              extra: { name: "USDT0", version: "1", decimals: 6 },
            },
            payTo: sellerAddress,
          },
        ],
        description: "Weather data",
        mimeType: "application/json",
      },
    },
    new x402ResourceServer(facilitatorClient).register(
      PLASMA_NETWORK,
      new ExactEvmScheme(),
    ),
  ),
);

// Gated - requires payment
app.get("/weather", (req, res) => {
  res.json({ weather: "sunny", temperature: 70 });
});

// Not gated - no payment config
app.get("/health", (req, res) => {
  res.json({ status: "ok" });
});

app.listen(4021);

Multi-Chain (Plasma + Stable)

To accept payments on both chains, add both networks to the accepts array and register both with the resource server. The default x402 client selects the first compatible payment option; it does not select by wallet balance. Fund that network or provide an application-owned payment selector.

const NETWORKS = {
  plasma: { network: "eip155:9745", usdt0: "0xB8CE59FC3717ada4C02eaDF9682A9e934F625ebb" },
  stable: { network: "eip155:988",  usdt0: "0x779Ded0c9e1022225f8E0630b35a9b54bE713736" },
};

const resourceServer = new x402ResourceServer(facilitatorClient)
  .register(NETWORKS.plasma.network, new ExactEvmScheme())
  .register(NETWORKS.stable.network, new ExactEvmScheme());

// In paymentMiddleware config:
// accepts: [
//   { scheme: "exact", network: NETWORKS.plasma.network, price: priceOnChain("plasma"), payTo },
//   { scheme: "exact", network: NETWORKS.stable.network, price: priceOnChain("stable"), payTo },
// ]

Lifecycle Events

For facilitator-specific notifications, consult the Semantic facilitator API and confirm support with the provider. Use verification and settlement responses to decide whether a payment succeeded.

Server: Self-Hosted Facilitator (In-Process)

The @semanticio/wdk-wallet-evm-x402-facilitator community module is intended to adapt a WDK EVM account to the x402 facilitator signer interface. Verify an exact compatible package set before using it for in-process verification and settlement.

The published package and its source repository are the primary references. The related SemanticPay demo targets an older, differently named GitHub dependency and x402 2.2.0, so it is not a runnable example for the npm package and versions documented above.

Summary

Resources

• x402 Protocol Spec - The open standard specification
• x402 GitHub - Reference implementations and examples
• Semantic Facilitator Docs - API reference for the hosted facilitator
• Self-Hosted Facilitator Module - Beta community adapter; check its exact dependencies before use
• x402-usdt0 Demo - Historical x402 2.2.0 demo source, not the package set used above
• WDK EVM Wallet Module - WDK EVM wallet documentation
• USD₮0 Deployments - Contract addresses on all chains
• EIP-3009 Specification - The token-neutral authorization standard used here for signed USD₮0 transfers; the facilitator submits the authorization on-chain