get_trades

Instructions

Implementation Reference

• src/index.ts:498-506 (registration)

  Registration of the 'get_trades' tool via registerHistoryTool helper. It's a Hyperliquid trade history tool using cursor pagination, normalized coin param, and delegating to api().hyperliquid.trades.list().

  // 4. Trades
  registerHistoryTool(
    "get_trades",
    "Get Hyperliquid trade/fill history for a coin over a time range. Returns price, size, side, timestamps, and user addresses. Data available from April 2023. Supports cursor pagination.",
    (coin, params) =>
      api().hyperliquid.trades.list(coin, params as any),
    CoinParam,
    normalizeHLCoin
  );

• src/index.ts:408-437 (handler)

  This is the shared handler/registration pattern ('Pattern 4') used by 'get_trades'. It creates the actual handler function that resolves time range, limit, cursor, calls the SDK, and formats the cursor-based response.

  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-97 (schema)

  Input schemas used by the 'get_trades' tool: CoinParam (string coin symbol), HistoryParams (start/end timestamps, limit, cursor), plus the ListOutputSchema for output.

  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");

• src/index.ts:156-164 (helper)

  Helper utilities used by 'get_trades': resolveTimeRange (defaults to 24h range), resolveLimit (defaults to 100), and normalizeHLCoin (uppercases coin symbol).

  function resolveTimeRange(
    start?: number | string,
    end?: number | string
  ): { start: number; end: number } {
    return {
      start: start != null ? toUnixMs(start) : Date.now() - 24 * 60 * 60 * 1000,
      end: end != null ? toUnixMs(end) : Date.now(),
    };
  }