Skip to main content

Wallet Portfolio Assistant

Answer "what does wallet X hold on chain Y?" in one round trip.

MCP tools

  • get_wallet_portfolio
  • get_tokens
  • get_exchange_rate

API endpoints

  • GET /v4/data/wallet/portfolio
  • GET /v4/data/wallet/tokens

Steps

  1. Parse the user prompt for address and chain.
  2. Validate the address shape for that chain.
  3. Call get_wallet_portfolio (or the Wallet API endpoint).
  4. Optionally enrich with get_exchange_rate to convert to a user-friendly quote currency.
  5. Return a structured summary: native balance, top tokens by value, NFT count.

Agent trace

The call sequence an MCP-capable agent logs when it runs this workflow.

  1. Validate the address shape per chain 
    // shape check: EVM addresses are 0x + 40 hex chars
const ok = /^0x[a-fA-F0-9]{40}$/.test(address);
if (!ok) throw new Error("not an evm address");
  2. Pull the aggregated portfolio 
    mcp.tatumio.get_wallet_portfolio({
  address: "0xab5801a7d398351b8be11c439e05c5b3259aec9b",
  chain:   "ethereum-mainnet"
})
  3. Decode + summarise the response 
    // → { native: { balance: "1.23", token: "ETH" },
//      tokens:  [ { symbol: "USDC", balance: "812.04" }, ... ] }
"Wallet holds 1.23 ETH + 5 tokens (USDC top by USD value)."

Possible failures

  • Unsupported chain for the address
  • Address checksum invalid for the chain
  • Token contract returns malformed metadata

Recovery guidance

  • Validate address against chain rules before calling
  • Surface the chain support list from /api/chains when the chain is unknown
  • Skip malformed tokens, never fail the whole portfolio call