/algorand-x402-python

x402 Python Server Middleware Reference

Detailed API reference for FastAPI and Flask payment middleware in the x402-avm Python package.

FastAPI Middleware API

payment_middleware(routes, server, ...)

Creates an async middleware callable for FastAPI.

Returns: Async middleware callable (Request, call_next) -> Response

Usage:

x402_mw = payment_middleware(routes=routes, server=server)

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

payment_middleware_from_config(routes, facilitator_client, ...)

Creates middleware with an internally-created resource server.

Returns: Async middleware callable (Request, call_next) -> Response

PaymentMiddlewareASGI

Starlette BaseHTTPMiddleware subclass. Accepts same parameters as payment_middleware via app.add_middleware().

Usage:

app.add_middleware(PaymentMiddlewareASGI, routes=routes, server=server)

FastAPIAdapter

Implements the HTTPAdapter protocol for FastAPI/Starlette requests. Used internally.

Flask Middleware API

PaymentMiddleware(app, routes, server, ...)

The main WSGI middleware class. Replaces app.wsgi_app on initialization.

Side effect: Replaces app.wsgi_app with the payment-checking WSGI middleware.

payment_middleware(app, routes, server, ...)

Factory function. Accepts same parameters as PaymentMiddleware, returns PaymentMiddleware instance.

Returns: PaymentMiddleware instance.

payment_middleware_from_config(app, routes, ...)

Convenience function that creates the x402ResourceServer internally.

Returns: PaymentMiddleware instance.

FlaskAdapter

Implements the HTTPAdapter protocol for Flask requests. Used internally.

ResponseWrapper

Internal class that captures and buffers the WSGI response for settlement processing.

RouteConfig

Dataclass for route configuration.

from x402.http.types import RouteConfig

RouteConfig(
    accepts=PaymentOption(...),          # Required: single payment option
    # or: accepts=[PaymentOption(...), PaymentOption(...)],  # Multiple options
    resource="https://api.example.com/api/weather",  # Optional: resource URL
    description="Weather data API",      # Optional: description
    mime_type="application/json",        # Optional: response MIME type
)

Route Key Format

Route keys follow the pattern "METHOD /path":

PaymentOption

Dataclass for payment options.

from x402.http import PaymentOption

PaymentOption(
    scheme="exact",              # Payment scheme name
    network="algorand:SGO...",   # CAIP-2 network identifier
    pay_to="ALGO_ADDRESS",       # Recipient address
    price="$0.01",               # Auto-converted to AssetAmount
    # or: price=AssetAmount(amount="10000", asset="10458941"),
)

AssetAmount

Explicit asset amount specification.

from x402.schemas import AssetAmount

AssetAmount(
    amount="10000",                      # Atomic units (string)
    asset="10458941",                    # Asset identifier (ASA ID as string)
    extra={"name": "USDC", "decimals": 6},  # Optional metadata
)

Sync vs Async Comparison

Middleware Flow

FastAPI (ASGI)

1. Client sends request with Payment-Signature header
2. Middleware checks if the route requires payment via requires_payment(context)
3. On first protected request, facilitator support is synchronized (lazy init)
4. process_http_request(context) verifies the payment:
   • "no-payment-required" -- route not protected, passes through
   • "payment-error" -- returns 402 response (JSON or HTML paywall)
   • "payment-verified" -- stores on request.state, calls route handler
5. If route handler returns a successful (2xx) response, settlement is processed
6. Settlement headers are added to the response

Flask (WSGI)

1. Client sends request with Payment-Signature header
2. The WSGI middleware intercepts the request within a Flask request context
3. Middleware checks if the route requires payment via requires_payment(context)
4. On first protected request, facilitator support is synchronized (lazy init)
5. process_http_request(context) verifies the payment synchronously:
   • "no-payment-required" -- passes through to original_wsgi
   • "payment-error" -- returns 402 response
   • "payment-verified" -- stores on flask.g, calls original WSGI app
6. Response is captured by ResponseWrapper, settlement is processed synchronously
7. Settlement headers are added to the buffered response

Environment Variables

Algorand-Specific Constants

Values as of x402-avm 2.0.2; note the TypeScript @x402/avm package ≥2.20.0 uses the 32-char form algorand:SGO1GKSzyE7IEPItTxCByw9x8FmnrCDe — a TS server/client and a Python facilitator (or vice-versa) will not match until x402-avm adopts the same form. Always use the constants in code rather than hardcoding the string.

CAIP-2 Network Identifiers

Algorand values as of x402-avm 2.0.2 (see note above regarding the TypeScript @x402/avm ≥2.20.0 32-char form). Use ALGORAND_TESTNET_CAIP2 / ALGORAND_MAINNET_CAIP2 in code.

Error Handling

Payment Errors (402 Responses)

When a client sends a request without a valid payment, the middleware returns a 402 response containing PaymentRequirements the client needs to fulfill.

Settlement Failures

If the route handler succeeds but settlement fails:

{
    "error": "Settlement failed",
    "details": "reason for failure"
}

Unprotected Routes

Routes not listed in the routes configuration are served normally without any payment check.

External Resources

• x402-avm on PyPI
• x402-avm Examples Repository
• x402 Algorand Documentation
• FastAPI Documentation
• Flask Documentation
• Coinbase x402 Specification