@nktkas/hyperliquid 0.31.0 → 0.32.0

package/src/api/exchange/mod.ts

@@ -0,0 +1,93 @@
+/**
+ * This module re-exports all exchange-related API request functions and types.
+ *
+ * You can use raw functions to maximize tree-shaking in your app,
+ * or to access {@link https://github.com/fabian-hiller/valibot | valibot} schemas Request/Response.
+ *
+ * @example
+ * ```ts
+ * import { privateKeyToAccount } from "npm:viem/accounts";
+ * import { HttpTransport } from "@nktkas/hyperliquid";
+ * import { order } from "@nktkas/hyperliquid/api/exchange";
+ * //       ^^^^^
+ * //       same name as in `ExchangeClient`
+ *
+ * const wallet = privateKeyToAccount("0x..."); // viem or ethers
+ * const transport = new HttpTransport(); // or `WebSocketTransport`
+ *
+ * const data = await order(
+ *   { transport, wallet }, // same params as in `ExchangeClient`
+ *   {
+ *     orders: [
+ *       {
+ *         a: 0,
+ *         b: true,
+ *         p: "30000",
+ *         s: "0.1",
+ *         r: false,
+ *         t: { limit: { tif: "Gtc" } },
+ *         c: "0x...",
+ *       },
+ *     ],
+ *     grouping: "na",
+ *   },
+ * );
+ * ```
+ *
+ * @module
+ */
+
+export { ApiRequestError } from "./_methods/_base/errors.js";
+export type { ExchangeMultiSigConfig, ExchangeSingleWalletConfig } from "./_methods/_base/execute.js";
+
+export * from "./_methods/agentEnableDexAbstraction.js";
+export * from "./_methods/agentSetAbstraction.js";
+export * from "./_methods/approveAgent.js";
+export * from "./_methods/approveBuilderFee.js";
+export * from "./_methods/batchModify.js";
+export * from "./_methods/borrowLend.js";
+export * from "./_methods/cancel.js";
+export * from "./_methods/cancelByCloid.js";
+export * from "./_methods/cDeposit.js";
+export * from "./_methods/claimRewards.js";
+export * from "./_methods/convertToMultiSigUser.js";
+export * from "./_methods/createSubAccount.js";
+export * from "./_methods/createVault.js";
+export * from "./_methods/cSignerAction.js";
+export * from "./_methods/cValidatorAction.js";
+export * from "./_methods/cWithdraw.js";
+export * from "./_methods/evmUserModify.js";
+export * from "./_methods/linkStakingUser.js";
+export * from "./_methods/modify.js";
+export * from "./_methods/noop.js";
+export * from "./_methods/order.js";
+export * from "./_methods/perpDeploy.js";
+export * from "./_methods/registerReferrer.js";
+export * from "./_methods/reserveRequestWeight.js";
+export * from "./_methods/scheduleCancel.js";
+export * from "./_methods/sendAsset.js";
+export * from "./_methods/sendToEvmWithData.js";
+export * from "./_methods/setDisplayName.js";
+export * from "./_methods/setReferrer.js";
+export * from "./_methods/spotDeploy.js";
+export * from "./_methods/spotSend.js";
+export * from "./_methods/spotUser.js";
+export * from "./_methods/subAccountModify.js";
+export * from "./_methods/subAccountSpotTransfer.js";
+export * from "./_methods/subAccountTransfer.js";
+export * from "./_methods/tokenDelegate.js";
+export * from "./_methods/topUpIsolatedOnlyMargin.js";
+export * from "./_methods/twapCancel.js";
+export * from "./_methods/twapOrder.js";
+export * from "./_methods/updateIsolatedMargin.js";
+export * from "./_methods/updateLeverage.js";
+export * from "./_methods/usdClassTransfer.js";
+export * from "./_methods/usdSend.js";
+export * from "./_methods/userDexAbstraction.js";
+export * from "./_methods/userPortfolioMargin.js";
+export * from "./_methods/userSetAbstraction.js";
+export * from "./_methods/validatorL1Stream.js";
+export * from "./_methods/vaultDistribute.js";
+export * from "./_methods/vaultModify.js";
+export * from "./_methods/vaultTransfer.js";
+export * from "./_methods/withdraw3.js";

package/src/api/info/_methods/_base/commonSchemas.ts

