Skip to main content
Before you stand up an x402 facilitator or agent, set up a Fireblocks workspace and gather testnet funds. This page lists what you need and walks through getting testnet USDC and gas, the step where evaluations most often stall. Once these are in place, follow the x402 Quickstart to a first settled payment.

​
Software

​
Fireblocks workspace

You need a Fireblocks workspace to settle payments (selling) or to sign them (buying). If you only want to read code or run the facilitator with an empty config, you can start the server without credentials, but you cannot test signing or settle until Fireblocks is connected.

​
Create a scoped API user

Create a dedicated API user rather than reusing a workspace-admin key. Follow the Fireblocks guides on creating a new API user and choosing user roles. The process gives you two things the facilitator and agent both need:
  • The API key (a UUID that identifies the API user).
  • The API secret, a PEM-format private key file. Save it somewhere outside your repository and restrict its permissions (chmod 600).
For an agent, scope the API user to Signer (or any role limited to signing) and to a single dedicated vault. For full per-agent control, see Fund and Control Agent Spending.
The API key and PEM secret are production credentials. Never commit them, paste them into chat or screenshots, or bake the PEM into a container image. In any non-development deployment, keep them in a secrets manager (AWS Secrets Manager, GCP Secret Manager, Azure Key Vault, or HashiCorp Vault) and inject them at runtime.

​
Create a vault account

The facilitator settles from a vault account you own; the receiver address (payTo) is derived from it. An agent pays from a vault account it is scoped to. Create at least one vault account in the Fireblocks Console and note its vault account ID (a number, often 0 for the first). The facilitator activates the asset wallets it needs and caches the receiver addresses when you run x402 fireblocks test --create-missing.

​
Testnet funds

x402 on Fireblocks is testnet-only by default, so evaluate with valueless testnet tokens. Two parties need funding, and they need different things. A pure eip-3009 (USDC) payment needs no ETH on the payer side, because the payer only signs. Permit2 and ERC-7710 need a one-time on-chain setup transaction the first time, so the payer needs a little gas ETH then.

​
Get testnet USDC

Use the Circle faucet, which supports the testnets x402 commonly runs on:
  • USDC on Base Sepolia or Ethereum Sepolia — faucet.circle.com. Select the network, paste the receiving address, and claim.
For an agent or test client, the receiving address is the payer’s address. For the test client in the facilitator repo, run npm run whoami to print the address to fund.

​
Get testnet gas (ETH)

Fund the facilitator’s vault, and the payer when using Permit2 or ERC-7710, with testnet ETH:
Most faucets require a captcha or social login by design, and each claim takes about half a minute. Fund the facilitator’s vault separately from the payer: the vault pays the on-chain settlement gas, which is independent of the tokens the payer spends.

​
Mainnet, when you are ready

Moving real value requires opting out of the default testnet-only policy and reviewing the operator responsibilities first. Do not enable mainnet during evaluation. When you are ready, see Network policy and Supported Networks and Assets.