Python x402 Facilitator (E2E)

A Python implementation of an x402 facilitator service for end-to-end testing.

Features

  • Multi-Chain Support: Handles EVM (Base Sepolia), SVM (Solana Devnet), and TVM (TON testnet/mainnet) networks
  • Protocol Versions: Supports both x402 V1 and V2 protocols
  • Bazaar Extension: Full support for resource discovery and cataloging
  • Lifecycle Hooks: Payment verification tracking and discovery info extraction

Requirements

  • Python 3.10+
  • uv for dependency management

Setup

# Install dependencies
./install.sh

# Or manually
uv sync

Running

# Using run.sh (recommended for e2e tests)
./run.sh

# Or manually
uv run python main.py

# Or with uvicorn directly
uv run uvicorn main:app --port 4022

Environment Variables

Variable Required Description
PORT No Server port (default: 4022)
EVM_PRIVATE_KEY Conditionally Private key for EVM transactions
SVM_PRIVATE_KEY Conditionally Private key for SVM transactions
TVM_PRIVATE_KEY Conditionally Private key for the TVM highload facilitator wallet
EVM_RPC_URL No Custom EVM RPC URL (default: Base Sepolia)
EVM_NETWORK No EVM network identifier
SVM_NETWORK No SVM network identifier
TVM_NETWORK No TVM network identifier (default: tvm:-3)
TVM_PROVIDER No TVM provider: toncenter (default) or tonapi
TONCENTER_API_KEY No Toncenter API key for TVM testnet
TONCENTER_BASE_URL No Custom Toncenter base URL for TVM
TONAPI_API_KEY No TonAPI API key when TVM_PROVIDER=tonapi
TONAPI_BASE_URL No Custom TonAPI base URL for TVM

TVM funding notes

To fund the TVM facilitator wallet, request testnet TON from @testgiver_ton_bot. The facilitator wallet only needs TON for relay fees and must hold at least 1.1 TON before running tests.

Note: the facilitator uses a highload-wallet-v3 account, so the facilitator's wallet address differs from your W5 address — fund the highload-v3 address, not the W5 one derived from the same key.

To get testnet-USDT for the payer wallet, open the testnet USDT transfer link or scan the QR code below: QR code for the testnet USDT transfer link

Endpoints

Method Path Description
POST /verify Verify a payment against requirements
POST /settle Settle a payment on-chain
GET /supported Get supported payment kinds and extensions
GET /discovery/resources List discovered resources (bazaar)
GET /health Health check
POST /close Graceful shutdown

API Examples

Verify Payment

curl -X POST http://localhost:4022/verify \
  -H "Content-Type: application/json" \
  -d '{
    "paymentPayload": {...},
    "paymentRequirements": {...}
  }'

Settle Payment

curl -X POST http://localhost:4022/settle \
  -H "Content-Type: application/json" \
  -d '{
    "paymentPayload": {...},
    "paymentRequirements": {...}
  }'

Health Check

curl http://localhost:4022/health

Architecture

The facilitator uses:

  • FastAPI: Web framework for HTTP endpoints
  • x402 Python SDK: Core x402 functionality
  • web3.py: EVM blockchain interactions
  • solders: SVM blockchain interactions
  • pytoniq + Toncenter/TonAPI: TVM blockchain interactions

E2E Test Integration

This facilitator is automatically discovered by the e2e test framework via test.config.json. The framework will:

  1. Start the facilitator on an available port
  2. Wait for the "Facilitator listening" log message
  3. Run tests through the facilitator
  4. Shut down via POST /close