pulse_token_leaderboard

Instructions

Implementation Reference

• src/index.ts:787-799 (registration)

  Tool registration: pulse_token_leaderboard is registered with server.registerTool(). It calls the API endpoint /pulse/token-leaderboard/{coin} with a limit parameter.

  if (shouldRegister("pulse_token_leaderboard")) server.registerTool(
    "pulse_token_leaderboard",
    {
      description: "Get the top traders for a specific coin. Answers questions like 'who are the best BTC traders?' or 'who profits most from SOL?'. Returns ranked traders with PnL, trade count, win rate, and volume for that specific coin.",
      inputSchema: {
        useToonFormat: useToonFormatSchema,
        coin: z.string().min(1).max(20).describe("Coin symbol (e.g. BTC, ETH, SOL). For builder dex markets use prefix:COIN (e.g. xyz:SILVER, km:OIL, cash:TSLA)"),
        limit: z.number().min(1).max(100).default(50).describe("Number of traders to return"),
      },
    },
    async ({ useToonFormat, coin, limit }) =>
      toolResult(await callAPI(useToonFormat, `/pulse/token-leaderboard/${normalizeCoin(coin)}`, { limit: String(limit) }))
  );

• src/index.ts:790-796 (schema)

  Input schema for pulse_token_leaderboard: accepts useToonFormat (boolean), coin (string 1-20 chars with builder dex prefix support), and limit (number 1-100, default 50).

    description: "Get the top traders for a specific coin. Answers questions like 'who are the best BTC traders?' or 'who profits most from SOL?'. Returns ranked traders with PnL, trade count, win rate, and volume for that specific coin.",
    inputSchema: {
      useToonFormat: useToonFormatSchema,
      coin: z.string().min(1).max(20).describe("Coin symbol (e.g. BTC, ETH, SOL). For builder dex markets use prefix:COIN (e.g. xyz:SILVER, km:OIL, cash:TSLA)"),
      limit: z.number().min(1).max(100).default(50).describe("Number of traders to return"),
    },
  },

• src/index.ts:797-799 (handler)

  Handler function: calls the API at /pulse/token-leaderboard/{coin} with the normalized coin symbol and limit parameter, then returns the result via toolResult().

    async ({ useToonFormat, coin, limit }) =>
      toolResult(await callAPI(useToonFormat, `/pulse/token-leaderboard/${normalizeCoin(coin)}`, { limit: String(limit) }))
  );

• src/index.ts:84-91 (helper)

  normalizeCoin helper function: uppercase the coin name while preserving a lowercase builder dex prefix (e.g. 'xyz:silver' → 'xyz:SILVER', 'btc' → 'BTC'). Used by pulse_token_leaderboard to normalize the coin input before calling the API.

  function normalizeCoin(raw: string): string {
    const idx = raw.indexOf(':');
    if (idx !== -1) {
      // Builder dex format — keep prefix lowercase, uppercase the coin
      return raw.slice(0, idx).toLowerCase() + ':' + raw.slice(idx + 1).toUpperCase();
    }
    return raw.toUpperCase();
  }

• src/index.ts:94-166 (helper)

  callAPI helper: makes HTTP requests to the Coinversa API with timeout, retries, and error handling. Used by pulse_token_leaderboard handler to make the actual API call.

  async function callAPI(useToon: boolean, path: string, params?: Record<string, string>): Promise<any> {
    const url = new URL(`${BASE}${path}`);
    if (params) {
      Object.entries(params).forEach(([key, value]) => {
        if (value !== undefined && value !== "") {
          url.searchParams.set(key, value);
        }
      });
    }
  
    let lastError: Error | null = null;
  
    for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
      try {
        const controller = new AbortController();
        const timeout = setTimeout(() => controller.abort(), REQUEST_TIMEOUT_MS);
  
        const headers: Record<string, string> = {};
        if (API_KEY) headers["X-API-Key"] = API_KEY;
  
        const response = await fetch(url.toString(), {
          headers,
          signal: controller.signal,
        });
  
        clearTimeout(timeout);
  
        if (response.status === 429) {
          // Rate limited — retry after delay
          if (attempt < MAX_RETRIES) {
            await new Promise((r) => setTimeout(r, RETRY_DELAY_MS * (attempt + 1)));
            continue;
          }
          throw new Error("Rate limit exceeded. Please wait a moment and try again.");
        }
  
        if (response.status === 404) {
          throw new Error("Not found. The requested resource does not exist — check the address or symbol.");
        }
  
        if (response.status === 401) {
          throw new Error("Invalid API key. Check your COINVERSAA_API_KEY environment variable.");
        }
  
        if (!response.ok) {
          const body = await response.json().catch(() => null);
          const msg = body?.error || response.statusText;
          throw new Error(`Request failed (${response.status}): ${msg}`);
        }
  
        const data = await response.json();
        return useToon ? toonEncode(data) : data;
      } catch (err: any) {
        if (err.name === "AbortError") {
          lastError = new Error("Request timed out after 30 seconds. The server may be under heavy load — try again.");
        } else if (err.cause?.code === "ECONNREFUSED" || err.cause?.code === "ENOTFOUND") {
          lastError = new Error("Cannot connect to the Coinversa API. Check your COINVERSAA_API_URL setting and network connection.");
        } else {
          lastError = err;
        }
  
        // Retry on transient network errors
        if (attempt < MAX_RETRIES && (err.name === "AbortError" || err.cause?.code === "ECONNRESET")) {
          await new Promise((r) => setTimeout(r, RETRY_DELAY_MS * (attempt + 1)));
          continue;
        }
  
        throw lastError;
      }
    }
  
    throw lastError || new Error("Request failed after retries");
  }