@k256/sdk 0.4.0 → 0.5.0

package/dist/ws/index.d.cts

@@ -44,6 +44,16 @@ declare const MessageType: {
     readonly PoolUpdateBatch: 14;
     /** Block-level statistics (v3) */
     readonly BlockStats: 15;
+    /** Subscribe to price updates (JSON) - Client → Server */
+    readonly SubscribePrice: 16;
+    /** Single price update (bincode 56B) - Server → Client */
+    readonly PriceUpdate: 17;
+    /** Batched price updates (bincode [u16 count][entries...]) - Server → Client */
+    readonly PriceBatch: 18;
+    /** Initial price snapshot (same binary format as PriceBatch) - Server → Client */
+    readonly PriceSnapshot: 19;
+    /** Unsubscribe from prices (no payload) - Client → Server */
+    readonly UnsubscribePrice: 20;
     /** Error message (UTF-8 string) */
     readonly Error: 255;
 };
@@ -210,6 +220,38 @@ interface QuoteSubscribedMessage {
         timestampMs: number;
     };
 }
+/**
+ * Single decoded price entry (shared by PriceUpdate, PriceBatch, PriceSnapshot)
+ */
+interface PriceEntry {
+    mint: string;
+    usdPrice: number;
+    slot: number;
+    timestampMs: number;
+}
+/**
+ * Single price update from binary message (0x11)
+ * Note: K2 currently sends all updates via PriceBatch (0x12)
+ */
+interface PriceUpdateMessage {
+    type: 'price_update';
+    data: PriceEntry;
+}
+/**
+ * Batched price updates from binary message (0x12)
+ */
+interface PriceBatchMessage {
+    type: 'price_batch';
+    data: PriceEntry[];
+}
+/**
+ * Initial price snapshot from binary message (0x13)
+ * Same binary format as PriceBatch — sent once after subscribe_price
+ */
+interface PriceSnapshotMessage {
+    type: 'price_snapshot';
+    data: PriceEntry[];
+}
 /**
  * Error message from server
  */
@@ -231,7 +273,7 @@ interface PongMessage {
 /**
  * Union of all decoded message types
  */
-type DecodedMessage = PoolUpdateMessage | FeeMarketMessage | BlockStatsMessage | BlockhashMessage | QuoteMessage | HeartbeatMessage | SubscribedMessage | QuoteSubscribedMessage | ErrorMessage | PongMessage;
+type DecodedMessage = PoolUpdateMessage | FeeMarketMessage | BlockStatsMessage | BlockhashMessage | QuoteMessage | PriceUpdateMessage | PriceBatchMessage | PriceSnapshotMessage | HeartbeatMessage | SubscribedMessage | QuoteSubscribedMessage | ErrorMessage | PongMessage;
 
 /**
  * K256 WebSocket Client
@@ -327,6 +369,15 @@ interface SubscribeQuoteOptions {
     /** How often to refresh the quote (ms) */
     refreshIntervalMs?: number;
 }
+/**
+ * Price subscription options
+ */
+interface SubscribePriceOptions {
+    /** Token mint addresses to track */
+    tokens: string[];
+    /** Minimum bps change to receive an update (default 10) */
+    thresholdBps?: number;
+}
 /**
  * WebSocket client configuration
  */
