> ## 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"
  }
}
```