@nktkas/hyperliquid 0.25.9 → 0.26.0

package/src/api/info/delegatorRewards.ts

@@ -0,0 +1,101 @@
+import * as v from "valibot";
+import { Address, type DeepImmutable, parser, UnsignedDecimal, UnsignedInteger } from "../_base.ts";
+import type { InfoRequestConfig } from "./_types.ts";
+
+// -------------------- Schemas --------------------
+
+/**
+ * Request user staking rewards.
+ * @see https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/info-endpoint#query-a-users-staking-rewards
+ */
+export const DelegatorRewardsRequest = /* @__PURE__ */ (() => {
+  return v.pipe(
+    v.object({
+      /** Type of request. */
+      type: v.pipe(
+        v.literal("delegatorRewards"),
+        v.description("Type of request."),
+      ),
+      /** User address. */
+      user: v.pipe(
+        Address,
+        v.description("User address."),
+      ),
+    }),
+    v.description("Request user staking rewards."),
+  );
+})();
+export type DelegatorRewardsRequest = v.InferOutput<typeof DelegatorRewardsRequest>;
+
+/**
+ * Array of rewards received from staking activities.
+ * @see https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/info-endpoint#query-a-users-staking-rewards
+ */
+export const DelegatorRewardsResponse = /* @__PURE__ */ (() => {
+  return v.pipe(
+    v.array(
+      /** Reward received from staking activities. */
+      v.pipe(
+        v.object({
+          /** Timestamp when the reward was received (in ms since epoch). */
+          time: v.pipe(
+            UnsignedInteger,
+            v.description("Timestamp when the reward was received (in ms since epoch)."),
+          ),
+          /** Source of the reward. */
+          source: v.pipe(
+            v.union([v.literal("delegation"), v.literal("commission")]),
+            v.description("Source of the reward."),
+          ),
+          /** Total reward amount. */
+          totalAmount: v.pipe(
+            UnsignedDecimal,
+            v.description("Total reward amount."),
+          ),
+        }),
+        v.description("Reward received from staking activities."),
+      ),
+    ),
+    v.description("Array of rewards received from staking activities."),
+  );
+})();
+export type DelegatorRewardsResponse = v.InferOutput<typeof DelegatorRewardsResponse>;
+
+// -------------------- Function --------------------
+
+/** Request parameters for the {@linkcode delegatorRewards} function. */
+export type DelegatorRewardsParameters = Omit<v.InferInput<typeof DelegatorRewardsRequest>, "type">;
+
+/**
+ * Request user staking rewards.
+ * @param config - General configuration for Info API requests.
+ * @param params - Parameters specific to the API request.
+ * @param signal - An [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal) can be used to cancel the request by calling [`abort()`](https://developer.mozilla.org/en-US/docs/Web/API/AbortController/abort) on the corresponding [`AbortController`](https://developer.mozilla.org/en-US/docs/Web/API/AbortController).
+ * @returns Array of rewards received from staking activities.
+ *
+ * @throws {TransportError} When the transport layer throws an error.
+ *
+ * @see https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/info-endpoint#query-a-users-staking-rewards
+ * @example
+ * ```ts
+ * import { HttpTransport } from "@nktkas/hyperliquid";
+ * import { delegatorRewards } from "@nktkas/hyperliquid/api/info";
+ *
+ * const transport = new HttpTransport(); // or `WebSocketTransport`
+ * const data = await delegatorRewards(
+ *   { transport },
+ *   { user: "0x..." },
+ * );
+ * ```
+ */
+export function delegatorRewards(
+  config: InfoRequestConfig,
+  params: DeepImmutable<DelegatorRewardsParameters>,
+  signal?: AbortSignal,
+): Promise<DelegatorRewardsResponse> {
+  const request = parser(DelegatorRewardsRequest)({
+    type: "delegatorRewards",
+    ...params,
+  });
+  return config.transport.request("info", request, signal);
+}

package/src/api/info/delegatorSummary.ts

