x402 middleware guide

x402 middleware lets you charge per API request. When a request arrives without valid payment, the middleware returns 402 Payment Required with payment details. The client pays and retries — all transparent to your application code.

Prerequisites

@arcenpay/node installed
An active ArcenPay API key
For production: a Redis-compatible nonce store for replay protection

Basic setup

import express from "express";
import { x402Middleware } from "@arcenpay/node";

const app = express();

app.use("/api/protected", x402Middleware({
  planId: "starter",
  ratePerCall: "0.001",  // $0.001 USDC per request
  chainId: 84532,         // Base Sepolia (or 677 BOT, 9100000 Solana, 5042002 Arc)
  network: "base-sepolia",
}));

app.get("/api/protected/data", (req, res) => {
  const { payment } = req.x402;
  console.log(`Paid ${payment.amount}`);
  res.json({ data: "protected" });
});

Production setup

For production, use a Redis-backed nonce store for reliable replay protection:

import { x402Middleware, RedisNonceStore } from "@arcenpay/node";

app.use("/api/protected", x402Middleware({
  planId: "pro",
  ratePerCall: "0.001",
  chainId: 677,           // BOT Chain Mainnet (or 84532 Base Sepolia)
  network: "bot-mainnet", // auto-inferred from chainId; explicit here
  nonceStore,             // RedisNonceStore instance
  maxPaymentAgeMs: 300000, // 5 minutes
  nonceTtlMs: 600000,     // 10 minutes
}));

Use RedisNonceStore for multi-instance production deployments. For local development, omit the option — the middleware falls back to an in-memory store.

Middleware options

Option	Type	Required	Default	Description
`planId`	`string`	Yes	—	Plan ID for pricing reference.
`ratePerCall`	`string`	Yes	—	Price per call in USDC (e.g., `"0.001"`).
`chainId`	`number`	No	`84532`	Chain ID for on-chain validation: `84532` (Base Sepolia), `677` (BOT Chain), `9100000` (Solana Mainnet), `5042002` (Arc Testnet).
`network`	`string`	No	Inferred	Network identifier returned to clients (`base-sepolia`, `bot-mainnet`, `arc-testnet`, …). Auto-inferred from `chainId`.
`rpcUrl`	`string`	No	—	RPC URL for on-chain validation.
`payTo`	`string`	No	Platform fee collector	Wallet address that receives settled payments.
`nonceStore`	`NonceStore`	No	`InMemoryNonceStore`	Pluggable nonce store for anti-replay. Pass `RedisNonceStore` for production.
`maxPaymentAgeMs`	`number`	No	`300000`	Max age of payment timestamp (5 minutes default).
`nonceTtlMs`	`number`	No	`600000`	TTL for nonce deduplication (10 minutes default).
`failOpenOnBalanceCheck`	`boolean`	No	`false`	Allow requests when balance check fails. Keep `false` in production.
`settlePayment`	`function`	No	—	Optional settlement hook called after payment verification.

Payment flow

Client sends a request to your protected endpoint.
Middleware returns 402 Payment Required with payment details in the response body.
Client’s agent SDK processes the payment on-chain.
Client retries with payment signature headers.
Middleware verifies the payment and forwards the request to your handler.
Your handler receives req.x402.payment with the payment details.

Testing x402 locally with ArcenAgent

Set up a test endpoint and use the agent SDK to verify:

import { ArcenAgent } from "@arcenpay/agent";

const agent = new ArcenAgent({
  privateKey: process.env.AGENT_PRIVATE_KEY!,
  rpcUrl: "https://rpc.botchain.ai",
  chainId: 677, // or Solana (9100000), Arc (5042002), Base Sepolia (84532)
});

const response = await agent.fetch("http://localhost:3000/api/protected");
const result = await response.json();
console.log("Protected API response:", result);

The agent automatically handles the 402 response, signs payment, and retries transparently.

Next steps

Agent payments guide — the client side of x402 payments
Agent SDK overview — full agent SDK reference
Webhooks — listen for payment events from x402 transactions

Get started

Core concepts

Guides

Integrations

x402 middleware guide

Prerequisites

Basic setup

Production setup

Middleware options

Payment flow

Testing x402 locally with ArcenAgent

Next steps

​Prerequisites

​Basic setup

​Production setup

​Middleware options

​Payment flow

​Testing x402 locally with ArcenAgent

​Next steps

Prerequisites

Basic setup

Production setup

Middleware options

Payment flow

Testing x402 locally with ArcenAgent

Next steps