get_hip3_candles

Instructions

Implementation Reference

• src/index.ts:700-708 (registration)

  Registration of the 'get_hip3_candles' tool via the registerCandleTool helper. The tool is registered with name 'get_hip3_candles', description about HIP-3 OHLCV candle data, and delegates to the SDK method api().hyperliquid.hip3.candles.history(). It uses Hip3CoinParam (CASE-SENSITIVE coin symbols) and normalizeHip3Coin for normalization, with an optional IntervalParam.

  // 19. HIP-3 Candles
  registerCandleTool(
    "get_hip3_candles",
    "Get HIP-3 OHLCV candle data. Symbols are CASE-SENSITIVE (e.g. 'km:US500'). Intervals: 1m to 1w (default 1h). Returns open, high, low, close, volume.",
    (coin, params) =>
      api().hyperliquid.hip3.candles.history(coin, params as any),
    Hip3CoinParam,
    normalizeHip3Coin
  );

• src/index.ts:57-61 (schema)

  Hip3CoinParam — the Zod schema for the 'coin' input parameter. Describes HIP-3 coin symbols as CASE-SENSITIVE with examples and references get_hip3_instruments for discovery.

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

  IntervalParam — the Zod schema for the optional 'interval' parameter used by the candle tool. Defines valid intervals: 1m, 5m, 15m, 30m, 1h, 4h, 1d, 1w (default 1h).

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

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

  registerCandleTool — the helper function that registers candle tools. It calls registerHistoryTool with an extra IntervalParam schema, which in turn calls registerTool to wire up the handler. The handler resolves time range via resolveTimeRange and passes interval through to the SDK.

  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:700-708 (handler)

  The handler function for get_hip3_candles (inlined in registerCandleTool call). It calls api().hyperliquid.hip3.candles.history(coin, params) where params includes start, end, limit, cursor, and interval. The actual handler logic is contained within the registerCandleTool → registerHistoryTool → registerTool chain.

  // 19. HIP-3 Candles
  registerCandleTool(
    "get_hip3_candles",
    "Get HIP-3 OHLCV candle data. Symbols are CASE-SENSITIVE (e.g. 'km:US500'). Intervals: 1m to 1w (default 1h). Returns open, high, low, close, volume.",
    (coin, params) =>
      api().hyperliquid.hip3.candles.history(coin, params as any),
    Hip3CoinParam,
    normalizeHip3Coin
  );