Skip to Content
DocsQuickstartsPython Quickstart (fx402-fastapi)

Python Quickstart (fx402-fastapi)

This guide shows how to serve and verify FX402 rentals using the Python FastAPI package fx402-fastapi.

It lets you expose endpoints that automatically:

  • Return a structured 402 Payment Required JSON
  • Verify payments
  • Issue time-limited receipts

⚙️ 1. Installation

pip install fx402-fastapi

🧩 2. Basic Usage

from fastapi import FastAPI
from fx402_fastapi import r402, R402Config, R402Receipt, R402Tier
 
app = FastAPI()
 
# Define payment destination and configuration
cfg = R402Config(
    pay_to="SoLWallet111...xyz",
    chain="solana",
    facilitator_url="https://facilitator.fx402.xyz/settle"
)
 
# Gate an endpoint using the @r402 decorator
@app.get("/memes/{slug}")
@r402(
    cfg,
    tiers=[
        R402Tier(id="1d", seconds=86400, amount="0.50", currency="USDC"),
        R402Tier(id="7d", seconds=604800, amount="2.00", currency="USDC"),
    ],
    modes=["view", "remix"]
)
def get_meme(slug: str, receipt: R402Receipt | None = None):
    """
    Return meme only after successful payment.
    """
    return {
        "slug": slug,
        "message": "Payment verified, enjoy your meme!",
        "valid_until": receipt.valid_until if receipt else None
    }

🔁 3. Request Flow

StepDescription
1️⃣Client requests /memes/rare-001
2️⃣Server returns 402 Payment Required + tiers JSON
3️⃣Client selects tier, sends payment proof
4️⃣fx402-fastapi verifies payment and issues receipt
5️⃣Endpoint executes and returns resource

🧾 4. Customizing Tiers & Rights

@r402(cfg, tiers=[
    R402Tier(id="30d", seconds=2592000, amount="6.00", currency="USDC")
], modes=["view", "commercial-lite"])
def get_poster():
    ...

Each tier defines:

  • id: unique key (1d, 7d, etc.)
  • seconds: license duration
  • amount and currency: payment price
  • modes: permitted rights

🧠 5. Working with Receipts

The receipt param is automatically injected by the decorator if verification succeeds:

def get_file(receipt: R402Receipt):
    print(receipt.tier_id, receipt.valid_until)

Example Receipt Object:

{
  "resource": "meme:rare-001",
  "tier_id": "7d",
  "valid_until": "2025-11-05T00:00:00Z",
  "paid": { "amount": "2.00", "currency": "USDC", "chain": "solana" }
}

🔐 6. Advanced Options

Manual Verification

from fx402_fastapi import verify_payment
 
valid = verify_payment(tx="4sJQd2cA...FyW", chain="solana")

Custom Facilitator

cfg = R402Config(
    pay_to="SoLWallet111...xyz",
    chain="solana",
    facilitator_url="https://custom-facilitator.example/settle"
)

Returning Files or Media

from fastapi.responses import FileResponse
 
@app.get("/download")
@r402(cfg, tiers=[R402Tier(id="1d", seconds=86400, amount="1.00", currency="USDC")])
def download(receipt: R402Receipt):
    return FileResponse("poster.png")

✅ Summary

ObjectPurpose
R402ConfigSets wallet, chain, facilitator URL
R402TierDefines time-based pricing tiers
@r402()Decorator that enforces payment flow
R402ReceiptInjected proof of payment and license validity
verify_payment()Optional helper for manual validation

📚 Next Steps

Last updated on
JavaScript Quickstart (@fx402/r402)