@@ -0,0 +1,100 @@
+import * as v from "valibot";
+import { Address, type DeepImmutable, parser, UnsignedDecimal, UnsignedInteger } from "../_base.ts";
+import type { InfoRequestConfig } from "./_types.ts";
+
+// -------------------- Schemas --------------------
+
+/**
+ * Request user's staking summary.
+ * @see https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/info-endpoint#query-a-users-staking-summary
+ */
+export const DelegatorSummaryRequest = /* @__PURE__ */ (() => {
+  return v.pipe(
+    v.object({
+      /** Type of request. */
+      type: v.pipe(
+        v.literal("delegatorSummary"),
+        v.description("Type of request."),
+      ),
+      /** User address. */
+      user: v.pipe(
+        Address,
+        v.description("User address."),
+      ),
+    }),
+    v.description("Request user's staking summary."),
+  );
+})();
+export type DelegatorSummaryRequest = v.InferOutput<typeof DelegatorSummaryRequest>;
+
+/**
+ * User's staking summary.
+ * @see https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/info-endpoint#query-a-users-staking-summary
+ */
+export const DelegatorSummaryResponse = /* @__PURE__ */ (() => {
+  return v.pipe(
+    v.object({
+      /** Total amount of delegated tokens. */
+      delegated: v.pipe(
+        UnsignedDecimal,
+        v.description("Total amount of delegated tokens."),
+      ),
+      /** Total amount of undelegated tokens. */
+      undelegated: v.pipe(
+        UnsignedDecimal,
+        v.description("Total amount of undelegated tokens."),
+      ),
+      /** Total amount of tokens pending withdrawal. */
+      totalPendingWithdrawal: v.pipe(
+        UnsignedDecimal,
+        v.description("Total amount of tokens pending withdrawal."),
+      ),
+      /** Number of pending withdrawals. */
+      nPendingWithdrawals: v.pipe(
+        UnsignedInteger,
+        v.description("Number of pending withdrawals."),
+      ),
+    }),
+    v.description("User's staking summary."),
+  );
+})();
+export type DelegatorSummaryResponse = v.InferOutput<typeof DelegatorSummaryResponse>;
+
+// -------------------- Function --------------------
+
+/** Request parameters for the {@linkcode delegatorSummary} function. */
+export type DelegatorSummaryParameters = Omit<v.InferInput<typeof DelegatorSummaryRequest>, "type">;
+
+/**
+ * Request user's staking summary.
+ * @param config - General configuration for Info API requests.
+ * @param params - Parameters specific to the API request.
+ * @param signal - An [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal) can be used to cancel the request by calling [`abort()`](https://developer.mozilla.org/en-US/docs/Web/API/AbortController/abort) on the corresponding [`AbortController`](https://developer.mozilla.org/en-US/docs/Web/API/AbortController).
+ * @returns User's staking summary.
+ *
+ * @throws {TransportError} When the transport layer throws an error.
+ *
+ * @see https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/info-endpoint#query-a-users-staking-summary
+ * @example
+ * ```ts
+ * import { HttpTransport } from "@nktkas/hyperliquid";
+ * import { delegatorSummary } from "@nktkas/hyperliquid/api/info";
+ *
+ * const transport = new HttpTransport(); // or `WebSocketTransport`
+ * const data = await delegatorSummary(
+ *   { transport },
+ *   { user: "0x..." },
+ * );
+ * ```
+ */
+export function delegatorSummary(
+  config: InfoRequestConfig,
+  params: DeepImmutable<DelegatorSummaryParameters>,
+  signal?: AbortSignal,
+): Promise<DelegatorSummaryResponse> {
+  const request = parser(DelegatorSummaryRequest)({
+    type: "delegatorSummary",
+    ...params,
+  });
+  return config.transport.request("info", request, signal);
+}

package/src/api/info/exchangeStatus.ts

