6.0 KiB
x402 Facilitator Example
FastAPI-based facilitator service that verifies and settles payments on-chain for the x402 protocol.
Prerequisites
- Python 3.10+ (install via pyenv or uv)
- uv package manager (install via uv installation)
- Dedicated EVM facilitator private key with Base Sepolia ETH for transaction fees
- Dedicated SVM facilitator private key with Solana Devnet SOL for transaction fees
Setup
- Copy
.env-localto.env:
cp .env-local .env
and fill required environment variables:
EVM_PRIVATE_KEY- Ethereum facilitator private key (hex with 0x prefix)SVM_PRIVATE_KEY- Solana facilitator private key (base58 encoded)PORT- Server port (optional, defaults to 4022)EVM_RPC_URL- Custom EVM RPC URL (optional, defaults to Base Sepolia)
⚠️ Security Note: The facilitator key is the signer used to settle payments on-chain. Keep it separate from your seller payTo wallet and buyer test wallets, and make sure it is funded only for facilitator gas/fees.
- Install dependencies:
uv sync
- Run the server:
uv run python main.py
Or with uvicorn directly:
uv run uvicorn main:app --port 4022
API Endpoints
GET /supported
Returns payment schemes and networks this facilitator supports.
{
"kinds": [
{
"x402Version": 2,
"scheme": "exact",
"network": "eip155:84532"
},
{
"x402Version": 2,
"scheme": "exact",
"network": "solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1",
"extra": {
"feePayer": "..."
}
}
],
"extensions": [],
"signers": {
"eip155": ["0x..."],
"solana": ["..."]
}
}
POST /verify
Verifies a payment payload against requirements before settlement.
Request:
{
"paymentPayload": {
"x402Version": 2,
"resource": {
"url": "http://localhost:4021/weather",
"description": "Weather data",
"mimeType": "application/json"
},
"accepted": {
"scheme": "exact",
"network": "eip155:84532",
"asset": "0x036CbD53842c5426634e7929541eC2318f3dCF7e",
"amount": "1000",
"payTo": "0x...",
"maxTimeoutSeconds": 300,
"extra": {
"name": "USDC",
"version": "2"
}
},
"payload": {
"signature": "0x...",
"authorization": {}
}
},
"paymentRequirements": {
"scheme": "exact",
"network": "eip155:84532",
"asset": "0x036CbD53842c5426634e7929541eC2318f3dCF7e",
"amount": "1000",
"payTo": "0x...",
"maxTimeoutSeconds": 300,
"extra": {
"name": "USDC",
"version": "2"
}
}
}
Response (success):
{
"isValid": true,
"payer": "0x..."
}
Response (failure):
{
"isValid": false,
"invalidReason": "invalid_signature"
}
POST /settle
Settles a verified payment by broadcasting the transaction on-chain.
Request body is identical to /verify.
Response (success):
{
"success": true,
"transaction": "0x...",
"network": "eip155:84532",
"payer": "0x..."
}
Response (failure):
{
"success": false,
"errorReason": "insufficient_balance",
"transaction": "",
"network": "eip155:84532"
}
Extending the Example
Adding Networks
Register additional schemes for other networks:
from x402 import x402Facilitator
from x402.mechanisms.evm.exact import register_exact_evm_facilitator
from x402.mechanisms.svm.exact import register_exact_svm_facilitator
facilitator = x402Facilitator()
register_exact_evm_facilitator(
facilitator,
evm_signer,
networks="eip155:84532",
)
register_exact_svm_facilitator(
facilitator,
svm_signer,
networks="solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1",
)
Lifecycle Hooks
Add custom logic before/after verify and settle operations:
from x402 import x402Facilitator
from x402.schemas import AbortResult
facilitator = (
x402Facilitator()
.on_before_verify(lambda ctx: print(f"Verifying: {ctx.payment_payload}"))
.on_after_verify(lambda ctx: print(f"Verified: {ctx.result}"))
.on_verify_failure(lambda ctx: print(f"Verify failed: {ctx.error}"))
.on_before_settle(lambda ctx: (
# Return AbortResult to cancel settlement
AbortResult(reason="Custom rejection") if should_reject(ctx) else None
))
.on_after_settle(lambda ctx: print(f"Settled: {ctx.result}"))
.on_settle_failure(lambda ctx: print(f"Settle failed: {ctx.error}"))
)
Custom EVM Signer
Create a custom signer for different providers:
from x402.mechanisms.evm.signer import FacilitatorEvmSigner
from x402.mechanisms.evm.types import TransactionReceipt
class MyCustomSigner:
"""Implement FacilitatorEvmSigner protocol."""
def get_addresses(self) -> list[str]:
return ["0x..."]
def read_contract(self, address, abi, function_name, *args):
# Your implementation
pass
def verify_typed_data(self, address, domain, types, primary_type, message, signature):
# Your implementation
pass
def write_contract(self, address, abi, function_name, *args):
# Your implementation
pass
def send_transaction(self, to, data):
# Your implementation
pass
def wait_for_transaction_receipt(self, tx_hash) -> TransactionReceipt:
# Your implementation
pass
def get_balance(self, address, token_address) -> int:
# Your implementation
pass
def get_chain_id(self) -> int:
# Your implementation
pass
def get_code(self, address) -> bytes:
# Your implementation
pass
Network Identifiers
Networks use CAIP-2 format:
eip155:84532— Base Sepoliaeip155:8453— Base Mainnetsolana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1— Solana Devnetsolana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp— Solana Mainnet