@nktkas/hyperliquid 0.31.0 → 0.32.0

package/src/api/info/_methods/recentTrades.ts

@@ -0,0 +1,104 @@
+import * as v from "valibot";
+
+// ============================================================
+// API Schemas
+// ============================================================
+
+/**
+ * Request recent trades.
+ * @see null
+ */
+export const RecentTradesRequest = /* @__PURE__ */ (() => {
+  return v.object({
+    /** Type of request. */
+    type: v.literal("recentTrades"),
+    /** Asset symbol (e.g., BTC). */
+    coin: v.string(),
+  });
+})();
+export type RecentTradesRequest = v.InferOutput<typeof RecentTradesRequest>;
+
+/**
+ * Array of recent trades.
+ * @see null
+ */
+export type RecentTradesResponse = {
+  /** Asset symbol (e.g., BTC). */
+  coin: string;
+  /** Trade side ("B" = Bid/Buy, "A" = Ask/Sell). */
+  side: "B" | "A";
+  /**
+   * Trade price.
+   * @pattern ^[0-9]+(\.[0-9]+)?$
+   */
+  px: string;
+  /**
+   * Trade size.
+   * @pattern ^[0-9]+(\.[0-9]+)?$
+   */
+  sz: string;
+  /** Trade timestamp (in ms since epoch). */
+  time: number;
+  /**
+   * Transaction hash.
+   * @pattern ^0x[a-fA-F0-9]{64}$
+   */
+  hash: `0x${string}`;
+  /** Trade ID. */
+  tid: number;
+  /** Addresses of users involved in the trade [Maker, Taker]. */
+  users: [
+    /** @pattern ^0x[a-fA-F0-9]{40}$ */
+    maker: `0x${string}`,
+    /** @pattern ^0x[a-fA-F0-9]{40}$ */
+    taker: `0x${string}`,
+  ];
+}[];
+
+// ============================================================
+// Execution Logic
+// ============================================================
+
+import { parse } from "../../../_base.js";
+import type { InfoConfig } from "./_base/types.js";
+
+/** Request parameters for the {@linkcode recentTrades} function. */
+export type RecentTradesParameters = Omit<v.InferInput<typeof RecentTradesRequest>, "type">;
+
+/**
+ * Request recent trades.
+ *
+ * @param config General configuration for Info API requests.
+ * @param params Parameters specific to the API request.
+ * @param signal {@link https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal | AbortSignal} to cancel the request.
+ * @return Array of recent trades.
+ *
+ * @throws {ValidationError} When the request parameters fail validation (before sending).
+ * @throws {TransportError} When the transport layer throws an error.
+ *
+ * @example
+ * ```ts
+ * import { HttpTransport } from "@nktkas/hyperliquid";
+ * import { recentTrades } from "@nktkas/hyperliquid/api/info";
+ *
+ * const transport = new HttpTransport(); // or `WebSocketTransport`
+ *
+ * const data = await recentTrades(
+ *   { transport },
+ *   { coin: "ETH" },
+ * );
+ * ```
+ *
+ * @see null
+ */
+export function recentTrades(
+  config: InfoConfig,
+  params: RecentTradesParameters,
+  signal?: AbortSignal,
+): Promise<RecentTradesResponse> {
+  const request = parse(RecentTradesRequest, {
+    type: "recentTrades",
+    ...params,
+  });
+  return config.transport.request("info", request, signal);
+}

package/src/api/info/_methods/referral.ts

