get_orderbook_history

Instructions

Implementation Reference

• src/index.ts:488-496 (registration)

  Registration of the 'get_orderbook_history' tool using the registerHistoryTool helper. Binds the Hyperliquid orderbook history SDK call with the CoinParam schema, normalizeHLCoin normalizer, and an optional depth parameter.

  registerHistoryTool(
    "get_orderbook_history",
    "Get historical Hyperliquid orderbook snapshots (~1.2s resolution). Returns L2 snapshots with bids/asks over a time range. Data available from April 2023. Free: BTC only (20 levels). Build+: all symbols (200 levels). Pro+: full depth.",
    (coin, params) =>
      api().hyperliquid.orderbook.history(coin, params as any),
    CoinParam,
    normalizeHLCoin,
    { depth: DepthParam }
  );

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

  The registerHistoryTool helper function that implements the actual handler logic for all history/paginated tools including get_orderbook_history. It builds the SDK query params from the user's input (coin, start, end, limit, cursor, plus any extra params like depth), then calls the SDK and formats the response with cursor pagination support.

  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:113-122 (schema)

  HistoryParams shared schema used by get_orderbook_history (start, end, limit, cursor). These define the time range and pagination input parameters.

  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,
  };

• src/index.ts:98-101 (schema)

  DepthParam optional schema — extra parameter added to get_orderbook_history's input schema to allow specifying the number of price levels per side.

  const DepthParam = z
    .number()
    .optional()
    .describe("Orderbook depth — number of price levels per side");

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

  ListOutputSchema — the output schema for get_orderbook_history, defining the structured response shape with records array, count, and optional nextCursor for pagination.

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