@xpaysh/x402

XPay facilitator for the x402 payment protocol — open, no API keys required.

Drop-in replacement for @coinbase/x402. Works with @x402/express and @x402/next middleware.

What is x402?

x402 is an open payment protocol built on HTTP 402 (Payment Required). It enables machine-to-machine payments over the internet — APIs can require payment per request, and clients (including AI agents) can pay automatically using USDC on Base.

The protocol requires a facilitator — a service that verifies and settles payments on-chain. This package provides a zero-config facilitator so you can start accepting x402 payments immediately.

What is a facilitator?

In the x402 protocol, a facilitator is a trusted third-party service that:

1. Verifies payment authorizations — checks that the payer has sufficient USDC balance and the EIP-3009 signature is valid
2. Settles payments on-chain — submits the transferWithAuthorization transaction to move USDC from payer to payee

The facilitator is non-custodial — it never holds funds. It only submits pre-signed transactions that transfer USDC directly from payer to payee on the Base blockchain.

Why XPay?

XPay runs the only open, no-auth-required x402 facilitator. Other facilitators require API keys or JWT tokens before you can use them. With XPay, you install the package and you're done.

| | XPay | Coinbase | PayAI | |---|---|---|---| | Auth required | None | CDP API keys | JWT token | | Setup time | 0 min | ~5 min | ~5 min | | Networks | Base, Base Sepolia | Base, Base Sepolia | Base, Base Sepolia | | Asset | USDC | USDC | USDC | | Custodial | No | No | No | | Open source | Yes | Yes | No | | x402 versions | v1 + v2 | v1 + v2 | v2 only |

Install

npm install @xpaysh/x402
# or
yarn add @xpaysh/x402
# or
pnpm add @xpaysh/x402
# or
bun add @xpaysh/x402

Quick start

The package exports a pre-configured facilitator object. Pass it to any x402 middleware to start accepting payments:

import { facilitator } from "@xpaysh/x402";
// That's it — no API keys, no configuration

Usage with Express

import express from "express";
import { paymentMiddleware } from "@x402/express";
import { facilitator } from "@xpaysh/x402";

const app = express();

app.use(
  paymentMiddleware(facilitator, "0xYourWalletAddress", {
    "/api/premium": {
      price: "$0.01",
      network: "base-sepolia",
      description: "Access premium endpoint",
    },
  }),
);

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

app.listen(3000);

Usage with Next.js

// middleware.ts
import { paymentMiddleware } from "@x402/next";
import { facilitator } from "@xpaysh/x402";

export const middleware = paymentMiddleware(facilitator, "0xYourWalletAddress", {
  "/api/premium": {
    price: "$0.01",
    network: "base-sepolia",
    description: "Access premium endpoint",
  },
});

export const config = {
  matcher: ["/api/premium"],
};

Usage with AI agents

AI agents can pay for x402-protected APIs automatically. When an agent receives an HTTP 402 response, it signs a USDC payment authorization and retries — the XPay facilitator verifies and settles the payment on-chain.

import { x402HTTPClient } from "@x402/core";

// Client-side: agent pays for API access
const client = new x402HTTPClient(walletSigner);
const response = await client.fetch("https://api.example.com/premium-data");

The facilitator handles the server side. No coordination needed between client and server SDKs — they communicate through standard HTTP headers.

Custom facilitator URL

If you're running your own facilitator instance, use the factory function:

import { createFacilitatorConfig } from "@xpaysh/x402";

const facilitator = createFacilitatorConfig({
  url: "https://my-facilitator.example.com",
});

API reference

facilitator

Pre-configured FacilitatorConfig pointing to https://facilitator.xpay.sh. No authentication needed. Use this directly with @x402/express or @x402/next middleware.

createFacilitatorConfig(options?)

Factory function to create a facilitator config with optional overrides.

| Option | Type | Default | Description | |--------|------|---------|-------------| | url | string | https://facilitator.xpay.sh | Facilitator service URL |

Returns a FacilitatorConfig object.

FacilitatorConfig

interface FacilitatorConfig {
  url: string;
  createAuthHeaders?: () => Promise<{
    verify: Record<string, string>;
    settle: Record<string, string>;
    supported: Record<string, string>;
  }>;
}

Compatible with the FacilitatorConfig type from @x402/core/http.

Supported networks

| Network | Chain ID | x402 identifier | Status | |---------|----------|-----------------|--------| | Base Mainnet | 8453 | eip155:8453 / base | Production | | Base Sepolia | 84532 | eip155:84532 / base-sepolia | Testnet |

Both x402 v1 (legacy string network names) and v2 (CAIP-2 identifiers) are supported.

Supported assets

| Asset | Mainnet address | Sepolia address | |-------|----------------|-----------------| | USDC | 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913 | 0x036CbD53842c5426634e7929541eC2318f3dCF7e |

How it works

Client (AI agent / browser)          Your API server            XPay Facilitator
        │                                  │                          │
        ├─── GET /api/premium ────────────►│                          │
        │                                  │                          │
        │◄── 402 Payment Required ─────────┤                          │
        │    (payment requirements)        │                          │
        │                                  │                          │
        ├─── GET /api/premium ────────────►│                          │
        │    (X-PAYMENT header with        │                          │
        │     signed USDC authorization)   │                          │
        │                                  ├─── POST /verify ────────►│
        │                                  │◄── { isValid: true } ────┤
        │                                  │                          │
        │◄── 200 OK (premium content) ─────┤                          │
        │                                  │                          │
        │                                  ├─── POST /settle ────────►│
        │                                  │◄── { success: true, ─────┤
        │                                  │      transaction: 0x.. } │

Migrating from @coinbase/x402

Replace the import — everything else stays the same:

- import { facilitator } from "@coinbase/x402";
+ import { facilitator } from "@xpaysh/x402";

No CDP API keys needed. No environment variables to configure.

Facilitator endpoints

The XPay facilitator exposes these endpoints at https://facilitator.xpay.sh:

| Endpoint | Method | Description | |----------|--------|-------------| | /health | GET | Service health check | | /supported | GET | List supported networks and schemes | | /verify | POST | Verify a payment authorization | | /settle | POST | Settle a payment on-chain |

Links

• XPay x402 Facilitator
• x402 Protocol specification
• Facilitator health check
• GitHub
• @x402/express middleware
• @x402/next middleware

License

MIT