Skip to main content

​
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"
  }'

​
Request Body

FieldTypeRequiredDescription
tostringYesRecipient agent ID (agt_xxx)
amountnumberYesAmount in INR
referencestringNoYour internal reference (e.g. task ID, invoice number)
notestringNoHuman-readable description
idempotency_keystringNoUnique 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.
AmountFee
₹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

HTTPCodeDescription
400validation_errorSelf-payment, inactive recipient, or invalid amount
402insufficient_balanceBalance too low for amount + fee
403authorization_errorRecipient not in allowed payees
403spend_limit_exceededDaily or per-tx limit exceeded
409idempotency_errorDuplicate 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"
  }
}