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

# Balance & Transactions

> Check agent balances and query transaction history

# Balance & Transactions

## Check Balance

<CodeGroup>
  ```bash cURL theme={null}
  curl https://api.amrood.io/v1/agents/agt_xxx/balance \
    -H "x-agent-key: agk_live_xxx"
  ```

  ```python Python SDK theme={null}
  from amrood import Amrood

  client = Amrood(api_key="agk_live_xxx", agent_id="agt_xxx")
  balance = client.wallet.balance()
  print(balance)
  # { "available": 8500.00, "total_funded": 50000.00, "total_spent": 41500.00 }
  ```

  ```text MCP (natural language) theme={null}
  > What's my agent's balance?

  Claude: Your balance is ₹8,500.00.
          Total funded: ₹50,000.00 · Total spent: ₹41,500.00
  ```
</CodeGroup>

### Response

```json theme={null}
{
  "available": 8500.00,
  "total_funded": 50000.00,
  "total_spent": 41500.00
}
```

| Field          | Description                                                   |
| -------------- | ------------------------------------------------------------- |
| `available`    | Current spendable balance                                     |
| `total_funded` | Lifetime funds received (owner payments + incoming transfers) |
| `total_spent`  | Lifetime amount spent (outgoing payments + fees)              |

<Note>
  Balance is a cached value updated atomically on every funding and payment. It is not recomputed from transaction history.
</Note>

## List Transactions

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://api.amrood.io/v1/agents/agt_xxx/transactions?limit=10&type=pay_out" \
    -H "x-agent-key: agk_live_xxx"
  ```

  ```python Python SDK theme={null}
  # The SDK doesn't have a transactions method yet.
  # Use the REST API directly with httpx:
  import httpx

  resp = httpx.get(
      "https://api.amrood.io/v1/agents/agt_xxx/transactions",
      headers={"x-agent-key": "agk_live_xxx"},
      params={"limit": 10, "type": "pay_out"},
  )
  print(resp.json())
  ```

  ```text MCP (natural language) theme={null}
  > Show my last 5 transactions

  Claude: Here are your recent transactions:
          1. PAY_OUT  ₹150.00 → agt_receiver  (translation_job_42)
          2. PAY_IN   ₹200.00 ← agt_client    (research_task_7)
          3. FUND     ₹5,000.00               (fund_abc123)
          ...
  ```
</CodeGroup>

### Query Parameters

| Param       | Type     | Default | Description                |
| ----------- | -------- | ------- | -------------------------- |
| `type`      | string   | all     | Filter by transaction type |
| `status`    | string   | all     | Filter by status           |
| `from_date` | ISO date | —       | Start date (inclusive)     |
| `to_date`   | ISO date | —       | End date (inclusive)       |
| `limit`     | integer  | 20      | Results per page (max 100) |
| `offset`    | integer  | 0       | Pagination offset          |

### Transaction Types

| Type         | Description                         |
| ------------ | ----------------------------------- |
| `fund`       | Wallet funded by owner              |
| `pay_out`    | Outgoing payment to another agent   |
| `pay_in`     | Incoming payment from another agent |
| `withdraw`   | Withdrawal to owner's bank          |
| `settlement` | Automatic T+2 settlement            |
| `fee`        | Fee deduction                       |

### Transaction Statuses

| Status      | Description                                 |
| ----------- | ------------------------------------------- |
| `pending`   | In progress (e.g. funding awaiting payment) |
| `completed` | Successfully processed                      |
| `failed`    | Payment failed                              |
| `reversed`  | Reversed after completion                   |

### Response

```json theme={null}
{
  "transactions": [
    {
      "id": "txn_abc123",
      "type": "pay_out",
      "amount": 150.00,
      "fee": 1.00,
      "net_amount": 151.00,
      "counterparty_type": "agent",
      "counterparty_id": "agt_receiver",
      "agent_name": "Research Bot",
      "counterparty_name": "Translator Bot",
      "reference": "translation_job_42",
      "note": "Translation of 3 documents",
      "status": "completed",
      "created_at": "2025-06-15T10:30:00Z"
    }
  ],
  "pagination": {
    "total": 47,
    "limit": 20,
    "offset": 0
  }
}
```

## Withdrawal

Withdraw the agent's balance to the owner's bank account:

<CodeGroup>
  ```bash cURL theme={null}
  # Withdraw full balance
  curl -X POST https://api.amrood.io/v1/agents/agt_xxx/withdraw \
    -H "x-agent-key: agk_live_xxx" \
    -H "Content-Type: application/json" \
    -d '{}'

  # Withdraw specific amount
  curl -X POST https://api.amrood.io/v1/agents/agt_xxx/withdraw \
    -H "x-agent-key: agk_live_xxx" \
    -H "Content-Type: application/json" \
    -d '{ "amount": 2000 }'
  ```

  ```python Python SDK theme={null}
  # Withdraw full balance
  client.wallet.withdraw()

  # Withdraw specific amount
  client.wallet.withdraw(amount=2000)
  ```
</CodeGroup>

Withdrawals are processed via Cashfree vendor settlement. Funds arrive in the owner's bank account within 1-2 business days.

## Owner-Level Transaction View

Owners can view transactions across **all their agents** in one place:

* **Via Dashboard**: Visit the **Transactions** page at [amrood.io/transactions](https://amrood.io/transactions)
* **Via API**: `GET /api/web/transactions` (session-authenticated)

## Transaction Verification

For [x402-style payments](/payments/x402-paywall), you can verify a specific transaction:

```bash theme={null}
GET /v1/transactions/{txn_id}/verify?expected_payee=databot&expected_amount=5.00&nonce=uuid
x-agent-key: agk_live_xxx
```

See [HTTP 402 Paywall](/payments/x402-paywall) for details.

## Automatic Settlement

Unused agent balances settle to the owner's bank account on a **T+2 schedule** (two business days). When settlement occurs, all agent balances under the vendor are **zeroed out** — see [Agent Wallets](/concepts/wallets) for details.

When settlement occurs, Amrood fires an `agent.settlement.completed` webhook:

```json theme={null}
{
  "event": "agent.settlement.completed",
  "data": {
    "agent_id": "agt_xxx",
    "amount": 3200.00,
    "utr": "UTR123456789"
  }
}
```