# Overview

BlockPay ships as a set of npm packages under the `@blockpay402` scope. Each package covers one side of the protocol, so you install only what you need.

### Packages

| Package                    | Role                                                                                                                    | Install                          |
| -------------------------- | ----------------------------------------------------------------------------------------------------------------------- | -------------------------------- |
| `@blockpay402/core`        | Shared types, payload schemas, codecs, and the intent-signing helper. Used by every other package.                      | `npm i @blockpay402/core`        |
| `@blockpay402/server`      | Framework-agnostic middleware for Resource Servers.                                                                     | `npm i @blockpay402/server`      |
| `@blockpay402/express`     | Express adapter on top of `@blockpay402/server`.                                                                        | `npm i @blockpay402/express`     |
| `@blockpay402/next`        | Next.js Route Handler and Middleware adapter.                                                                           | `npm i @blockpay402/next`        |
| `@blockpay402/client`      | HTTP clients for paying x402 endpoints (plain `fetch` wrapper, `axios` interceptor).                                    | `npm i @blockpay402/client`      |
| `@blockpay402/agent`       | Higher-level helpers for AI agents: budget controls, per-endpoint caps, approvals.                                      | `npm i @blockpay402/agent`       |
| `@blockpay402/facilitator` | Reference Facilitator service you can deploy yourself.                                                                  | `npm i @blockpay402/facilitator` |
| `@blockpay402/sui`         | Sui-specific primitives: key loading, PTB builders, coin selection. Used by the other packages; rarely needed directly. | `npm i @blockpay402/sui`         |

All packages ship both ESM and CJS builds, full TypeScript types, and work in Node 20+ and modern browsers (the `server` and `facilitator` packages are Node-only).

### Picking a starting point

* Building an **API or MCP tool** that should charge per call → start with the Server SDK.
* Building an **agent or client** that needs to pay for paid endpoints → start with the Client SDK.
* Running **verification and settlement infrastructure** for others → start with the Facilitator SDK.
* Just want to see it work end-to-end → jump to the Quickstart.

### Prerequisites

* **Node.js 20+** (24+ recommended).
* A **Sui wallet** with a keypair you control. For servers, this is the merchant wallet that receives payments; for clients, it's the one that pays. Fund it with testnet SUI and testnet USDC before starting on `sui-testnet`.
* A **Sui RPC endpoint**. The public endpoints work fine for development. For production, run your own or use a provider.
* A **Facilitator URL**. You can point at a public BlockPay Facilitator during development, or run your own.

### Configuration conventions

Every package reads configuration from constructor options, with optional fallback to environment variables:

```
BLOCKPAY_FACILITATOR_URL=https://facilitator.blockpay.gg
BLOCKPAY_NETWORK=sui-testnet
BLOCKPAY_RPC_URL=https://fullnode.testnet.sui.io:443
BLOCKPAY_RECEIVE_ADDRESS=0xabc...def     # servers
BLOCKPAY_PRIVATE_KEY=suiprivkey1...      # clients / facilitators only
```

Never commit private keys. Load them from a secret manager in production.


---

# 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.blockpay.gg/integration/overview.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.