get_recent_trades

Instructions

Implementation Reference

• mcp-server.ts:313-332 (handler)

  The handler function for 'get_recent_trades' tool. Calls the Hyperliquid API with type 'recentTrades' for the given coin, filters for outcome trades (coin starting with '@'), and returns up to the 50 most recent trades formatted as timestamp, side, size, and price percentage.

    async ({ coin }) => {
      const trades = await hlInfo<RecentTrade[]>({
        type: 'recentTrades',
        coin: coinToAtFormat(coin),
      });
  
      const outcomeTrades = trades.filter(t => t.coin.startsWith('@'));
  
      if (outcomeTrades.length === 0) {
        return { content: [{ type: 'text', text: 'No recent trades found.' }] };
      }
  
      const lines = outcomeTrades.slice(0, 50).map(t => {
        const time = new Date(t.time).toISOString().slice(0, 19);
        return `${time} ${t.side.toUpperCase()} ${t.sz} @ ${(parseFloat(t.px) * 100).toFixed(1)}%`;
      });
  
      return { content: [{ type: 'text', text: lines.join('\n') }] };
    },
  );

• mcp-server.ts:59-61 (schema)

  TypeScript interface for the RecentTrade data structure returned by the HL API and used by the handler.

  interface RecentTrade {
    coin: string; side: string; px: string; sz: string; time: number; hash: string; tid: number;
  }

• mcp-server.ts:308-332 (registration)

  Registration of the 'get_recent_trades' tool on the MCP server using server.tool(), with a single 'coin' string parameter described as 'Coin identifier, e.g. "#90"'.

  // --- get_recent_trades ---
  server.tool(
    'get_recent_trades',
    'Get recent trades for a prediction market outcome',
    { coin: z.string().describe('Coin identifier, e.g. "#90"') },
    async ({ coin }) => {
      const trades = await hlInfo<RecentTrade[]>({
        type: 'recentTrades',
        coin: coinToAtFormat(coin),
      });
  
      const outcomeTrades = trades.filter(t => t.coin.startsWith('@'));
  
      if (outcomeTrades.length === 0) {
        return { content: [{ type: 'text', text: 'No recent trades found.' }] };
      }
  
      const lines = outcomeTrades.slice(0, 50).map(t => {
        const time = new Date(t.time).toISOString().slice(0, 19);
        return `${time} ${t.side.toUpperCase()} ${t.sz} @ ${(parseFloat(t.px) * 100).toFixed(1)}%`;
      });
  
      return { content: [{ type: 'text', text: lines.join('\n') }] };
    },
  );

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

  Helper utility that converts a coin identifier (e.g. '#90') to the '@' format expected by the Hyperliquid API (e.g. '@90'), used in the handler when calling hlInfo.

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

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

  Generic helper that posts to the Hyperliquid /info API endpoint and returns typed JSON. Used by the handler to fetch recentTrades data.

  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>;
  }