get_token_balances

Instructions

Implementation Reference

• src/server.ts:68-90 (registration)

  Tool registration for 'get_token_balances' via server.registerTool(). Delegates to fetchTokenBalances().

  // ── Tool: get_token_balances ─────────────────────────────────────────────────
  
  server.registerTool(
    "get_token_balances",
    {
      description:
        "Spot token balances only (no DeFi positions). Use when the question is specifically about token holdings: 'does this wallet hold ETH?', 'how much USDC is on Base?'",
      inputSchema: {
        address: z.string().describe("Wallet address or ENS name"),
        networks: networksSchema,
      },
    },
    async ({ address, networks }) => {
      try {
        const result = await fetchTokenBalances(apiKey, address, resolveChainIds(networks));
        return {
          content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
        };
      } catch (err) {
        return errorResponse(err);
      }
    },
  );

• src/zapper.ts:333-348 (handler)

  The actual handler function fetchTokenBalances() that executes the logic: queries Zapper GraphQL API for token balances and returns typed TokenBalancesResult.

  export async function fetchTokenBalances(
    apiKey: string,
    address: string,
    chainIds?: number[],
  ): Promise<TokenBalancesResult> {
    const data = (await gql(apiKey, TOKEN_BALANCES_QUERY, {
      addresses: [address],
      chainIds: chainIds ?? null,
    })) as { portfolioV2: { tokenBalances: { totalBalanceUSD: number; byToken: { edges: Array<{ node: GqlTokenNode }> } } } };
  
    const tb = data.portfolioV2.tokenBalances;
    return {
      totalUSD: tb.totalBalanceUSD ?? 0,
      tokens: tb.byToken.edges.map(({ node }) => parseTokenNode(node)),
    };
  }

• src/zapper.ts:27-39 (schema)

  Type definitions: TokenBalance interface and TokenBalancesResult interface defining the output shape.

  export interface TokenBalance {
    symbol: string;
    name: string;
    balance: number;
    balanceUSD: number;
    price: number;
    network: string;
  }
  
  export interface TokenBalancesResult {
    totalUSD: number;
    tokens: TokenBalance[];
  }

• src/server.ts:74-78 (schema)

  Input schema for the tool: address (string) and optional networks (array of strings).

    "Spot token balances only (no DeFi positions). Use when the question is specifically about token holdings: 'does this wallet hold ETH?', 'how much USDC is on Base?'",
  inputSchema: {
    address: z.string().describe("Wallet address or ENS name"),
    networks: networksSchema,
  },

• src/zapper.ts:120-140 (helper)

  The TOKEN_BALANCES_QUERY GraphQL string used by fetchTokenBalances to query the Zapper API.

  const TOKEN_BALANCES_QUERY = `
    query TokenBalances($addresses: [Address!]!, $chainIds: [Int!]) {
      portfolioV2(addresses: $addresses, chainIds: $chainIds) {
        tokenBalances {
          totalBalanceUSD
          byToken(first: 50) {
            edges {
              node {
                symbol
                name
                balance
                balanceUSD
                price
                network { name }
              }
            }
          }
        }
      }
    }
  `;