# x402-server

**GitHub:** [fastxyz/fast-sdk](https://github.com/fastxyz/fast-sdk/blob/main/packages/x402-server/README.md)

## 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](https://github.com/fastxyz/fast-sdk/blob/main/packages/x402-server/README.md).

## 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](/sdk-references/payment-protocol-adapters/x402-sdk/x402-facilitator.md)).

## 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](https://github.com/fastxyz/fast-sdk/blob/main/packages/x402-server/README.md).

## 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**](https://github.com/fastxyz/fast-sdk/blob/main/packages/x402-server/README.md)**.**


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.fast.xyz/sdk-references/payment-protocol-adapters/x402-sdk/x402-server.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.