@@ -0,0 +1,74 @@
+import * as v from "valibot";
+import { parser, UnsignedInteger } from "../_base.ts";
+import type { InfoRequestConfig } from "./_types.ts";
+
+// -------------------- Schemas --------------------
+
+/**
+ * Request exchange system status information.
+ * @see null
+ */
+export const ExchangeStatusRequest = /* @__PURE__ */ (() => {
+  return v.pipe(
+    v.object({
+      /** Type of request. */
+      type: v.pipe(
+        v.literal("exchangeStatus"),
+        v.description("Type of request."),
+      ),
+    }),
+    v.description("Request exchange system status information."),
+  );
+})();
+export type ExchangeStatusRequest = v.InferOutput<typeof ExchangeStatusRequest>;
+
+/**
+ * Exchange system status information.
+ * @see null
+ */
+export const ExchangeStatusResponse = /* @__PURE__ */ (() => {
+  return v.pipe(
+    v.object({
+      /** Server time (in ms since epoch). */
+      time: v.pipe(
+        UnsignedInteger,
+        v.description("Server time (in ms since epoch)."),
+      ),
+      specialStatuses: v.pipe(
+        v.nullable(v.unknown()),
+      ),
+    }),
+    v.description("Exchange system status information."),
+  );
+})();
+export type ExchangeStatusResponse = v.InferOutput<typeof ExchangeStatusResponse>;
+
+// -------------------- Function --------------------
+
+/**
+ * Request exchange system status information.
+ * @param config - General configuration for Info API requests.
+ * @param signal - An [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal) can be used to cancel the request by calling [`abort()`](https://developer.mozilla.org/en-US/docs/Web/API/AbortController/abort) on the corresponding [`AbortController`](https://developer.mozilla.org/en-US/docs/Web/API/AbortController).
+ * @returns Exchange system status information.
+ *
+ * @throws {TransportError} When the transport layer throws an error.
+ *
+ * @see null
+ * @example
+ * ```ts
+ * import { HttpTransport } from "@nktkas/hyperliquid";
+ * import { exchangeStatus } from "@nktkas/hyperliquid/api/info";
+ *
+ * const transport = new HttpTransport(); // or `WebSocketTransport`
+ * const data = await exchangeStatus({ transport });
+ * ```
+ */
+export function exchangeStatus(
+  config: InfoRequestConfig,
+  signal?: AbortSignal,
+): Promise<ExchangeStatusResponse> {
+  const request = parser(ExchangeStatusRequest)({
+    type: "exchangeStatus",
+  });
+  return config.transport.request("info", request, signal);
+}

package/src/api/info/extraAgents.ts

