get_liquidation_volume

Instructions

Implementation Reference

• src/index.ts:592-601 (registration)

  Registration of the 'get_liquidation_volume' tool using the registerHistoryTool helper. It is tool #12, registered under the Hyperliquid section.

  // 12. Liquidation Volume
  registerHistoryTool(
    "get_liquidation_volume",
    "Get aggregated liquidation volume for a coin in time-bucketed intervals. Returns total, long, and short USD volumes. Data available from May 2025.",
    (coin, params) =>
      api().hyperliquid.liquidations.volume(coin, params as any),
    CoinParam,
    normalizeHLCoin,
    { interval: z.enum(["5m", "15m", "30m", "1h", "4h", "1d"]).optional().describe("Aggregation interval: '5m', '15m', '30m', '1h', '4h', '1d'. Default '1h'") }
  );

• src/index.ts:408-437 (handler)

  The registerHistoryTool factory function that generates the actual handler logic for get_liquidation_volume. It resolves time range, injects the interval param via extra, calls api().hyperliquid.liquidations.volume(), and formats the cursor-paginated response.

  function registerHistoryTool(
    name: string,
    description: string,
    sdkCall: (coin: string, params: Record<string, unknown>) => Promise<{ data: unknown; nextCursor?: string }>,
    coinSchema: z.ZodString,
    normFn: (coin: string) => string,
    extraSchema?: ZodRawShape
  ): void {
    const schema: ZodRawShape = { coin: coinSchema, ...HistoryParams };
    if (extraSchema) Object.assign(schema, extraSchema);
  
    registerTool(name, description, schema, ListOutputSchema, async (params) => {
      const { coin, start, end, limit, cursor, ...extra } = params;
  
      const timeRange = resolveTimeRange(start, end);
      const sdkParams: Record<string, unknown> = {
        ...timeRange,
        limit: resolveLimit(limit),
      };
  
      if (cursor) sdkParams.cursor = cursor;
  
      // Pass through extra params (interval, side, etc.)
      for (const [k, v] of Object.entries(extra)) {
        if (v !== undefined) sdkParams[k] = v;
      }
  
      const result = await sdkCall(normFn(coin), sdkParams);
      return formatCursorResponse(result);
    });

• src/index.ts:600-601 (schema)

  The extra input schema passed for the interval parameter, defined inline as a Zod enum of aggregation intervals.

    { interval: z.enum(["5m", "15m", "30m", "1h", "4h", "1d"]).optional().describe("Aggregation interval: '5m', '15m', '30m', '1h', '4h', '1d'. Default '1h'") }
  );

• src/index.ts:129-136 (schema)

  The output schema used by get_liquidation_volume (ListOutputSchema), defining returned records, count, and optional nextCursor.

  const ListOutputSchema: ZodRawShape = {
    records: z.array(z.record(z.unknown())).describe("Array of result records"),
    count: z.number().describe("Total number of records in the full result set"),
    nextCursor: z
      .string()
      .optional()
      .describe("Cursor for next page, if more results available"),
  };

• src/index.ts:328-358 (helper)

  The generic registerTool helper that wraps the SDK's server.registerTool, adds API key guard, and standardizes error handling. Used by registerHistoryTool which is ultimately called for get_liquidation_volume.

  function registerTool(
    name: string,
    description: string,
    inputSchema: ZodRawShape,
    outputSchema: ZodRawShape,
    handler: (params: any) => Promise<McpContent>
  ): void {
    server.registerTool(
      name,
      {
        description,
        inputSchema,
        outputSchema,
        annotations: TOOL_ANNOTATIONS,
      },
      async (params: any) => {
        if (!client) {
          return {
            content: [{ type: "text" as const, text: MISSING_KEY_MESSAGE }],
            isError: true,
          };
        }
        try {
          return await handler(params);
        } catch (err) {
          const error = err instanceof OxArchiveError ? err : new OxArchiveError(String(err), 500);
          return formatError(error);
        }
      }
    );
  }