DEV Community

OpenClaw Cash
OpenClaw Cash

Posted on

Read your agent wallet's balances and transaction history

#api #agents #tutorial #webdev

Your agent moved money, and now someone asks where it went. OpenClawCash keeps a read side next to the wallet API: list your wallets, read the balances, then pull the merged transaction history. Three calls, copy-pasteable, and you can run the whole thing in one sitting.

What you need

  • An API key for the account that owns the wallets. Every call below sends it as X-Agent-Key: occ_your_api_key.
  • The API base URL, https://openclawcash.com.
  • Nothing else. These are reads: no Idempotency-Key header and no request signing.

1. List the wallets to get the walletId 

curl https://openclawcash.com/api/agent/wallets \
  -H "X-Agent-Key: occ_your_api_key"
Enter fullscreen mode Exit fullscreen mode

The response gives each wallet its id, label, address, network and chain:

[
  {
    "id": "Q7X2K9P",
    "label": "Trading Bot",
    "address": "0x14ae8d93...",
    "network": "sepolia",
    "chain": "evm"
  },
  {
    "id": "YUZE66Z",
    "label": "SOL TEST",
    "address": "GmjrX8...",
    "network": "solana-devnet",
    "chain": "solana"
  }
]
Enter fullscreen mode Exit fullscreen mode

Every call after this selects the wallet by that walletId (or by walletLabel or walletAddress). Prefer the id: older accounts can hold two wallets that share a label. If you want the native balance in the same response, add ?includeBalances=true and each row also carries balance and nativeSymbol.

2. Read one wallet's balances 

curl "https://openclawcash.com/api/agent/wallet?walletId=Q7X2K9P&chain=evm" \
  -H "X-Agent-Key: occ_your_api_key"
Enter fullscreen mode Exit fullscreen mode

The response is the wallet fields plus the native balance and every token balance:

{
  "id": "Q7X2K9P",
  "label": "MinWallet",
  "address": "0xManagedWalletAddress...",
  "network": "sepolia",
  "chain": "evm",
  "nativeBalanceDisplay": "0.0395",
  "nativeBalanceBaseUnits": "39500000000000000",
  "balance": "0.0395 ETH",
  "nativeSymbol": "ETH",
  "otherTokenCount": 0,
  "tokenBalances": [
    {
      "token": "0x0000...0000",
      "symbol": "ETH",
      "balance": "0.0395",
      "balanceBaseUnits": "39500000000000000",
      "decimals": 18
    }
  ]
}
Enter fullscreen mode Exit fullscreen mode

Keep the two shapes straight: the ...Display fields are ready for a human, the base-unit fields are the integer strings a service wants, and each token row carries its own decimals. The same split runs through every balance endpoint.

If you only want tokens and you want to filter, POST /api/agent/token-balance takes a wallet and an optional token:

curl -X POST https://openclawcash.com/api/agent/token-balance \
  -H "Content-Type: application/json" \
  -H "X-Agent-Key: occ_your_api_key" \
  -d '{ "walletId": "Q7X2K9P", "token": "USDC" }'
Enter fullscreen mode Exit fullscreen mode

Leave token out and it returns every supported token on the wallet.

3. Page through the transaction history 

curl "https://openclawcash.com/api/agent/transactions?walletId=YUZE66Z&chain=solana" \
  -H "X-Agent-Key: occ_your_api_key"
Enter fullscreen mode Exit fullscreen mode

This returns merged on-chain and app-recorded history for the wallet, and it works for both EVM and Solana wallets. Select the wallet with walletId, walletLabel or walletAddress; chain is optional and only enforces a wallet-chain match. For EVM wallets, network scopes the rows to mainnet, polygon-mainnet, base-mainnet or sepolia, and network=all merges across every EVM chain. Each row carries data.network, so you always know which chain it ran on. One row looks like this:

[
  {
    "id": 0,
    "walletId": "YUZE66Z",
    "hash": "5tS4...sig",
    "to": "GmjrX8...",
    "value": "1000000000",
    "fee": "5000",
    "platformFee": "0",
    "feePercent": "0%",
    "type": "transfer",
    "status": "confirmed",
    "data": "{\"source\":\"on-chain\",\"direction\":\"incoming\",\"token\":\"SOL\"}",
    "createdAt": "2026-02-19T17:15:00.000Z"
  }
]
Enter fullscreen mode Exit fullscreen mode

Two fee fields, and they are not the same thing. fee is the network gas fee in native base units, and it reads "0" until the transaction is indexed on-chain. platformFee is the OpenClawCash platform fee in base units of the transferred token, with feePercent as its rate.

4. Put it together 

const base = "https://openclawcash.com";
const headers = { "X-Agent-Key": process.env.OCC_API_KEY };

const wallets = await (await fetch(base + "/api/agent/wallets", { headers })).json();

for (const w of wallets) {
  const detail = await (await fetch(
    base + "/api/agent/wallet?walletId=" + w.id + "&chain=" + w.chain,
    { headers }
  )).json();
  console.log(w.label, detail.balance, detail.tokenBalances.length, "token rows");

  const txs = await (await fetch(
    base + "/api/agent/transactions?walletId=" + w.id + "&chain=" + w.chain,
    { headers }
  )).json();
  console.log(txs.length, "transactions on", w.chain);
}
Enter fullscreen mode Exit fullscreen mode

That is the whole audit loop: wallets, balances, history, for every wallet the key can see. The endpoints are read-only, so running it against production is safe. Full contract and the other endpoints are in the docs at https://openclawcash.com/docs.

Top comments (0)