get_hip3_liquidation_volume

Instructions

Implementation Reference

• src/index.ts:760-769 (registration)

  Registration of the 'get_hip3_liquidation_volume' tool via registerHistoryTool helper pattern. It uses the SDK api().hyperliquid.hip3.liquidations.volume call with a HIP-3 coin (case-sensitive) and an optional aggregation interval.

  // 21c. HIP-3 Liquidation Volume
  registerHistoryTool(
    "get_hip3_liquidation_volume",
    "Get aggregated HIP-3 liquidation volume for a coin in time-bucketed intervals. Returns total, long, and short USD volumes. Symbols are CASE-SENSITIVE (e.g. 'km:US500'). Data available from February 2026.",
    (coin, params) =>
      api().hyperliquid.hip3.liquidations.volume(coin, params as any),
    Hip3CoinParam,
    normalizeHip3Coin,
    { interval: z.enum(["5m", "15m", "30m", "1h", "4h", "1d"]).optional().describe("Aggregation interval: '5m', '15m', '30m', '1h', '4h', '1d'. Default '1h'") }
  );

• src/index.ts:407-438 (helper)

  The registerHistoryTool helper that generates the tool handler for get_hip3_liquidation_volume. It builds query params (start, end, limit, cursor, plus extra interval), normalizes the coin via normalizeHip3Coin, calls the SDK's liquidations.volume method, and formats the cursor-paginated response.

  // Pattern 4: History with cursor pagination (coin + time range)
  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:57-61 (schema)

  Zod schema for the HIP-3 coin parameter input, used by get_hip3_liquidation_volume.

  const Hip3CoinParam = z
    .string()
    .describe(
      "HIP-3 coin symbol (CASE-SENSITIVE). 125+ markets across 6 builders: xyz, flx, hyna, km, vntl, cash. Examples: 'km:US500', 'xyz:GOLD', 'hyna:BTC', 'vntl:SPACEX', 'flx:TSLA', 'cash:NVDA'. Use get_hip3_instruments to list all."
    );

• src/index.ts:108-111 (schema)

  The aggregation interval schema. However, get_hip3_liquidation_volume uses an inline enum for interval rather than reusing AggregationIntervalParam.

  const AggregationIntervalParam = z
    .enum(["5m", "15m", "30m", "1h", "4h", "1d"])
    .optional()
    .describe("Aggregation interval. Omit for raw ~1 min data.");

• src/index.ts:300-302 (helper)

  The coin normalization function for HIP-3 symbols (pass-through, case-sensitive), used by get_hip3_liquidation_volume.

  function normalizeHip3Coin(coin: string): string {
    return coin; // Case-sensitive
  }