Skip to main content

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.

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.
The Fireblocks x402 Facilitator turns HTTP 402 (“Payment Required”) into a working payment rail. A client signs an 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 to deploy.

​
What x402 is

x402 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

  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. 
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: 
curl http://localhost:3000/api/health
# {"status":"ok","role":"all","mechanisms":[...], …}
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.
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.
  • Integration — wire the facilitator into your merchant server, the payment processing API endpoints, transfer mechanisms, and pricing modes.
  • Operating and production — the config file, auth model, management API, CLI reference, Payment Instruction Integrity, production deployment, and operator responsibilities.
  • Repository — source code, issue tracker, releases.
  • ARCHITECTURE.md — internal source layout, repository conventions, and contributor-facing detail.
  • DISCLAIMER.md — operator-facing risk and compliance notices.
  • x402.org — the open protocol specification.