account-balance

Instructions

Implementation Reference

• src/tools/private.ts:23-58 (handler)

  The core handler function that executes the 'account-balance' tool logic: authenticates with the exchange using provided credentials, fetches the balance via ccxt-like API, formats the response, and handles errors.

  }, async ({ exchange, apiKey, secret, passphrase, marketType }) => {
    try {
      return await rateLimiter.execute(exchange, async () => {
        // Get exchange with market type
        const ex = getExchangeWithCredentials(exchange, apiKey, secret, marketType, passphrase);
        
        // Fetch balance
        log(LogLevel.INFO, `Fetching account balance for ${exchange}`);
        const balance = await ex.fetchBalance();
        
        // Format the balance for better readability
        const formattedBalance = {
          total: balance.total,
          free: balance.free,
          used: balance.used,
          timestamp: new Date(balance.timestamp || Date.now()).toISOString()
        };
        
        return {
          content: [{
            type: "text",
            text: JSON.stringify(formattedBalance, null, 2)
          }]
        };
      });
    } catch (error) {
      log(LogLevel.ERROR, `Error fetching account balance: ${error instanceof Error ? error.message : String(error)}`);
      return {
        content: [{
          type: "text",
          text: `Error fetching account balance: ${error instanceof Error ? error.message : String(error)}`
        }],
        isError: true
      };
    }
  });

• src/tools/private.ts:18-22 (schema)

  Zod input schema for validating parameters: exchange ID, API credentials, optional passphrase and market type.

  exchange: z.string().describe("Exchange ID (e.g., binance, coinbase)"),
  apiKey: z.string().describe("API key for authentication"),
  secret: z.string().describe("API secret for authentication"),
  passphrase: z.string().optional().describe("Passphrase for authentication (required for some exchanges like KuCoin)"),
  marketType: z.enum(["spot", "future", "swap", "option", "margin"]).optional().describe("Market type (default: spot)")

• src/tools/private.ts:17-58 (registration)

  The direct registration of the 'account-balance' tool using McpServer.tool() method within registerPrivateTools, specifying name, description, input schema, and handler.

  server.tool("account-balance", "Get your account balance from a crypto exchange", {
    exchange: z.string().describe("Exchange ID (e.g., binance, coinbase)"),
    apiKey: z.string().describe("API key for authentication"),
    secret: z.string().describe("API secret for authentication"),
    passphrase: z.string().optional().describe("Passphrase for authentication (required for some exchanges like KuCoin)"),
    marketType: z.enum(["spot", "future", "swap", "option", "margin"]).optional().describe("Market type (default: spot)")
  }, async ({ exchange, apiKey, secret, passphrase, marketType }) => {
    try {
      return await rateLimiter.execute(exchange, async () => {
        // Get exchange with market type
        const ex = getExchangeWithCredentials(exchange, apiKey, secret, marketType, passphrase);
        
        // Fetch balance
        log(LogLevel.INFO, `Fetching account balance for ${exchange}`);
        const balance = await ex.fetchBalance();
        
        // Format the balance for better readability
        const formattedBalance = {
          total: balance.total,
          free: balance.free,
          used: balance.used,
          timestamp: new Date(balance.timestamp || Date.now()).toISOString()
        };
        
        return {
          content: [{
            type: "text",
            text: JSON.stringify(formattedBalance, null, 2)
          }]
        };
      });
    } catch (error) {
      log(LogLevel.ERROR, `Error fetching account balance: ${error instanceof Error ? error.message : String(error)}`);
      return {
        content: [{
          type: "text",
          text: `Error fetching account balance: ${error instanceof Error ? error.message : String(error)}`
        }],
        isError: true
      };
    }
  });

• src/tools/index.ts:28-28 (registration)

  Invocation of registerPrivateTools in the tools index, which registers the private tools including 'account-balance'.

  registerPrivateTools(server);

• src/index.ts:194-194 (registration)

  Top-level call to registerAllTools in the main server file, which chains to private tools registration including 'account-balance'.

  registerAllTools(server);