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.
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.
In the x402 protocol, a facilitator is a trusted third-party service that:
- Verifies payment authorizations — checks that the payer has sufficient USDC balance and the EIP-3009 signature is valid
- Settles payments on-chain — submits the
transferWithAuthorizationtransaction 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.
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 |
npm install @xpaysh/x402
# or
yarn add @xpaysh/x402
# or
pnpm add @xpaysh/x402
# or
bun add @xpaysh/x402The 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 configurationimport 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);// 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"],
};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.
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",
});Pre-configured FacilitatorConfig pointing to https://facilitator.xpay.sh. No authentication needed. Use this directly with @x402/express or @x402/next middleware.
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.
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.
| 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.
| Asset | Mainnet address | Sepolia address |
|---|---|---|
| USDC | 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913 |
0x036CbD53842c5426634e7929541eC2318f3dCF7e |
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.. } │
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.
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 |
- XPay x402 Facilitator
- x402 Protocol specification
- Facilitator health check
- GitHub
- @x402/express middleware
- @x402/next middleware
MIT