get_spot_twap_by_user

Instructions

Implementation Reference

• src/index.ts:1447-1467 (handler)

  Tool handler for 'get_spot_twap_by_user'. Registers the tool with address and history params, calls api().spot.twap.byUser() SDK method, and formats the cursor-paginated response.

  // Spot TWAP by User
  registerTool(
    "get_spot_twap_by_user",
    "Get Hyperliquid Spot TWAP statuses for a single user wallet across every spot pair. Returns timestamped TWAP status records with coin, twap_id, side, size, filled_size, status, and execution metadata. Sourced from the L4 order stream. Live from 2026-05-05.",
    {
      address: z.string().describe("User wallet address (e.g., '0x1234...')"),
      ...HistoryParams,
    },
    ListOutputSchema,
    async (params) => {
      const { address, start, end, limit, cursor } = params;
      const timeRange = resolveTimeRange(start, end);
      const sdkParams: Record<string, unknown> = {
        ...timeRange,
        limit: resolveLimit(limit),
      };
      if (cursor) sdkParams.cursor = cursor;
      const result = await api().spot.twap.byUser(address, sdkParams as any);
      return formatCursorResponse(result);
    }
  );

• src/index.ts:1451-1455 (schema)

  Input schema for get_spot_twap_by_user: requires an 'address' string, plus optional HistoryParams (start, end, limit, cursor).

  {
    address: z.string().describe("User wallet address (e.g., '0x1234...')"),
    ...HistoryParams,
  },
  ListOutputSchema,

• src/index.ts:1448-1467 (registration)

  Registration of the tool named 'get_spot_twap_by_user' via the registerTool helper function.

  registerTool(
    "get_spot_twap_by_user",
    "Get Hyperliquid Spot TWAP statuses for a single user wallet across every spot pair. Returns timestamped TWAP status records with coin, twap_id, side, size, filled_size, status, and execution metadata. Sourced from the L4 order stream. Live from 2026-05-05.",
    {
      address: z.string().describe("User wallet address (e.g., '0x1234...')"),
      ...HistoryParams,
    },
    ListOutputSchema,
    async (params) => {
      const { address, start, end, limit, cursor } = params;
      const timeRange = resolveTimeRange(start, end);
      const sdkParams: Record<string, unknown> = {
        ...timeRange,
        limit: resolveLimit(limit),
      };
      if (cursor) sdkParams.cursor = cursor;
      const result = await api().spot.twap.byUser(address, sdkParams as any);
      return formatCursorResponse(result);
    }
  );

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

  Generic tool registration helper used by get_spot_twap_by_user. Wraps the SDK call with null-client guard, error formatting, and MCP server registration.

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