@@ -0,0 +1,411 @@
+/**
+ * Common types shared across Info API methods.
+ * @module
+ */
+
+/** Perpetual asset context. */
+export type PerpAssetCtxSchema = {
+  /**
+   * Previous day's closing price.
+   * @pattern ^[0-9]+(\.[0-9]+)?$
+   */
+  prevDayPx: string;
+  /**
+   * Daily notional volume.
+   * @pattern ^[0-9]+(\.[0-9]+)?$
+   */
+  dayNtlVlm: string;
+  /**
+   * Mark price.
+   * @pattern ^[0-9]+(\.[0-9]+)?$
+   */
+  markPx: string;
+  /**
+   * Mid price.
+   * @pattern ^[0-9]+(\.[0-9]+)?$
+   */
+  midPx: string | null;
+  /**
+   * Funding rate.
+   * @pattern ^-?[0-9]+(\.[0-9]+)?$
+   */
+  funding: string;
+  /**
+   * Total open interest.
+   * @pattern ^[0-9]+(\.[0-9]+)?$
+   */
+  openInterest: string;
+  /**
+   * Premium price.
+   * @pattern ^-?[0-9]+(\.[0-9]+)?$
+   */
+  premium: string | null;
+  /**
+   * Oracle price.
+   * @pattern ^[0-9]+(\.[0-9]+)?$
+   */
+  oraclePx: string;
+  /**
+   * Array of impact prices.
+   * @pattern ^[0-9]+(\.[0-9]+)?$
+   */
+  impactPxs: string[] | null;
+  /**
+   * Daily volume in base currency.
+   * @pattern ^[0-9]+(\.[0-9]+)?$
+   */
+  dayBaseVlm: string;
+};
+
+/** Spot asset context. */
+export type SpotAssetCtxSchema = {
+  /**
+   * Previous day's closing price.
+   * @pattern ^[0-9]+(\.[0-9]+)?$
+   */
+  prevDayPx: string;
+  /**
+   * Daily notional volume.
+   * @pattern ^[0-9]+(\.[0-9]+)?$
+   */
+  dayNtlVlm: string;
+  /**
+   * Mark price.
+   * @pattern ^[0-9]+(\.[0-9]+)?$
+   */
+  markPx: string;
+  /**
+   * Mid price.
+   * @pattern ^[0-9]+(\.[0-9]+)?$
+   */
+  midPx: string | null;
+  /**
+   * Circulating supply.
+   * @pattern ^[0-9]+(\.[0-9]+)?$
+   */
+  circulatingSupply: string;
+  /** Asset symbol. */
+  coin: string;
+  /**
+   * Total supply.
+   * @pattern ^[0-9]+(\.[0-9]+)?$
+   */
+  totalSupply: string;
+  /**
+   * Daily volume in base currency.
+   * @pattern ^[0-9]+(\.[0-9]+)?$
+   */
+  dayBaseVlm: string;
+};
+
+/** Open order with additional display information. */
+export type FrontendOpenOrderSchema = {
+  /** Asset symbol. */
+  coin: string;
+  /** Order side ("B" = Bid/Buy, "A" = Ask/Sell). */
+  side: "B" | "A";
+  /**
+   * Limit price.
+   * @pattern ^[0-9]+(\.[0-9]+)?$
+   */
+  limitPx: string;
+  /**
+   * Size.
+   * @pattern ^[0-9]+(\.[0-9]+)?$
+   */
+  sz: string;
+  /** Order ID. */
+  oid: number;
+  /** Timestamp when the order was placed (in ms since epoch). */
+  timestamp: number;
+  /**
+   * Original size at order placement.
+   * @pattern ^[0-9]+(\.[0-9]+)?$
+   */
+  origSz: string;
+  /** Condition for triggering the order. */
+  triggerCondition: string;
+  /** Indicates if the order is a trigger order. */
+  isTrigger: boolean;
+  /**
+   * Trigger price.
+   * @pattern ^[0-9]+(\.[0-9]+)?$
+   */
+  triggerPx: string;
+  /** Child orders associated with this order. */
+  children: unknown[];
+  /** Indicates if the order is a position TP/SL order. */
+  isPositionTpsl: boolean;
+  /** Indicates whether the order is reduce-only. */
+  reduceOnly: boolean;
+  /**
+   * Order type for market execution.
+   * - `"Market"`: Executes immediately at the market price.
+   * - `"Limit"`: Executes at the specified limit price or better.
+   * - `"Stop Market"`: Activates as a market order when a stop price is reached.
+   * - `"Stop Limit"`: Activates as a limit order when a stop price is reached.
+   * - `"Take Profit Market"`: Executes as a market order when a take profit price is reached.
+   * - `"Take Profit Limit"`: Executes as a limit order when a take profit price is reached.
+   * @see https://hyperliquid.gitbook.io/hyperliquid-docs/trading/order-types
+   */
+  orderType:
+    | "Market"
+    | "Limit"
+    | "Stop Market"
+    | "Stop Limit"
+    | "Take Profit Market"
+    | "Take Profit Limit";
+  /**
+   * Time-in-force:
+   * - `"Gtc"`: Remains active until filled or canceled.
+   * - `"Ioc"`: Fills immediately or cancels any unfilled portion.
+   * - `"Alo"`: Adds liquidity only.
+   * - `"FrontendMarket"`: Similar to Ioc, used in Hyperliquid UI.
+   * - `"LiquidationMarket"`: Similar to Ioc, used in Hyperliquid UI.
+   */
+  tif:
+    | "Gtc"
+    | "Ioc"
+    | "Alo"
+    | "FrontendMarket"
+    | "LiquidationMarket"
+    | null;
+  /**
+   * Client Order ID.
+   * @pattern ^0x[a-fA-F0-9]{32}$
+   */
+  cloid: `0x${string}` | null;
+};
+
+/** Open order. */
+export type OpenOrderSchema = {
+  /** Asset symbol. */
+  coin: string;
+  /** Order side ("B" = Bid/Buy, "A" = Ask/Sell). */
+  side: "B" | "A";
+  /**
+   * Limit price.
+   * @pattern ^[0-9]+(\.[0-9]+)?$
+   */
+  limitPx: string;
+  /**
+   * Size.
+   * @pattern ^[0-9]+(\.[0-9]+)?$
+   */
+  sz: string;
+  /** Order ID. */
+  oid: number;
+  /** Timestamp when the order was placed (in ms since epoch). */
+  timestamp: number;
+  /**
+   * Original size at order placement.
+   * @pattern ^[0-9]+(\.[0-9]+)?$
+   */
+  origSz: string;
+  /**
+   * Client Order ID.
+   * @pattern ^0x[a-fA-F0-9]{32}$
+   */
+  cloid?: `0x${string}`;
+  /** Indicates if the order is reduce-only. */
+  reduceOnly?: true;
+};
+
+/** TWAP order state. */
+export type TwapStateSchema = {
+  /** Asset symbol. */
+  coin: string;
+  /**
+   * Executed notional value.
+   * @pattern ^[0-9]+(\.[0-9]+)?$
+   */
+  executedNtl: string;
+  /**
+   * Executed size.
+   * @pattern ^[0-9]+(\.[0-9]+)?$
+   */
+  executedSz: string;
+  /** Duration in minutes. */
+  minutes: number;
+  /** Indicates if the TWAP randomizes execution. */
+  randomize: boolean;
+  /** Indicates if the order is reduce-only. */
+  reduceOnly: boolean;
+  /** Order side ("B" = Bid/Buy, "A" = Ask/Sell). */
+  side: "B" | "A";
+  /**
+   * Order size.
+   * @pattern ^[0-9]+(\.[0-9]+)?$
+   */
+  sz: string;
+  /** Start time of the TWAP order (in ms since epoch). */
+  timestamp: number;
+  /**
+   * User address.
+   * @pattern ^0x[a-fA-F0-9]{40}$
+   */
+  user: `0x${string}`;
+};
+
+/** Vault relationship type. */
+export type VaultRelationshipSchema = {
+  /** Relationship type. */
+  type: "normal" | "child";
+} | {
+  /** Relationship type. */
+  type: "parent";
+  /** Child vault information. */
+  data: {
+    /**
+     * Child vault addresses.
+     * @pattern ^0x[a-fA-F0-9]{40}$
+     */
+    childAddresses: `0x${string}`[];
+  };
+};
+
+/** Explorer transaction. */
+export type ExplorerTransactionSchema = {
+  /** Action performed in transaction. */
+  action: {
+    /** Action type. */
+    type: string;
+    [key: string]: unknown;
+  };
+  /** Block number where transaction was included. */
+  block: number;
+  /** Error message if transaction failed. */
+  error: string | null;
+  /**
+   * Transaction hash.
+   * @pattern ^0x[a-fA-F0-9]{64}$
+   */
+  hash: `0x${string}`;
+  /** Transaction creation timestamp. */
+  time: number;
+  /**
+   * Creator's address.
+   * @pattern ^0x[a-fA-F0-9]{40}$
+   */
+  user: `0x${string}`;
+};
+
+/** User fill. */
+export type UserFillSchema = {
+  /** Asset symbol. */
+  coin: string;
+  /**
+   * Price.
+   * @pattern ^[0-9]+(\.[0-9]+)?$
+   */
+  px: string;
+  /**
+   * Size.
+   * @pattern ^[0-9]+(\.[0-9]+)?$
+   */
+  sz: string;
+  /** Order side ("B" = Bid/Buy, "A" = Ask/Sell). */
+  side: "B" | "A";
+  /** Timestamp when the trade occurred (in ms since epoch). */
+  time: number;
+  /**
+   * Start position size.
+   * @pattern ^-?[0-9]+(\.[0-9]+)?$
+   */
+  startPosition: string;
+  /** Direction indicator for frontend display. */
+  dir: string;
+  /**
+   * Realized PnL.
+   * @pattern ^-?[0-9]+(\.[0-9]+)?$
+   */
+  closedPnl: string;
+  /**
+   * L1 transaction hash.
+   * @pattern ^0x[a-fA-F0-9]{64}$
+   */
+  hash: `0x${string}`;
+  /** Order ID. */
+  oid: number;
+  /** Indicates if the fill was a taker order. */
+  crossed: boolean;
+  /**
+   * Fee charged or rebate received (negative indicates rebate).
+   * @pattern ^-?[0-9]+(\.[0-9]+)?$
+   */
+  fee: string;
+  /**
+   * Optional fee charged by the UI builder.
+   * @pattern ^-?[0-9]+(\.[0-9]+)?$
+   */
+  builderFee?: string;
+  /** Unique transaction identifier for a partial fill of an order. */
+  tid: number;
+  /** Token in which the fee is denominated (e.g., "USDC"). */
+  feeToken: string;
+  /** ID of the TWAP. */
+  twapId: number | null;
+};
+
+/**
+ * Order processing status:
+ * - `"open"`: Order active and waiting to be filled.
+ * - `"filled"`: Order fully executed.
+ * - `"canceled"`: Order canceled by the user.
+ * - `"triggered"`: Order triggered and awaiting execution.
+ * - `"rejected"`: Order rejected by the system.
+ * - `"marginCanceled"`: Order canceled due to insufficient margin.
+ * - `"vaultWithdrawalCanceled"`: Canceled due to a user withdrawal from vault.
+ * - `"openInterestCapCanceled"`: Canceled due to order being too aggressive when open interest was at cap.
+ * - `"selfTradeCanceled"`: Canceled due to self-trade prevention.
+ * - `"reduceOnlyCanceled"`: Canceled reduced-only order that does not reduce position.
+ * - `"siblingFilledCanceled"`: Canceled due to sibling ordering being filled.
+ * - `"delistedCanceled"`: Canceled due to asset delisting.
+ * - `"liquidatedCanceled"`: Canceled due to liquidation.
+ * - `"scheduledCancel"`: Canceled due to exceeding scheduled cancel deadline (dead man's switch).
+ * - `"tickRejected"`: Rejected due to invalid tick price.
+ * - `"minTradeNtlRejected"`: Rejected due to order notional below minimum.
+ * - `"perpMarginRejected"`: Rejected due to insufficient margin.
+ * - `"reduceOnlyRejected"`: Rejected due to reduce only.
+ * - `"badAloPxRejected"`: Rejected due to post-only immediate match.
+ * - `"iocCancelRejected"`: Rejected due to IOC not able to match.
+ * - `"badTriggerPxRejected"`: Rejected due to invalid TP/SL price.
+ * - `"marketOrderNoLiquidityRejected"`: Rejected due to lack of liquidity for market order.
+ * - `"positionIncreaseAtOpenInterestCapRejected"`: Rejected due to open interest cap.
+ * - `"positionFlipAtOpenInterestCapRejected"`: Rejected due to open interest cap.
+ * - `"tooAggressiveAtOpenInterestCapRejected"`: Rejected due to price too aggressive at open interest cap.
+ * - `"openInterestIncreaseRejected"`: Rejected due to open interest cap.
+ * - `"insufficientSpotBalanceRejected"`: Rejected due to insufficient spot balance.
+ * - `"oracleRejected"`: Rejected due to price too far from oracle.
+ * - `"perpMaxPositionRejected"`: Rejected due to exceeding margin tier limit at current leverage.
+ */
+export type OrderProcessingStatusSchema =
+  | "open"
+  | "filled"
+  | "canceled"
+  | "triggered"
+  | "rejected"
+  | "marginCanceled"
+  | "vaultWithdrawalCanceled"
+  | "openInterestCapCanceled"
+  | "selfTradeCanceled"
+  | "reduceOnlyCanceled"
+  | "siblingFilledCanceled"
+  | "delistedCanceled"
+  | "liquidatedCanceled"
+  | "scheduledCancel"
+  | "tickRejected"
+  | "minTradeNtlRejected"
+  | "perpMarginRejected"
+  | "reduceOnlyRejected"
+  | "badAloPxRejected"
+  | "iocCancelRejected"
+  | "badTriggerPxRejected"
+  | "marketOrderNoLiquidityRejected"
+  | "positionIncreaseAtOpenInterestCapRejected"
+  | "positionFlipAtOpenInterestCapRejected"
+  | "tooAggressiveAtOpenInterestCapRejected"
+  | "openInterestIncreaseRejected"
+  | "insufficientSpotBalanceRejected"
+  | "oracleRejected"
+  | "perpMaxPositionRejected";

