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:
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:
- Start the facilitator on an available port
- Wait for the "Facilitator listening" log message
- Run tests through the facilitator
- Shut down via POST
/close