# x402-client

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

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

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