← all AgentPay tools

wallet_balance

Get the token balances for any Ethereum or Stellar wallet address.

When agents use this

You need to look up the token holdings of an Ethereum or Stellar wallet address.

Parameters

name	type	required	description
chain	string	yes	Blockchain to query
address	string	yes	Wallet address (Ethereum 0x... or Stellar G...)

Returns

list of token balances (symbol, amount) for the given address

Example response

{
  "address": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
  "chain": "ethereum",
  "balances": [
    {
      "token": "ETH",
      "amount": "1.234"
    },
    {
      "token": "USDC",
      "contract": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
      "amount": "500.00"
    }
  ]
}

Call it — HTTP (x402)

curl -X POST https://agentpay.tools/tools/wallet_balance/call \
  -H 'Content-Type: application/json' \
  -d '{"parameters": {"chain": "Blockchain to query", "address": "Wallet address (Ethereum 0x... or Stellar G...)"}, "agent_address": "<your wallet or any identifier>"}'

Call it — Python SDK

from agentpay import quickstart  # pip install agentpay-x402

s = quickstart(max_spend=0.10)   # hard budget cap; mints a wallet, no funding needed
r = s.call("wallet_balance", {"chain": "Blockchain to query", "address": "Wallet address (Ethereum 0x... or Stellar G...)"})
print(r.data)                    # + r.cost, r.tx, r.network — full receipt

Call it — MCP

npx -y @romudille/agentpay-mcp   # keyless; exposes wallet_balance to any MCP agent runtime