@@ -0,0 +1,224 @@
+import * as v from "valibot";
+
+// ============================================================
+// API Schemas
+// ============================================================
+
+import { Address } from "../../_schemas.js";
+
+/**
+ * Request user referral.
+ * @see https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/info-endpoint#query-a-users-referral-information
+ */
+export const ReferralRequest = /* @__PURE__ */ (() => {
+  return v.object({
+    /** Type of request. */
+    type: v.literal("referral"),
+    /** User address. */
+    user: Address,
+  });
+})();
+export type ReferralRequest = v.InferOutput<typeof ReferralRequest>;
+
+/**
+ * Referral details for a user.
+ * @see https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/info-endpoint#query-a-users-referral-information
+ */
+export type ReferralResponse = {
+  /** Referrer details. */
+  referredBy: {
+    /**
+     * Referrer address.
+     * @pattern ^0x[a-fA-F0-9]{40}$
+     */
+    referrer: `0x${string}`;
+    /** Referral code used. */
+    code: string;
+  } | null;
+  /**
+   * Cumulative traded volume.
+   * @pattern ^[0-9]+(\.[0-9]+)?$
+   */
+  cumVlm: string;
+  /**
+   * Rewards earned but not yet claimed.
+   * @pattern ^[0-9]+(\.[0-9]+)?$
+   */
+  unclaimedRewards: string;
+  /**
+   * Rewards that have been claimed.
+   * @pattern ^[0-9]+(\.[0-9]+)?$
+   */
+  claimedRewards: string;
+  /**
+   * Builder reward amount.
+   * @pattern ^[0-9]+(\.[0-9]+)?$
+   */
+  builderRewards: string;
+  /** Current state of the referrer. */
+  referrerState: {
+    /** Referrer is ready to receive rewards. */
+    stage: "ready";
+    /** Referral program details. */
+    data: {
+      /** Assigned referral code. */
+      code: string;
+      /** Total number of referrals. */
+      nReferrals: number;
+      /** Summary of each referral state. */
+      referralStates: {
+        /**
+         * Cumulative traded volume.
+         * @pattern ^[0-9]+(\.[0-9]+)?$
+         */
+        cumVlm: string;
+        /**
+         * Total fees rewarded to the referred user since referral.
+         * @pattern ^[0-9]+(\.[0-9]+)?$
+         */
+        cumRewardedFeesSinceReferred: string;
+        /**
+         * Total fees rewarded to the referrer from referred trades.
+         * @pattern ^[0-9]+(\.[0-9]+)?$
+         */
+        cumFeesRewardedToReferrer: string;
+        /** Timestamp when the referred user joined (in ms since epoch). */
+        timeJoined: number;
+        /**
+         * Address of the referred user.
+         * @pattern ^0x[a-fA-F0-9]{40}$
+         */
+        user: `0x${string}`;
+        /** Mapping of token IDs to referral reward states. */
+        tokenToState: [
+          tokenId: number,
+          state: {
+            /**
+             * Cumulative traded volume.
+             * @pattern ^[0-9]+(\.[0-9]+)?$
+             */
+            cumVlm: string;
+            /**
+             * Total fees rewarded to the referred user since referral.
+             * @pattern ^[0-9]+(\.[0-9]+)?$
+             */
+            cumRewardedFeesSinceReferred: string;
+            /**
+             * Total fees rewarded to the referrer from referred trades.
+             * @pattern ^[0-9]+(\.[0-9]+)?$
+             */
+            cumFeesRewardedToReferrer: string;
+          },
+        ][];
+      }[];
+    };
+  } | {
+    /** Referrer needs to create a referral code. */
+    stage: "needToCreateCode";
+  } | {
+    /** Referrer must complete a trade before earning rewards. */
+    stage: "needToTrade";
+    /** Required trading volume details for activation. */
+    data: {
+      /**
+       * Required trading volume.
+       * @pattern ^[0-9]+(\.[0-9]+)?$
+       */
+      required: string;
+    };
+  };
+  /** History of referral rewards. */
+  rewardHistory: {
+    /**
+     * Amount of earned rewards.
+     * @pattern ^[0-9]+(\.[0-9]+)?$
+     */
+    earned: string;
+    /**
+     * Traded volume at the time of reward.
+     * @pattern ^[0-9]+(\.[0-9]+)?$
+     */
+    vlm: string;
+    /**
+     * Traded volume via referrals.
+     * @pattern ^[0-9]+(\.[0-9]+)?$
+     */
+    referralVlm: string;
+    /** Timestamp when the reward was earned (in ms since epoch). */
+    time: number;
+  }[];
+  /** Mapping of token IDs to referral reward states. */
+  tokenToState: [
+    tokenId: number,
+    state: {
+      /**
+       * Cumulative traded volume.
+       * @pattern ^[0-9]+(\.[0-9]+)?$
+       */
+      cumVlm: string;
+      /**
+       * Rewards earned but not yet claimed.
+       * @pattern ^[0-9]+(\.[0-9]+)?$
+       */
+      unclaimedRewards: string;
+      /**
+       * Rewards that have been claimed.
+       * @pattern ^[0-9]+(\.[0-9]+)?$
+       */
+      claimedRewards: string;
+      /**
+       * Builder reward amount.
+       * @pattern ^[0-9]+(\.[0-9]+)?$
+       */
+      builderRewards: string;
+    },
+  ][];
+};
+
+// ============================================================
+// Execution Logic
+// ============================================================
+
+import { parse } from "../../../_base.js";
+import type { InfoConfig } from "./_base/types.js";
+
+/** Request parameters for the {@linkcode referral} function. */
+export type ReferralParameters = Omit<v.InferInput<typeof ReferralRequest>, "type">;
+
+/**
+ * Request user referral.
+ *
+ * @param config General configuration for Info API requests.
+ * @param params Parameters specific to the API request.
+ * @param signal {@link https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal | AbortSignal} to cancel the request.
+ * @return Referral details for a user.
+ *
+ * @throws {ValidationError} When the request parameters fail validation (before sending).
+ * @throws {TransportError} When the transport layer throws an error.
+ *
+ * @example
+ * ```ts
+ * import { HttpTransport } from "@nktkas/hyperliquid";
+ * import { referral } from "@nktkas/hyperliquid/api/info";
+ *
+ * const transport = new HttpTransport(); // or `WebSocketTransport`
+ *
+ * const data = await referral(
+ *   { transport },
+ *   { user: "0x..." },
+ * );
+ * ```
+ *
+ * @see https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/info-endpoint#query-a-users-referral-information
+ */
+export function referral(
+  config: InfoConfig,
+  params: ReferralParameters,
+  signal?: AbortSignal,
+): Promise<ReferralResponse> {
+  const request = parse(ReferralRequest, {
+    type: "referral",
+    ...params,
+  });
+  return config.transport.request("info", request, signal);
+}

