Get Top DEX Pairs

Instructions

Implementation Reference

• mcp-server/src/index.ts:266-289 (registration)

  Registration of 'get-top-pairs' tool via server.registerTool() with its name, schema, and handler.

  server.registerTool(
    'get-top-pairs',
    {
      title: 'Get Top DEX Pairs',
      description: 'List top PulseX DEX trading pairs by volume.',
      inputSchema: {
        limit: z.number().min(1).max(500).optional().describe('Number of pairs (default 20, max 500)'),
      },
      outputSchema: z.object({
        pairs: z.array(z.object({
          pair_address: z.string().describe('DEX pair contract address'),
          token0_symbol: z.string().describe('First token symbol'),
          token1_symbol: z.string().describe('Second token symbol'),
          volume_24h: z.number().describe('24-hour volume in USD'),
          liquidity_usd: z.number().describe('Total pair liquidity in USD'),
        }).passthrough()).describe('Array of top trading pairs'),
      }).passthrough(),
      annotations: READ_ONLY_ANNOTATIONS,
    },
    async ({ limit }) => {
      const data = await fetchJSON(`${API}/api/v1/pairs?limit=${limit ?? 20}`)
      return wrapResult(data)
    }
  )

• mcp-server/src/index.ts:268-283 (schema)

  Input/output schema definitions for get-top-pairs: input accepts optional 'limit' (number, 1-500), output returns array of pairs with pair_address, token0_symbol, token1_symbol, volume_24h, liquidity_usd.

  {
    title: 'Get Top DEX Pairs',
    description: 'List top PulseX DEX trading pairs by volume.',
    inputSchema: {
      limit: z.number().min(1).max(500).optional().describe('Number of pairs (default 20, max 500)'),
    },
    outputSchema: z.object({
      pairs: z.array(z.object({
        pair_address: z.string().describe('DEX pair contract address'),
        token0_symbol: z.string().describe('First token symbol'),
        token1_symbol: z.string().describe('Second token symbol'),
        volume_24h: z.number().describe('24-hour volume in USD'),
        liquidity_usd: z.number().describe('Total pair liquidity in USD'),
      }).passthrough()).describe('Array of top trading pairs'),
    }).passthrough(),
    annotations: READ_ONLY_ANNOTATIONS,

• mcp-server/src/index.ts:284-289 (handler)

  Handler function for get-top-pairs: accepts { limit }, calls fetchJSON to fetch pairs from API endpoint /api/v1/pairs, and wraps the result via wrapResult().

    },
    async ({ limit }) => {
      const data = await fetchJSON(`${API}/api/v1/pairs?limit=${limit ?? 20}`)
      return wrapResult(data)
    }
  )

• mcp-server/src/index.ts:54-74 (helper)

  fetchJSON helper: generic async function to fetch JSON from a URL with auth header and timeout.

  async function fetchJSON(url: string): Promise<any> {
    const headers: Record<string, string> = { 'Accept': 'application/json' }
    if (HAS_API_KEY) headers['Authorization'] = `Bearer ${API_KEY}`
    const controller = new AbortController()
    const timer = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS)
    try {
      const res = await fetch(url, { headers, signal: controller.signal })
      if (!res.ok) {
        if (res.status === 401 || res.status === 403) {
          throw new Error(
            `API ${res.status}: This endpoint requires a valid API key. ` +
            `Get one at ${PRICING_URL}`
          )
        }
        throw new Error(`API request failed with status ${res.status}`)
      }
      return res.json()
    } finally {
      clearTimeout(timer)
    }
  }

• mcp-server/src/index.ts:127-132 (helper)

  wrapResult helper: wraps API response data into MCP-compatible ToolResult format with text JSON and structuredContent.

  function wrapResult(data: any): ToolResult {
    return {
      content: [{ type: 'text' as const, text: JSON.stringify(data, null, 2) }],
      structuredContent: data,
    }
  }