access402-fastapi

Access402 FastAPI adapter

This package protects explicitly declared FastAPI routes with Access402's managed x402 v2 payment service. Routes, USDC prices, access policy, descriptions, and discovery intent live beside the endpoint in Python. Access402 provides signed configuration, x402 challenges, hosted verification and settlement, plan enforcement, discovery publication, and activity logs.

Install locally

pip install -e "./adapters/fastapi[test]"

Connect an application

Create a FastAPI installation in the Access402 dashboard, then configure server-only environment variables:

ACCESS402_INSTALLATION_ID=your-installation-uuid
ACCESS402_API_KEY=your-installation-key
ACCESS402_PUBLIC_BASE_URL=https://api.example.com
ACCESS402_MODE=sandbox

The API key belongs only in the FastAPI server environment. Never expose it in browser code, logs, OpenAPI documents, or a committed .env file. ACCESS402_API_BASE_URL is intentionally optional and should only be overridden for local Access402 backend development.

Create the Access402 manager before declaring paid routes, then install it after all routes:

from fastapi import FastAPI
from access402_fastapi import Access402

app = FastAPI()
access402 = Access402.from_env()

@app.get("/reports/{report_id}")
@access402.protect(
    price="0.05",
    access_type="per_request",
    description="Read one premium report",
    discovery_enabled=True,
    representative_queries=("Read report 42", "Get a premium research report"),
    capabilities=("x402", "research"),
)
async def report(report_id: str):
    return {"id": report_id, "result": "..."}

access402.install(app)

Live discoverable routes are published in an ARD 0.91 manifest at /.well-known/ard.json; /.well-known/ai-catalog.json is retained as a compatibility path. Each entry includes the route's media type, canonical URL, representative queries, capabilities, and Access402 payment metadata. Sandbox manifests remain valid but intentionally contain no public entries.

On startup, the adapter authenticates the installation, uploads only decorated payment policies, and downloads HMAC-authenticated configuration. The configuration is cached in memory and refreshed periodically; payment requests go directly to the Access402 settlement function. No CDP credential is installed in this package.

The dashboard displays a read-only mirror of code-owned policies and the mode reported by the deployment. The FastAPI environment controls the payment network, while protected routes fail closed if Access402 cannot confirm a matching server-side policy.

Dynamic path routes such as /reports/{report_id} can be protected. Discovery publication for those routes stays disabled until Access402 supports a concrete path-parameter example; publishing a literal template URL would create a broken Bazaar entry.

ACCESS402_PUBLIC_BASE_URL remains required. It is the trusted canonical origin placed in x402 resource URLs and validated against the installation's authorized origins. Inferring it from an incoming Host or forwarding header would allow a spoofed request to alter payment and discovery metadata. Use a separate FastAPI installation for local, staging, and production deployments; replicas of the same deployment may share one installation.

Set ACCESS402_MODE=sandbox for Base Sepolia or ACCESS402_MODE=live for Base mainnet, then restart the deployment. There is no dashboard mode override.

The adapter answers its own 402 responses with Access-Control-Allow-Origin: * by default so agent and browser clients can read the payment challenge. Set ACCESS402_CORS_ALLOW_ORIGIN to the API's exact browser origin when credentials are involved. CORS preflight (OPTIONS) is never paywalled.

Bypasses

There is no header-based administrator bypass. If an application needs trusted internal access, pass a callback that validates the application's real authentication state:

async def trusted_internal_request(scope):
    user = scope.get("state", {}).get("user")
    return bool(user and user.is_admin)

access402 = Access402.from_env(bypass=trusted_internal_request)

Put authentication middleware outside Access402 if the callback depends on middleware-populated state. A spoofable header must never be used as the bypass decision.

Tests

cd adapters/fastapi
python -m pip install -e ".[test]"
pytest