get_funding_history

Instructions

Implementation Reference

• src/index.ts:528-536 (registration)

  Registration of the `get_funding_history` tool using `registerHistoryTool`. It binds the tool name to the SDK call `api().hyperliquid.funding.history(coin, params)` with CoinParam, normalizeHLCoin, and an extra `interval: AggregationIntervalParam` schema.

  registerHistoryTool(
    "get_funding_history",
    "Get Hyperliquid funding rate history for a coin over a time range. Returns timestamped funding rates and premiums. Data available from May 2023. Supports aggregation intervals (5m, 15m, 30m, 1h, 4h, 1d).",
    (coin, params) =>
      api().hyperliquid.funding.history(coin, params as any),
    CoinParam,
    normalizeHLCoin,
    { interval: AggregationIntervalParam }
  );

• src/index.ts:528-536 (handler)

  The handler logic for `get_funding_history` is defined inline via the arrow function `(coin, params) => api().hyperliquid.funding.history(coin, params as any)` passed to `registerHistoryTool`. The actual handler execution is inside `registerHistoryTool` (lines 419-437) which resolves time range, limit, cursor, and extra params then calls `sdkCall(normFn(coin), sdkParams)`.

  registerHistoryTool(
    "get_funding_history",
    "Get Hyperliquid funding rate history for a coin over a time range. Returns timestamped funding rates and premiums. Data available from May 2023. Supports aggregation intervals (5m, 15m, 30m, 1h, 4h, 1d).",
    (coin, params) =>
      api().hyperliquid.funding.history(coin, params as any),
    CoinParam,
    normalizeHLCoin,
    { interval: AggregationIntervalParam }
  );

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

  `registerHistoryTool` (Pattern 4) is the helper function that generates the actual tool handler. It builds the Zod input schema from `coin`, `HistoryParams` (start, end, limit, cursor), and any extraSchema (here `{ interval: AggregationIntervalParam }`). The handler resolves time range via `resolveTimeRange`, applies `resolveLimit`, passes through cursor and extra params, calls `sdkCall(normFn(coin), sdkParams)`, and formats the result via `formatCursorResponse`.

  // 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:113-122 (schema)

  `HistoryParams` shared Zod schema used by `get_funding_history` — defines `start`, `end`, `limit`, and `cursor` input parameters.

  const HistoryParams = {
    start: TimestampParam.describe(
      "Start timestamp (Unix ms or ISO). Defaults to 24h ago."
    ),
    end: TimestampParam.describe(
      "End timestamp (Unix ms or ISO). Defaults to now."
    ),
    limit: LimitParam,
    cursor: CursorParam,
  };

• src/index.ts:108-111 (schema)

  `AggregationIntervalParam` Zod enum schema for the `interval` parameter, allowing '5m', '15m', '30m', '1h', '4h', '1d' — used as extra schema in `get_funding_history`.

  const AggregationIntervalParam = z
    .enum(["5m", "15m", "30m", "1h", "4h", "1d"])
    .optional()
    .describe("Aggregation interval. Omit for raw ~1 min data.");