get_top_pools_by_token
Identify top liquidity pools for a specific token by contract address across supported blockchains. Filter results by network, include attributes like base/quote tokens or DEX, and sort by volume or transaction count for better decision-making in DeFi trading.
Instructions
Get top pools for a specific token by contract address
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| include | No | Attributes to include: 'base_token', 'quote_token', 'dex' (comma-separated) | |
| network | Yes | Network ID (e.g., 'eth', 'bsc', 'polygon_pos') | |
| 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') | |
| tokenAddress | Yes | Token contract address |
Input Schema (JSON Schema)
{
"properties": {
"include": {
"description": "Attributes to include: 'base_token', 'quote_token', 'dex' (comma-separated)",
"type": "string"
},
"network": {
"description": "Network ID (e.g., 'eth', 'bsc', 'polygon_pos')",
"type": "string"
},
"page": {
"description": "Page number for pagination (optional, default: 1)",
"type": "integer"
},
"sort": {
"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"
],
"type": "string"
},
"tokenAddress": {
"description": "Token contract address",
"type": "string"
}
},
"required": [
"network",
"tokenAddress"
],
"type": "object"
}
Implementation Reference
- Core handler function that executes the tool logic by making HTTP request to CoinGecko API to fetch top pools for a specific tokenasync 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/toolService.js:277-296 (handler)ToolService wrapper handler that validates parameters, calls CoinGeckoApiService, and formats the MCP responseasync 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)MCP input schema definition and tool registration in ListToolsRequestHandlername: 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)Registration and dispatch in MCP CallToolRequestHandler switch statementcase 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/constants.js:30-30 (helper)Constant definition for the tool name used across the codebaseGET_TOP_POOLS_BY_TOKEN: "get_top_pools_by_token",