get_hip3_l4_orderbook_history

Instructions

Implementation Reference

• src/index.ts:1250-1258 (registration)

  Registration of the 'get_hip3_l4_orderbook_history' tool using the registerHistoryTool helper pattern. It registers the tool with the description 'Get HIP-3 L4 orderbook checkpoints (Pro+ tier)...' and delegates to the SDK method api().hyperliquid.hip3.l4Orderbook.history(coin, params).

  // HIP-3 L4 Orderbook History (Checkpoints)
  registerHistoryTool(
    "get_hip3_l4_orderbook_history",
    "Get HIP-3 L4 orderbook checkpoints (Pro+ tier). Symbols are CASE-SENSITIVE (e.g. 'km:US500'). Returns periodic full order-level orderbook snapshots.",
    (coin, params) =>
      api().hyperliquid.hip3.l4Orderbook.history(coin, params as any),
    Hip3CoinParam,
    normalizeHip3Coin
  );

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

  The registerHistoryTool helper function that acts as the actual handler for this tool. It resolves the coin symbol using normalizeHip3Coin, computes time range with resolveTimeRange, builds SDK params (start, end, limit, cursor, plus any extras like depth), calls the provided SDK callback, and formats the result with formatCursorResponse.

  // 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)

  The Hip3CoinParam Zod schema used as the input coin parameter. It describes HIP-3 coin symbols as CASE-SENSITIVE (e.g. 'km:US500').

  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:300-302 (helper)

  The normalizeHip3Coin helper function that normalizes HIP-3 coin symbols (case-sensitive, passthrough).

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

• src/index.ts:113-122 (schema)

  The HistoryParams shared schema defining the start, end, limit, and cursor parameters used by the history tool.

  const HistoryParams = {
    start: TimestampParam.describe(
      "Start timestamp (Unix ms or ISO). Defaults to 24h ago."
    ),
    end: TimestampParam.describe(
      "End timestamp (Unix ms or ISO). Defaults to now."
    ),
    limit: LimitParam,
    cursor: CursorParam,
  };