Balance & Transactions

Check Balance

curl https://api.amrood.io/v1/agents/agt_xxx/balance \
  -H "x-agent-key: agk_live_xxx"

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 }

> What's my agent's balance?

Claude: Your balance is ₹8,500.00.
        Total funded: ₹50,000.00 · Total spent: ₹41,500.00

Response

{
  "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)

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

List Transactions

curl "https://api.amrood.io/v1/agents/agt_xxx/transactions?limit=10&type=pay_out" \
  -H "x-agent-key: agk_live_xxx"

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

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

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

{
  "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:

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

# Withdraw full balance
client.wallet.withdraw()

# Withdraw specific amount
client.wallet.withdraw(amount=2000)

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
Via API: GET /api/web/transactions (session-authenticated)

Transaction Verification

For x402-style payments, you can verify a specific transaction:

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 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 for details. When settlement occurs, Amrood fires an agent.settlement.completed webhook:

{
  "event": "agent.settlement.completed",
  "data": {
    "agent_id": "agt_xxx",
    "amount": 3200.00,
    "utr": "UTR123456789"
  }
}

Getting Started

Payments

Concepts

Governance

Events

Use Cases

Balance & Transactions

Balance & Transactions

Check Balance

Response

List Transactions

Query Parameters

Transaction Types

Transaction Statuses

Response

Withdrawal

Owner-Level Transaction View

Transaction Verification

Automatic Settlement

​Balance & Transactions

​Check Balance

​Response

​List Transactions

​Query Parameters

​Transaction Types

​Transaction Statuses

​Response

​Withdrawal

​Owner-Level Transaction View

​Transaction Verification

​Automatic Settlement

Balance & Transactions

Check Balance

Response

List Transactions

Query Parameters

Transaction Types

Transaction Statuses

Response

Withdrawal

Owner-Level Transaction View

Transaction Verification

Automatic Settlement