x402-server

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

GitHub: fastxyz/fast-sdkarrow-up-right

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 GitHubarrow-up-right.

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

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 GitHubarrow-up-right.

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 GitHubarrow-up-right.

Last updated

Was this helpful?