package/src/api/info/_methods/_base/types.ts

@@ -0,0 +1,12 @@
+/**
+ * Configuration types for the Info API.
+ * @module
+ */
+
+import type { IRequestTransport } from "../../../../transport/mod.js";
+
+/** Configuration for Info API requests. */
+export interface InfoConfig<T extends IRequestTransport = IRequestTransport> {
+  /** The transport used to connect to the Hyperliquid API. */
+  transport: T;
+}

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

@@ -0,0 +1,121 @@
+import * as v from "valibot";
+
+// ============================================================
+// API Schemas
+// ============================================================
+
+import { Address } from "../../_schemas.js";
+
+/**
+ * Request user active asset data.
+ * @see https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/info-endpoint/perpetuals#retrieve-users-active-asset-data
+ */
+export const ActiveAssetDataRequest = /* @__PURE__ */ (() => {
+  return v.object({
+    /** Type of request. */
+    type: v.literal("activeAssetData"),
+    /** Asset symbol (e.g., BTC). */
+    coin: v.string(),
+    /** User address. */
+    user: Address,
+  });
+})();
+export type ActiveAssetDataRequest = v.InferOutput<typeof ActiveAssetDataRequest>;
+
+/**
+ * User active asset data.
+ * @see https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/info-endpoint/perpetuals#retrieve-users-active-asset-data
+ */
+export type ActiveAssetDataResponse = {
+  /**
+   * User address.
+   * @pattern ^0x[a-fA-F0-9]{40}$
+   */
+  user: `0x${string}`;
+  /** Asset symbol (e.g., BTC). */
+  coin: string;
+  /** Leverage configuration. */
+  leverage: {
+    /** Leverage type. */
+    type: "isolated";
+    /** Leverage value used. */
+    value: number;
+    /**
+     * Amount of USD used (1 = $1).
+     * @pattern ^-?[0-9]+(\.[0-9]+)?$
+     */
+    rawUsd: string;
+  } | {
+    /** Leverage type. */
+    type: "cross";
+    /** Leverage value used. */
+    value: number;
+  };
+  /** Maximum trade size range [min, max]. */
+  maxTradeSzs: [
+    /** @pattern ^[0-9]+(\.[0-9]+)?$ */
+    min: string,
+    /** @pattern ^[0-9]+(\.[0-9]+)?$ */
+    max: string,
+  ];
+  /** Available to trade range [min, max]. */
+  availableToTrade: [
+    /** @pattern ^[0-9]+(\.[0-9]+)?$ */
+    min: string,
+    /** @pattern ^[0-9]+(\.[0-9]+)?$ */
+    max: string,
+  ];
+  /**
+   * Mark price.
+   * @pattern ^[0-9]+(\.[0-9]+)?$
+   */
+  markPx: string;
+};
+
+// ============================================================
+// Execution Logic
+// ============================================================
+
+import { parse } from "../../../_base.js";
+import type { InfoConfig } from "./_base/types.js";
+
+/** Request parameters for the {@linkcode activeAssetData} function. */
+export type ActiveAssetDataParameters = Omit<v.InferInput<typeof ActiveAssetDataRequest>, "type">;
+
+/**
+ * Request user active asset data.
+ *
+ * @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 User active asset data.
+ *
+ * @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 { activeAssetData } from "@nktkas/hyperliquid/api/info";
+ *
+ * const transport = new HttpTransport(); // or `WebSocketTransport`
+ *
+ * const data = await activeAssetData(
+ *   { transport },
+ *   { user: "0x...", coin: "ETH" },
+ * );
+ * ```
+ *
+ * @see https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/info-endpoint/perpetuals#retrieve-users-active-asset-data
+ */
+export function activeAssetData(
+  config: InfoConfig,
+  params: ActiveAssetDataParameters,
+  signal?: AbortSignal,
+): Promise<ActiveAssetDataResponse> {
+  const request = parse(ActiveAssetDataRequest, {
+    type: "activeAssetData",
+    ...params,
+  });
+  return config.transport.request("info", request, signal);
+}