> For the complete documentation index, see [llms.txt](https://docs.fast.xyz/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.fast.xyz/sdk-references/payment-protocol-adapters/x402-sdk/x402-server.md).

# 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
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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, and the optional `goal` query parameter:

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.