From eb6947d60c1bf246b2f10597aa3c01d15146afe0 Mon Sep 17 00:00:00 2001 From: "JJ-Cro (Codex)" Date: Mon, 16 Nov 2026 12:14:41 +0100 Subject: [PATCH 1/2] feat(v1.0.4): expose node error codes and additional order status - Add support for the insufficientWeiCanceled order status. - Expose numeric Hyperliquid node errors as exchangeCode while preserving messages, responses and Axios codes. - Release SDK version 1.0.4 and update the Node.js pin to v24.22.3. --- .nvmrc | 2 +- package-lock.json | 4 ++-- package.json | 2 +- src/lib/BaseRestClient.ts | 16 ++++++++++++---- src/lib/errors.ts | 5 +++++ src/types/response/info.types.ts | 2 ++ 6 files changed, 23 insertions(+), 8 deletions(-) diff --git a/.nvmrc b/.nvmrc index 5bcf9c6..22fbfc0 100644 --- a/.nvmrc +++ b/.nvmrc @@ -1 +1 @@ -v24.18.0 +v24.22.3 diff --git a/package-lock.json b/package-lock.json index 82e9045..09ae435 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1,12 +1,12 @@ { "name": "@siebly/hyperliquid-api", - "version": "1.0.3", + "version": "1.0.4", "lockfileVersion": 3, "requires": true, "packages": { "": { "name": "@siebly/hyperliquid-api", - "version": "1.0.3", + "version": "1.0.4", "license": "MIT", "dependencies": { "@msgpack/msgpack": "^3.1.2", diff --git a/package.json b/package.json index 95c4246..8922ff6 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "@siebly/hyperliquid-api", - "version": "1.0.3", + "version": "1.0.4", "description": "Professional JavaScript & Node.js SDK for Hyperliquid's REST APIs and WebSockets, built in TypeScript with strong end to end tests.", "scripts": { "clean": "node scripts/clean.mjs", diff --git a/src/lib/BaseRestClient.ts b/src/lib/BaseRestClient.ts index b579b7f..115101c 100644 --- a/src/lib/BaseRestClient.ts +++ b/src/lib/BaseRestClient.ts @@ -228,10 +228,18 @@ export abstract class BaseRestClient { const response = await this.axios.post(path, body); if (isHyperliquidErrorResponse(response.data)) { - throw new HyperliquidApiError( - response.data.response || 'Hyperliquid rejected the request.', - { response: response.data, status: response.status }, - ); + const message = + response.data.response || 'Hyperliquid rejected the request.'; + const exchangeCode = /Unexpected error \(code=(\d+)\)/.exec( + message, + )?.[1]; + + throw new HyperliquidApiError(message, { + exchangeCode: + exchangeCode === undefined ? undefined : Number(exchangeCode), + response: response.data, + status: response.status, + }); } return response.data; diff --git a/src/lib/errors.ts b/src/lib/errors.ts index dba50df..bcf0a1e 100644 --- a/src/lib/errors.ts +++ b/src/lib/errors.ts @@ -1,6 +1,7 @@ export interface HyperliquidApiErrorOptions { cause?: unknown; code?: string | undefined; + exchangeCode?: number | undefined; response?: unknown; status?: number | undefined; } @@ -8,6 +9,9 @@ export interface HyperliquidApiErrorOptions { export class HyperliquidApiError extends Error { readonly code: string | undefined; + /** Numeric error code reported by the Hyperliquid node in "Unexpected error (code=N)" messages. */ + readonly exchangeCode?: number | undefined; + readonly response?: unknown; readonly status: number | undefined; @@ -16,6 +20,7 @@ export class HyperliquidApiError extends Error { super(message, { cause: options.cause }); this.name = 'HyperliquidApiError'; this.code = options.code; + this.exchangeCode = options.exchangeCode; this.response = options.response; this.status = options.status; } diff --git a/src/types/response/info.types.ts b/src/types/response/info.types.ts index a185475..37a6d9f 100644 --- a/src/types/response/info.types.ts +++ b/src/types/response/info.types.ts @@ -254,6 +254,8 @@ export type OrderState = | 'delistedCanceled' | 'filled' | 'insufficientSpotBalanceRejected' + /** Returned by Hyperliquid, not yet in their docs. */ + | 'insufficientWeiCanceled' | 'internalCancel' | 'iocCancelRejected' | 'liquidatedCanceled' From 5250f8adc36fb273332164b999ece17b002c5341 Mon Sep 17 00:00:00 2001 From: JJ-Cro sync bot Date: Mon, 16 Nov 2026 13:08:06 +0100 Subject: [PATCH 2/2] chore: regenerate endpoint docs and examples --- llms.txt | 268 ++++++++++++++++++++++++++++--------------------------- 1 file changed, 136 insertions(+), 132 deletions(-) diff --git a/llms.txt b/llms.txt index 45bf15a..7dbebb2 100644 --- a/llms.txt +++ b/llms.txt @@ -245,11 +245,6 @@ File: .npmrc ================ min-release-age=30 -================ -File: .nvmrc -================ -v24.18.0 - ================ File: .prettierrc ================ @@ -989,6 +984,11 @@ export interface L1ActionOptions { vaultAddress?: string | null; } +================ +File: .nvmrc +================ +v24.22.3 + ================ File: tsconfig.extensions.json ================ @@ -3740,6 +3740,132 @@ examples/tstests localtest.sh rest-ts.ts +================ +File: src/WebsocketClient.ts +================ +import { inflateSync, strFromU8 } from 'fflate'; +⋮---- +import { MAINNET_WS_URL, TESTNET_WS_URL } from './constants.js'; +import type { ResolvedAsset } from './lib/asset-resolver.js'; +import { + BaseWebsocketClient, + type EmittableEvent, + type WSOperation, +} from './lib/BaseWSClient.js'; +import { HyperliquidApiError } from './lib/errors.js'; +import { normalizeAddresses } from './lib/normalize-addresses.js'; +import { HyperliquidWebSocketError } from './lib/websocket/errors.js'; +import { + DefaultLogger, + type DefaultLogger as Logger, +} from './lib/websocket/logger.js'; +import { sanitizeObjectForWire } from './lib/wire.js'; +import { RestClient } from './RestClient.js'; +import type { ExchangeResponse } from './types/response/exchange.types.js'; +import type { RequestOptions } from './types/shared.types.js'; +import type { + WebsocketMessageEvent, + WebsocketPostResponseEvent, + WebsocketResponseEvent, +} from './types/websockets/ws-events.js'; +import type { + WebsocketClientOptions, + WsKey, +} from './types/websockets/ws-general.js'; +import type { WebsocketSubscription } from './types/websockets/ws-subscriptions.js'; +⋮---- +function normalizeSubscriptionFields( + subscription: WebsocketSubscription, +): WebsocketSubscription +⋮---- +function recordValue(value: unknown): Record | undefined +⋮---- +function postErrorRequestId(message: string): number | undefined +⋮---- +function decompressFastAssetCtxs(data: unknown): unknown +⋮---- +export class WebsocketClient extends BaseWebsocketClient< +⋮---- +constructor( + options: WebsocketClientOptions = {}, + logger: Logger = DefaultLogger, + ) +⋮---- +connect(wsKey: WsKey = 'public'): Promise +⋮---- +/** Connect all cached connection groups, or the public connection if none exist. */ +async connectAll(): Promise +⋮---- +isConnected(wsKey: WsKey = 'public'): boolean +⋮---- +/** Reject pending work immediately; emit 'close' when the socket confirms closure. */ +close(wsKey?: WsKey): void +⋮---- +/** + * Subscribe to one or more wire topics. Listen for data with on('message'). + * Topics are cached before connecting and restored automatically after reconnect. + * The promise confirms local sending; server acknowledgements emit 'response'. + * Resolve display aliases explicitly with nameToCoin() when needed. + */ +async subscribe( + subscriptions: WebsocketSubscription | readonly WebsocketSubscription[], + ): Promise +⋮---- +/** Remove cached topics independently of event listeners, including while disconnected. */ +async unsubscribe( + subscriptions: WebsocketSubscription | readonly WebsocketSubscription[], + ): Promise +⋮---- +async sendWSAPIRequest( + endpoint: 'action' | 'info', + body: unknown, + options: RequestOptions = {}, + ): Promise +⋮---- +resolveAsset(identifier: number | string): Promise +⋮---- +nameToCoin(name: string): Promise +⋮---- +refreshAssetMetadata(): Promise +⋮---- +private groupSubscriptions( + subscriptions: WebsocketSubscription | readonly WebsocketSubscription[], + ): Map +⋮---- +protected override getWsUrl(): string +⋮---- +protected override getMaxConnections(): number +⋮---- +protected override getWsRequestEvents( + _wsKey: WsKey, + operation: WSOperation, + topics: WebsocketSubscription[], + ): object[] +⋮---- +protected override sendPingEvent(wsKey: WsKey): boolean +⋮---- +protected override resolveEmittableEvents( + wsKey: WsKey, + message: string, + ): EmittableEvent[] +⋮---- +// Emit each wire message once. Subscription ownership never controls listeners. +// Keep upstream channel names (including user and activeSpotAssetCtx) unchanged. +⋮---- +private handlePostMessage( + record: Record, + ): 'exception' | 'response' +⋮---- +private logUnmatchedResponse( + requestId: unknown, + parsed: Record, + ): void +⋮---- +// IDs are monotonic for this client. A known ID without a pending promise has +// already settled (for example by timeout or abort); its late reply is expected. +⋮---- +private rejectRequest(id: number, error: unknown): void + ================ File: src/types/response/info.types.ts ================ @@ -4001,6 +4127,8 @@ export type OrderState = | 'delistedCanceled' | 'filled' | 'insufficientSpotBalanceRejected' + /** Returned by Hyperliquid, not yet in their docs. */ + | 'insufficientWeiCanceled' | 'internalCancel' | 'iocCancelRejected' | 'liquidatedCanceled' @@ -4028,6 +4156,8 @@ export type OrderState = | 'triggered' | 'vaultWithdrawalCanceled'; ⋮---- +/** Returned by Hyperliquid, not yet in their docs. */ +⋮---- export interface OrderStatusDetails { order: FrontendOpenOrder; status: OrderState; @@ -4880,132 +5010,6 @@ export interface WebData2 { user: string; } -================ -File: src/WebsocketClient.ts -================ -import { inflateSync, strFromU8 } from 'fflate'; -⋮---- -import { MAINNET_WS_URL, TESTNET_WS_URL } from './constants.js'; -import type { ResolvedAsset } from './lib/asset-resolver.js'; -import { - BaseWebsocketClient, - type EmittableEvent, - type WSOperation, -} from './lib/BaseWSClient.js'; -import { HyperliquidApiError } from './lib/errors.js'; -import { normalizeAddresses } from './lib/normalize-addresses.js'; -import { HyperliquidWebSocketError } from './lib/websocket/errors.js'; -import { - DefaultLogger, - type DefaultLogger as Logger, -} from './lib/websocket/logger.js'; -import { sanitizeObjectForWire } from './lib/wire.js'; -import { RestClient } from './RestClient.js'; -import type { ExchangeResponse } from './types/response/exchange.types.js'; -import type { RequestOptions } from './types/shared.types.js'; -import type { - WebsocketMessageEvent, - WebsocketPostResponseEvent, - WebsocketResponseEvent, -} from './types/websockets/ws-events.js'; -import type { - WebsocketClientOptions, - WsKey, -} from './types/websockets/ws-general.js'; -import type { WebsocketSubscription } from './types/websockets/ws-subscriptions.js'; -⋮---- -function normalizeSubscriptionFields( - subscription: WebsocketSubscription, -): WebsocketSubscription -⋮---- -function recordValue(value: unknown): Record | undefined -⋮---- -function postErrorRequestId(message: string): number | undefined -⋮---- -function decompressFastAssetCtxs(data: unknown): unknown -⋮---- -export class WebsocketClient extends BaseWebsocketClient< -⋮---- -constructor( - options: WebsocketClientOptions = {}, - logger: Logger = DefaultLogger, - ) -⋮---- -connect(wsKey: WsKey = 'public'): Promise -⋮---- -/** Connect all cached connection groups, or the public connection if none exist. */ -async connectAll(): Promise -⋮---- -isConnected(wsKey: WsKey = 'public'): boolean -⋮---- -/** Reject pending work immediately; emit 'close' when the socket confirms closure. */ -close(wsKey?: WsKey): void -⋮---- -/** - * Subscribe to one or more wire topics. Listen for data with on('message'). - * Topics are cached before connecting and restored automatically after reconnect. - * The promise confirms local sending; server acknowledgements emit 'response'. - * Resolve display aliases explicitly with nameToCoin() when needed. - */ -async subscribe( - subscriptions: WebsocketSubscription | readonly WebsocketSubscription[], - ): Promise -⋮---- -/** Remove cached topics independently of event listeners, including while disconnected. */ -async unsubscribe( - subscriptions: WebsocketSubscription | readonly WebsocketSubscription[], - ): Promise -⋮---- -async sendWSAPIRequest( - endpoint: 'action' | 'info', - body: unknown, - options: RequestOptions = {}, - ): Promise -⋮---- -resolveAsset(identifier: number | string): Promise -⋮---- -nameToCoin(name: string): Promise -⋮---- -refreshAssetMetadata(): Promise -⋮---- -private groupSubscriptions( - subscriptions: WebsocketSubscription | readonly WebsocketSubscription[], - ): Map -⋮---- -protected override getWsUrl(): string -⋮---- -protected override getMaxConnections(): number -⋮---- -protected override getWsRequestEvents( - _wsKey: WsKey, - operation: WSOperation, - topics: WebsocketSubscription[], - ): object[] -⋮---- -protected override sendPingEvent(wsKey: WsKey): boolean -⋮---- -protected override resolveEmittableEvents( - wsKey: WsKey, - message: string, - ): EmittableEvent[] -⋮---- -// Emit each wire message once. Subscription ownership never controls listeners. -// Keep upstream channel names (including user and activeSpotAssetCtx) unchanged. -⋮---- -private handlePostMessage( - record: Record, - ): 'exception' | 'response' -⋮---- -private logUnmatchedResponse( - requestId: unknown, - parsed: Record, - ): void -⋮---- -// IDs are monotonic for this client. A known ID without a pending promise has -// already settled (for example by timeout or abort); its late reply is expected. -⋮---- -private rejectRequest(id: number, error: unknown): void - ================ File: src/RestClient.ts ================ @@ -6186,7 +6190,7 @@ File: package.json ================ { "name": "@siebly/hyperliquid-api", - "version": "1.0.3", + "version": "1.0.4", "description": "Professional JavaScript & Node.js SDK for Hyperliquid's REST APIs and WebSockets, built in TypeScript with strong end to end tests.", "scripts": { "clean": "node scripts/clean.mjs",