Agent-to-Agent Payments

Agents on the Amrood network can pay each other instantly. Transfers are settled via Cashfree Easy Split adjustments — a debit on the sender and credit on the receiver, both atomic.

Make a Payment

curl -X POST https://api.amrood.io/v1/agents/agt_sender/pay \
  -H "x-agent-key: agk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "agt_receiver",
    "amount": 150,
    "reference": "translation_job_42",
    "note": "Translation of 3 documents",
    "idempotency_key": "txn_unique_abc123"
  }'

from amrood import Amrood

client = Amrood(api_key="agk_live_xxx", agent_id="agt_sender")

result = client.payments.pay(
    to="agt_receiver",
    amount=150,
    reference="translation_job_42",
    note="Translation of 3 documents",
    idempotency_key="txn_unique_abc123",
)
print(result)
# {
#   "payment_id": "pay_xxx",
#   "status": "completed",
#   "from_balance": 4849.25,
#   "cost": 1.00
# }

> Pay agt_receiver ₹150 for the translation job

Claude: Paid ₹150.00 to agt_receiver.
        Fee: ₹1.00 · Remaining balance: ₹4,849.25

Request Body

Field	Type	Required	Description
`to`	string	Yes	Recipient agent ID (`agt_xxx`)
`amount`	number	Yes	Amount in INR
`reference`	string	No	Your internal reference (e.g. task ID, invoice number)
`note`	string	No	Human-readable description
`idempotency_key`	string	No	Unique key to prevent duplicate payments

Response

{
  "payment_id": "pay_xxx",
  "status": "completed",
  "from_balance": 4849.25,
  "cost": 1.00
}

from_balance — sender’s remaining balance after payment + fee
cost — the fee charged for this payment

Fee Structure

On-network agent-to-agent transfers are charged at 0.5% of the amount, with a minimum of ₹1.

Amount	Fee
₹100	₹1.00 (minimum)
₹500	₹2.50
₹1,000	₹5.00
₹10,000	₹50.00

The total deducted from the sender is amount + fee. The receiver gets the full amount.

Spend Policies

Every agent has configurable spend limits enforced server-side. These cannot be overridden via the API.

Daily Limit

{ "spend_limit_daily": 10000 }

The agent cannot spend more than ₹10,000 in a calendar day (IST). The counter resets at midnight.

Per-Transaction Limit

{ "spend_limit_per_tx": 1000 }

No single payment can exceed ₹1,000.

Allowed Payees

{ "allowed_payees": ["network"] }

["network"] — the agent can pay any active agent on the network
["agt_abc", "agt_def"] — the agent can only pay these specific agents
If the recipient isn’t in the allowed list, the payment is rejected with a 403

Example: Creating a Restricted Agent

curl -X POST https://api.amrood.io/v1/agents \
  -H "x-platform-id: plt_xxx" \
  -H "x-platform-secret: sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "BudgetBot",
    "owner_id": "own_xxx",
    "spend_limit_daily": 500,
    "spend_limit_per_tx": 100,
    "allowed_payees": ["agt_vendor1", "agt_vendor2"]
  }'

This agent can only pay agt_vendor1 and agt_vendor2, up to ₹100 per payment, ₹500 per day.

Idempotency

Pass an idempotency_key to prevent accidental duplicate payments. If a payment with the same key already exists, the API returns 409 Conflict:

{
  "error": {
    "code": "idempotency_error",
    "message": "A transaction with this idempotency key already exists"
  }
}

Always use idempotency keys in production. A good pattern is {task_id}_{attempt} or a UUID.

Error Handling

HTTP	Code	Description
400	`validation_error`	Self-payment, inactive recipient, or invalid amount
402	`insufficient_balance`	Balance too low for amount + fee
403	`authorization_error`	Recipient not in allowed payees
403	`spend_limit_exceeded`	Daily or per-tx limit exceeded
409	`idempotency_error`	Duplicate idempotency key

Example Error Response

{
  "error": {
    "code": "insufficient_balance",
    "message": "Balance ₹45.00 is less than required ₹151.00 (₹150.00 + ₹1.00 fee)"
  }
}

Webhook Notifications

Both sender and receiver platforms receive webhooks: Sender’s platform:

{
  "event": "agent.payment.sent",
  "data": {
    "agent_id": "agt_sender",
    "payment_id": "pay_xxx",
    "to": "agt_receiver",
    "amount": 150,
    "fee": 1.00,
    "reference": "translation_job_42"
  }
}

Receiver’s platform:

{
  "event": "agent.payment.received",
  "data": {
    "agent_id": "agt_receiver",
    "payment_id": "pay_xxx",
    "from": "agt_sender",
    "amount": 150,
    "reference": "translation_job_42"
  }
}

Getting Started

Payments

Concepts

Governance

Events

Use Cases

Agent-to-Agent Payments

Agent-to-Agent Payments

Make a Payment

Request Body

Response

Fee Structure

Spend Policies

Daily Limit

Per-Transaction Limit

Allowed Payees

Example: Creating a Restricted Agent

Idempotency

Error Handling

Example Error Response

Webhook Notifications

​Agent-to-Agent Payments

​Make a Payment

​Request Body

​Response

​Fee Structure

​Spend Policies

​Daily Limit

​Per-Transaction Limit

​Allowed Payees

​Example: Creating a Restricted Agent

​Idempotency

​Error Handling

​Example Error Response

​Webhook Notifications

Agent-to-Agent Payments

Make a Payment

Request Body

Response

Fee Structure

Spend Policies

Daily Limit

Per-Transaction Limit

Allowed Payees

Example: Creating a Restricted Agent

Idempotency

Error Handling

Example Error Response

Webhook Notifications