fastapi_mpp

MPP-based payment gating for FastAPI. Add a single decorator to any route and it handles the full 402 → pay → verify flow automatically.

Quick start

from fastapi import FastAPI
from fastapi_mpp import ChargeableFactory, PaymentMethod

app = FastAPI()

factory = ChargeableFactory.create(
    PaymentMethod.tempo(
        currency="0x20C000...",   # USDC token address
        recipient="0xYourWallet",
    ),
    realm="my-api",               # shown in WWW-Authenticate
    secret_key="...",             # or set MPP_SECRET_KEY env var
)

@app.get("/premium")
@factory.Chargeable(amount="0.50", description="Premium data")
async def premium():
    return {"data": "paid content"}

Without a valid payment credential the route returns:

HTTP/1.1 402 Payment Required
WWW-Authenticate: MPP realm="my-api", ...

{"error": "Payment Required", "challenge": {...}}

With a valid credential the route runs and responds:

HTTP/1.1 200 OK
Payment-Receipt: MPP receipt=...

{"data": "paid content"}

Factory config reference

ChargeableFactory.create(*methods, realm=None, secret_key=None)

PaymentMethod.tempo() config reference

Decorator config reference

@factory.Chargeable(amount, *, ...)

Optional middleware

MppMiddleware attaches the Mpp instance to request.state.mpp for advanced use cases:

from fastapi_mpp import MppMiddleware

app.add_middleware(MppMiddleware, factory=factory)

@app.get("/advanced")
async def route(request: Request):
    mpp = request.state.mpp
    result = await mpp.charge(
        authorization=request.headers.get("Authorization"),
        amount="1.00",
    )
    ...

Testing with npx mppx

mppx is the MPP CLI test client. Run your FastAPI app locally, then:

# Install once
npm install -g mppx

# Hit a gated endpoint — mppx handles the 402 → wallet → credential flow
npx mppx http://localhost:8000/premium

# Specify a wallet private key
npx mppx --key 0xYourPrivateKey http://localhost:8000/premium

# Testnet (Moderato)
npx mppx --network moderato http://localhost:8000/premium

Start the example app:

export MPP_SECRET_KEY=dev-secret
export MPP_REALM=example-api
export TEMPO_CURRENCY=0x20c0000000000000000000000000000000000000   # Tempo PATH/USD (testnet)
export TEMPO_RECIPIENT=0xYourWalletAddress

uv run fastapi dev examples/basic.py

Running tests

uv sync --group dev
uv run pytest

Run a single test file:

uv run pytest tests/test_402_flow.py -v