@deeeed/hyperliquid-node20
Version:
Unofficial Hyperliquid API SDK for all major JS runtimes, written in TypeScript. Fork with Node.js 20.18.0+ compatibility.
580 lines (579 loc) • 21.6 kB
JavaScript
;
Object.defineProperty(exports, "__esModule", { value: true });
exports.SubscriptionClient = void 0;
/**
* Subscription client for subscribing to various Hyperliquid events.
* @typeParam T The type of transport used to connect to the Hyperliquid Websocket API.
*/
class SubscriptionClient {
transport;
/**
* Initialises a new instance.
* @param args - The arguments for initialisation.
*
* @example
* ```ts
* import * as hl from "@nktkas/hyperliquid";
*
* const transport = new hl.WebSocketTransport();
* const subsClient = new hl.SubscriptionClient({ transport });
* ```
*/
constructor(args) {
this.transport = args.transport;
}
/**
* Subscribe to context updates for a specific perpetual asset.
* @param args - The parameters for the subscription.
* @param listener - The callback function to be called when the event is received.
* @returns A promise that resolves with a {@link Subscription} object to manage the subscription lifecycle.
*
* @throws {TransportError} When the transport layer throws an error.
*
* @see https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/websocket/subscriptions
* @example
* ```ts
* import * as hl from "@nktkas/hyperliquid";
*
* const transport = new hl.WebSocketTransport();
* const subsClient = new hl.SubscriptionClient({ transport });
*
* const sub = await subsClient.activeAssetCtx({ coin: "BTC" }, (data) => {
* console.log(data);
* });
* ```
*/
activeAssetCtx(args, listener) {
const channel = args.coin.startsWith("@") ? "activeSpotAssetCtx" : "activeAssetCtx";
const payload = {
type: "activeAssetCtx",
coin: args.coin,
};
return this.transport.subscribe(channel, payload, (e) => {
if (e.detail.coin === args.coin) {
listener(e.detail);
}
});
}
/**
* Subscribe to trading data updates for a specific asset and user.
* @param args - The parameters for the subscription.
* @param listener - The callback function to be called when the event is received.
* @returns A promise that resolves with a {@link Subscription} object to manage the subscription lifecycle.
*
* @throws {TransportError} When the transport layer throws an error.
*
* @see https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/websocket/subscriptions
* @example
* ```ts
* import * as hl from "@nktkas/hyperliquid";
*
* const transport = new hl.WebSocketTransport();
* const subsClient = new hl.SubscriptionClient({ transport });
*
* const sub = await subsClient.activeAssetData({ coin: "BTC", user: "0x..." }, (data) => {
* console.log(data);
* });
* ```
*/
activeAssetData(args, listener) {
const payload = {
type: "activeAssetData",
coin: args.coin,
user: args.user,
};
return this.transport.subscribe(payload.type, payload, (e) => {
if (e.detail.coin === args.coin && e.detail.user === args.user.toLowerCase()) {
listener(e.detail);
}
});
}
allMids(args_or_listener, maybeListener) {
const args = typeof args_or_listener === "function" ? {} : args_or_listener;
const listener = typeof args_or_listener === "function" ? args_or_listener : maybeListener;
const payload = {
type: "allMids",
dex: args.dex,
};
return this.transport.subscribe(payload.type, payload, (e) => {
listener(e.detail);
});
}
/**
* Subscribe to best bid and offer updates for a specific asset.
* @param args - The parameters for the subscription.
* @param listener - The callback function to be called when the event is received.
* @returns A promise that resolves with a {@link Subscription} object to manage the subscription lifecycle.
*
* @throws {TransportError} When the transport layer throws an error.
*
* @see https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/websocket/subscriptions
* @example
* ```ts
* import * as hl from "@nktkas/hyperliquid";
*
* const transport = new hl.WebSocketTransport();
* const subsClient = new hl.SubscriptionClient({ transport });
*
* const sub = await subsClient.bbo({ coin: "BTC" }, (data) => {
* console.log(data);
* });
* ```
*/
bbo(args, listener) {
const payload = {
type: "bbo",
coin: args.coin,
};
return this.transport.subscribe(payload.type, payload, (e) => {
if (e.detail.coin === args.coin) {
listener(e.detail);
}
});
}
/**
* Subscribe to candlestick data updates for a specific asset.
* @param args - The parameters for the subscription.
* @param listener - The callback function to be called when the event is received.
* @returns A promise that resolves with a {@link Subscription} object to manage the subscription lifecycle.
*
* @throws {TransportError} When the transport layer throws an error.
*
* @see https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/websocket/subscriptions
* @example
* ```ts
* import * as hl from "@nktkas/hyperliquid";
*
* const transport = new hl.WebSocketTransport();
* const subsClient = new hl.SubscriptionClient({ transport });
*
* const sub = await subsClient.candle({ coin: "BTC", interval: "1h" }, (data) => {
* console.log(data);
* });
* ```
*/
candle(args, listener) {
const payload = {
type: "candle",
coin: args.coin,
interval: args.interval,
};
return this.transport.subscribe(payload.type, payload, (e) => {
if (e.detail.s === args.coin && e.detail.i === args.interval) {
listener(e.detail);
}
});
}
/**
* Subscribe to explorer block updates.
* @param listener - The callback function to be called when the event is received.
* @returns A promise that resolves with a {@link Subscription} object to manage the subscription lifecycle.
* @note Make sure the endpoint in the {@link transport} supports this method.
*
* @throws {TransportError} When the transport layer throws an error.
*
* @see null
* @example
* ```ts
* import * as hl from "@nktkas/hyperliquid";
*
* const transport = new hl.WebSocketTransport();
* const subsClient = new hl.SubscriptionClient({ transport });
*
* const sub = await subsClient.explorerBlock((data) => {
* console.log(data);
* });
* ```
*/
explorerBlock(listener) {
const payload = {
type: "explorerBlock",
};
return this.transport.subscribe("_explorerBlock", payload, (e) => {
listener(e.detail);
});
}
/**
* Subscribe to explorer transaction updates.
* @param listener - The callback function to be called when the event is received.
* @returns A promise that resolves with a {@link Subscription} object to manage the subscription lifecycle.
* @note Make sure the endpoint in the {@link transport} supports this method.
*
* @throws {TransportError} When the transport layer throws an error.
*
* @see null
* @example
* ```ts
* import * as hl from "@nktkas/hyperliquid";
*
* const transport = new hl.WebSocketTransport();
* const subsClient = new hl.SubscriptionClient({ transport });
*
* const sub = await subsClient.explorerTxs((data) => {
* console.log(data);
* });
* ```
*/
explorerTxs(listener) {
const payload = {
type: "explorerTxs",
};
return this.transport.subscribe("_explorerTxs", payload, (e) => {
listener(e.detail);
});
}
/**
* Subscribe to L2 order book updates for a specific asset.
* @param args - The parameters for the subscription.
* @param listener - The callback function to be called when the event is received.
* @returns A promise that resolves with a {@link Subscription} object to manage the subscription lifecycle.
*
* @throws {TransportError} When the transport layer throws an error.
*
* @see https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/websocket/subscriptions
* @example
* ```ts
* import * as hl from "@nktkas/hyperliquid";
*
* const transport = new hl.WebSocketTransport();
* const subsClient = new hl.SubscriptionClient({ transport });
*
* const sub = await subsClient.l2Book({ coin: "BTC" }, (data) => {
* console.log(data);
* });
* ```
*/
l2Book(args, listener) {
const payload = {
type: "l2Book",
coin: args.coin,
nSigFigs: args.nSigFigs ?? null,
mantissa: args.mantissa ?? null,
};
return this.transport.subscribe(payload.type, payload, (e) => {
if (e.detail.coin === args.coin) {
listener(e.detail);
}
});
}
/**
* Subscribe to notification updates for a specific user.
* @param args - The parameters for the subscription.
* @param listener - The callback function to be called when the event is received.
* @returns A promise that resolves with a {@link Subscription} object to manage the subscription lifecycle.
*
* @throws {TransportError} When the transport layer throws an error.
*
* @see https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/websocket/subscriptions
* @example
* ```ts
* import * as hl from "@nktkas/hyperliquid";
*
* const transport = new hl.WebSocketTransport();
* const subsClient = new hl.SubscriptionClient({ transport });
*
* const sub = await subsClient.notification({ user: "0x..." }, (data) => {
* console.log(data);
* });
* ```
*/
notification(args, listener) {
const payload = {
type: "notification",
user: args.user,
};
return this.transport.subscribe(payload.type, payload, (e) => {
listener(e.detail);
});
}
/**
* Subscribe to order status updates for a specific user.
* @param args - The parameters for the subscription.
* @param listener - The callback function to be called when the event is received.
* @returns A promise that resolves with a {@link Subscription} object to manage the subscription lifecycle.
*
* @throws {TransportError} When the transport layer throws an error.
*
* @see https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/websocket/subscriptions
* @example
* ```ts
* import * as hl from "@nktkas/hyperliquid";
*
* const transport = new hl.WebSocketTransport();
* const subsClient = new hl.SubscriptionClient({ transport });
*
* const sub = await subsClient.orderUpdates({ user: "0x..." }, (data) => {
* console.log(data);
* });
* ```
*/
orderUpdates(args, listener) {
const payload = {
type: "orderUpdates",
user: args.user,
};
return this.transport.subscribe(payload.type, payload, (e) => {
listener(e.detail);
});
}
/**
* Subscribe to real-time trade updates for a specific asset.
* @param args - The parameters for the subscription.
* @param listener - The callback function to be called when the event is received.
* @returns A promise that resolves with a {@link Subscription} object to manage the subscription lifecycle.
*
* @throws {TransportError} When the transport layer throws an error.
*
* @see https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/websocket/subscriptions
* @example
* ```ts
* import * as hl from "@nktkas/hyperliquid";
*
* const transport = new hl.WebSocketTransport();
* const subsClient = new hl.SubscriptionClient({ transport });
*
* const sub = await subsClient.trades({ coin: "BTC" }, (data) => {
* console.log(data);
* });
* ```
*/
trades(args, listener) {
const payload = {
type: "trades",
coin: args.coin,
};
return this.transport.subscribe(payload.type, payload, (e) => {
if (e.detail[0]?.coin === args.coin) {
listener(e.detail);
}
});
}
/**
* Subscribe to non-order events for a specific user.
* @param args - The parameters for the subscription.
* @param listener - The callback function to be called when the event is received.
* @returns A promise that resolves with a {@link Subscription} object to manage the subscription lifecycle.
* @note Different subscriptions cannot be distinguished from each other.
*
* @throws {TransportError} When the transport layer throws an error.
*
* @see https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/websocket/subscriptions
* @example
* ```ts
* import * as hl from "@nktkas/hyperliquid";
*
* const transport = new hl.WebSocketTransport();
* const subsClient = new hl.SubscriptionClient({ transport });
*
* const sub = await subsClient.userEvents({ user: "0x..." }, (data) => {
* console.log(data);
* });
* ```
*/
userEvents(args, listener) {
const payload = {
type: "userEvents",
user: args.user,
};
return this.transport.subscribe("user", payload, (e) => {
listener(e.detail);
});
}
/**
* Subscribe to trade fill updates for a specific user.
* @param args - The parameters for the subscription.
* @param listener - The callback function to be called when the event is received.
* @returns A promise that resolves with a {@link Subscription} object to manage the subscription lifecycle.
*
* @throws {TransportError} When the transport layer throws an error.
*
* @see https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/websocket/subscriptions
* @example
* ```ts
* import * as hl from "@nktkas/hyperliquid";
*
* const transport = new hl.WebSocketTransport();
* const subsClient = new hl.SubscriptionClient({ transport });
*
* const sub = await subsClient.userFills({ user: "0x..." }, (data) => {
* console.log(data);
* });
* ```
*/
userFills(args, listener) {
const payload = {
type: "userFills",
user: args.user,
aggregateByTime: args.aggregateByTime ?? false,
};
return this.transport.subscribe(payload.type, payload, (e) => {
if (e.detail.user === args.user.toLowerCase()) {
listener(e.detail);
}
});
}
/**
* Subscribe to funding payment updates for a specific user.
* @param args - The parameters for the subscription.
* @param listener - The callback function to be called when the event is received.
* @returns A promise that resolves with a {@link Subscription} object to manage the subscription lifecycle.
*
* @throws {TransportError} When the transport layer throws an error.
*
* @see https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/websocket/subscriptions
* @example
* ```ts
* import * as hl from "@nktkas/hyperliquid";
*
* const transport = new hl.WebSocketTransport();
* const subsClient = new hl.SubscriptionClient({ transport });
*
* const sub = await subsClient.userFundings({ user: "0x..." }, (data) => {
* console.log(data);
* });
* ```
*/
userFundings(args, listener) {
const payload = {
type: "userFundings",
user: args.user,
};
return this.transport.subscribe(payload.type, payload, (e) => {
if (e.detail.user === args.user.toLowerCase()) {
listener(e.detail);
}
});
}
/**
* Subscribe to non-funding ledger updates for a specific user.
* @param args - The parameters for the subscription.
* @param listener - The callback function to be called when the event is received.
* @returns A promise that resolves with a {@link Subscription} object to manage the subscription lifecycle.
*
* @throws {TransportError} When the transport layer throws an error.
*
* @see https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/websocket/subscriptions
* @example
* ```ts
* import * as hl from "@nktkas/hyperliquid";
*
* const transport = new hl.WebSocketTransport();
* const subsClient = new hl.SubscriptionClient({ transport });
*
* const sub = await subsClient.userNonFundingLedgerUpdates({ user: "0x..." }, (data) => {
* console.log(data);
* });
* ```
*/
userNonFundingLedgerUpdates(args, listener) {
const payload = {
type: "userNonFundingLedgerUpdates",
user: args.user,
};
return this.transport.subscribe(payload.type, payload, (e) => {
if (e.detail.user === args.user.toLowerCase()) {
listener(e.detail);
}
});
}
/**
* Subscribe to TWAP order history updates for a specific user.
* @param args - The parameters for the subscription.
* @param listener - The callback function to be called when the event is received.
* @returns A promise that resolves with a {@link Subscription} object to manage the subscription lifecycle.
*
* @throws {TransportError} When the transport layer throws an error.
*
* @see https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/websocket/subscriptions
* @example
* ```ts
* import * as hl from "@nktkas/hyperliquid";
*
* const transport = new hl.WebSocketTransport();
* const subsClient = new hl.SubscriptionClient({ transport });
*
* const sub = await subsClient.userTwapHistory({ user: "0x..." }, (data) => {
* console.log(data);
* });
* ```
*/
userTwapHistory(args, listener) {
const payload = {
type: "userTwapHistory",
user: args.user,
};
return this.transport.subscribe(payload.type, payload, (e) => {
if (e.detail.user === args.user.toLowerCase()) {
listener(e.detail);
}
});
}
/**
* Subscribe to TWAP execution updates for a specific user.
* @param args - The parameters for the subscription.
* @param listener - The callback function to be called when the event is received.
* @returns A promise that resolves with a {@link Subscription} object to manage the subscription lifecycle.
*
* @throws {TransportError} When the transport layer throws an error.
*
* @see https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/websocket/subscriptions
* @example
* ```ts
* import * as hl from "@nktkas/hyperliquid";
*
* const transport = new hl.WebSocketTransport();
* const subsClient = new hl.SubscriptionClient({ transport });
*
* const sub = await subsClient.userTwapSliceFills({ user: "0x..." }, (data) => {
* console.log(data);
* });
* ```
*/
userTwapSliceFills(args, listener) {
const payload = {
type: "userTwapSliceFills",
user: args.user,
};
return this.transport.subscribe(payload.type, payload, (e) => {
if (e.detail.user === args.user.toLowerCase()) {
listener(e.detail);
}
});
}
/**
* Subscribe to comprehensive user and market data updates.
* @param args - The parameters for the subscription.
* @param listener - The callback function to be called when the event is received.
* @returns A promise that resolves with a {@link Subscription} object to manage the subscription lifecycle.
*
* @throws {TransportError} When the transport layer throws an error.
*
* @see https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/websocket/subscriptions
* @example
* ```ts
* import * as hl from "@nktkas/hyperliquid";
*
* const transport = new hl.WebSocketTransport();
* const subsClient = new hl.SubscriptionClient({ transport });
*
* const sub = await subsClient.webData2({ user: "0x..." }, (data) => {
* console.log(data);
* });
* ```
*/
webData2(args, listener) {
const payload = {
type: "webData2",
user: args.user,
};
return this.transport.subscribe(payload.type, payload, (e) => {
if (e.detail.user === args.user.toLowerCase()) {
listener(e.detail);
}
});
}
async [Symbol.asyncDispose]() {
await this.transport[Symbol.asyncDispose]?.();
}
}
exports.SubscriptionClient = SubscriptionClient;