x402-fl: Local x402 Payment Facilitator

A local x402 facilitator for development and testing. One command gives you a fully functional x402 payment environment: a forked Base mainnet via Foundry Anvil paired with a local facilitator server. Build and test x402-powered apps without touching real funds.

Warning: Local development only. Uses Anvil's deterministic private keys, which are publicly known and provide zero security. Do not use in production.

Note: Currently supports USDC on Base and Base Sepolia. Custom ERC-20 token support is on the roadmap.

What it does

npx x402-fl dev

That's it. Behind the scenes, x402-fl:

1. Forks Base mainnet using Anvil with real USDC contract state, at zero cost
2. Starts a facilitator server that verifies and settles x402 payments locally
3. Provides a fund command to mint USDC to any address instantly

Prerequisites

• Node.js 20+
• pnpm
• One of:
  • Foundry (recommended, provides anvil)
  • Docker (fallback, runs Anvil in a container; also required for Testcontainers)

Quick Start

Try it instantly with npx:

npx x402-fl dev

Or install globally:

npm install -g x402-fl
x402-fl dev

This starts Anvil on port 8545 and launches the facilitator on port 4022.

From source

git clone https://github.com/kevzzsk/x402-fl.git
cd x402-fl
pnpm install
pnpm dev

Fund an account with 100 USDC:

x402-fl fund 0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266 100

CLI Commands

x402-fl dev

Start Anvil fork + facilitator server for local x402 development.

x402-fl dev [options]

| Flag | Default | Description | | ----------------------- | -------------------------- | -------------------------------------------------------------------- | | --port <number> | 4022 | Facilitator HTTP port | | --anvil-port <number> | 8545 | Anvil RPC port (first instance; additional instances use next ports) | | --network <name...> | base | Network preset(s) to fork — repeatable (e.g. --network base --network base-sepolia) | | --rpc-url <url> | https://mainnet.base.org | RPC URL to fork (overrides the first --network preset's default) | | -v | | Show facilitator request logs | | -vv | | Show facilitator request logs and Anvil process logs | | --private-key <key> | | Custom facilitator private key (prefer default Anvil account) |

The --network flag controls which chains get a local Anvil fork. Specify it multiple times to run multiple Anvil instances (e.g. --network base --network base-sepolia). The facilitator always registers all supported schemes across all configured networks, so GET /supported will list every scheme/network combination.

Warning: --private-key is not recommended

Note: anvil state is not persisted.

x402-fl fund

Fund any address with USDC on the local Anvil fork.

x402-fl fund <address> <amount> [options]

| Argument / Flag | Default | Description | | ----------------------- | -------- | ---------------------------------------------------------------- | | <address> | required | 0x-prefixed Ethereum address to fund | | <amount> | required | USDC amount in major units (human-readable, e.g. 100 or 1.5) | | --anvil-port <number> | 8545 | Anvil RPC port |

x402-fl balance

Check USDC balance for an address on the local Anvil fork.

x402-fl balance <address> [options]

| Argument / Flag | Default | Description | | ----------------------- | -------- | ---------------------------- | | <address> | required | 0x-prefixed Ethereum address | | --anvil-port <number> | 8545 | Anvil RPC port |

Facilitator API Endpoints

The facilitator server exposes the following HTTP endpoints (default http://localhost:4022):

POST /verify

Verify an x402 payment payload without settling it.

Request body:

{
  "paymentPayload": { ... },
  "paymentRequirements": { ... }
}

Response: Verification result from the facilitator.

POST /settle

Settle (execute) a verified x402 payment on-chain.

Request body:

{
  "paymentPayload": { ... },
  "paymentRequirements": { ... }
}

Response: Settlement result with transaction details.

GET /supported

List supported payment schemes and networks.

Response:

{ ... }

GET /health

Health check endpoint.

Response:

{
  "status": "ok",
  "networks": ["eip155:8453", "eip155:84532"],
  "facilitator": "0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266"
}

Docker

A pre-built Docker image is available on GitHub Container Registry:

docker pull ghcr.io/kevzzsk/x402-fl:latest

Run it directly:

docker run -p 4022:4022 -p 8545:8545 ghcr.io/kevzzsk/x402-fl:latest

Override the fork RPC URL:

docker run -p 4022:4022 -p 8545:8545 ghcr.io/kevzzsk/x402-fl:latest --rpc-url https://your-rpc-url.com

| Tag | Description | | -------- | ----------------------------------------------------- | | latest | Latest stable release | | next | Pre-release builds (e.g. 1.0.0-beta.1) | | x.y.z | Pinned version (e.g. ghcr.io/kevzzsk/x402-fl:0.1.0) |

Testcontainers

x402-fl ships a Testcontainers module so you can spin up a fully isolated x402 environment in integration tests. The container pulls the GHCR image by default.

Install

The testcontainers package is an optional peer dependency:

pnpm install -D testcontainers

Usage

import { describe, it, expect, beforeAll, afterAll } from "vitest";
import {
  X402FacilitatorLocalContainer,
  type StartedX402FacilitatorLocalContainer,
  accounts,
} from "x402-fl/testcontainers";

describe("x402 integration", () => {
  let container: StartedX402FacilitatorLocalContainer;

  beforeAll(async () => {
    container = await new X402FacilitatorLocalContainer().start();
  });

  afterAll(async () => {
    await container?.stop();
  });

  it("facilitator is healthy", async () => {
    const res = await fetch(`${container.getFacilitatorUrl()}/health`);
    expect(res.status).toBe(200);
  });

  it("funds an address with USDC", async () => {
    await container.fund(accounts.facilitator.address, "100");
  });
});

API

X402FacilitatorLocalContainer

| Method | Description | | ------------------------------------------- | -------------------------------------------------------------- | | new X402FacilitatorLocalContainer(image?) | Create a container (default: ghcr.io/kevzzsk/x402-fl:latest) | | .withNetworkPreset(...names) | Select network preset(s) — pass multiple for multi-Anvil (chainable) | | .withForkUrl(url) | Set a custom RPC URL to fork (chainable) | | .start() | Build the image (if needed) and start the container |

StartedX402FacilitatorLocalContainer

| Method | Description | | ----------------------------------- | ---------------------------------------------------------------- | | .getRpcUrl(network?) | Anvil RPC endpoint (pass network name for multi-network setups) | | .getFacilitatorUrl() | Facilitator HTTP endpoint (http://host:port) | | .fund(address, amount, network?) | Mint USDC to an address (network name selects Anvil instance) | | .balance(address, network?) | Get USDC balance (network name selects Anvil instance) | | .getPublicClient(network?) | Get a viem PublicClient (network name selects Anvil instance) | | .stop() | Stop and remove the container |

Note: The first call to .start() pulls the Docker image from GHCR, which may take a moment. Subsequent calls reuse the cached image. You can pass a custom image tag to the constructor if needed.

Test Accounts

The facilitator uses Anvil's default deterministic account (index 0). Do not use these keys for anything real.

| Role | Address | | ----------- | -------------------------------------------- | | Facilitator | 0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266 |

Any address can be funded using x402-fl fund.

Roadmap

• [ ] Custom Asset support (EIP-3009 tokens)
• [ ] Custom Fork url
• [ ] Custom Fork block height
• [x] Dockerised anvil node (fallback when Foundry is not installed)
• [x] Testcontainers for facilitator + anvil for deterministic testing env
• [ ] Support all anvil args and passdown the args
• [ ] Support SVM

Issues

Found a bug or have a feature request? Open an issue.

License

MIT