get_hip3_open_interest_history
Read-onlyIdempotent
Retrieve historical open interest snapshots for HIP-3 symbols over a specified time range. Supports multiple markets and aggregation intervals.
Instructions
Get HIP-3 open interest history over a time range. Symbols are CASE-SENSITIVE (e.g. 'km:US500'). Returns timestamped OI snapshots.
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 | |
| 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:739-748 (handler)The handler function for get_hip3_open_interest_history tool. It uses registerHistoryTool with Hip3CoinParam, normalizeHip3Coin, and an optional AggregationIntervalParam. The actual SDK call is api().hyperliquid.hip3.openInterest.history(coin, params).
// 22. HIP-3 Open Interest History registerHistoryTool( "get_hip3_open_interest_history", "Get HIP-3 open interest history over a time range. Symbols are CASE-SENSITIVE (e.g. 'km:US500'). Returns timestamped OI snapshots.", (coin, params) => api().hyperliquid.hip3.openInterest.history(coin, params as any), Hip3CoinParam, normalizeHip3Coin, { interval: AggregationIntervalParam } ); - src/index.ts:408-438 (registration)The registerHistoryTool function (Pattern 4) that registers the tool on the MCP server. It builds the input schema with coin, HistoryParams, and any extraSchema, resolves time ranges and limits, calls the SDK, and formats the cursor response.
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 used for the 'coin' input parameter. Defines HIP-3 coin symbols as case-sensitive strings with documentation about available markets.
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 AggregationIntervalParam schema used for the optional 'interval' parameter on this tool.
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 normalizeHip3Coin helper function that normalizes HIP-3 coin symbols (case-sensitive, so identity function).
function normalizeHip3Coin(coin: string): string { return coin; // Case-sensitive }