pulse_global_stats

Instructions

Implementation Reference

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

  Registration of the pulse_global_stats tool with the MCP server, including its description, input schema (optional useToonFormat boolean), and the handler that delegates to the callAPI helper.

  if (shouldRegister("pulse_global_stats")) server.registerTool(
    "pulse_global_stats",
    {
      description: "Get global Hyperliquid trading statistics: total traders, trades, volume, PnL, and data coverage period. Use this to understand the overall scale of the market.",
      inputSchema: { useToonFormat: useToonFormatSchema },
    },
    async ({ useToonFormat }) => toolResult(await callAPI(useToonFormat, "/pulse/stats"))
  );

• src/index.ts:244-244 (handler)

  Handler function: takes useToonFormat, calls the Coinversa API at /pulse/stats endpoint, and wraps the result via toolResult() for MCP response format.

  async ({ useToonFormat }) => toolResult(await callAPI(useToonFormat, "/pulse/stats"))

• src/index.ts:54-57 (schema)

  Shared input schema (useToonFormatSchema) used by pulse_global_stats and other tools. Accepts a boolean defaulting to true.

  const useToonFormatSchema = z
    .boolean()
    .default(true)
    .describe("Return data in compact toon format (default: true). Set to false for standard JSON.");

• src/index.ts:172-175 (helper)

  Helper function that wraps API response data into the MCP text content format for tool results.

  function toolResult(data: any) {
    return { content: [{ type: "text" as const, text: formatJSON(data) }] };
  }

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

  Generic API helper that pulse_global_stats uses to call the /pulse/stats endpoint on the Coinversa backend with timeout, retries, and optional toon-format encoding.

  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");
  }