package/src/api/info/_methods/spotClearinghouseState.ts

@@ -0,0 +1,112 @@
+import * as v from "valibot";
+
+// ============================================================
+// API Schemas
+// ============================================================
+
+import { Address } from "../../_schemas.js";
+
+/**
+ * Request spot clearinghouse state.
+ * @see https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/info-endpoint/spot#retrieve-a-users-token-balances
+ */
+export const SpotClearinghouseStateRequest = /* @__PURE__ */ (() => {
+  return v.object({
+    /** Type of request. */
+    type: v.literal("spotClearinghouseState"),
+    /** User address. */
+    user: Address,
+    /** DEX name (empty string for main dex). */
+    dex: v.optional(v.string()),
+  });
+})();
+export type SpotClearinghouseStateRequest = v.InferOutput<typeof SpotClearinghouseStateRequest>;
+
+/**
+ * Account summary for spot trading.
+ * @see https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/info-endpoint/spot#retrieve-a-users-token-balances
+ */
+export type SpotClearinghouseStateResponse = {
+  /** Array of available token balances. */
+  balances: {
+    /** Asset symbol. */
+    coin: string;
+    /** Unique identifier for the token. */
+    token: number;
+    /**
+     * Total balance.
+     * @pattern ^[0-9]+(\.[0-9]+)?$
+     */
+    total: string;
+    /**
+     * Amount on hold.
+     * @pattern ^[0-9]+(\.[0-9]+)?$
+     */
+    hold: string;
+    /**
+     * Entry notional value.
+     * @pattern ^[0-9]+(\.[0-9]+)?$
+     */
+    entryNtl: string;
+  }[];
+  /** Array of escrowed balances. */
+  evmEscrows?: {
+    /** Asset symbol. */
+    coin: string;
+    /** Unique identifier for the token. */
+    token: number;
+    /**
+     * Total balance.
+     * @pattern ^[0-9]+(\.[0-9]+)?$
+     */
+    total: string;
+  }[];
+};
+
+// ============================================================
+// Execution Logic
+// ============================================================
+
+import { parse } from "../../../_base.js";
+import type { InfoConfig } from "./_base/types.js";
+
+/** Request parameters for the {@linkcode spotClearinghouseState} function. */
+export type SpotClearinghouseStateParameters = Omit<v.InferInput<typeof SpotClearinghouseStateRequest>, "type">;
+
+/**
+ * Request spot clearinghouse state.
+ *
+ * @param config General configuration for Info API requests.
+ * @param params Parameters specific to the API request.
+ * @param signal {@link https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal | AbortSignal} to cancel the request.
+ * @return Account summary for spot trading.
+ *
+ * @throws {ValidationError} When the request parameters fail validation (before sending).
+ * @throws {TransportError} When the transport layer throws an error.
+ *
+ * @example
+ * ```ts
+ * import { HttpTransport } from "@nktkas/hyperliquid";
+ * import { spotClearinghouseState } from "@nktkas/hyperliquid/api/info";
+ *
+ * const transport = new HttpTransport(); // or `WebSocketTransport`
+ *
+ * const data = await spotClearinghouseState(
+ *   { transport },
+ *   { user: "0x..." },
+ * );
+ * ```
+ *
+ * @see https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/info-endpoint/spot#retrieve-a-users-token-balances
+ */
+export function spotClearinghouseState(
+  config: InfoConfig,
+  params: SpotClearinghouseStateParameters,
+  signal?: AbortSignal,
+): Promise<SpotClearinghouseStateResponse> {
+  const request = parse(SpotClearinghouseStateRequest, {
+    type: "spotClearinghouseState",
+    ...params,
+  });
+  return config.transport.request("info", request, signal);
+}

