Metadata-Version: 2.4
Name: amrood-mcp
Version: 0.4.0
Summary: MCP server for Amrood — give your AI agent a KYC-verified INR wallet
License: MIT
Project-URL: Homepage, https://amrood.io
Project-URL: Documentation, https://docs.amrood.io
Project-URL: Repository, https://github.com/amroodio/amrood
Keywords: mcp,amrood,payments,ai-agents
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: mcp>=1.0.0
Requires-Dist: httpx>=0.25.0

# amrood-mcp

<!-- mcp-name: io.github.saurabh-karn/amrood-mcp -->

MCP server for [Amrood](https://amrood.io) — payment infrastructure for AI agents in India.

Give your AI agent a KYC-verified wallet. Agents can hold INR, pay other agents, hold funds in escrow, and settle to their owner's bank account — all through MCP tools.

## Quick Start

### With an existing agent key

```json
{
  "mcpServers": {
    "amrood": {
      "command": "uvx",
      "args": ["amrood-mcp"],
      "env": {
        "AMROOD_AGENT_KEY": "agk_live_xxx"
      }
    }
  }
}
```

### Fresh onboarding (no key yet)

```json
{
  "mcpServers": {
    "amrood": {
      "command": "uvx",
      "args": ["amrood-mcp"]
    }
  }
}
```

Then ask your AI assistant to "register me on Amrood" and follow the OTP flow.

## How Money Works

### Funding an Agent

An agent's owner adds funds through a Cashfree payment link (UPI, card, or netbanking). The agent calls `amrood_fund` to generate a payment link, the human completes the payment, and the agent's balance is credited automatically.

```
Owner opens payment link → pays via UPI/card
  → Cashfree PG processes the payment
    → Agent's wallet balance is credited
```

Funds are held in a Cashfree Easy Split escrow account linked to the owner's PAN-verified identity. Amrood is non-custodial — it never holds the money directly.

### Agent-to-Agent Payments

Agents pay each other instantly using `amrood_pay`. Specify the recipient by handle (e.g. `researchbot`) or agent ID. A 0.5% fee (minimum ₹1) is deducted from the sender.

```
Agent A calls amrood_pay(to="agentb", amount=100)
  → ₹100 credited to Agent B's balance
  → ₹1 fee deducted from Agent A
  → Both balances update instantly
```

Same-owner transfers (two agents owned by the same person) are ledger-only — no external payment gateway calls, instant settlement.

### Escrow

For conditional payments, agents can hold funds in escrow before releasing them:

- **Basic hold** — funds held until explicitly released or refunded
- **Timed hold** — auto-refunds if not released within a deadline
- **Attested hold** — requires a third-party agent to approve before release

```
Agent A holds ₹500 in escrow
  → Agent B completes the work
    → Agent A releases escrow to Agent B
      → ₹500 credited to Agent B
```

### Withdrawals

Owners can withdraw funds from an agent's wallet to their verified bank account in two ways:

- **Via MCP**: Call `amrood_withdraw` with the agent ID and optional amount (defaults to full balance)
- **Via Web Dashboard**: Click the "Withdraw" button on the agent card at [amrood.io/profile](https://amrood.io/profile)

The agent's ledger balance is reduced immediately. The actual money reaches the bank via Cashfree's settlement cycle.

```
Agent calls amrood_withdraw(amount=500)
  → Agent balance reduced by ₹500
  → Owner receives SMS + WhatsApp confirmation
  → Funds settle to owner's bank on next T+2 cycle
```

If Cashfree has already auto-settled the escrow balance, the withdrawal is processed as a ledger-only update (balance deducted, no duplicate bank transfer).

### Settlement (How Money Reaches Your Bank)

Amrood uses Cashfree Easy Split for all fund management. Here's how settlement works:

- **Schedule**: All vendor balances are settled on a **T+2 basis** (2 business days after the transaction, at 11:00 AM).
- **Auto-settlement**: Cashfree automatically transfers the vendor's unsettled balance to the owner's linked bank account.
- **On settlement, agent balances are zeroed out**: When funds are settled to the bank, all agent wallets under that owner reset to ₹0. A settlement transaction is recorded for each agent.
- **Notification**: The owner receives an SMS and WhatsApp notification listing which agents were affected and how much was settled.

```
Day 0: Agent funded with ₹1,000
Day 0: Agent pays ₹200 to another agent, withdraws ₹300
        → Agent balance: ₹499 (after ₹1 fee)
Day 2: Cashfree auto-settles full vendor balance to owner's bank
        → Agent balance resets to ₹0
        → Owner receives SMS: "₹X settled to your HDFC account"
        → Owner re-funds agents as needed
```

**Why zeroing out?** Withdrawals and same-owner transfers are ledger-only operations — they reduce the agent's balance in Amrood but don't move money out of Cashfree's escrow. When Cashfree settles the full escrow balance to the bank, any remaining agent balance would be unbacked. Zeroing out keeps the ledger honest.

### HTTP 402 Paywall (x402-style)

Amrood supports an x402-style payment protocol over HTTP — any API can charge per-call in INR, and AI agents with Amrood wallets can pay automatically.

**How it works:**

```
1. Agent requests a paywalled API endpoint
2. Server returns HTTP 402 with X-AMROOD-PAY header (amount, payee, nonce)
3. Agent pays the specified payee via amrood_pay
4. Agent retries the request with X-AMROOD-PAYMENT header (transaction proof)
5. Server verifies the payment via Amrood's /verify endpoint
6. Server returns the resource
```

**As an AI agent (client)** — use the `amrood_http_pay` tool. It handles the full 402 flow automatically:

```
"Fetch data from https://api.example.com/premium"
  → amrood_http_pay(url="https://api.example.com/premium")
  → Automatically pays ₹5 to @databot, retries, returns the data
```

**As an API developer (server)** — install `amrood-paywall` and add a one-line decorator:

```python
pip install amrood-paywall
```

```python
from amrood_paywall import amrood_pay

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

Set `AMROOD_AGENT_KEY` to your agent's API key so the server can verify incoming payments.

See [`amrood-paywall` on PyPI](https://pypi.org/project/amrood-paywall/) for full documentation.

### Spend Policies

Owners can configure guardrails on each agent:

- **Daily spend limit** — max amount the agent can spend per day
- **Per-transaction limit** — max amount per single payment
- **Allowed payees** — restrict which agents can receive payments

## Available Tools

### Onboarding (create an account via MCP)

| Tool | Description |
|---|---|
| `amrood_register` | Start signup — sends OTP to a 10-digit Indian phone number |
| `amrood_verify` | Verify the OTP code and create/login the account |
| `amrood_kyc` | Submit KYC — PAN card + bank account or UPI ID |
| `amrood_create_agent` | Create an agent with a unique handle, returns the API key |

### Wallet & Payments

| Tool | Description |
|---|---|
| `amrood_balance` | Check wallet balance, total funded, total spent |
| `amrood_pay` | Pay another agent by handle or ID |
| `amrood_fund` | Generate a payment link to add funds |
| `amrood_withdraw` | Withdraw funds to owner's bank account |
| `amrood_transactions` | View transaction history with filters |
| `amrood_http_pay` | Make an HTTP request with automatic x402 payment handling |

### Escrow

| Tool | Description |
|---|---|
| `amrood_escrow_hold` | Hold funds in escrow (basic, timed, or attested) |
| `amrood_escrow_release` | Release escrowed funds to a recipient |
| `amrood_escrow_refund` | Refund escrowed funds to sender |
| `amrood_escrow_status` | Check escrow status |

### Identity & Verification

| Tool | Description |
|---|---|
| `amrood_identity` | View own handle, name, and status |
| `amrood_proof` | Generate a platform-signed proof of network membership |
| `amrood_verify_agent` | Check if an agent exists on the network |
| `amrood_status` | Check auth status and connectivity |

## Environment Variables

| Variable | Required | Description |
|---|---|---|
| `AMROOD_AGENT_KEY` | No | Agent API key (skips onboarding if provided) |
| `AMROOD_AGENT_ID` | No | Agent ID (auto-resolved from key if not set) |
| `AMROOD_BASE_URL` | No | API base URL (default: `https://amrood.io`) |

## Key Concepts

| Term | Meaning |
|---|---|
| **Owner** | A PAN-verified human who owns one or more agents |
| **Agent** | A programmable payment identity with its own wallet and API key |
| **Handle** | A unique username for an agent (e.g. `researchbot`) — used for payments and discovery |
| **Vendor** | The Cashfree Easy Split entity linked to an owner's bank account |
| **Settlement** | The process of Cashfree transferring escrowed funds to the owner's bank (T+2) |
| **Escrow** | Funds held conditionally — released on approval, refunded on timeout or dispute |

## Example: Full Agent Lifecycle

```
1. "Register me on Amrood"           → amrood_register (sends OTP)
2. "My code is 123456"               → amrood_verify (creates account)
3. "My PAN is ABCDE1234F, bank ..."  → amrood_kyc (verifies identity)
4. "Create an agent called ResBot"   → amrood_create_agent (returns API key)
5. "Fund my agent with ₹500"         → amrood_fund (returns payment link)
6. [Owner pays via UPI]              → balance credited automatically
7. "Pay @translator ₹50"             → amrood_pay (instant transfer)
8. "Hold ₹200 in escrow"             → amrood_escrow_hold
9. "Release escrow to @writer"       → amrood_escrow_release
10. "Withdraw ₹100"                  → amrood_withdraw (settles to bank at T+2)
```

## Development

```bash
cd mcp
pip install -e .
amrood-mcp
```

## Links

- [Amrood Website](https://amrood.io)
- [API Documentation](https://docs.amrood.io)
- [GitHub](https://github.com/amroodio/amrood)
