get_spot_trades

Instructions

Implementation Reference

• src/index.ts:1351-1360 (registration)

  Registration of the 'get_spot_trades' tool using registerHistoryTool pattern. It registers the tool with name 'get_spot_trades', accepts a SpotCoinParam (dashed canonical pair symbol), time range params (start/end/limit/cursor), and an optional user wallet filter. The handler calls api().spot.trades.list(coin, params) which invokes the SDK's Hyperliquid Spot trades list endpoint.

  // Spot Trades
  registerHistoryTool(
    "get_spot_trades",
    "Get Hyperliquid Spot trade/fill history for a pair over a time range. Symbols are dashed canonical (e.g. 'HYPE-USDC'). Returns price, size, side, timestamps, and user addresses. S3 backfill from 2025-03-22 (the earliest published date); live since. Supports cursor pagination and optional user wallet filter.",
    (coin, params) =>
      api().spot.trades.list(coin, params as any),
    SpotCoinParam,
    normalizeSpotCoin,
    { user: UserParam }
  );

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

  The generic handler logic from registerHistoryTool. This is the actual handler function that executes when 'get_spot_trades' is invoked. It extracts coin, start, end, limit, cursor, and extra params (including optional 'user' filter), resolves the time range, builds SDK params, calls the SDK function (api().spot.trades.list), and formats the cursor-paginated response.

  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:77-81 (schema)

  Input schema for the 'coin' parameter used by get_spot_trades. Expects a string in dashed canonical pair format (e.g. 'HYPE-USDC').

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

• src/index.ts:991-994 (schema)

  Optional 'user' parameter schema used as extra param in get_spot_trades for filtering by wallet address.

  const UserParam = z
    .string()
    .optional()
    .describe("User wallet address filter (e.g., '0x1234...')");

• src/index.ts:320-322 (helper)

  Normalization helper for spot coin symbols (uppercases them) passed to the SDK call.

  function normalizeSpotCoin(coin: string): string {
    return coin.toUpperCase();
  }