get_open_interest_history
Read-onlyIdempotent
Retrieve historical open interest data for any Hyperliquid coin with timestamped snapshots and price data. Supports custom time ranges and aggregation intervals from 5 minutes to daily.
Instructions
Get Hyperliquid open interest history for a coin over a time range. Returns timestamped OI snapshots with mark/oracle prices. Data available from May 2023. Supports aggregation intervals (5m, 15m, 30m, 1h, 4h, 1d).
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| coin | Yes | Coin/market symbol, e.g. 'BTC', 'ETH', 'SOL' | |
| 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 | |
| interval | No | Aggregation interval. Omit for raw ~1 min data. |
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:547-556 (registration)Registration of the 'get_open_interest_history' tool using the registerHistoryTool helper pattern. It calls api().hyperliquid.openInterest.history() with coin, time range params, and an optional aggregation interval.
// 9. Open Interest History registerHistoryTool( "get_open_interest_history", "Get Hyperliquid open interest history for a coin over a time range. Returns timestamped OI snapshots with mark/oracle prices. Data available from May 2023. Supports aggregation intervals (5m, 15m, 30m, 1h, 4h, 1d).", (coin, params) => api().hyperliquid.openInterest.history(coin, params as any), CoinParam, normalizeHLCoin, { interval: AggregationIntervalParam } ); - src/index.ts:108-112 (schema)Zod schema for the optional aggregation interval parameter used by get_open_interest_history.
const AggregationIntervalParam = z .enum(["5m", "15m", "30m", "1h", "4h", "1d"]) .optional() .describe("Aggregation interval. Omit for raw ~1 min data."); - src/index.ts:113-122 (schema)Shared input schema for history-type tools providing start/end timestamps, limit, and cursor for pagination.
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:407-438 (handler)Generic handler function (registerHistoryTool) that wraps the tool logic. This is the actual handler for get_open_interest_history — it resolves time range, builds SDK params, calls the SDK, 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); }); }