get_spot_twap_by_symbol

Instructions

Implementation Reference

• src/index.ts:1437-1445 (registration)

  The tool 'get_spot_twap_by_symbol' is registered via registerHistoryTool pattern. It calls api().spot.twap.bySymbol(coin, params) with SpotCoinParam as the coin schema and normalizeSpotCoin as the normalizer.

  // Spot TWAP by Symbol
  registerHistoryTool(
    "get_spot_twap_by_symbol",
    "Get Hyperliquid Spot TWAP statuses for a single pair (every TWAP touching this pair). Symbols are dashed canonical (e.g. 'HYPE-USDC'). Returns timestamped TWAP status records with twap_id, user_address, side, size, filled_size, status, and execution metadata. Sourced from the L4 order stream. Live from 2026-05-05.",
    (coin, params) =>
      api().spot.twap.bySymbol(coin, params as any),
    SpotCoinParam,
    normalizeSpotCoin
  );

• src/index.ts:77-82 (schema)

  SpotCoinParam is the Zod schema used for the coin parameter. It expects a Hyperliquid Spot dashed canonical pair symbol (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:320-322 (helper)

  normalizeSpotCoin is the normalization helper called on the coin parameter before passing to the SDK call. It uppercases the coin symbol.

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

• src/index.ts:440-456 (helper)

  registerCandleTool is used to register 'get_spot_twap_by_symbol' (via the pattern). Since the tool has no extra params beyond coin+history, it simplifies to registerHistoryTool with just coin and history params.

  // Pattern 5: Candle history (coin + time range + interval)
  function registerCandleTool(
    name: string,
    description: string,
    sdkCall: (coin: string, params: Record<string, unknown>) => Promise<{ data: unknown; nextCursor?: string }>,
    coinSchema: z.ZodString,
    normFn: (coin: string) => string
  ): void {
    registerHistoryTool(
      name,
      description,
      sdkCall,
      coinSchema,
      normFn,
      { interval: IntervalParam }
    );
  }

• src/index.ts:407-438 (helper)

  registerHistoryTool (Pattern 4) is the actual registration helper used for 'get_spot_twap_by_symbol'. It accepts coin, start, end, limit, cursor params and calls the SDK's bySymbol function with cursor pagination support.

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