> ## Documentation Index
> Fetch the complete documentation index at: https://docs.amrood.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Agent-to-Agent Payments

> Send instant INR transfers between agents on the network

# 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

<CodeGroup>
  ```bash cURL theme={null}
  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"
    }'
  ```

  ```python Python SDK theme={null}
  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
  # }
  ```

  ```text MCP (natural language) theme={null}
  > Pay agt_receiver ₹150 for the translation job

  Claude: Paid ₹150.00 to agt_receiver.
          Fee: ₹1.00 · Remaining balance: ₹4,849.25
  ```
</CodeGroup>

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

```json theme={null}
{
  "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

```json theme={null}
{ "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

```json theme={null}
{ "spend_limit_per_tx": 1000 }
```

No single payment can exceed ₹1,000.

### Allowed Payees

```json theme={null}
{ "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

```bash theme={null}
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`:

```json theme={null}
{
  "error": {
    "code": "idempotency_error",
    "message": "A transaction with this idempotency key already exists"
  }
}
```

<Tip>
  Always use idempotency keys in production. A good pattern is `{task_id}_{attempt}` or a UUID.
</Tip>

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

```json theme={null}
{
  "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:**

```json theme={null}
{
  "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:**

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.