bnbchain-mcp

Instructions

Implementation Reference

• src/evm/modules/tokens/tools.ts:35-57 (registration)

  Full registration of the get_native_balance MCP tool, including description, input schema, and handler function.

    "get_native_balance",
    "Get native token balance for an address",
    {
      network: defaultNetworkParam,
      address: z
        .string()
        .optional()
        .describe("The address to check balance for"),
      privateKey: privateKeyParam
    },
    async ({ network, address, privateKey }) => {
      try {
        const result = await services.getNativeBalance(
          address || privateKeyToAccount(privateKey as Hex).address,
          network
        )
  
        return mcpToolRes.success(result)
      } catch (error) {
        return mcpToolRes.error(error, "fetching native token balance")
      }
    }
  )

• src/evm/services/balance.ts:13-37 (handler)

  Core handler logic for fetching native balance: resolves address/ENS, uses viem to get balance, formats with ether units and metadata.

  export async function getNativeBalance(
    addressOrEns: string,
    network = "bsc"
  ): Promise<{
    raw: bigint
    formatted: string
    network: string
    symbol: string
    decimals: number
  }> {
    // Resolve ENS name to address if needed
    const address = await resolveAddress(addressOrEns, network)
  
    const client = getPublicClient(network)
    const balance = await client.getBalance({ address })
    const nativeCurrency = client.chain?.nativeCurrency
  
    return {
      raw: balance,
      formatted: formatEther(balance),
      network,
      symbol: nativeCurrency?.symbol ?? "Unknown",
      decimals: nativeCurrency?.decimals ?? 18
    }
  }

• src/evm/modules/tokens/tools.ts:37-44 (schema)

  Input schema for get_native_balance tool using Zod: network, optional address, optional privateKey (to derive address).

  {
    network: defaultNetworkParam,
    address: z
      .string()
      .optional()
      .describe("The address to check balance for"),
    privateKey: privateKeyParam
  },

• src/evm/modules/tokens/tools.ts:45-56 (helper)

  Tool wrapper handler: derives address from privateKey if needed, calls getNativeBalance service, wraps response in MCP format.

  async ({ network, address, privateKey }) => {
    try {
      const result = await services.getNativeBalance(
        address || privateKeyToAccount(privateKey as Hex).address,
        network
      )
  
      return mcpToolRes.success(result)
    } catch (error) {
      return mcpToolRes.error(error, "fetching native token balance")
    }
  }