get_candles

Instructions

Implementation Reference

• mcp-server.ts:56-58 (schema)

  Candle interface defining the shape of OHLCV data returned by the API (t, o, h, l, c, v, n).

  interface Candle {
    t: number; o: string; h: string; l: string; c: string; v: string; n: number;
  }

• mcp-server.ts:282-306 (handler)

  Registration of the 'get_candles' tool via server.tool() with Zod schema for coin, interval, and hours, and the async handler that fetches candleSnapshot data from HL API and formats it as text.

  server.tool(
    'get_candles',
    'Get OHLCV candle data for a prediction market outcome',
    {
      coin: z.string().describe('Coin identifier, e.g. "#90"'),
      interval: z.string().default('1h').describe('Candle interval: "1m", "5m", "15m", "1h", "4h", "1d"'),
      hours: z.number().default(24).describe('Hours of history to fetch'),
    },
    async ({ coin, interval, hours }) => {
      const endTime = Date.now();
      const startTime = endTime - hours * 60 * 60 * 1000;
  
      const candles = await hlInfo<Candle[]>({
        type: 'candleSnapshot',
        req: { coin: coinToAtFormat(coin), interval, startTime, endTime },
      });
  
      const lines = candles.map(c => {
        const time = new Date(c.t).toISOString().slice(0, 16);
        return `${time}  O:${(parseFloat(c.o) * 100).toFixed(1)}% H:${(parseFloat(c.h) * 100).toFixed(1)}% L:${(parseFloat(c.l) * 100).toFixed(1)}% C:${(parseFloat(c.c) * 100).toFixed(1)}% V:${c.v} (${c.n} trades)`;
      });
  
      return { content: [{ type: 'text', text: lines.length > 0 ? lines.join('\n') : 'No candle data found.' }] };
    },
  );

• mcp-server.ts:290-297 (handler)

  Core handler logic: computes start/end times, calls hlInfo with type 'candleSnapshot' and the converted coin identifier, then maps result to formatted lines.

  async ({ coin, interval, hours }) => {
    const endTime = Date.now();
    const startTime = endTime - hours * 60 * 60 * 1000;
  
    const candles = await hlInfo<Candle[]>({
      type: 'candleSnapshot',
      req: { coin: coinToAtFormat(coin), interval, startTime, endTime },
    });

• mcp-server.ts:67-69 (helper)

  Utility function coinToAtFormat that converts a coin identifier (e.g. '#90') to the '@' format required by the Hyperliquid API.

  function coinToAtFormat(coin: string): string {
    const num = coin.startsWith('#') ? coin.slice(1) : coin;
    return `@${num}`;

• mcp-server.ts:21-29 (helper)

  Generic hlInfo helper that POSTs a JSON body to the HL /info endpoint and returns typed JSON.

  async function hlInfo<T>(body: object): Promise<T> {
    const res = await fetch(`${API_URL}/info`, {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify(body),
    });
    if (!res.ok) throw new Error(`HL API error: ${res.status}`);
    return res.json() as Promise<T>;
  }