@nktkas/hyperliquid 0.32.0 → 0.32.2

package/src/api/info/client.ts

@@ -102,7 +102,13 @@ import {
 import { openOrders, type OpenOrdersParameters, type OpenOrdersResponse } from "./_methods/openOrders.js";
 import { orderStatus, type OrderStatusParameters, type OrderStatusResponse } from "./_methods/orderStatus.js";
 import { outcomeMeta, type OutcomeMetaResponse } from "./_methods/outcomeMeta.js";
+import {
+  perpAnnotation,
+  type PerpAnnotationParameters,
+  type PerpAnnotationResponse,
+} from "./_methods/perpAnnotation.js";
 import { perpCategories, type PerpCategoriesResponse } from "./_methods/perpCategories.js";
+import { perpConciseAnnotations, type PerpConciseAnnotationsResponse } from "./_methods/perpConciseAnnotations.js";
 import { perpDeployAuctionStatus, type PerpDeployAuctionStatusResponse } from "./_methods/perpDeployAuctionStatus.js";
 import { perpDexLimits, type PerpDexLimitsParameters, type PerpDexLimitsResponse } from "./_methods/perpDexLimits.js";
 import { perpDexs, type PerpDexsResponse } from "./_methods/perpDexs.js";
@@ -1235,6 +1241,35 @@ export class InfoClient<C extends InfoConfig = InfoConfig> {
     return outcomeMeta(this.config_, signal);
   }
 
+  /**
+   * Request perp annotation.
+   *
+   * @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 Perp annotation for an asset.
+   *
+   * @throws {ValidationError} When the request parameters fail validation (before sending).
+   * @throws {TransportError} When the transport layer throws an error.
+   *
+   * @example
+   * ```ts
+   * import * as hl from "@nktkas/hyperliquid";
+   *
+   * const transport = new hl.HttpTransport(); // or `WebSocketTransport`
+   * const client = new hl.InfoClient({ transport });
+   *
+   * const data = await client.perpAnnotation({ coin: "BTC" });
+   * ```
+   *
+   * @see https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/info-endpoint/perpetuals#retrieve-perp-annotation
+   */
+  perpAnnotation(
+    params: PerpAnnotationParameters,
+    signal?: AbortSignal,
+  ): Promise<PerpAnnotationResponse> {
+    return perpAnnotation(this.config_, params, signal);
+  }
+
   /**
    * Request all perpetual asset categories.
    *
@@ -1262,6 +1297,33 @@ export class InfoClient<C extends InfoConfig = InfoConfig> {
     return perpCategories(this.config_, signal);
   }
 
+  /**
+   * Request concise annotations for all perpetual assets.
+   *
+   * @param signal {@link https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal | AbortSignal} to cancel the request.
+   * @return Array of tuples mapping coin names to their concise annotations.
+   *
+   * @throws {ValidationError} When the request parameters fail validation (before sending).
+   * @throws {TransportError} When the transport layer throws an error.
+   *
+   * @example
+   * ```ts
+   * import * as hl from "@nktkas/hyperliquid";
+   *
+   * const transport = new hl.HttpTransport(); // or `WebSocketTransport`
+   * const client = new hl.InfoClient({ transport });
+   *
+   * const data = await client.perpConciseAnnotations();
+   * ```
+   *
+   * @see https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/info-endpoint/perpetuals#retrieve-concise-perp-annotations
+   */
+  perpConciseAnnotations(
+    signal?: AbortSignal,
+  ): Promise<PerpConciseAnnotationsResponse> {
+    return perpConciseAnnotations(this.config_, signal);
+  }
+
   /**
    * Request for the status of the perpetual deploy auction.
    *
@@ -2469,7 +2531,9 @@ export type { MetaAndAssetCtxsParameters, MetaAndAssetCtxsResponse } from "./_me
 export type { OpenOrdersParameters, OpenOrdersResponse } from "./_methods/openOrders.js";
 export type { OrderStatusParameters, OrderStatusResponse } from "./_methods/orderStatus.js";
 export type { OutcomeMetaResponse } from "./_methods/outcomeMeta.js";
+export type { PerpAnnotationParameters, PerpAnnotationResponse } from "./_methods/perpAnnotation.js";
 export type { PerpCategoriesResponse } from "./_methods/perpCategories.js";
+export type { PerpConciseAnnotationsResponse } from "./_methods/perpConciseAnnotations.js";
 export type { PerpDeployAuctionStatusResponse } from "./_methods/perpDeployAuctionStatus.js";
 export type { PerpDexLimitsParameters, PerpDexLimitsResponse } from "./_methods/perpDexLimits.js";
 export type { PerpDexsResponse } from "./_methods/perpDexs.js";

package/src/api/info/mod.ts

@@ -58,7 +58,9 @@ export * from "./_methods/metaAndAssetCtxs.js";
 export * from "./_methods/openOrders.js";
 export * from "./_methods/orderStatus.js";
 export * from "./_methods/outcomeMeta.js";
+export * from "./_methods/perpAnnotation.js";
 export * from "./_methods/perpCategories.js";
+export * from "./_methods/perpConciseAnnotations.js";
 export * from "./_methods/perpDeployAuctionStatus.js";
 export * from "./_methods/perpDexLimits.js";
 export * from "./_methods/perpDexs.js";

package/src/api/subscription/_methods/l2Book.ts

@@ -4,8 +4,6 @@ import * as v from "valibot";
 // API Schemas
 // ============================================================
 
-import { Integer } from "../../_schemas.js";
-
 /**
  * Subscription to L2 order book events for a specific asset.
  * @see https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/websocket/subscriptions
@@ -17,13 +15,28 @@ export const L2BookRequest = /* @__PURE__ */ (() => {
     /** Asset symbol (e.g., BTC). */
     coin: v.string(),
     /** Number of significant figures. */
-    nSigFigs: v.nullish(v.pipe(Integer, v.picklist([2, 3, 4, 5]))),
+    nSigFigs: v.nullish(v.picklist([2, 3, 4, 5])),
     /** Mantissa for aggregation (if `nSigFigs` is 5). */
-    mantissa: v.nullish(v.pipe(Integer, v.picklist([2, 5]))),
+    mantissa: v.nullish(v.picklist([2, 5])),
   });
 })();
 export type L2BookRequest = v.InferOutput<typeof L2BookRequest>;
 
