get_price_history

Instructions

Implementation Reference

• src/index.ts:621-630 (handler)

  Registration of the 'get_price_history' tool using registerHistoryTool helper. The handler calls api().hyperliquid.priceHistory(coin, params) to get mark/oracle price history for a Hyperliquid coin over a time range. Accepts an optional aggregation interval parameter (5m, 15m, 30m, 1h, 4h, 1d).

  // 15. Price History
  registerHistoryTool(
    "get_price_history",
    "Get mark/oracle price history for a coin over a time range. Returns mark_price, oracle_price, and mid_price at each timestamp. Supports aggregation intervals. Data available from May 2023.",
    (coin, params) =>
      api().hyperliquid.priceHistory(coin, params as any),
    CoinParam,
    normalizeHLCoin,
    { interval: z.enum(["5m", "15m", "30m", "1h", "4h", "1d"]).optional().describe("Aggregation interval: '5m', '15m', '30m', '1h', '4h', '1d'. Default '1h'") }
  );

• src/index.ts:621-630 (registration)

  Registration call that wires up the tool name 'get_price_history' with the MCP server via the registerTool helper.

  // 15. Price History
  registerHistoryTool(
    "get_price_history",
    "Get mark/oracle price history for a coin over a time range. Returns mark_price, oracle_price, and mid_price at each timestamp. Supports aggregation intervals. Data available from May 2023.",
    (coin, params) =>
      api().hyperliquid.priceHistory(coin, params as any),
    CoinParam,
    normalizeHLCoin,
    { 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 (helper)

  Pattern 4 helper function that wraps tool registration for history/paginated endpoints. Used by get_price_history to build the input schema (coin + HistoryParams + extra interval param), resolve time range, and call the SDK 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:53-121 (schema)

  Input/output schemas used by get_price_history: CoinParam for coin symbol, HistoryParams for time range/pagination, and ListOutputSchema for the response shape. The interval param is defined inline at the registration site (5m-1d enum).

  const CoinParam = z
    .string()
    .describe("Coin/market symbol, e.g. 'BTC', 'ETH', 'SOL'");
  
  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."
    );
  
  const Hip4CoinParam = z
    .string()
    .describe(
      "HIP-4 outcome-market coin symbol. Canonical form is the bare numeric '<10*outcome_id + side>' (e.g. '0' for outcome 0 Yes, '1' for outcome 0 No, '10' for outcome 1 Yes). The legacy '#0' and '%230' forms are also accepted. Use get_hip4_instruments to list all."
    );
  
  const Hip4OutcomeIdParam = z
    .union([z.number(), z.string()])
    .describe("HIP-4 outcome_id (integer). Each outcome has two sides: '<10*id>' (Yes) and '<10*id+1>' (No).");
  
  const LighterCoinParam = z
    .string()
    .describe("Lighter.xyz coin symbol, e.g. 'BTC', 'ETH'");
  
  const SpotCoinParam = z
    .string()
    .describe(
      "Hyperliquid Spot dashed canonical pair symbol (e.g. 'HYPE-USDC', 'PURR-USDC'). 294 pairs available. The server resolves the dashed form to Hyperliquid's wire format ('PURR/USDC', '@107') internally. Use get_spot_pairs to list all."
    );
  
  const TimestampParam = z
    .union([z.number(), z.string()])
    .optional()
    .describe("Timestamp as Unix milliseconds or ISO 8601 string");
  
  const LimitParam = z
    .number()
    .optional()
    .describe("Max records to return (default 100, max 1000)");
  
  const CursorParam = z
    .string()
    .optional()
    .describe("Pagination cursor from previous response's nextCursor");
  
  const DepthParam = z
    .number()
    .optional()
    .describe("Orderbook depth — number of price levels per side");
  
  const IntervalParam = z
    .enum(["1m", "5m", "15m", "30m", "1h", "4h", "1d", "1w"])
    .optional()
    .describe("Candle interval (default '1h')");
  
  const AggregationIntervalParam = z
    .enum(["5m", "15m", "30m", "1h", "4h", "1d"])
    .optional()
    .describe("Aggregation interval. Omit for raw ~1 min data.");
  
  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,