package/src/api/info/_methods/spotDeployState.ts

@@ -0,0 +1,135 @@
+import * as v from "valibot";
+
+// ============================================================
+// API Schemas
+// ============================================================
+
+import { Address } from "../../_schemas.js";
+import type { SpotPairDeployAuctionStatusResponse } from "./spotPairDeployAuctionStatus.js";
+
+/**
+ * Request spot deploy state.
+ * @see https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/info-endpoint/spot#retrieve-information-about-the-spot-deploy-auction
+ */
+export const SpotDeployStateRequest = /* @__PURE__ */ (() => {
+  return v.object({
+    /** Type of request. */
+    type: v.literal("spotDeployState"),
+    /** User address. */
+    user: Address,
+  });
+})();
+export type SpotDeployStateRequest = v.InferOutput<typeof SpotDeployStateRequest>;
+
+/**
+ * Deploy state for spot tokens.
+ * @see https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/info-endpoint/spot#retrieve-information-about-the-spot-deploy-auction
+ */
+export type SpotDeployStateResponse = {
+  /** Array of deploy states for tokens. */
+  states: {
+    /** Token ID. */
+    token: number;
+    /** Token specification. */
+    spec: {
+      /** Name of the token. */
+      name: string;
+      /** Minimum decimal places for order sizes. */
+      szDecimals: number;
+      /** Number of decimals for the token's smallest unit. */
+      weiDecimals: number;
+    };
+    /** Full name of the token. */
+    fullName: string | null;
+    /**
+     * Deployer trading fee share for the token.
+     * @pattern ^[0-9]+(\.[0-9]+)?$
+     */
+    deployerTradingFeeShare: string;
+    /** Spot indices for the token. */
+    spots: number[];
+    /**
+     * Maximum supply of the token.
+     * @pattern ^[0-9]+(\.[0-9]+)?$
+     */
+    maxSupply: string | null;
+    /**
+     * Hyperliquidity genesis balance of the token.
+     * @pattern ^[0-9]+(\.[0-9]+)?$
+     */
+    hyperliquidityGenesisBalance: string;
+    /**
+     * Total genesis balance (in wei) for the token.
+     * @pattern ^[0-9]+(\.[0-9]+)?$
+     */
+    totalGenesisBalanceWei: string;
+    /** User genesis balances for the token. */
+    userGenesisBalances: [
+      /** @pattern ^0x[a-fA-F0-9]{40}$ */
+      address: `0x${string}`,
+      /** @pattern ^[0-9]+(\.[0-9]+)?$ */
+      balance: string,
+    ][];
+    /** Existing token genesis balances for the token. */
+    existingTokenGenesisBalances: [
+      token: number,
+      /** @pattern ^[0-9]+(\.[0-9]+)?$ */
+      balance: string,
+    ][];
+    /**
+     * Blacklisted users for the token.
+     * @pattern ^0x[a-fA-F0-9]{40}$
+     */
+    blacklistUsers: `0x${string}`[];
+  }[];
+  /** Status of the spot deploy auction. */
+  gasAuction: SpotPairDeployAuctionStatusResponse;
+};
+
+// ============================================================
+// Execution Logic
+// ============================================================
+
+import { parse } from "../../../_base.js";
+import type { InfoConfig } from "./_base/types.js";
+
+/** Request parameters for the {@linkcode spotDeployState} function. */
+export type SpotDeployStateParameters = Omit<v.InferInput<typeof SpotDeployStateRequest>, "type">;
+
+/**
+ * Request spot deploy state.
+ *
+ * @param config General configuration for Info API requests.
+ * @param params Parameters specific to the API request.
+ * @param signal {@link https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal | AbortSignal} to cancel the request.
+ * @return Deploy state for spot tokens.
+ *
+ * @throws {ValidationError} When the request parameters fail validation (before sending).
+ * @throws {TransportError} When the transport layer throws an error.
+ *
+ * @example
+ * ```ts
+ * import { HttpTransport } from "@nktkas/hyperliquid";
+ * import { spotDeployState } from "@nktkas/hyperliquid/api/info";
+ *
+ * const transport = new HttpTransport(); // or `WebSocketTransport`
+ *
+ * const data = await spotDeployState(
+ *   { transport },
+ *   { user: "0x..." },
+ * );
+ * ```
+ *
+ * @see https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/info-endpoint/spot#retrieve-information-about-the-spot-deploy-auction
+ */
+export function spotDeployState(
+  config: InfoConfig,
+  params: SpotDeployStateParameters,
+  signal?: AbortSignal,
+): Promise<SpotDeployStateResponse> {
+  const request = parse(SpotDeployStateRequest, {
+    type: "spotDeployState",
+    ...params,
+  });
+  return config.transport.request("info", request, signal);
+}