+type L2BookLevel = {
+  /**
+   * Price.
+   * @pattern ^[0-9]+(\.[0-9]+)?$
+   */
+  px: string;
+  /**
+   * Total size.
+   * @pattern ^[0-9]+(\.[0-9]+)?$
+   */
+  sz: string;
+  /** Number of individual orders. */
+  n: number;
+};
+
 /**
  * Event of L2 order book snapshot.
  * @see https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/websocket/subscriptions
@@ -34,38 +47,12 @@ export type L2BookEvent = {
   /** Timestamp of the snapshot (in ms since epoch). */
   time: number;
   /** Bid and ask levels (index 0 = bids, index 1 = asks). */
-  levels: [{
-    /**
-     * Price.
-     * @pattern ^[0-9]+(\.[0-9]+)?$
-     */
-    px: string;
-    /**
-     * Total size.
-     * @pattern ^[0-9]+(\.[0-9]+)?$
-     */
-    sz: string;
-    /** Number of individual orders. */
-    n: number;
-  }[], {
-    /**
-     * Price.
-     * @pattern ^[0-9]+(\.[0-9]+)?$
-     */
-    px: string;
-    /**
-     * Total size.
-     * @pattern ^[0-9]+(\.[0-9]+)?$
-     */
-    sz: string;
-    /** Number of individual orders. */
-    n: number;
-  }[]];
+  levels: [bids: L2BookLevel[], asks: L2BookLevel[]];
   /**
    * Spread (only present when `nSigFigs` is non-null).
    * @pattern ^[0-9]+(\.[0-9]+)?$
    */
-  spread?: string | undefined;
+  spread?: string;
 };
 
 // ============================================================

package/src/api/subscription/_methods/spotState.ts

@@ -18,7 +18,7 @@ export const SpotStateRequest = /* @__PURE__ */ (() => {
     /** User address. */
     user: Address,
     /** Whether to ignore portfolio margin calculations. */
-    ignorePortfolioMargin: v.optional(v.boolean(), false),
+    ignorePortfolioMargin: v.optional(v.boolean()),
   });
 })();
 export type SpotStateRequest = v.InferOutput<typeof SpotStateRequest>;
