get_balance

Instructions

Implementation Reference

• src/tools/account.ts:17-63 (handler)

  The main handler function for get_balance tool. Validates exchange input, gets the exchange connector, calls connector.getBalance() to fetch balances, optionally filters by asset, and returns the formatted JSON response with balance information.

  async ({ exchange, asset }) => {
    const validExchange = validateExchange(exchange);
  
    const connector = await getConnectorSafe(exchange);
    const balances = await connector.getBalance();
  
    let entries = Object.values(balances);
    if (asset) {
      const upperAsset = asset.toUpperCase();
      entries = entries.filter((b) => b.asset.toUpperCase() === upperAsset);
      if (entries.length === 0) {
        return {
          content: [
            {
              type: 'text' as const,
              text: JSON.stringify(
                {
                  asset: upperAsset,
                  message: `No balance found for asset: ${upperAsset}`,
                  exchange: validExchange,
                },
                null,
                2
              ),
            },
          ],
        };
      }
    }
  
    return {
      content: [
        {
          type: 'text' as const,
          text: JSON.stringify(
            {
              balances: entries,
              totalAssets: entries.length,
              exchange: validExchange,
            },
            null,
            2
          ),
        },
      ],
    };
  }

• src/tools/account.ts:6-64 (registration)

  The registration of the get_balance tool with the MCP server using server.tool(). Defines the tool name, description, input schema (exchange and optional asset), and associates it with the handler function.

  export function registerAccountTools(server: McpServer): void {
    server.tool(
      'get_balance',
      'Get account balances for all assets (or a specific asset) on a supported exchange',
      {
        exchange: ExchangeParam,
        asset: z
          .string()
          .optional()
          .describe('Optional asset to filter by (e.g., USDT, BTC). Returns all assets if omitted.'),
      },
      async ({ exchange, asset }) => {
        const validExchange = validateExchange(exchange);
  
        const connector = await getConnectorSafe(exchange);
        const balances = await connector.getBalance();
  
        let entries = Object.values(balances);
        if (asset) {
          const upperAsset = asset.toUpperCase();
          entries = entries.filter((b) => b.asset.toUpperCase() === upperAsset);
          if (entries.length === 0) {
            return {
              content: [
                {
                  type: 'text' as const,
                  text: JSON.stringify(
                    {
                      asset: upperAsset,
                      message: `No balance found for asset: ${upperAsset}`,
                      exchange: validExchange,
                    },
                    null,
                    2
                  ),
                },
              ],
            };
          }
        }
  
        return {
          content: [
            {
              type: 'text' as const,
              text: JSON.stringify(
                {
                  balances: entries,
                  totalAssets: entries.length,
                  exchange: validExchange,
                },
                null,
                2
              ),
            },
          ],
        };
      }
    );

• src/tools/account.ts:10-16 (schema)

  Input parameter schema for get_balance tool. Defines 'exchange' parameter (required, using ExchangeParam) and 'asset' parameter (optional string to filter by specific asset like USDT, BTC).

  {
    exchange: ExchangeParam,
    asset: z
      .string()
      .optional()
      .describe('Optional asset to filter by (e.g., USDT, BTC). Returns all assets if omitted.'),
  },

• src/utils/validators.ts:3-5 (schema)

  Schema definition for ExchangeParam used by get_balance. A zod string schema that describes supported exchanges (mexc, gateio, bitget, kraken).

  export const ExchangeParam = z
    .string()
    .describe('Exchange to query. Supported: mexc, gateio, bitget, kraken');

• src/exchange/exchange-manager.ts:16-25 (helper)

  getConnectorSafe helper function used by get_balance handler. Validates the exchange string and returns a BaseExchangeConnector instance from the ExchangeFactory, with error handling for connection failures.

  export async function getConnectorSafe(exchange: string): Promise<BaseExchangeConnector> {
    const validExchange = validateExchange(exchange);
    const { ExchangeFactory } = await import('@3rd-eye-labs/openmm');
    try {
      return await ExchangeFactory.getExchange(validExchange as any);
    } catch (error) {
      const message = error instanceof Error ? error.message : String(error);
      throw new Error(`Failed to connect to ${validExchange}: ${message}`);
    }
  }