get_hip3_price_history

Instructions

Implementation Reference

• src/index.ts:942-951 (registration)

  Registration of the get_hip3_price_history tool via registerHistoryTool helper. It delegates to api().hyperliquid.hip3.priceHistory() with coin normalization (case-sensitive) and supports an optional aggregation interval parameter.

  // HIP-3 Price History
  registerHistoryTool(
    "get_hip3_price_history",
    "Get mark/oracle/mid price history for a HIP-3 coin over a time range. Symbols are CASE-SENSITIVE (e.g. 'km:US500'). Returns mark_price, oracle_price, and mid_price at each timestamp. Supports aggregation intervals.",
    (coin, params) =>
      api().hyperliquid.hip3.priceHistory(coin, params as any),
    Hip3CoinParam,
    normalizeHip3Coin,
    { interval: z.enum(["5m", "15m", "30m", "1h", "4h", "1d"]).optional().describe("Aggregation interval: '5m', '15m', '30m', '1h', '4h', '1d'. Default '1h'") }
  );

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

  Generic handler pattern used by get_hip3_price_history. Parses coin, time range, limit, cursor, and extra params (like interval), resolves time defaults, then calls the SDK's priceHistory() and formats the cursor-paginated 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:113-122 (schema)

  Shared HistoryParams input schema used by get_hip3_price_history: start, end, limit, 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,
  };

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

  Shared ListOutputSchema output schema used by get_hip3_price_history (returns records, count, nextCursor).

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

• src/index.ts:156-164 (helper)

  Helper used by the tool handler to resolve default time range (24h ago to now) and convert timestamps to Unix ms.

  function resolveTimeRange(
    start?: number | string,
    end?: number | string
  ): { start: number; end: number } {
    return {
      start: start != null ? toUnixMs(start) : Date.now() - 24 * 60 * 60 * 1000,
      end: end != null ? toUnixMs(end) : Date.now(),
    };
  }