get_top_pools_by_token

Find the most active liquidity pools for any token by contract address across multiple blockchains to analyze trading opportunities.

Instructions

Get top pools for a specific token by contract address

Input Schema

TableJSON Schema

Name	Required	Description
`network`	Yes	Network ID (e.g., 'eth', 'bsc', 'polygon_pos')
`tokenAddress`	Yes	Token contract address
`include`	No	Attributes to include: 'base_token', 'quote_token', 'dex' (comma-separated)
`page`	No	Page number for pagination (optional, default: 1)
`sort`	No	Sort by: 'h24_volume_usd_liquidity_desc', 'h24_tx_count_desc', 'h24_volume_usd_desc' (optional, default: 'h24_volume_usd_liquidity_desc')

Implementation Reference

src/toolService.js:277-296 (handler)

Main handler function for the 'get_top_pools_by_token' MCP tool. Validates inputs, calls CoinGecko API service, and formats the response.

async getTopPoolsByToken(network, tokenAddress, options = {}) {
  if (!network || !tokenAddress) {
    throw new Error("Missing required parameters: network, tokenAddress");
  }

  const result = await this.coinGeckoApi.getTopPoolsByToken(
    network,
    tokenAddress,
    options
  );

  return {
    message: `Top pools for token ${tokenAddress} on ${network} retrieved successfully`,
    data: result,
    summary: `Found ${
      result.data?.length || 0
    } pools for token ${tokenAddress}`,
    sort: options.sort || "h24_volume_usd_liquidity_desc",
  };
}

src/index.js:436-471 (schema)

Input schema and description definition for the 'get_top_pools_by_token' tool in MCP tool listing.

  name: TOOL_NAMES.GET_TOP_POOLS_BY_TOKEN,
  description: "Get top pools for a specific token by contract address",
  inputSchema: {
    type: "object",
    properties: {
      network: {
        type: "string",
        description: "Network ID (e.g., 'eth', 'bsc', 'polygon_pos')",
      },
      tokenAddress: {
        type: "string",
        description: "Token contract address",
      },
      include: {
        type: "string",
        description:
          "Attributes to include: 'base_token', 'quote_token', 'dex' (comma-separated)",
      },
      page: {
        type: "integer",
        description: "Page number for pagination (optional, default: 1)",
      },
      sort: {
        type: "string",
        description:
          "Sort by: 'h24_volume_usd_liquidity_desc', 'h24_tx_count_desc', 'h24_volume_usd_desc' (optional, default: 'h24_volume_usd_liquidity_desc')",
        enum: [
          "h24_volume_usd_liquidity_desc",
          "h24_tx_count_desc",
          "h24_volume_usd_desc",
        ],
      },
    },
    required: ["network", "tokenAddress"],
  },
},

src/index.js:1072-1082 (registration)

Tool execution registration in the MCP CallToolRequestHandler switch statement, mapping tool name to handler.

case TOOL_NAMES.GET_TOP_POOLS_BY_TOKEN:
  result = await toolService.getTopPoolsByToken(
    args.network,
    args.tokenAddress,
    {
      include: args.include,
      page: args.page,
      sort: args.sort,
    }
  );
  break;

src/services/coinGeckoApiService.js:241-265 (helper)

Core helper function that performs the HTTP request to CoinGecko's onchain API to fetch top pools for a given token.

async getTopPoolsByToken(network, tokenAddress, options = {}) {
  try {
    const queryParams = new URLSearchParams();
    
    if (options.include) queryParams.append('include', options.include);
    if (options.page) queryParams.append('page', options.page);
    if (options.sort) queryParams.append('sort', options.sort);

    const url = `${this.baseUrl}/networks/${network}/tokens/${tokenAddress}/pools${queryParams.toString() ? '?' + queryParams.toString() : ''}`;
    
    const response = await fetch(url, {
      headers: {
        'x-cg-demo-api-key': this.apiKey
      }
    });
    
    if (!response.ok) {
      throw new Error(`HTTP ${response.status}: ${response.statusText}`);
    }
    
    return await response.json();
  } catch (error) {
    throw new Error(`Failed to get top pools by token: ${error.message}`);
  }
}

src/constants.js:30-30 (registration)
Constant definition for the tool name used in registration and handler mapping.
```
GET_TOP_POOLS_BY_TOKEN: "get_top_pools_by_token",
```

DeFi Trading Agent MCP Server