get_candles

Instructions

Implementation Reference

• src/index.ts:509-516 (registration)

  Registration of the 'get_candles' tool using the registerCandleTool helper. It registers the Hyperliquid OHLCV candle endpoint with interval support (1m to 1w, default 1h).

  registerCandleTool(
    "get_candles",
    "Get Hyperliquid OHLCV candle data for a coin. Intervals: 1m, 5m, 15m, 30m, 1h, 4h, 1d, 1w (default 1h). Returns open, high, low, close, volume. Data available from April 2023.",
    (coin, params) =>
      api().hyperliquid.candles.history(coin, params as any),
    CoinParam,
    normalizeHLCoin
  );

• src/index.ts:509-516 (handler)

  The handler lambda passed to registerCandleTool calls api().hyperliquid.candles.history(coin, params) with the normalized coin and params.

  registerCandleTool(
    "get_candles",
    "Get Hyperliquid OHLCV candle data for a coin. Intervals: 1m, 5m, 15m, 30m, 1h, 4h, 1d, 1w (default 1h). Returns open, high, low, close, volume. Data available from April 2023.",
    (coin, params) =>
      api().hyperliquid.candles.history(coin, params as any),
    CoinParam,
    normalizeHLCoin
  );

• src/index.ts:441-456 (helper)

  The registerCandleTool helper function that wraps registerHistoryTool with an extra 'interval' parameter from IntervalParam.

  function registerCandleTool(
    name: string,
    description: string,
    sdkCall: (coin: string, params: Record<string, unknown>) => Promise<{ data: unknown; nextCursor?: string }>,
    coinSchema: z.ZodString,
    normFn: (coin: string) => string
  ): void {
    registerHistoryTool(
      name,
      description,
      sdkCall,
      coinSchema,
      normFn,
      { interval: IntervalParam }
    );
  }

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

  The registerHistoryTool helper function that handles coin normalization, time range resolution, limit, cursor pagination, and extra params (like interval). This is the underlying pattern used by registerCandleTool.

  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:103-106 (schema)

  The IntervalParam Zod enum schema defining valid candle intervals: '1m', '5m', '15m', '30m', '1h', '4h', '1d', '1w'.

  const IntervalParam = z
    .enum(["1m", "5m", "15m", "30m", "1h", "4h", "1d", "1w"])
    .optional()
    .describe("Candle interval (default '1h')");