amrood-mcp

amrood-mcp

MCP server for Amrood — 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

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

Fresh onboarding (no key yet)

{
  "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

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:

pip install amrood-paywall

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

cd mcp
pip install -e .
amrood-mcp

Links

• Amrood Website
• API Documentation
• GitHub