@@ -0,0 +1,102 @@
+import * as v from "valibot";
+import { Address, type DeepImmutable, parser, UnsignedInteger } from "../_base.ts";
+import type { InfoRequestConfig } from "./_types.ts";
+
+// -------------------- Schemas --------------------
+
+/**
+ * Request user extra agents.
+ * @see null
+ */
+export const ExtraAgentsRequest = /* @__PURE__ */ (() => {
+  return v.pipe(
+    v.object({
+      /** Type of request. */
+      type: v.pipe(
+        v.literal("extraAgents"),
+        v.description("Type of request."),
+      ),
+      /** User address. */
+      user: v.pipe(
+        Address,
+        v.description("User address."),
+      ),
+    }),
+    v.description("Request user extra agents."),
+  );
+})();
+export type ExtraAgentsRequest = v.InferOutput<typeof ExtraAgentsRequest>;
+
+/**
+ * Array of extra agent details for a user.
+ * @see null
+ */
+export const ExtraAgentsResponse = /* @__PURE__ */ (() => {
+  return v.pipe(
+    v.array(
+      /** Extra agent details for a user. */
+      v.pipe(
+        v.object({
+          /** Extra agent address. */
+          address: v.pipe(
+            Address,
+            v.description("Extra agent address."),
+          ),
+          /** Extra agent name. */
+          name: v.pipe(
+            v.string(),
+            v.minLength(1),
+            v.description("Extra agent name."),
+          ),
+          /** Validity period as a timestamp (in ms since epoch). */
+          validUntil: v.pipe(
+            UnsignedInteger,
+            v.description("Validity period as a timestamp (in ms since epoch)."),
+          ),
+        }),
+        v.description("Extra agent details for a user."),
+      ),
+    ),
+    v.description("Array of extra agent details for a user."),
+  );
+})();
+export type ExtraAgentsResponse = v.InferOutput<typeof ExtraAgentsResponse>;
+
+// -------------------- Function --------------------
+
+/** Request parameters for the {@linkcode extraAgents} function. */
+export type ExtraAgentsParameters = Omit<v.InferInput<typeof ExtraAgentsRequest>, "type">;
+
+/**
+ * Request user extra agents.
+ * @param config - General configuration for Info API requests.
+ * @param params - Parameters specific to the API request.
+ * @param signal - An [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal) can be used to cancel the request by calling [`abort()`](https://developer.mozilla.org/en-US/docs/Web/API/AbortController/abort) on the corresponding [`AbortController`](https://developer.mozilla.org/en-US/docs/Web/API/AbortController).
+ * @returns Array of extra agent details for a user.
+ *
+ * @throws {TransportError} When the transport layer throws an error.
+ *
+ * @see null
+ * @example
+ * ```ts
+ * import { HttpTransport } from "@nktkas/hyperliquid";
+ * import { extraAgents } from "@nktkas/hyperliquid/api/info";
+ *
+ * const transport = new HttpTransport(); // or `WebSocketTransport`
+ * const data = await extraAgents(
+ *   { transport },
+ *   { user: "0x..." },
+ * );
+ * ```
+ */
+export function extraAgents(
+  config: InfoRequestConfig,
+  params: DeepImmutable<ExtraAgentsParameters>,
+  signal?: AbortSignal,
+): Promise<ExtraAgentsResponse> {
+  const request = parser(ExtraAgentsRequest)({
+    type: "extraAgents",
+    ...params,
+  });
+  return config.transport.request("info", request, signal);
+}

package/src/api/info/frontendOpenOrders.ts

@@ -0,0 +1,86 @@
+import * as v from "valibot";
+import { Address, type DeepImmutable, parser } from "../_base.ts";
+import type { InfoRequestConfig } from "./_types.ts";
+
+import { DetailedOrderSchema } from "../_common_schemas.ts";
+
+// -------------------- Schemas --------------------
+
+/**
+ * Request frontend open orders.
+ * @see https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/info-endpoint#retrieve-a-users-open-orders-with-additional-frontend-info
+ */
+export const FrontendOpenOrdersRequest = /* @__PURE__ */ (() => {
+  return v.pipe(
+    v.object({
+      /** Type of request. */
+      type: v.pipe(
+        v.literal("frontendOpenOrders"),
+        v.description("Type of request."),
+      ),
+      /** User address. */
+      user: v.pipe(
+        Address,
+        v.description("User address."),
+      ),
+      /** DEX name (empty string for main dex). */
+      dex: v.pipe(
+        v.optional(v.string()),
+        v.description("DEX name (empty string for main dex)."),
+      ),
+    }),
+    v.description("Request frontend open orders."),
+  );
+})();
+export type FrontendOpenOrdersRequest = v.InferOutput<typeof FrontendOpenOrdersRequest>;
+
+/**
+ * Array of open orders with additional display information.
+ * @see https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/info-endpoint#retrieve-a-users-open-orders-with-additional-frontend-info
+ */
+export const FrontendOpenOrdersResponse = /* @__PURE__ */ (() => {
+  return v.pipe(
+    v.array(DetailedOrderSchema),
+    v.description("Array of open orders with additional display information."),
+  );
+})();
+export type FrontendOpenOrdersResponse = v.InferOutput<typeof FrontendOpenOrdersResponse>;
+
+// -------------------- Function --------------------
+
+/** Request parameters for the {@linkcode frontendOpenOrders} function. */
+export type FrontendOpenOrdersParameters = Omit<v.InferInput<typeof FrontendOpenOrdersRequest>, "type">;
+
+/**
+ * Request frontend open orders.
+ * @param config - General configuration for Info API requests.
+ * @param params - Parameters specific to the API request.
+ * @param signal - An [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal) can be used to cancel the request by calling [`abort()`](https://developer.mozilla.org/en-US/docs/Web/API/AbortController/abort) on the corresponding [`AbortController`](https://developer.mozilla.org/en-US/docs/Web/API/AbortController).
+ * @returns Array of open orders with additional display information.
+ *
+ * @throws {TransportError} When the transport layer throws an error.
+ *
+ * @see https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/info-endpoint#retrieve-a-users-open-orders-with-additional-frontend-info
+ * @example
+ * ```ts
+ * import { HttpTransport } from "@nktkas/hyperliquid";
+ * import { frontendOpenOrders } from "@nktkas/hyperliquid/api/info";
+ *
+ * const transport = new HttpTransport(); // or `WebSocketTransport`
+ * const data = await frontendOpenOrders(
+ *   { transport },
+ *   { user: "0x..." },
+ * );
+ * ```
+ */
+export function frontendOpenOrders(
+  config: InfoRequestConfig,
+  params: DeepImmutable<FrontendOpenOrdersParameters>,
+  signal?: AbortSignal,
+): Promise<FrontendOpenOrdersResponse> {
+  const request = parser(FrontendOpenOrdersRequest)({
+    type: "frontendOpenOrders",
+    ...params,
+  });
+  return config.transport.request("info", request, signal);
+}

