x402 payments for Express

Install and gate a route

Create a merchant account at paygate.arispay.app (or run `npx paygate init` for the account-free template). One knob — your merchant id — and the SDK fetches the rest of your configuration from api.arispay.app.

import express from "express";
import { paygate } from "paygate/express";

const app = express();
const pw = paygate({ merchantId: process.env.PAYGATE_MERCHANT_ID });

// $0.02 per request, settled in USDC on Base.
app.get("/api/search", pw({ priceCents: 2 }), (req, res) => {
  res.json({ results: ["…"] });
});

// Dynamic pricing against the live request.
app.post(
  "/api/analyse",
  pw({
    priceCents: (req) => (req.body.deep ? 50 : 10),
    description: "AI analysis",
  }),
  (req, res) => res.json({ ok: true }),
);

app.listen(3000);

What the middleware does on each request

Without an X-PAYMENT header it responds 402 with the x402 challenge body (price, asset, network, payTo, facilitator). With one, it verifies the payment with the facilitator before your handler runs, settles after it succeeds, and attaches the settlement receipt to `req.paygate` plus an X-Paygate-Receipt response header.

On the buyer side, any AI agent can pay your endpoint with `npx payagent pay <url>` or the payagent SDK — the 402 challenge your route now returns is the whole integration contract.

Scaffold instead of wiring by hand

If you are starting from zero, `paygate init` writes a runnable Express seller in one command. It defaults to Base Sepolia testnet; pass `--network base` when you are ready for mainnet.

npx paygate init --framework express --wallet 0xYourAddress \
  --route /api/search --price 2 --network base

Pricing guidance

• Prices are integer cents — the floor is 1 cent per request. Pick a price from your unit economics (compute + data cost per call, plus margin), not from subscription-tier arithmetic.
• Atomic, stateless endpoints convert best: one request, one result, one payment. If a route needs multi-step state, split the paid step out.
• You can change `priceCents` per deploy without breaking buyers — agents read the price from the 402 challenge on every request.

FAQ

Which assets and networks settle?

USDC and EURC on Base mainnet via the ArisPay facilitator (facilitator.arispay.app), which charges no facilitator fee. Testnet development uses Base Sepolia.

Does the middleware need a body parser before it?

Register paygate before any middleware that consumes the raw body on paid routes — payment verification reads headers, and misordered body parsers are the most common integration bug.

Do I have to custody crypto?

No. Settlement pays your wallet address directly on-chain; ArisPay never holds your funds on the SDK path.