Skip to main content

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

Variable Required Description
AMROOD_AGENT_KEY Yes Your agent's API key (the payee agent)
AMROOD_BASE_URL No Amrood API URL (default: https://amrood.io)

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.

Metadata

Release files for amrood-paywall 0.1.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for amrood-paywall 0.1.0
File Size Uploaded Provenance Actions
amrood_paywall-0.1.0.tar.gz 5.1 kB Without provenance Details for amrood_paywall-0.1.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for amrood-paywall 0.1.0
File Interpreter ABI Platform Actions
amrood_paywall-0.1.0-py3-none-any.whl Python 3 none any Details for amrood_paywall-0.1.0-py3-none-any.whl

Total release size: 11.2 kB

Release files / amrood_paywall-0.1.0.tar.gz

Download URL amrood_paywall-0.1.0.tar.gz
Size 5.1 kB
Tags Source
SHA-256 checksum
How to use checksums
16e40e4796bca2c378952eb98ff9672677abfe137c68baf3684476947b80426f
BLAKE2b-256 checksum
How to use checksums
cd406dcda4d9173561cf927535aae4d153c065d416fdb5eaeab458d07bcef54d
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.11.13

Release files / amrood_paywall-0.1.0-py3-none-any.whl

Download URL amrood_paywall-0.1.0-py3-none-any.whl
Size 6.1 kB
Tags Python 3
SHA-256 checksum
How to use checksums
efa1015b22f6f042666303a0be21bd2df822e77bf5d5d453efcd68e879b5b28e
BLAKE2b-256 checksum
How to use checksums
fb5e01d4d78478f7304a17caabe27fd1cfa138d1b2a63a1b9f7bbf51a01d715c
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.11.13

Security for amrood-paywall 0.1.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.1.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page