x402-flow-facilitator — x402 Payments Facilitator for Flow EVM

x402 payment facilitator and examples for Flow EVM (eip155:747).

Overview

This repo contains:

• Facilitator — Verifies and settles x402 payments on Flow EVM
• Examples — Multiple server and client demos adapted from the official x402 examples

Architecture

sequenceDiagram
    participant C as Client (payer)
    participant S as Resource Server (paywall)
    participant F as Facilitator
    participant E as Flow EVM (on-chain)

    C->>S: 1. GET /weather
    S-->>C: 2. 402 + PaymentRequirements

    Note over C: Sign payment with<br/>EOA key or COA (EIP-1271)

    C->>S: 3. GET /weather + payment signature
    S->>F: 4. POST /verify
    F-->>S: Payment valid

    S-->>C: 5. Weather data + tx receipt

    S->>F: 6. POST /settle
    F->>E: transferWithAuthorization (stgUSDC)
    E-->>F: tx hash
    F-->>S: Settlement confirmed

Live Facilitator

URL: https://facilitator.flowindex.io

Examples

Servers (paywall)

Clients (payer)

Quick Start

1. Run the Resource Server (paywall)

cd examples/server
npm install
cp .env.example .env
# Edit .env: set PAY_TO_ADDRESS to your wallet
npm start

The server starts at http://localhost:4021 with a paid /weather endpoint ($0.001 per request in stgUSDC on Flow EVM).

2. Run the Client (payer)

cd examples/client
npm install
cp .env.example .env
# Edit .env: set EVM_PRIVATE_KEY (needs stgUSDC on Flow EVM)
npm start

The client automatically handles the 402 payment flow:

1. Requests /weather → gets 402 + payment requirements
2. Signs payment with your private key
3. Retries with payment signature → gets weather data
4. Facilitator settles the payment on-chain

Flow EVM Details

Deployed Contracts

Cadence (COA) Support

x402 natively supports EIP-1271 smart contract signature verification, so COA (Cadence Owned Account) users can make x402 payments without any special handling.

Cadence Transactions

Usage with Flow CLI

# One-shot setup: create COA, deposit 1.0 FLOW, approve max stgUSDC for Permit2
flow transactions send cadence/transactions/setup_x402.cdc \
  1.0 \
  115792089237316195423570985008687907853269984665640564039457584007913129639935 \
  --network mainnet --signer mainnet-account

Self-Hosting the Facilitator

git clone https://github.com/onflow/x402-flow-facilitator.git
cd x402-flow-facilitator
npm install
cp .env.example .env
# Edit .env: set EVM_PRIVATE_KEY (needs FLOW for gas)
npm start

PaymentRequirements Example

Use this in your resource server to accept payments on Flow EVM:

{
  scheme: "exact",
  network: "eip155:747",
  asset: "0xF1815bd50389c46847f0Bda824eC8da914045D14",
  extra: {
    name: "Bridged USDC (Stargate)",
    version: "2",
  },
}

Links

• x402 Protocol
• x402 Docs
• Flow EVM
• Flow EVM Explorer

About Flow

This repo is part of the Flow network, a Layer 1 blockchain built for consumer applications, AI agents, and DeFi at scale.

• Developer docs: https://developers.flow.com
• Cadence language: https://cadence-lang.org
• Community: Flow Discord · Flow Forum
• Governance: Flow Improvement Proposals