package/src/api/info/fundingHistory.ts

@@ -0,0 +1,116 @@
+import * as v from "valibot";
+import { Decimal, type DeepImmutable, parser, UnsignedInteger } from "../_base.ts";
+import type { InfoRequestConfig } from "./_types.ts";
+
+// -------------------- Schemas --------------------
+
+/**
+ * Request funding history.
+ * @see https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/info-endpoint/perpetuals#retrieve-historical-funding-rates
+ */
+export const FundingHistoryRequest = /* @__PURE__ */ (() => {
+  return v.pipe(
+    v.object({
+      /** Type of request. */
+      type: v.pipe(
+        v.literal("fundingHistory"),
+        v.description("Type of request."),
+      ),
+      /** Asset symbol (e.g., BTC). */
+      coin: v.pipe(
+        v.string(),
+        v.description("Asset symbol (e.g., BTC)."),
+      ),
+      /** Start time (in ms since epoch). */
+      startTime: v.pipe(
+        UnsignedInteger,
+        v.description("Start time (in ms since epoch)."),
+      ),
+      /** End time (in ms since epoch). */
+      endTime: v.pipe(
+        v.nullish(UnsignedInteger),
+        v.description("End time (in ms since epoch)."),
+      ),
+    }),
+    v.description("Request funding history."),
+  );
+})();
+export type FundingHistoryRequest = v.InferOutput<typeof FundingHistoryRequest>;
+
+/**
+ * Array of historical funding rate records for an asset.
+ * @see https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/info-endpoint/perpetuals#retrieve-historical-funding-rates
+ */
+export const FundingHistoryResponse = /* @__PURE__ */ (() => {
+  return v.pipe(
+    v.array(
+      /** Historical funding rate record for an asset. */
+      v.pipe(
+        v.object({
+          /** Asset symbol. */
+          coin: v.pipe(
+            v.string(),
+            v.description("Asset symbol."),
+          ),
+          /** Funding rate. */
+          fundingRate: v.pipe(
+            Decimal,
+            v.description("Funding rate."),
+          ),
+          /** Premium price. */
+          premium: v.pipe(
+            Decimal,
+            v.description("Premium price."),
+          ),
+          /** Funding record timestamp (ms since epoch). */
+          time: v.pipe(
+            UnsignedInteger,
+            v.description("Funding record timestamp (ms since epoch)."),
+          ),
+        }),
+        v.description("Historical funding rate record for an asset."),
+      ),
+    ),
+    v.description("Array of historical funding rate records for an asset."),
+  );
+})();
+export type FundingHistoryResponse = v.InferOutput<typeof FundingHistoryResponse>;
+
+// -------------------- Function --------------------
+
+/** Request parameters for the {@linkcode fundingHistory} function. */
+export type FundingHistoryParameters = Omit<v.InferInput<typeof FundingHistoryRequest>, "type">;
+
+/**
+ * Request funding history.
+ * @param config - General configuration for Info API requests.
+ * @param params - Parameters specific to the API request.
+ * @param signal - An [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal) can be used to cancel the request by calling [`abort()`](https://developer.mozilla.org/en-US/docs/Web/API/AbortController/abort) on the corresponding [`AbortController`](https://developer.mozilla.org/en-US/docs/Web/API/AbortController).
+ * @returns Array of historical funding rate records for an asset.
+ *
+ * @throws {TransportError} When the transport layer throws an error.
+ *
+ * @see https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/info-endpoint/perpetuals#retrieve-historical-funding-rates
+ * @example
+ * ```ts
+ * import { HttpTransport } from "@nktkas/hyperliquid";
+ * import { fundingHistory } from "@nktkas/hyperliquid/api/info";
+ *
+ * const transport = new HttpTransport(); // or `WebSocketTransport`
+ * const data = await fundingHistory(
+ *   { transport },
+ *   { coin: "ETH", startTime: Date.now() - 1000 * 60 * 60 * 24 },
+ * );
+ * ```
+ */
+export function fundingHistory(
+  config: InfoRequestConfig,
+  params: DeepImmutable<FundingHistoryParameters>,
+  signal?: AbortSignal,
+): Promise<FundingHistoryResponse> {
+  const request = parser(FundingHistoryRequest)({
+    type: "fundingHistory",
+    ...params,
+  });
+  return config.transport.request("info", request, signal);
+}

