x402-client

x402 Client SDK (@fastxyz/x402-client) — pays for HTTP resources protected by the x402 payment protocol.

GitHub: fastxyz/fast-sdk

What You Can Do

The x402 Client SDK is used by consumers of paid HTTP APIs. It handles the full payment flow so you can access x402-protected resources as naturally as a free endpoint:

• Pay for protected resources — respond to a 402 Payment Required challenge and receive the paid response automatically

• Auto-bridge Fast USDC to EVM USDC — when an EVM-side payment is required and the EVM wallet is short, the SDK can bridge supported Fast-side funds before retrying

• Dry-run payment inspection — ask the server what payment it requires before spending anything; useful for showing users a price estimate upfront

• Retries after payment — if a request gets a 402, the SDK pays, attaches the payment header, and retries in a single call

Installation

Install from npm as @fastxyz/x402-client. For the exact install command and current integration examples, use the package README on GitHub.

Architecture

The main entry point is x402Pay() — a payment-aware replacement for fetch that handles the full 402 flow automatically.

Concept	Description
Payment requirement	The 402 Payment Required response contains a structured description of what must be paid: amount, asset, recipient address, and a network-specific payment identifier
Payment header	The paid retry includes an X-PAYMENT header produced by the SDK for the selected payment network
Auto-bridge	In supported flows, the SDK can bridge Fast-side USDC to EVM-side USDC before retrying a request
Dry-run	Request the payment requirement without spending anything

How the Payment Flow Works

x402 is a protocol layer on top of HTTP — it works with any framework and any language, as long as both client and server speak the protocol.

Client                              Server
  │                                    │
  │  1. GET /resource                  │
  │ ─────────────────────────────────►│
  │                                    │
  │  2. 402 Payment Required          │
  │     { amount: 1000, asset: USDC,  │
  │       recipient: fast1...,        │
  │       description: "API access" } │
  │ ◄─────────────────────────────────│
  │                                    │
  │  3. SDK pays on Fast network      │
  │     (signs + submits tx)           │
  │                                    │
  │  4. GET /resource                 │
  │     X-PAYMENT: <payment payload>  │
  │ ─────────────────────────────────►│
  │                                    │
  │  5. 200 OK + resource data        │
  │ ◄─────────────────────────────────│

Steps in detail:

1. Initial request — Client makes a normal HTTP request to the protected endpoint

2. 402 response — Server responds with HTTP 402 and a JSON body describing the payment requirement (amount, asset, recipient, memo)

3. Payment — Client SDK authorizes a payment on the Fast network for the required amount to the specified recipient

4. Header attachment — After the SDK prepares payment for the selected network, it attaches the X-PAYMENT header to the retry request

5. Retry — Client re-requests the same resource with the payment header included

6. 200 response — Server verifies the payment through its x402 flow and returns the resource

Key Design Notes

• The SDK never stores credentials — provide your Fast signer per-request or via a secure token store

• Payments are non-refundable — the server is obligated to deliver the resource once payment is confirmed, but there is no reversal mechanism

• The X-PAYMENT header is an opaque protocol payload — don't parse it directly; the SDK manages it

---

For complete API documentation, full code examples, supported payment assets, error handling, and configuration options, see the x402-client README on GitHub.