<!--
Parallel Documentation — this page, as markdown.
Index of every page: https://docs.parallel.best/llms.txt
The whole documentation in one file: https://docs.parallel.best/llms-full.txt
-->

# Accept stablecoins in 5 minutes

This guide adds stablecoin payment support to an API. The same pattern works for Express, Next.js, Fastify, and Hono.

## 1. Install the middleware

```bash
npm install @parallel-protocol/x402
```

:::warning
Use version 0.8.2 or later. Since 1 October 2026 the facilitator settles a payment only when the settle presents the token it issued at verify, and versions before 0.8.0 do not send it: their settlements are refused with `SETTLE_TOKEN_REQUIRED`, and the agent gets a `402` instead of your response. Version 0.8.1 adds the facilitator URL checks of step 2, and 0.8.2 tells the agent to check with you before paying again for the reasons listed in the error codes.
:::

Install your framework separately — they are optional peer dependencies:

```bash
npm install express   # or: next · fastify · hono
```

## 2. Add the middleware

Point the middleware at the facilitator, then declare which routes are paid, at what price, on which network, and where funds should settle.

Write the facilitator's URL with https, as below. Since version 0.8.1, the SDK refuses any other URL with an `X402ConfigError` when the middleware is created, except plain http on `localhost`, `127.0.0.1` and `[::1]`: `http://agents.parallel.best` is refused. The SDK calls that address only and never follows a redirect, which fails the call with `FACILITATOR_UNAVAILABLE`.

#### Express

```ts
import express from "express";
import { paymentMiddleware } from "@parallel-protocol/x402/express";

const app = express();

app.use(
  paymentMiddleware({
    facilitator: { url: "https://agents.parallel.best" },
    routes: {
      "/api/data": { price: "0.01", network: "base", payTo: "0xYourAddress" },
    },
  }),
);

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

app.listen(3000);
```

#### Next.js

```ts
// app/api/data/route.ts
import { NextResponse } from "next/server";
import { withPayment } from "@parallel-protocol/x402/next";

const config = {
  facilitator: { url: "https://agents.parallel.best" },
  routes: {
    "/api/data": { price: "0.10", network: "ethereum", payTo: "0xYourAddress" as const },
  },
};

export const GET = withPayment(config, async (req) => {
  return NextResponse.json({ data: "protected content" });
});
```

#### Fastify

```ts
import Fastify from "fastify";
import { paymentMiddleware } from "@parallel-protocol/x402/fastify";

const app = Fastify();

await app.register(
  paymentMiddleware({
    facilitator: { url: "https://agents.parallel.best" },
    routes: {
      "/api/data": { price: "0.05", network: "avalanche", payTo: "0xYourAddress" },
    },
  }),
);

app.get("/api/data", async () => ({ data: "protected content" }));
```

#### Hono

```ts
import { Hono } from "hono";
import { paymentMiddleware } from "@parallel-protocol/x402/hono";

const app = new Hono();

app.use(
  paymentMiddleware({
    facilitator: { url: "https://agents.parallel.best" },
    routes: {
      "/api/data": { price: "0.01", network: "base", payTo: "0xYourAddress" },
    },
  }),
);

app.get("/api/data", (c) => c.json({ data: "protected content" }));
```

That's it. Your API now charges $0.01 per request to `/api/data`. Agents pay in any [supported stablecoin](/agents/x402/concepts#supported-stablecoins) — funds settle directly to the wallet address you configured.

**No signup. No platform fee. Funds settle straight to your wallet.**

:::tip
`price` is a human amount (`"0.01"`). Each accepted token is priced with its own decimals automatically, from Parallel's on-chain token catalog — `"0.01"` invoices 0.01 USDp and 0.01 USDC on the same 402. Set `decimals` on a route only for a custom token the catalog doesn't know; an unknown token without it fails fast at startup. See the [route configuration](/agents/x402/api-reference#routeconfig).
:::

## 3. What happens behind the scenes

When an agent calls your endpoint with a signed payment header:

1. The middleware sends the payload to the facilitator's `/x402/verify` endpoint — an instant, off-chain check of the signature, the amount, the token and the recipient. A valid payment comes back with a settle token, which the middleware keeps in memory.
2. If valid, **your handler runs** and produces the response.
3. If your handler returns a 2xx, the middleware calls `/x402/settle` with that token — the on-chain transfer happens, once per payment.
4. If your handler fails, **no settlement happens** — the agent is not charged.
5. If the settlement fails, the agent gets a `402` with `PAYMENT_SETTLEMENT_FAILED` and a `reason` instead of your response. A settle that timed out or could not reach the facilitator is retried once first: repeating it is safe, since the facilitator answers with the recorded outcome. See the [error codes](/agents/x402/error-codes).

Read more: [The verify / settle flow](/agents/x402/verify-vs-settle).

## Next steps

* [Concepts: how routing, fees, and gas work](/agents/x402/concepts)
* [Migrate from Coinbase x402 in one line](/agents/recipes/migrate-from-coinbase-x402)
* [API reference](/agents/x402/api-reference)