Bankless Onchain MCP Server

Instructions

Implementation Reference

• src/operations/tokens.ts:21-87 (handler)

  The primary handler function that executes the tool logic by querying the Bankless API for token balances on a specified network and address, with comprehensive error handling for various HTTP status codes.

  export async function getTokenBalancesOnNetwork(
    network: string,
    address: string
  ): Promise<{
    balances: Array<{
      amount: number;
      network: string;
      token: {
        network: string;
        logo: string;
        name: string;
        symbol: string;
        address: string;
        decimals: number;
        totalSupply: number;
        underlyingTokens: Array<any>;
        verified: boolean;
        type: string;
      };
      price: number;
      decimalAmount: number;
      dollarValue: number;
    }>;
    totalDollarValue: number;
  }> {
    const token = process.env.BANKLESS_API_TOKEN;
    
    if (!token) {
      throw new BanklessAuthenticationError('BANKLESS_API_TOKEN environment variable is not set');
    }
  
    const endpoint = `${BASE_URL}/token/balance/${address}/${network}`;
    
    try {
      const response = await axios.get(
        endpoint,
        {
          headers: {
            'Content-Type': 'application/json',
            'X-BANKLESS-TOKEN': `${token}`
          }
        }
      );
  
      return response.data;
    } catch (error) {
      if (axios.isAxiosError(error)) {
        const statusCode = error.response?.status || 'unknown';
        const errorMessage = error.response?.data?.message || error.message;
        
        if (statusCode === 401 || statusCode === 403) {
          throw new BanklessAuthenticationError(`Authentication Failed: ${errorMessage}`);
        } else if (statusCode === 404) {
          throw new BanklessResourceNotFoundError(`Address or network not found: ${address} on ${network}`);
        } else if (statusCode === 422) {
          throw new BanklessValidationError(`Validation Error: ${errorMessage}`, error.response?.data);
        } else if (statusCode === 429) {
          const resetAt = new Date();
          resetAt.setSeconds(resetAt.getSeconds() + 60);
          throw new BanklessRateLimitError(`Rate Limit Exceeded: ${errorMessage}`, resetAt);
        }
        
        throw new Error(`Bankless API Error (${statusCode}): ${errorMessage}`);
      }
      throw new Error(`Failed to get token balances: ${error instanceof Error ? error.message : String(error)}`);
    }
  }

• src/operations/tokens.ts:8-11 (schema)

  Zod schema defining the input parameters for the tool: network and address.

  export const TokenBalancesOnNetworkSchema = z.object({
    network: z.string().describe('The blockchain network (e.g., "ethereum", "base")'),
    address: z.string().describe('The address to check token balances for')
  });

• src/index.ts:124-127 (registration)

  Tool registration in the MCP server's list of tools, including name, description, and input schema reference.

      name: "get_token_balances_on_network",
      description: "Gets all token balances for a given address on a specific network",
      inputSchema: zodToJsonSchema(tokens.TokenBalancesOnNetworkSchema),
  },

• src/index.ts:245-254 (registration)

  Dispatcher case in the CallToolRequestHandler that validates input with the schema and invokes the handler function.

  case "get_token_balances_on_network": {
      const args = tokens.TokenBalancesOnNetworkSchema.parse(request.params.arguments);
      const result = await tokens.getTokenBalancesOnNetwork(
          args.network,
          args.address
      );
      return {
          content: [{type: "text", text: JSON.stringify(result, null, 2)}],
      };
  }