package/src/api/info/_methods/spotMeta.ts

@@ -0,0 +1,109 @@
+import * as v from "valibot";
+
+// ============================================================
+// API Schemas
+// ============================================================
+
+/**
+ * Request spot trading metadata.
+ * @see https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/info-endpoint/spot#retrieve-spot-metadata
+ */
+export const SpotMetaRequest = /* @__PURE__ */ (() => {
+  return v.object({
+    /** Type of request. */
+    type: v.literal("spotMeta"),
+  });
+})();
+export type SpotMetaRequest = v.InferOutput<typeof SpotMetaRequest>;
+
+/**
+ * Metadata for spot assets.
+ * @see https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/info-endpoint/spot#retrieve-spot-metadata
+ */
+export type SpotMetaResponse = {
+  /** Trading universes available for spot trading. */
+  universe: {
+    /** Token indices included in this universe. */
+    tokens: number[];
+    /** Name of the universe. */
+    name: string;
+    /** Unique identifier of the universe. */
+    index: number;
+    /** Indicates if the token is the primary representation in the system. */
+    isCanonical: boolean;
+  }[];
+  /** Tokens available for spot trading. */
+  tokens: {
+    /** Name of the token. */
+    name: string;
+    /** Minimum decimal places for order sizes. */
+    szDecimals: number;
+    /** Number of decimals for the token's smallest unit. */
+    weiDecimals: number;
+    /** Unique identifier for the token. */
+    index: number;
+    /**
+     * Token ID.
+     * @pattern ^0[xX][0-9a-fA-F]{32}$
+     */
+    tokenId: `0x${string}`;
+    /** Indicates if the token is the primary representation in the system. */
+    isCanonical: boolean;
+    /** EVM contract details. */
+    evmContract: {
+      /**
+       * Contract address.
+       * @pattern ^0x[a-fA-F0-9]{40}$
+       */
+      address: `0x${string}`;
+      /** Extra decimals in the token's smallest unit. */
+      evm_extra_wei_decimals: number;
+    } | null;
+    /** Full display name of the token. */
+    fullName: string | null;
+    /**
+     * Deployer trading fee share for the token.
+     * @pattern ^[0-9]+(\.[0-9]+)?$
+     */
+    deployerTradingFeeShare: string;
+  }[];
+};
+
+// ============================================================
+// Execution Logic
+// ============================================================
+
+import { parse } from "../../../_base.js";
+import type { InfoConfig } from "./_base/types.js";
+
+/**
+ * Request spot trading metadata.
+ *
+ * @param config General configuration for Info API requests.
+ * @param signal {@link https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal | AbortSignal} to cancel the request.
+ * @return Metadata for spot assets.
+ *
+ * @throws {ValidationError} When the request parameters fail validation (before sending).
+ * @throws {TransportError} When the transport layer throws an error.
+ *
+ * @example
+ * ```ts
+ * import { HttpTransport } from "@nktkas/hyperliquid";
+ * import { spotMeta } from "@nktkas/hyperliquid/api/info";
+ *
+ * const transport = new HttpTransport(); // or `WebSocketTransport`
+ *
+ * const data = await spotMeta({ transport });
+ * ```
+ *
+ * @see https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/info-endpoint/spot#retrieve-spot-metadata
+ */
+export function spotMeta(
+  config: InfoConfig,
+  signal?: AbortSignal,
+): Promise<SpotMetaResponse> {
+  const request = parse(SpotMetaRequest, {
+    type: "spotMeta",
+  });
+  return config.transport.request("info", request, signal);
+}