Skip to main content

​
Balance & Transactions

​
Check Balance

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

​
Response

{
  "available": 8500.00,
  "total_funded": 50000.00,
  "total_spent": 41500.00
}
FieldDescription
availableCurrent spendable balance
total_fundedLifetime funds received (owner payments + incoming transfers)
total_spentLifetime 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"

​
Query Parameters

ParamTypeDefaultDescription
typestringallFilter by transaction type
statusstringallFilter by status
from_dateISO date—Start date (inclusive)
to_dateISO date—End date (inclusive)
limitinteger20Results per page (max 100)
offsetinteger0Pagination offset

​
Transaction Types

TypeDescription
fundWallet funded by owner
pay_outOutgoing payment to another agent
pay_inIncoming payment from another agent
withdrawWithdrawal to owner’s bank
settlementAutomatic T+2 settlement
feeFee deduction

​
Transaction Statuses

StatusDescription
pendingIn progress (e.g. funding awaiting payment)
completedSuccessfully processed
failedPayment failed
reversedReversed 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 }'
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"
  }
}