get_hip3_orderbook_history
Read-onlyIdempotent
Get historical HIP-3 orderbook L2 snapshots with bids and asks for a coin symbol over a time range. Supports pagination and depth control.
Instructions
Get historical HIP-3 orderbook snapshots. Symbols are CASE-SENSITIVE (e.g. 'km:US500'). Returns L2 snapshots with bids/asks over a time range. Free tier: km:US500 only. Build+: all HIP-3 symbols.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| coin | Yes | 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. | |
| start | No | Start timestamp (Unix ms or ISO). Defaults to 24h ago. | |
| end | No | End timestamp (Unix ms or ISO). Defaults to now. | |
| limit | No | Max records to return (default 100, max 1000) | |
| cursor | No | Pagination cursor from previous response's nextCursor | |
| depth | No | Orderbook depth — number of price levels per side |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| records | Yes | Array of result records | |
| count | Yes | Total number of records in the full result set | |
| nextCursor | No | Cursor for next page, if more results available |
Implementation Reference
- src/index.ts:661-670 (registration)Tool 'get_hip3_orderbook_history' is registered using the registerHistoryTool helper. It uses the HIP-3 coin param schema (case-sensitive), the normalizeHip3Coin normalization function, and calls api().hyperliquid.hip3.orderbook.history(coin, params) via the 0xArchive SDK. It also includes an optional depth parameter.
// HIP-3 Orderbook History registerHistoryTool( "get_hip3_orderbook_history", "Get historical HIP-3 orderbook snapshots. Symbols are CASE-SENSITIVE (e.g. 'km:US500'). Returns L2 snapshots with bids/asks over a time range. Free tier: km:US500 only. Build+: all HIP-3 symbols.", (coin, params) => api().hyperliquid.hip3.orderbook.history(coin, params as any), Hip3CoinParam, normalizeHip3Coin, { depth: DepthParam } ); - src/index.ts:407-438 (handler)The registerHistoryTool helper function generates the actual handler logic. It builds time-range parameters (start/end with defaults of 24h ago / now), passes limit, cursor, and any extra params (like depth) to the SDK call, then formats the response with cursor-based pagination.
// 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 schema validates HIP-3 coin symbols (case-sensitive, e.g. 'km:US500', 'xyz:GOLD').
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 ensures HIP-3 coin symbols are passed through without transformation (case-sensitive).
function normalizeHip3Coin(coin: string): string { return coin; // Case-sensitive } - src/index.ts:113-122 (schema)The HistoryParams schema defines the shared input parameters for history tools: start, end, limit, and cursor.
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, };