> ## Documentation Index
> Fetch the complete documentation index at: https://developers.fireblocks.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Overview

> Charge for any HTTP endpoint with a one-shot cryptographic signature. Verify and settle x402 payments on-chain through Fireblocks.

<Note>
  **Open-source or hosted? This page describes the open-source facilitator that you run yourself.** Fireblocks also offers a **fully managed, fully secured hosted x402 Facilitator** — production-grade security, operational support, monitoring, and a managed endpoint, with no infrastructure for you to run or upgrade. [Talk to us about early access](https://www.fireblocks.com/#request-demo).
</Note>

The Fireblocks x402 Facilitator turns HTTP 402 ("Payment Required") into a working payment rail. A client signs an [EIP-712](https://eips.ethereum.org/EIPS/eip-712) message authorizing a specific transfer; your merchant server calls the facilitator to verify the signature and settle the on-chain transfer through Fireblocks. Customer traffic never passes through the facilitator — your server keeps serving its own requests.

The facilitator is open-source under Apache License 2.0. Clone it from [github.com/fireblocks/x402-facilitator](https://github.com/fireblocks/x402-facilitator) to deploy.

## What x402 is

[x402](https://x402.org) is an open protocol that gives the long-reserved HTTP 402 status code a job. A server responds **402** with a price quote; the client signs an EIP-712 message authorizing exactly that payment; the client retries the same request with a `payment-signature` header; the server verifies and delivers the resource.

The protocol is designed for machine-to-machine and agent-to-service commerce: API monetization, pay-per-call data, agentic checkout, content metering. Payments are denominated in ERC-20 tokens (commonly USDC) on EVM-compatible networks. The signature authorizes a single transfer of a specific amount — there is no long-lived approval, no subscription state, and no payment account to maintain.

### Where Fireblocks fits

In the x402 model, a **facilitator** is the service merchants call to verify signatures and settle payments. Fireblocks provides the facilitator implementation and the on-chain settlement layer:

* The facilitator validates the client's EIP-712 signature off-chain.
* When the merchant requests settlement, the facilitator submits a `CONTRACT_CALL` transaction through Fireblocks, drawing from the merchant's vault account.
* Raw private keys never leave Fireblocks. The facilitator process holds no signing material.

The merchant runs their own server and middleware, returns the 402 themselves, and calls the facilitator at two well-defined decision points. The facilitator is API-only — it does not proxy customer traffic.

## What's included

Out of the box, the facilitator gives you:

* **API-only surface** — `/api/payments/{create,verify,settle}`, `/api/discovery/*`, and a management API. No reverse proxy of merchant traffic.
* **Fireblocks settlement** — on-chain transfers via `CONTRACT_CALL`. No raw private keys in the facilitator process.
* **Pluggable payment store** — in-memory (tests), SQLite (default), or PostgreSQL.
* **Four transfer mechanisms** — `eip-3009` (USDC-style), `permit2` and `upto-permit2` (any ERC-20), `erc7710` (smart-account delegation).
* **Multi-configuration** — one deployment can host many merchants, each with their own Fireblocks vault, products, and API keys.
* **Two auth surfaces** — persistent API keys (opaque) for payment processing; JWT (HS256 or JWKS) for the management API. Never mixed.
* **Role-based profile** — run the same binary as `processing`, `management`, or `all`.
* **Remote admin CLI** (`x402`) — pure HTTP client for `/api/admin/*`. Authenticates with a JWT minted locally. Works from a laptop, CI, or a dashboard.
* **Local bootstrap** (`npm run setup`) — scaffold config, rotate JWT secrets, import legacy SQLite, all filesystem-only.
* **Testnet-only by default** — the facilitator refuses to boot or register mainnet assets unless `X402_ALLOW_MAINNET=true`.

## How a payment flows

```mermaid theme={"system"}
sequenceDiagram
    participant C as Client
    participant M as Merchant server
    participant F as Facilitator
    participant FB as Fireblocks

    C->>M: GET /premium
    M-->>C: 402 Payment Required<br/>{ amount, asset, payTo }
    Note over C: Sign EIP-712 authorization
    C->>M: GET /premium<br/>+ payment-signature
    M->>F: POST /api/payments/verify
    F-->>F: Validate signature off-chain
    F-->>M: { isValid: true, payer }
    M->>F: POST /api/payments/settle
    F->>FB: CONTRACT_CALL (token transfer)
    FB-->>F: Transaction confirmed
    F-->>M: { success, txHash }
    M-->>C: 200 OK + PAYMENT-RESPONSE
```

1. The client sends a normal HTTP request to your server.
2. Your middleware sees no `payment-signature` header and returns **402** with a JSON quote describing the amount, asset, and recipient.
3. The client signs an EIP-712 message authorizing exactly that transfer. No gas, no on-chain transaction at this stage.
4. The client retries the same request with `payment-signature: <base64>`.
5. Your middleware calls `POST /api/payments/verify` on the facilitator. If the signature is valid, it calls `POST /api/payments/settle`, then returns the resource with a `PAYMENT-RESPONSE` header.

## Prerequisites

* Node.js 20 or later.
* A Fireblocks workspace with an API key, a vault account ID, and the PEM-format API secret file. If you are evaluating the facilitator locally and do not have Fireblocks yet, the server still starts with an empty config — you just cannot call `fireblocks test` or settle payments.

## Quick start

The walkthrough below takes you from a fresh clone to a running facilitator with one merchant configured.

```bash theme={"system"}
git clone https://github.com/fireblocks/x402-facilitator
cd x402-facilitator
npm install

# 1. Local bootstrap — scaffolds config/facilitator.json + secrets/jwt-hs256.key
npm run setup

# 2. Fill in Fireblocks credentials: edit config/facilitator.json
#    fireblocks.api_key           → your Fireblocks API key
#    fireblocks.api_secret_path   → path to your PEM (e.g. ./secrets/fireblocks.pem)

# 3. Start the facilitator
npm run dev                                     # facilitator on :3000

# 4. Build and install the remote CLI globally (one-time)
npm run build && npm link                       # puts `x402` on your PATH

# 5. Mint a local admin JWT and export it
npm run setup:admin-token -- --preset full --ttl 2h
export X402_ADMIN_TOKEN=<paste the token>

# 6. Activate Fireblocks vault wallets and cache the receiver addresses
x402 fireblocks test --create-missing

# 7. Import an asset from Fireblocks
x402 assets import USDC_BASECHAIN_ETH_TEST5_8SH8 \
    --transfer-mechanism eip-3009 \
    --eip712-name "USDC" --eip712-version 2 \
    --stable

# 8. Declare a product (USD-priced)
x402 products add --name "Premium" --endpoint /premium \
    --usd-price 0.01 --asset USDC_BASECHAIN_ETH_TEST5_8SH8

# 9. Mint a machine API key for the merchant server
x402 keys create --scopes process-payments --label my-merchant
#   → prints the key once; copy it into your merchant app's config
```

Verify the server is up:

```bash theme={"system"}
curl http://localhost:3000/api/health
# {"status":"ok","role":"all","mechanisms":[...], …}
```

<Warning>
  Never commit `config/facilitator.json` with real Fireblocks credentials, and never commit the PEM secret. Both belong in a secrets manager (for example, AWS Secrets Manager, GCP Secret Manager, or HashiCorp Vault) in any non-development deployment. The repository's `.gitignore` excludes both paths by default — confirm this remains true in your fork.
</Warning>

<Warning>
  Treat the merchant API key as a secret. The plaintext is returned **once** at creation; only a SHA-256 hash is persisted. Store it in a secrets manager and inject it into your merchant application at runtime — never hard-code it, never commit it, and never expose it through a client-side surface. If you lose a key, revoke it and mint a new one.
</Warning>

## What to read next

* [Integration](/docs/x402-facilitator-integration) — wire the facilitator into your merchant server, the payment processing API endpoints, transfer mechanisms, and pricing modes.
* [Operating and production](/docs/x402-facilitator-operations) — the config file, auth model, management API, CLI reference, Payment Instruction Integrity, production deployment, and operator responsibilities.

## Helpful Links

* [Repository](https://github.com/fireblocks/x402-facilitator) — source code, issue tracker, releases.
* [`ARCHITECTURE.md`](https://github.com/fireblocks/x402-facilitator/blob/main/ARCHITECTURE.md) — internal source layout, repository conventions, and contributor-facing detail.
* [`DISCLAIMER.md`](https://github.com/fireblocks/x402-facilitator/blob/main/DISCLAIMER.md) — operator-facing risk and compliance notices.
* [x402.org](https://x402.org) — the open protocol specification.