get_hip3_trades

Instructions

Implementation Reference

• src/index.ts:672-680 (registration)

  Registration of the get_hip3_trades tool via registerHistoryTool helper. Calls api().hyperliquid.hip3.trades.list(coin, params) for HIP-3 trade history with cursor pagination.

  // 18. HIP-3 Trades
  registerHistoryTool(
    "get_hip3_trades",
    "Get HIP-3 trade history. Symbols are CASE-SENSITIVE (e.g. 'km:US500'). Returns trades with price, size, side, and timestamps over a time range. Supports cursor pagination.",
    (coin, params) =>
      api().hyperliquid.hip3.trades.list(coin, params as any),
    Hip3CoinParam,
    normalizeHip3Coin
  );

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

  Zod schema for HIP-3 coin parameter (CASE-SENSITIVE). Used as input validation for get_hip3_trades.

  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:407-438 (helper)

  registerHistoryTool helper function that wraps generic registerTool. Used by get_hip3_trades to add coin, time range, limit, and cursor parameters, then call the SDK with normalized coin symbol.

  // Pattern 4: History with cursor pagination (coin + time range)
  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:300-322 (helper)

  Normalization function for HIP-3 coins. Keeps the symbol case-sensitive as-is (no upper-casing), since HIP-3 symbols are case-sensitive.

  function normalizeHip3Coin(coin: string): string {
    return coin; // Case-sensitive
  }
  
  // HIP-4 path encoding: the canonical form is the bare numeric `0`, `1`, `42`.
  // The legacy `#0` / `%230` forms are still accepted by the API. We normalize to
  // the bare form when possible (avoids URL-fragment ambiguity entirely).
  function normalizeHip4Coin(coin: string): string {
    const trimmed = String(coin).trim();
    if (/^\d+$/.test(trimmed)) return trimmed;
    const stripped = trimmed.replace(/^(#|%23)/i, "");
    if (/^\d+$/.test(stripped)) return stripped;
    // Unknown shape — fall back to URL-encoding the original.
    return encodeURIComponent(trimmed);
  }
  
  function normalizeLighterCoin(coin: string): string {
    return coin.toUpperCase();
  }
  
  function normalizeSpotCoin(coin: string): string {
    return coin.toUpperCase();
  }

• src/index.ts:328-358 (helper)

  Generic registerTool helper that wraps server.registerTool with API key guard, error handling, and annotation setup. Called by registerHistoryTool (which is used by get_hip3_trades).

  function registerTool(
    name: string,
    description: string,
    inputSchema: ZodRawShape,
    outputSchema: ZodRawShape,
    handler: (params: any) => Promise<McpContent>
  ): void {
    server.registerTool(
      name,
      {
        description,
        inputSchema,
        outputSchema,
        annotations: TOOL_ANNOTATIONS,
      },
      async (params: any) => {
        if (!client) {
          return {
            content: [{ type: "text" as const, text: MISSING_KEY_MESSAGE }],
            isError: true,
          };
        }
        try {
          return await handler(params);
        } catch (err) {
          const error = err instanceof OxArchiveError ? err : new OxArchiveError(String(err), 500);
          return formatError(error);
        }
      }
    );
  }