# 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 using `amrood_withdraw`. Withdrawals update the agent's ledger balance immediately.

```
Agent calls amrood_withdraw(amount=500)
  → Agent balance reduced by ₹500
  → Funds marked for settlement to owner's bank
```

### 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.

### 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 |

### 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)