package/src/api/info/gossipRootIps.ts

@@ -0,0 +1,65 @@
+import * as v from "valibot";
+import { parser } from "../_base.ts";
+import type { InfoRequestConfig } from "./_types.ts";
+
+// -------------------- Schemas --------------------
+
+/**
+ * Request gossip root IPs.
+ * @see null
+ */
+export const GossipRootIpsRequest = /* @__PURE__ */ (() => {
+  return v.pipe(
+    v.object({
+      /** Type of request. */
+      type: v.pipe(
+        v.literal("gossipRootIps"),
+        v.description("Type of request."),
+      ),
+    }),
+    v.description("Request gossip root IPs."),
+  );
+})();
+export type GossipRootIpsRequest = v.InferOutput<typeof GossipRootIpsRequest>;
+
+/**
+ * Array of gossip root IPs.
+ * @see null
+ */
+export const GossipRootIpsResponse = /* @__PURE__ */ (() => {
+  return v.pipe(
+    v.array(v.pipe(v.string(), v.ipv4())),
+    v.description("Array of gossip root IPs."),
+  );
+})();
+export type GossipRootIpsResponse = v.InferOutput<typeof GossipRootIpsResponse>;
+
+// -------------------- Function --------------------
+
+/**
+ * Request gossip root IPs.
+ * @param config - General configuration for Info API requests.
+ * @param signal - An [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal) can be used to cancel the request by calling [`abort()`](https://developer.mozilla.org/en-US/docs/Web/API/AbortController/abort) on the corresponding [`AbortController`](https://developer.mozilla.org/en-US/docs/Web/API/AbortController).
+ * @returns Array of gossip root IPs.
+ *
+ * @throws {TransportError} When the transport layer throws an error.
+ *
+ * @see null
+ * @example
+ * ```ts
+ * import { HttpTransport } from "@nktkas/hyperliquid";
+ * import { gossipRootIps } from "@nktkas/hyperliquid/api/info";
+ *
+ * const transport = new HttpTransport(); // or `WebSocketTransport`
+ * const data = await gossipRootIps({ transport });
+ * ```
+ */
+export function gossipRootIps(
+  config: InfoRequestConfig,
+  signal?: AbortSignal,
+): Promise<GossipRootIpsResponse> {
+  const request = parser(GossipRootIpsRequest)({
+    type: "gossipRootIps",
+  });
+  return config.transport.request("info", request, signal);
+}