get_liquidations

Instructions

Implementation Reference

• src/index.ts:558-566 (registration)

  Registration of the 'get_liquidations' tool using the registerHistoryTool helper pattern. It is a Hyperliquid liquidation history tool for a coin over a time range, delegating to api().hyperliquid.liquidations.history().

  // 10. Liquidations
  registerHistoryTool(
    "get_liquidations",
    "Get Hyperliquid liquidation history for a coin over a time range. Returns liquidated/liquidator addresses, price, size, side, and PnL. Data available from May 2025. Real-time liquidations are also available on the WebSocket `liquidations` channel — each event is a fill row with `is_liquidation: true`, same shape as the `trades` channel.",
    (coin, params) =>
      api().hyperliquid.liquidations.history(coin, params as any),
    CoinParam,
    normalizeHLCoin
  );

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

  The registerHistoryTool helper that acts as the actual handler for 'get_liquidations'. It creates the handler function that resolves time range, limit, cursor, and calls the SDK method (in this case api().hyperliquid.liquidations.history()), then formats the cursor-paginated response.

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

  The input schema used by registerHistoryTool — defines start (timestamp), end (timestamp), limit (number), and cursor (string) parameters used by get_liquidations.

  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:129-136 (schema)

  The output schema (ListOutputSchema) used by get_liquidations — returns records array, count, and optional nextCursor.

  const ListOutputSchema: ZodRawShape = {
    records: z.array(z.record(z.unknown())).describe("Array of result records"),
    count: z.number().describe("Total number of records in the full result set"),
    nextCursor: z
      .string()
      .optional()
      .describe("Cursor for next page, if more results available"),
  };

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

  The registerTool helper function that registerHistoryTool builds upon. It wraps the handler with API key validation and error formatting.

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