amrood-paywall

x402-style HTTP 402 paywall for INR payments via Amrood.

Add pay-per-call pricing to any FastAPI endpoint in one line. AI agents with Amrood wallets pay automatically.

Quick Start

pip install amrood-paywall

from fastapi import FastAPI, Request
from amrood_paywall import amrood_pay

app = FastAPI()

@app.get("/api/data")
@amrood_pay(amount="5.00", pay_to="databot")
async def get_data(request: Request):
    return {"data": "premium content"}

Set your agent's API key so the server can verify incoming payments:

export AMROOD_AGENT_KEY=agk_live_xxx

How It Works

1. Client:  GET /api/data
2. Server:  402 Payment Required + X-AMROOD-PAY header
3. Client:  Pays ₹5.00 to @databot via Amrood API
4. Client:  GET /api/data + X-AMROOD-PAYMENT header (with transaction proof)
5. Server:  Verifies payment via Amrood's /v1/transactions/{id}/verify
6. Server:  200 OK + data

Payments between Amrood agents are instant and settled in INR. No crypto, no blockchain, no gas fees.

Protocol Headers

X-AMROOD-PAY (server → client)

Returned with HTTP 402 responses. Base64-encoded JSON:

{
  "version": 1,
  "payTo": "databot",
  "amount": "5.00",
  "asset": "INR",
  "resource": "/api/data",
  "description": "Payment for /api/data",
  "nonce": "n_abc123",
  "expiresAt": "2026-03-07T09:00:00Z"
}

X-AMROOD-PAYMENT (client → server)

Sent by the client after making the payment. Base64-encoded JSON:

{
  "version": 1,
  "transactionId": "txn_xyz789",
  "fromAgent": "researchbot",
  "nonce": "n_abc123"
}

Decorator Reference

@amrood_pay(
    amount="5.00",           # Price in INR (required)
    pay_to="databot",        # Amrood agent handle or ID (required)
    description="Premium data access",  # Human-readable (optional)
    agent_key="agk_live_...",  # Override AMROOD_AGENT_KEY env var (optional)
    base_url="https://amrood.io",  # Override AMROOD_BASE_URL (optional)
    expiry_seconds=600,      # Payment instruction validity (default 10 min)
)

Environment Variables

Client-Side (for AI agents)

If you're building an AI agent that needs to pay for APIs, use amrood-mcp which includes the amrood_http_pay tool. It handles the full 402 flow automatically:

"Fetch https://api.example.com/premium"
  → Agent detects 402, pays ₹5 to @databot, retries with proof
  → Returns the premium data

Replay Protection

Each 402 response includes a unique nonce. The server tracks used nonces in-memory with a 10-minute TTL. A payment proof with a reused nonce is rejected with HTTP 409.

Links

• Amrood — Payment infrastructure for AI agents
• amrood-mcp — MCP server with x402 client support
• GitHub