t402

t402 Python

Python package for the t402 payments protocol.

Installation

pip install t402

# or with uv
uv add t402

Overview

The t402 package provides the core building blocks for implementing the t402 Payment Protocol in Python. It's designed to be used by:

• FastAPI middleware for accepting payments
• Flask middleware for accepting payments
• httpx client for paying resources
• requests client for paying resources

FastAPI Integration

The simplest way to add t402 payment protection to your FastAPI application:

from fastapi import FastAPI
from t402.fastapi.middleware import require_payment

app = FastAPI()
app.middleware("http")(
    require_payment(price="0.01", pay_to_address="0x209693Bc6afc0C5328bA36FaF03C514EF312287C")
)

@app.get("/")
async def root():
    return {"message": "Hello World"}

To protect specific routes:

app.middleware("http")(
    require_payment(price="0.01",
    pay_to_address="0x209693Bc6afc0C5328bA36FaF03C514EF312287C"),
    path="/foo"  # <-- this can also be a list ex: ["/foo", "/bar"]
)

Flask Integration

The simplest way to add t402 payment protection to your Flask application:

from flask import Flask
from t402.flask.middleware import PaymentMiddleware

app = Flask(__name__)

# Initialize payment middleware
payment_middleware = PaymentMiddleware(app)

# Add payment protection for all routes
payment_middleware.add(
    price="$0.01",
    pay_to_address="0x209693Bc6afc0C5328bA36FaF03C514EF312287C",
)

@app.route("/")
def root():
    return {"message": "Hello World"}

To protect specific routes:

# Protect specific endpoint
payment_middleware.add(
    path="/foo",
    price="$0.001",
    pay_to_address="0x209693Bc6afc0C5328bA36FaF03C514EF312287C",
)

Client Integration

Simple Usage

Httpx Client

from eth_account import Account
from t402.clients.httpx import t402HttpxClient

# Initialize account
account = Account.from_key("your_private_key")

# Create client and make request
async with t402HttpxClient(account=account, base_url="https://api.example.com") as client:
    response = await client.get("/protected-endpoint")
    print(await response.aread())

Requests Session Client

from eth_account import Account
from t402.clients.requests import t402_requests

# Initialize account
account = Account.from_key("your_private_key")

# Create session and make request
session = t402_requests(account)
response = session.get("https://api.example.com/protected-endpoint")
print(response.content)

Advanced Usage

Httpx Extensible Example

import httpx
from eth_account import Account
from t402.clients.httpx import t402_payment_hooks

# Initialize account
account = Account.from_key("your_private_key")

# Create httpx client with t402 payment hooks
async with httpx.AsyncClient(base_url="https://api.example.com") as client:
    # Add payment hooks directly to client
    client.event_hooks = t402_payment_hooks(account)
    
    # Make request - payment handling is automatic
    response = await client.get("/protected-endpoint")
    print(await response.aread())

Requests Session Extensible Example

import requests
from eth_account import Account
from t402.clients.requests import t402_http_adapter

# Initialize account
account = Account.from_key("your_private_key")

# Create session and mount the t402 adapter
session = requests.Session()
adapter = t402_http_adapter(account)

# Mount the adapter for both HTTP and HTTPS
session.mount("http://", adapter)
session.mount("https://", adapter)

# Make request - payment handling is automatic
response = session.get("https://api.example.com/protected-endpoint")
print(response.content)

Manual Server Integration

If you're not using the FastAPI middleware, you can implement the t402 protocol manually. Here's what you'll need to handle:

• Return 402 error responses with the appropriate response body
• Use the facilitator to validate payments
• Use the facilitator to settle payments
• Return the appropriate response header to the caller

Here's an example of manual integration:

from typing import Annotated
from fastapi import FastAPI, Request
from t402.types import PaymentRequiredResponse, PaymentRequirements
from t402.encoding import safe_base64_decode

payment_requirements = PaymentRequirements(...)
facilitator = FacilitatorClient(facilitator_url)

@app.get("/foo")
async def foo(req: request: Request):
    payment_required = PaymentRequiredResponse(
        t402_version: 1,
        accepts=[payment_requirements],
        error="",
    )
    payment_header = req.headers.get("X-PAYMENT", "")

    if payment_header == "":
        payment_required.error = "X-PAYMENT header not set"
        return JSONResponse(
            content=payment_required.model_dump(by_alias=True),
            status_code=402,
        )
    
    payment = PaymentPayload(**json.loads(safe_base64_decode(payment_header)))

    verify_response = await facilitator.verify(payment, payment_requirements)
    if not verify_response.is_valid:
        payment_required.error = "Invalid payment"
        return JSONResponse(
            content=payment_required.model_dump(by_alias=True),
            status_code=402,
        )

    settle_response = await facilitator.settle(payment, payment_requirements)
    if settle_response.success:
        response.headers["X-PAYMENT-RESPONSE"] = base64.b64encode(
            settle_response.model_dump_json().encode("utf-8")
        ).decode("utf-8")
    else:
        payment_required.error = "Settle failed: " + settle_response.error
        return JSONResponse(
            content=payment_required.model_dump(by_alias=True),
            status_code=402,
        )

For more examples and advanced usage patterns, check out our examples directory.