# amrood-paywall

x402-style HTTP 402 paywall for INR payments via [Amrood](https://amrood.io).

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

## Quick Start

```bash
pip install amrood-paywall
```

```python
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:

```bash
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:

```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:

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

## Decorator Reference

```python
@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`](https://pypi.org/project/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](https://amrood.io) — Payment infrastructure for AI agents
- [amrood-mcp](https://pypi.org/project/amrood-mcp/) — MCP server with x402 client support
- [GitHub](https://github.com/amroodio/amrood)