@@ -80,7 +80,7 @@ export function spotState(
   params: SpotStateParameters,
   listener: (data: SpotStateEvent) => void,
 ): Promise<ISubscription> {
-  const payload = parse(SpotStateRequest, { type: "spotState", user: params.user });
+  const payload = parse(SpotStateRequest, { type: "spotState", ...params });
   return config.transport.subscribe<SpotStateEvent>(payload.type, payload, (e) => {
     if (e.detail.user === payload.user) {
       listener(e.detail);

package/src/api/subscription/_methods/userFundings.ts

@@ -55,7 +55,7 @@ export type UserFundingsEvent = {
     nSamples: number | null;
   }[];
   /** Whether this is an initial snapshot. */
-  isSnapshot?: true | undefined;
+  isSnapshot?: true;
 };
 
 // ============================================================

package/src/signing/_abstractWallet.ts

@@ -195,9 +195,16 @@ export async function signTypedData(args: {
 }
 
 function splitSignature(signature: `0x${string}`): Signature {
-  const r = `0x${signature.slice(2, 66)}` as const;
-  const s = `0x${signature.slice(66, 130)}` as const;
-  const v = parseInt(signature.slice(130, 132), 16) as 27 | 28;
+  if (signature.length !== 132) {
+    throw new AbstractWalletError(`Expected 65-byte signature (132 hex chars), got ${signature.length}`);
+  }
+  const r = `0x${signature.slice(2, 66)}` as `0x${string}`;
+  const s = `0x${signature.slice(66, 130)}` as `0x${string}`;
+  let v = parseInt(signature.slice(130, 132), 16);
+  if (v === 0 || v === 1) v += 27;
+  if (v !== 27 && v !== 28) {
+    throw new AbstractWalletError(`Invalid signature recovery value: ${v}, expected 27 or 28`);
+  }
   return { r, s, v };
 }
 
@@ -248,6 +255,7 @@ export async function getWalletAddress(wallet: AbstractWallet): Promise<`0x${str
     // Viem JSON-RPC account uses getAddresses()
     if (isViemJsonRpcAccount(wallet)) {
       const addresses = await wallet.getAddresses() as `0x${string}`[];
+      if (!addresses.length) throw new AbstractWalletError("Wallet returned no addresses");
       return addresses[0].toLowerCase() as `0x${string}`;
     }
 

package/src/transport/websocket/_postRequest.ts

@@ -3,6 +3,10 @@ import { TransportError } from "../_base.js";
 import { AbortSignal_, Promise_ } from "../_polyfills.js";
 import type { HyperliquidEventTarget } from "./_hyperliquidEventTarget.js";
 
+// ============================================================
+// Request Types
+// ============================================================
+
 interface PostRequest {
   method: "post";
   id: number;
@@ -24,6 +28,10 @@ interface PendingRequest {
   reject: (reason?: any) => void;
 }
 
+// ============================================================
+// Error Classes
+// ============================================================
+
 /** Error thrown when a WebSocket request fails. */
 export class WebSocketRequestError extends TransportError {
   constructor(message?: string, options?: ErrorOptions) {
@@ -32,6 +40,10 @@ export class WebSocketRequestError extends TransportError {
   }
 }
 
+// ============================================================
+// Post Request Manager
+// ============================================================
+
 /**
  * Manages WebSocket post requests to the Hyperliquid API.
  * Handles request creation, sending, and mapping responses to their corresponding requests.
@@ -232,6 +244,10 @@ export class WebSocketPostRequest {
   }
 }
 
+// ============================================================
+// Helpers
+// ============================================================
+
 function recursiveSortObjectKeys<T>(obj: T): T {
   if (Array.isArray(obj)) {
     return obj.map(recursiveSortObjectKeys) as T;

package/src/utils/_format.ts

@@ -173,7 +173,7 @@ const StringMath = {
   },
 };
 
-function formatDecimalString(value: string): string {
+export function formatDecimalString(value: string): string {
   return value
     // remove leading/trailing whitespace
     .trim() // "  123.45  " → "123.45"

package/src/utils/mod.ts

@@ -24,4 +24,4 @@
  */
 
 export * from "./_symbolConverter.js";
-export * from "./_format.js";
+export { formatPrice, formatSize } from "./_format.js";