Creating x402 Payment-Protected Servers in Python

Build FastAPI (async) or Flask (sync) servers that protect API endpoints behind Algorand USDC payments using x402 middleware.

Prerequisites

Before using this skill, ensure:

1. Python 3.10+ is installed
2. An Algorand address to receive payments (the payTo address)
3. A facilitator URL -- use https://x402.org/facilitator or run your own
4. Understanding of FastAPI or Flask basics

Core Workflow: Middleware-Based Payment Protection

The middleware intercepts requests to protected routes, checks for payment headers, verifies payments through the facilitator, and settles on success.

Client Request
      |
      v
x402 Middleware (checks route config)
      |
      +-- Not protected -> Pass through to handler
      |
      +-- Protected, no payment -> Return 402 with PaymentRequirements
      |
      +-- Protected, has payment -> Verify via Facilitator
            |
            +-- Invalid -> Return 402
            |
            +-- Valid -> Call handler, then settle payment

How to Proceed

Step 1: Install Dependencies

For FastAPI (async):

pip install "x402-avm[fastapi,avm]"

For Flask (sync):

pip install "x402-avm[flask,avm]"

Step 2: Choose Your Framework Pattern

FastAPI uses async components:

• x402ResourceServer (async)
• HTTPFacilitatorClient (async)
• PaymentMiddlewareASGI or payment_middleware

Flask uses sync components:

• x402ResourceServerSync (sync)
• HTTPFacilitatorClientSync (sync)
• PaymentMiddleware or payment_middleware

Step 3: Set Up the Resource Server

Create a facilitator client, resource server, and register the AVM scheme:

FastAPI:

from x402.server import x402ResourceServer
from x402.http import HTTPFacilitatorClient, FacilitatorConfig
from x402.mechanisms.avm.exact import ExactAvmServerScheme

facilitator = HTTPFacilitatorClient(FacilitatorConfig(url="https://x402.org/facilitator"))
server = x402ResourceServer(facilitator)
server.register("algorand:SGO1GKSzyE7IEPItTxCByw9x8FmnrCDexi9/cOUJOiI=", ExactAvmServerScheme())

Flask:

from x402.server import x402ResourceServerSync
from x402.http import HTTPFacilitatorClientSync, FacilitatorConfig
from x402.mechanisms.avm.exact import ExactAvmServerScheme

facilitator = HTTPFacilitatorClientSync(FacilitatorConfig(url="https://x402.org/facilitator"))
server = x402ResourceServerSync(facilitator)
server.register("algorand:SGO1GKSzyE7IEPItTxCByw9x8FmnrCDexi9/cOUJOiI=", ExactAvmServerScheme())

Step 4: Define Route Configurations

Routes map HTTP method + path patterns to payment requirements:

from x402.http import PaymentOption
from x402.http.types import RouteConfig

routes = {
    "GET /api/weather": RouteConfig(
        accepts=PaymentOption(
            scheme="exact",
            network="algorand:SGO1GKSzyE7IEPItTxCByw9x8FmnrCDexi9/cOUJOiI=",
            pay_to="YOUR_ALGORAND_ADDRESS",
            price="$0.01",
        ),
    ),
}

Step 5: Apply Middleware

FastAPI -- Option A (ASGI class, recommended):

from x402.http.middleware.fastapi import PaymentMiddlewareASGI
app.add_middleware(PaymentMiddlewareASGI, routes=routes, server=server)

FastAPI -- Option B (function-based):

from x402.http.middleware.fastapi import payment_middleware
x402_mw = payment_middleware(routes=routes, server=server)

@app.middleware("http")
async def x402_middleware(request, call_next):
    return await x402_mw(request, call_next)

Flask:

from x402.http.middleware.flask import PaymentMiddleware
PaymentMiddleware(app, routes, server)

Step 6: Define Route Handlers

Routes listed in the configuration require payment. Unlisted routes pass through freely.

FastAPI:

@app.get("/api/weather")
async def get_weather():
    return {"temperature": 72, "unit": "F"}

Flask:

@app.route("/api/weather")
def get_weather():
    return {"temperature": 72, "unit": "F"}

Important Rules / Guidelines

1. Match async/sync variants -- FastAPI uses x402ResourceServer + HTTPFacilitatorClient, Flask uses x402ResourceServerSync + HTTPFacilitatorClientSync
2. Route format -- Keys must be "METHOD /path" (e.g., "GET /api/weather", "POST /api/generate/*")
3. Wildcard paths -- Use /* suffix to match all sub-paths (e.g., "GET /api/premium/*")
4. Unlisted routes pass through -- Only routes in the config require payment
5. Register scheme before middleware -- Call server.register(...) before adding middleware
6. Price format -- Use "$0.01" for auto-conversion or AssetAmount(amount="10000", asset="10458941") for explicit control
7. CAIP-2 network IDs -- Use full CAIP-2 identifiers like "algorand:SGO1GKSzyE7IEPItTxCByw9x8FmnrCDexi9/cOUJOiI="

Pricing Options

Simple String Price

PaymentOption(
    scheme="exact",
    network="algorand:SGO1GKSzyE7IEPItTxCByw9x8FmnrCDexi9/cOUJOiI=",
    pay_to="YOUR_ADDRESS",
    price="$0.01",  # Auto-converts to 10000 microUSDC
)

Explicit AssetAmount

from x402.schemas import AssetAmount

PaymentOption(
    scheme="exact",
    network="algorand:SGO1GKSzyE7IEPItTxCByw9x8FmnrCDexi9/cOUJOiI=",
    pay_to="YOUR_ADDRESS",
    price=AssetAmount(
        amount="50000",       # 50000 microUSDC = $0.05
        asset="10458941",     # USDC ASA ID on testnet
        extra={"name": "USDC", "decimals": 6},
    ),
)

Multi-Network (AVM + EVM + SVM)

routes = {
    "GET /api/data/*": RouteConfig(
        accepts=[
            PaymentOption(scheme="exact", pay_to=AVM_ADDRESS, price="$0.01",
                         network="algorand:SGO1GKSzyE7IEPItTxCByw9x8FmnrCDexi9/cOUJOiI="),
            PaymentOption(scheme="exact", pay_to=EVM_ADDRESS, price="$0.01",
                         network="eip155:84532"),
            PaymentOption(scheme="exact", pay_to=SVM_ADDRESS, price="$0.01",
                         network="solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1"),
        ],
    ),
}

Common Errors / Troubleshooting

Error	Cause	Solution
TypeError: async errors in Flask	Using async variants with Flask	Use x402ResourceServerSync and HTTPFacilitatorClientSync
402 returned to all requests	Middleware applied but facilitator unreachable	Check FACILITATOR_URL and network connectivity
Route not protected	Path pattern mismatch	Verify route key format matches: "GET /exact/path" or "GET /prefix/*"
Settlement fails	Facilitator cannot reach Algorand network	Check facilitator logs and algod endpoint
ImportError on middleware	Missing extras	pip install "x402-avm[fastapi,avm]" or "x402-avm[flask,avm]"

References / Further Reading

• REFERENCE.md - Detailed API reference for middleware
• EXAMPLES.md - Complete code examples for FastAPI and Flask
• x402-avm Examples Repository
• x402 Algorand Documentation