@@ -387,6 +438,12 @@ interface K256WebSocketClientConfig {
     onQuoteSubscribed?: (data: DecodedMessage & {
         type: 'quote_subscribed';
     }) => void;
+    /** Called on single price update */
+    onPriceUpdate?: (message: PriceUpdateMessage) => void;
+    /** Called on batched price updates */
+    onPriceBatch?: (message: PriceBatchMessage) => void;
+    /** Called on initial price snapshot (after subscribe) */
+    onPriceSnapshot?: (message: PriceSnapshotMessage) => void;
     /** Called on heartbeat */
     onHeartbeat?: (data: DecodedMessage & {
         type: 'heartbeat';
@@ -432,6 +489,7 @@ declare class K256WebSocketClient {
     private lastHeartbeatTime;
     private pendingSubscription;
     private pendingQuoteSubscription;
+    private pendingPriceSubscription;
     private isIntentionallyClosed;
     /** Current connection state */
     get state(): ConnectionState;
@@ -466,6 +524,15 @@ declare class K256WebSocketClient {
      * @param topicId - Topic ID from quote_subscribed response
      */
     unsubscribeQuote(topicId: string): void;
+    /**
+     * Subscribe to real-time price updates
+     * @param options - Token mints and threshold configuration
+     */
+    subscribePrices(options: SubscribePriceOptions): void;
+    /**
+     * Unsubscribe from price updates
+     */
+    unsubscribePrices(): void;
     /**
      * Unsubscribe from all channels
      */
@@ -478,6 +545,7 @@ declare class K256WebSocketClient {
     private handleMessage;
     private sendSubscription;
     private sendQuoteSubscription;
+    private sendPriceSubscription;
     private setState;
     private handleError;
     private cleanup;
@@ -520,6 +588,12 @@ declare class K256WebSocketClient {
  * ```
  */
 declare function decodeMessage(data: ArrayBuffer): DecodedMessage | null;
+/**
+ * Decode price entries from a PriceBatch or PriceSnapshot payload.
+ *
+ * Wire format: [count:u16 LE][entry₁:56B]...[entryₙ:56B]
+ */
+declare function decodePriceEntries(payload: ArrayBuffer): PriceEntry[];
 /**
  * Decode a batch of pool updates
  *
@@ -541,4 +615,4 @@ declare function decodeMessage(data: ArrayBuffer): DecodedMessage | null;
  */
 declare function decodePoolUpdateBatch(payload: ArrayBuffer): PoolUpdateMessage[];
 
-export { type BlockStatsMessage, type BlockhashMessage, CloseCode, type CloseCodeValue, type ConnectionState, type DecodedMessage, type ErrorMessage, type FeeMarketMessage, type HeartbeatMessage, type K256ErrorCode, K256WebSocketClient, type K256WebSocketClientConfig, K256WebSocketError, MessageType, type MessageTypeValue, type PongMessage, type PoolUpdateMessage, type QuoteMessage, type QuoteSubscribedMessage, type SubscribeOptions, type SubscribeQuoteOptions, type SubscribedMessage, decodeMessage, decodePoolUpdateBatch };
+export { type BlockStatsMessage, type BlockhashMessage, CloseCode, type CloseCodeValue, type ConnectionState, type DecodedMessage, type ErrorMessage, type FeeMarketMessage, type HeartbeatMessage, type K256ErrorCode, K256WebSocketClient, type K256WebSocketClientConfig, K256WebSocketError, MessageType, type MessageTypeValue, type PongMessage, type PoolUpdateMessage, type PriceBatchMessage, type PriceEntry, type PriceSnapshotMessage, type PriceUpdateMessage, type QuoteMessage, type QuoteSubscribedMessage, type SubscribeOptions, type SubscribePriceOptions, type SubscribeQuoteOptions, type SubscribedMessage, decodeMessage, decodePoolUpdateBatch, decodePriceEntries };

package/dist/ws/index.d.ts

@@ -44,6 +44,16 @@ declare const MessageType: {
     readonly PoolUpdateBatch: 14;
     /** Block-level statistics (v3) */
     readonly BlockStats: 15;
+    /** Subscribe to price updates (JSON) - Client → Server */
+    readonly SubscribePrice: 16;
+    /** Single price update (bincode 56B) - Server → Client */
+    readonly PriceUpdate: 17;
+    /** Batched price updates (bincode [u16 count][entries...]) - Server → Client */
+    readonly PriceBatch: 18;
+    /** Initial price snapshot (same binary format as PriceBatch) - Server → Client */
+    readonly PriceSnapshot: 19;
+    /** Unsubscribe from prices (no payload) - Client → Server */
+    readonly UnsubscribePrice: 20;
     /** Error message (UTF-8 string) */
     readonly Error: 255;
 };
@@ -210,6 +220,38 @@ interface QuoteSubscribedMessage {
         timestampMs: number;
     };
 }
+/**
+ * Single decoded price entry (shared by PriceUpdate, PriceBatch, PriceSnapshot)
+ */
+interface PriceEntry {
+    mint: string;
+    usdPrice: number;
+    slot: number;
+    timestampMs: number;
+}
+/**
+ * Single price update from binary message (0x11)
+ * Note: K2 currently sends all updates via PriceBatch (0x12)
+ */
+interface PriceUpdateMessage {
+    type: 'price_update';
+    data: PriceEntry;
+}
+/**
+ * Batched price updates from binary message (0x12)
+ */
+interface PriceBatchMessage {
+    type: 'price_batch';
+    data: PriceEntry[];
+}
+/**
+ * Initial price snapshot from binary message (0x13)
+ * Same binary format as PriceBatch — sent once after subscribe_price
+ */
+interface PriceSnapshotMessage {
+    type: 'price_snapshot';
+    data: PriceEntry[];
+}
 /**
  * Error message from server
  */
@@ -231,7 +273,7 @@ interface PongMessage {
 /**
  * Union of all decoded message types
  */
-type DecodedMessage = PoolUpdateMessage | FeeMarketMessage | BlockStatsMessage | BlockhashMessage | QuoteMessage | HeartbeatMessage | SubscribedMessage | QuoteSubscribedMessage | ErrorMessage | PongMessage;
+type DecodedMessage = PoolUpdateMessage | FeeMarketMessage | BlockStatsMessage | BlockhashMessage | QuoteMessage | PriceUpdateMessage | PriceBatchMessage | PriceSnapshotMessage | HeartbeatMessage | SubscribedMessage | QuoteSubscribedMessage | ErrorMessage | PongMessage;
 
 /**
  * K256 WebSocket Client
@@ -327,6 +369,15 @@ interface SubscribeQuoteOptions {
     /** How often to refresh the quote (ms) */
     refreshIntervalMs?: number;
 }
+/**
+ * Price subscription options
+ */
+interface SubscribePriceOptions {
+    /** Token mint addresses to track */
+    tokens: string[];
+    /** Minimum bps change to receive an update (default 10) */
+    thresholdBps?: number;
+}
 /**
  * WebSocket client configuration
  */
@@ -387,6 +438,12 @@ interface K256WebSocketClientConfig {
     onQuoteSubscribed?: (data: DecodedMessage & {
         type: 'quote_subscribed';
     }) => void;
+    /** Called on single price update */
+    onPriceUpdate?: (message: PriceUpdateMessage) => void;
+    /** Called on batched price updates */
+    onPriceBatch?: (message: PriceBatchMessage) => void;
+    /** Called on initial price snapshot (after subscribe) */
+    onPriceSnapshot?: (message: PriceSnapshotMessage) => void;
     /** Called on heartbeat */
     onHeartbeat?: (data: DecodedMessage & {
         type: 'heartbeat';
@@ -432,6 +489,7 @@ declare class K256WebSocketClient {
     private lastHeartbeatTime;
     private pendingSubscription;
     private pendingQuoteSubscription;
+    private pendingPriceSubscription;
     private isIntentionallyClosed;
     /** Current connection state */
     get state(): ConnectionState;
@@ -466,6 +524,15 @@ declare class K256WebSocketClient {
      * @param topicId - Topic ID from quote_subscribed response
      */
     unsubscribeQuote(topicId: string): void;
+    /**
+     * Subscribe to real-time price updates
+     * @param options - Token mints and threshold configuration
+     */
+    subscribePrices(options: SubscribePriceOptions): void;
+    /**
+     * Unsubscribe from price updates
+     */
+    unsubscribePrices(): void;
     /**
      * Unsubscribe from all channels
      */
@@ -478,6 +545,7 @@ declare class K256WebSocketClient {
     private handleMessage;
     private sendSubscription;
     private sendQuoteSubscription;
+    private sendPriceSubscription;
     private setState;
     private handleError;
     private cleanup;
@@ -520,6 +588,12 @@ declare class K256WebSocketClient {
  * ```
  */
 declare function decodeMessage(data: ArrayBuffer): DecodedMessage | null;
+/**
+ * Decode price entries from a PriceBatch or PriceSnapshot payload.
+ *
+ * Wire format: [count:u16 LE][entry₁:56B]...[entryₙ:56B]
+ */
+declare function decodePriceEntries(payload: ArrayBuffer): PriceEntry[];
 /**
  * Decode a batch of pool updates
  *
@@ -541,4 +615,4 @@ declare function decodeMessage(data: ArrayBuffer): DecodedMessage | null;
  */
 declare function decodePoolUpdateBatch(payload: ArrayBuffer): PoolUpdateMessage[];
 
-export { type BlockStatsMessage, type BlockhashMessage, CloseCode, type CloseCodeValue, type ConnectionState, type DecodedMessage, type ErrorMessage, type FeeMarketMessage, type HeartbeatMessage, type K256ErrorCode, K256WebSocketClient, type K256WebSocketClientConfig, K256WebSocketError, MessageType, type MessageTypeValue, type PongMessage, type PoolUpdateMessage, type QuoteMessage, type QuoteSubscribedMessage, type SubscribeOptions, type SubscribeQuoteOptions, type SubscribedMessage, decodeMessage, decodePoolUpdateBatch };
+export { type BlockStatsMessage, type BlockhashMessage, CloseCode, type CloseCodeValue, type ConnectionState, type DecodedMessage, type ErrorMessage, type FeeMarketMessage, type HeartbeatMessage, type K256ErrorCode, K256WebSocketClient, type K256WebSocketClientConfig, K256WebSocketError, MessageType, type MessageTypeValue, type PongMessage, type PoolUpdateMessage, type PriceBatchMessage, type PriceEntry, type PriceSnapshotMessage, type PriceUpdateMessage, type QuoteMessage, type QuoteSubscribedMessage, type SubscribeOptions, type SubscribePriceOptions, type SubscribeQuoteOptions, type SubscribedMessage, decodeMessage, decodePoolUpdateBatch, decodePriceEntries };

package/dist/ws/index.js

@@ -53,6 +53,16 @@ var MessageType = {
   PoolUpdateBatch: 14,
   /** Block-level statistics (v3) */
   BlockStats: 15,
+  /** Subscribe to price updates (JSON) - Client → Server */
+  SubscribePrice: 16,
+  /** Single price update (bincode 56B) - Server → Client */
+  PriceUpdate: 17,
+  /** Batched price updates (bincode [u16 count][entries...]) - Server → Client */
+  PriceBatch: 18,
+  /** Initial price snapshot (same binary format as PriceBatch) - Server → Client */
+  PriceSnapshot: 19,
+  /** Unsubscribe from prices (no payload) - Client → Server */
+  UnsubscribePrice: 20,
   /** Error message (UTF-8 string) */
   Error: 255
 };
@@ -251,10 +261,48 @@ function decodeMessage(data) {
         receivedAt: Date.now()
       };
     }
+    case MessageType.PriceUpdate: {
+      if (payload.byteLength < 56) return null;
+      const mintBytes = new Uint8Array(payload, 0, 32);
+      return {
+        type: "price_update",
+        data: {
+          mint: base58Encode(mintBytes),
+          usdPrice: Number(payloadView.getBigUint64(32, true)) / 1e12,
+          slot: Number(payloadView.getBigUint64(40, true)),
+          timestampMs: Number(payloadView.getBigUint64(48, true))
+        }
+      };
+    }
+    case MessageType.PriceBatch:
+    case MessageType.PriceSnapshot: {
+      if (payload.byteLength < 2) return null;
+      const entries = decodePriceEntries(payload);
+      const priceType = msgType === MessageType.PriceSnapshot ? "price_snapshot" : "price_batch";
+      return { type: priceType, data: entries };
+    }
     default:
       return null;
   }
 }
+function decodePriceEntries(payload) {
+  const view = new DataView(payload);
+  if (payload.byteLength < 2) return [];
+  const count = view.getUint16(0, true);
+  const entries = [];
+  let offset = 2;
+  for (let i = 0; i < count && offset + 56 <= payload.byteLength; i++) {
+    const mintBytes = new Uint8Array(payload, offset, 32);
+    entries.push({
+      mint: base58Encode(mintBytes),
+      usdPrice: Number(view.getBigUint64(offset + 32, true)) / 1e12,
+      slot: Number(view.getBigUint64(offset + 40, true)),
+      timestampMs: Number(view.getBigUint64(offset + 48, true))
+    });
+    offset += 56;
+  }
+  return entries;
+}
 function decodePoolUpdateBatch(payload) {
   const view = new DataView(payload);
   if (payload.byteLength < 2) return [];
@@ -477,6 +525,7 @@ var K256WebSocketClient = class {
   lastHeartbeatTime = 0;
   pendingSubscription = null;
   pendingQuoteSubscription = null;
+  pendingPriceSubscription = null;
   isIntentionallyClosed = false;
   /** Current connection state */
   get state() {
@@ -566,12 +615,33 @@ var K256WebSocketClient = class {
     const msg = JSON.stringify({ type: "unsubscribe_quote", topicId });
     this.ws?.send(msg);
   }
+  /**
+   * Subscribe to real-time price updates
+   * @param options - Token mints and threshold configuration
+   */
+  subscribePrices(options) {
+    this.pendingPriceSubscription = options;
+    if (!this.isConnected) {
+      return;
+    }
+    this.sendPriceSubscription(options);
+  }
+  /**
+   * Unsubscribe from price updates
+   */
+  unsubscribePrices() {
+    this.pendingPriceSubscription = null;
+    if (!this.isConnected) return;
+    const buf = new Uint8Array([MessageType.UnsubscribePrice]);
+    this.ws?.send(buf);
+  }
   /**
    * Unsubscribe from all channels
    */
   unsubscribe() {
     this.pendingSubscription = null;
     this.pendingQuoteSubscription = null;
+    this.pendingPriceSubscription = null;
     if (!this.isConnected) return;
     this.ws?.send(JSON.stringify({ type: "unsubscribe" }));
   }
@@ -622,6 +692,9 @@ var K256WebSocketClient = class {
           if (this.pendingQuoteSubscription) {
             this.sendQuoteSubscription(this.pendingQuoteSubscription);
           }
+          if (this.pendingPriceSubscription) {
+            this.sendPriceSubscription(this.pendingPriceSubscription);
+          }
           this.config.onConnect?.();
           resolve();
         };
@@ -721,6 +794,21 @@ var K256WebSocketClient = class {
         case "quote_subscribed":
           this.config.onQuoteSubscribed?.(decoded);
           break;
+        case "price_update":
+          this.config.onPriceUpdate?.(decoded);
+          break;
+        case "price_batch":
+          this.config.onPriceBatch?.(decoded);
+          for (const entry of decoded.data) {
+            this.config.onPriceUpdate?.({ type: "price_update", data: entry });
+          }
+          break;
+        case "price_snapshot":
+          this.config.onPriceSnapshot?.(decoded);
+          for (const entry of decoded.data) {
+            this.config.onPriceUpdate?.({ type: "price_update", data: entry });
+          }
+          break;
         case "heartbeat":
           this.lastHeartbeatTime = Date.now();
           this.resetHeartbeatTimeout();
@@ -781,6 +869,18 @@ var K256WebSocketClient = class {
     };
     this.ws?.send(JSON.stringify(msg));
   }
+  sendPriceSubscription(options) {
+    const json = JSON.stringify({
+      tokens: options.tokens,
+      thresholdBps: options.thresholdBps ?? 10
+    });
+    const encoder = new TextEncoder();
+    const jsonBytes = encoder.encode(json);
+    const buf = new Uint8Array(1 + jsonBytes.length);
+    buf[0] = MessageType.SubscribePrice;
+    buf.set(jsonBytes, 1);
+    this.ws?.send(buf);
+  }
   setState(state) {
     if (this._state !== state) {
       const prevState = this._state;
@@ -921,6 +1021,6 @@ var K256WebSocketClient = class {
   }
 };
 
-export { CloseCode, K256WebSocketClient, K256WebSocketError, MessageType, decodeMessage, decodePoolUpdateBatch };
+export { CloseCode, K256WebSocketClient, K256WebSocketError, MessageType, decodeMessage, decodePoolUpdateBatch, decodePriceEntries };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map