x402-server

x402 Server SDK (@fastxyz/x402-server) — middleware for protecting HTTP resources with x402 payment requirements.

GitHub: fastxyz/fast-sdk

What You Can Do

The x402 Server SDK is used by API providers who want to charge for access to their HTTP endpoints. It adds payment requirements to any route and verifies incoming payment proofs:

• Protect routes with payments — add a price to any endpoint; unauthenticated requests get a 402 instead of the resource

• Verify payment payloads — confirm that incoming requests include a valid X-PAYMENT header before releasing the resource

• Configure per-route pricing — different endpoints can have different prices or no price at all

• Accept any x402 asset — USDC, USDT, FAST, or any token the Fast network supports, as configured

• Framework-agnostic — works with Express, Fastify, Hono, and any Node.js HTTP framework that supports middleware

Installation

Install from npm as @fastxyz/x402-server. For the exact install command and framework-specific examples, use the package README on GitHub.

Architecture

The server SDK is implemented as middleware — a function that wraps each protected route. It intercepts incoming requests, checks for an x402 payment header, and either lets the request through or responds with 402 Payment Required.

Component	Role
Route config	Defines the price (amount + asset) for each protected route
Middleware	Intercepts request, checks proof, enforces payment
Proof verifier	Calls the facilitator to confirm the payment payload is valid for the configured requirement
402 response builder	Serializes the payment requirement into the structured body the client SDK reads

The middleware is stateless — it doesn't track payments itself. Verification is delegated to the facilitator service (see x402 Facilitator).

How Requests Are Protected

Incoming Request
       │
       ▼
  Is route protected?
       │
   No │───► Pass through to handler
       │
  Yes
       │
       ▼
  Has X-PAYMENT header?
       │
   No  │───► Return 402 with payment requirement
       │       { amount, asset, recipient, description }
       │
  Yes
       │
       ▼
  Verify proof via facilitator
       │
   Invalid ──► Return 403 Forbidden
       │
   Valid
       │
       ▼
  Pass through to handler

Pricing Models

Route configs support common pricing patterns:

Model	How to Configure
Flat per-request	Set fixed amount on the route
Tiered by plan	Multiple middleware configs on different paths (e.g. /api/v1/, /api/v2/)
Unauthenticated free, paid auth	Apply middleware only to authenticated routes
Hybrid (free quota + paid)	Check a custom header or query param in your handler before the 402 is triggered

Integration with Frameworks

The server SDK provides middleware that integrates with Express, Fastify, Hono, and other Node.js frameworks. For framework-specific integration examples and setup code, see the x402-server README on GitHub.

Key Design Notes

• Your server doesn't need its own payment database — proof verification is done by the facilitator service, which tracks payment state off-chain

• Non-blocking — the facilitator call is fast (typically <100ms); it does not touch your database

• Idempotency — the same proof cannot be used twice; the facilitator rejects proof reuse attempts

• Payment is per-request — each request to a protected route requires its own payment (no session tokens from a single payment)

---

For complete API documentation, middleware options, framework-specific examples, error codes, and deployment details, see the x402-server README on GitHub.