◇Paywall

Official SDK · Python

x402 FastAPI SDKFastAPI (Python ≥ 3.10)

Thin FastAPI client for the x402 paywall platform. Implements the frozen X402v1 wire contract. No settlement logic — relays to the platform's signed challenge/verify and fails closed: if the platform is unreachable the gated route returns 502 and never serves paid content.

Start as a developerView source on GitHub

Source is public on GitHub — official registry packages (npm · PyPI · Packagist · Go · Maven Central · NuGet · RubyGems) are coming. Each SDK implements the same frozen X402v1 wire contract.

One async decorator turns a FastAPI endpoint into a pay-per-call route.

Quick start — 3 steps
  1. 01
    Create an account & register a route

    In the dashboard, add the route + price and issue a test or live API key.

  2. 02
    Install the SDK

    One package; the per-SDK command is below.

  3. 03
    Add one middleware

    Wrap the route — it now returns a signed x402 challenge and only serves paid content after the agent pays in USDC.

Install
pip install x402-fastapi

Package id: x402-fastapi

Minimal usage
from fastapi import FastAPI
from x402_fastapi import x402_paywall

app = FastAPI()

@app.get("/premium")
@x402_paywall(price="0.10")
async def premium():
    return {"data": "paid content"}
Configuration
X402_API_KEYyour key idIdentifies the key (from the API Keys page).
X402_SECRETshown onceHMAC signing secret — shown once on key creation, stored encrypted.
X402_ENVsandbox | livesandbox = test key (synthetic settlement); live = real on-chain USDC.
X402_BASE_URLhttps://api.payrelayer.comPlatform base URL the SDK calls.

Use a test key with X402_ENV=sandbox: payments settle synthetically so you can build and CI-assert the full challenge → pay → verify → allow loop with zero real USDC, then flip to a live key — no code change.

Built to save you time
  • Thin client — no settlement, custody, or crypto code runs in your process. Keys, fees, the on-chain 95/5 split and payouts all live on the platform; you add one middleware.
  • Fails closed — if the platform is unreachable the gated route returns 502 and never serves paid content. It cannot accidentally give away a paid response.
  • One frozen wire contract — X402v1 is byte-identical across all 9 SDKs, enforced by a shared known-answer signature test, so behaviour can't drift between languages.
  • Signed, retried webhooks (payment.settled, payout.sent, payout.failed) + a live dashboard of requests, balances and payouts — reconciliation is done for you.
  • @x402_paywall(price=...) decorator on the path operation.
  • Async; requires Python ≥ 3.10.
FAQ
Do I need blockchain or crypto code?

No. The SDK is a thin HTTP client. Settlement, the 95/5 split and payouts happen on-chain on the platform side; you add one middleware and read the result.

Can it accidentally serve paid content for free?

No. It fails closed — if the platform is unreachable the gated route returns 502 and never serves the paid response.

How do I test without spending real USDC?

Use a test/sandbox key (X402_ENV=sandbox). Payments settle synthetically end-to-end; flip to a live key when you're ready, with no code change.

Is the payment format stable across languages?

Yes. X402v1 is a frozen wire contract, byte-identical across all 9 SDKs and enforced by a shared known-answer signature test.

Is it async-safe?

Yes — the decorator is fully async and adds no blocking I/O to your handler.

All SDKsHow it works