@k256/sdk 0.3.2 → 0.5.0

package/src/ws/client.ts

@@ -24,7 +24,7 @@
  */
 
 import { decodeMessage, decodePoolUpdateBatch } from './decoder';
-import { MessageType, type DecodedMessage, type PoolUpdateMessage, type BlockStatsMessage } from './types';
+import { MessageType, type DecodedMessage, type PoolUpdateMessage, type BlockStatsMessage, type PriceUpdateMessage, type PriceBatchMessage, type PriceSnapshotMessage } from './types';
 
 /**
  * RFC 6455 WebSocket Close Codes
@@ -105,6 +105,16 @@ export interface SubscribeQuoteOptions {
   refreshIntervalMs?: number;
 }
 
+/**
+ * Price subscription options
+ */
+export interface SubscribePriceOptions {
+  /** Token mint addresses to track */
+  tokens: string[];
+  /** Minimum bps change to receive an update (default 10) */
+  thresholdBps?: number;
+}
+
 /**
  * WebSocket client configuration
  */
@@ -163,6 +173,12 @@ export interface K256WebSocketClientConfig {
   onQuote?: (data: DecodedMessage & { type: 'quote' }) => void;
   /** Called on quote subscription confirmed */
   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' }) => void;
   /** Called on pong response (with round-trip latency) */
@@ -228,8 +244,8 @@ export class K256WebSocketClient {
   private config: Required<Omit<K256WebSocketClientConfig, 
     'onStateChange' | 'onConnect' | 'onDisconnect' | 'onReconnecting' | 'onError' |
     'onSubscribed' | 'onPoolUpdate' | 'onPoolUpdateBatch' | 'onFeeMarket' | 'onBlockStats' |
-    'onBlockhash' | 'onQuote' | 'onQuoteSubscribed' | 'onHeartbeat' | 'onPong' | 
-    'onMessage' | 'onRawMessage'
+    'onBlockhash' | 'onQuote' | 'onQuoteSubscribed' | 'onPriceUpdate' | 'onPriceBatch' |
+    'onPriceSnapshot' | 'onHeartbeat' | 'onPong' | 'onMessage' | 'onRawMessage'
   >> & K256WebSocketClientConfig;
   
   private _state: ConnectionState = 'disconnected';
@@ -242,6 +258,7 @@ export class K256WebSocketClient {
   private lastHeartbeatTime = 0;
   private pendingSubscription: SubscribeOptions | null = null;
   private pendingQuoteSubscription: SubscribeQuoteOptions | null = null;
+  private pendingPriceSubscription: SubscribePriceOptions | null = null;
   private isIntentionallyClosed = false;
 
   /** Current connection state */
@@ -351,12 +368,39 @@ export class K256WebSocketClient {
     this.ws?.send(msg);
   }
 
+  /**
+   * Subscribe to real-time price updates
+   * @param options - Token mints and threshold configuration
+   */
+  subscribePrices(options: SubscribePriceOptions): void {
+    this.pendingPriceSubscription = options;
+
+    if (!this.isConnected) {
+      return;
+    }
+
+    this.sendPriceSubscription(options);
+  }
+
+  /**
+   * Unsubscribe from price updates
+   */
+  unsubscribePrices(): void {
+    this.pendingPriceSubscription = null;
+
+    if (!this.isConnected) return;
+
+    const buf = new Uint8Array([MessageType.UnsubscribePrice]);
+    this.ws?.send(buf);
+  }
+
   /**
    * Unsubscribe from all channels
    */
   unsubscribe(): void {
     this.pendingSubscription = null;
     this.pendingQuoteSubscription = null;
+    this.pendingPriceSubscription = null;
     
     if (!this.isConnected) return;
     
@@ -427,6 +471,9 @@ export class K256WebSocketClient {
           if (this.pendingQuoteSubscription) {
             this.sendQuoteSubscription(this.pendingQuoteSubscription);
           }
+          if (this.pendingPriceSubscription) {
+            this.sendPriceSubscription(this.pendingPriceSubscription);
+          }
           
           this.config.onConnect?.();
           resolve();
@@ -553,6 +600,21 @@ export class K256WebSocketClient {
         case 'quote_subscribed':
           this.config.onQuoteSubscribed?.(decoded as DecodedMessage & { type: 'quote_subscribed' });
           break;
+        case 'price_update':
+          this.config.onPriceUpdate?.(decoded as PriceUpdateMessage);
+          break;
+        case 'price_batch':
+          this.config.onPriceBatch?.(decoded as PriceBatchMessage);
+          for (const entry of (decoded as PriceBatchMessage).data) {
+            this.config.onPriceUpdate?.({ type: 'price_update', data: entry });
+          }
+          break;
+        case 'price_snapshot':
+          this.config.onPriceSnapshot?.(decoded as PriceSnapshotMessage);
+          for (const entry of (decoded as PriceSnapshotMessage).data) {
+            this.config.onPriceUpdate?.({ type: 'price_update', data: entry });
+          }
+          break;
         case 'heartbeat':
           this.lastHeartbeatTime = Date.now();
           this.resetHeartbeatTimeout();
@@ -622,6 +684,19 @@ export class K256WebSocketClient {
     this.ws?.send(JSON.stringify(msg));
   }
 
+  private sendPriceSubscription(options: SubscribePriceOptions): void {
+    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);
+  }
+
   private setState(state: ConnectionState): void {
     if (this._state !== state) {
       const prevState = this._state;

package/src/ws/decoder.ts

@@ -9,7 +9,7 @@
 
 import { base58Encode } from '../utils/base58';
 import type { BlockMiniStats, TrendDirection } from '../types';
-import { MessageType, type DecodedMessage, type PoolUpdateMessage, type FeeMarketMessage } from './types';
+import { MessageType, type DecodedMessage, type PoolUpdateMessage, type FeeMarketMessage, type PriceEntry, type PriceBatchMessage, type PriceSnapshotMessage } from './types';
 
 /**
  * Decode a binary WebSocket message from K2
@@ -232,11 +232,66 @@ export function decodeMessage(data: ArrayBuffer): DecodedMessage | null {
       };
     }
 
+    case MessageType.PriceUpdate: {
+      // Single price entry (56 bytes, no count prefix):
+      // [mint:32B][usd_price:u64 LE][slot:u64 LE][timestamp_ms:u64 LE]
+      // K2 currently doesn't send 0x11, but handle for forward compat.
+      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: {
+      // Both use identical binary format from serialize_price_message():
+      // [count:u16 LE][entry₁:56B]...[entryₙ:56B]
+      // Each entry: [mint:32B][usd_price:u64 LE][slot:u64 LE][timestamp_ms:u64 LE]
+      if (payload.byteLength < 2) return null;
+      const entries = decodePriceEntries(payload);
+      const priceType = msgType === MessageType.PriceSnapshot ? 'price_snapshot' : 'price_batch';
+      return { type: priceType, data: entries } as PriceBatchMessage | PriceSnapshotMessage;
+    }
+
     default:
       return null;
   }
 }
 
+/**
+ * Decode price entries from a PriceBatch or PriceSnapshot payload.
+ *
+ * Wire format: [count:u16 LE][entry₁:56B]...[entryₙ:56B]
+ */
+export function decodePriceEntries(payload: ArrayBuffer): PriceEntry[] {
+  const view = new DataView(payload);
+  if (payload.byteLength < 2) return [];
+
+  const count = view.getUint16(0, true);
+  const entries: PriceEntry[] = [];
+  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;
+}
+
 /**
  * Decode a batch of pool updates
  * 

package/src/ws/index.ts

@@ -33,10 +33,11 @@ export type {
   ConnectionState,
   SubscribeOptions,
   SubscribeQuoteOptions,
+  SubscribePriceOptions,
 } from './client';
 
 // Decoder (for advanced usage)
-export { decodeMessage, decodePoolUpdateBatch } from './decoder';
+export { decodeMessage, decodePoolUpdateBatch, decodePriceEntries } from './decoder';
 
 // Types
 export { MessageType } from './types';
@@ -48,6 +49,10 @@ export type {
   BlockStatsMessage,
   BlockhashMessage,
   QuoteMessage,
+  PriceEntry,
+  PriceUpdateMessage,
+  PriceBatchMessage,
+  PriceSnapshotMessage,
   HeartbeatMessage,
   ErrorMessage,
   SubscribedMessage,

package/src/ws/types.ts

@@ -44,6 +44,16 @@ export const MessageType = {
   PoolUpdateBatch: 0x0e,
   /** Block-level statistics (v3) */
   BlockStats: 0x0f,
+  /** Subscribe to price updates (JSON) - Client → Server */
+  SubscribePrice: 0x10,
+  /** Single price update (bincode 56B) - Server → Client */
+  PriceUpdate: 0x11,
+  /** Batched price updates (bincode [u16 count][entries...]) - Server → Client */
+  PriceBatch: 0x12,
+  /** Initial price snapshot (same binary format as PriceBatch) - Server → Client */
+  PriceSnapshot: 0x13,
+  /** Unsubscribe from prices (no payload) - Client → Server */
+  UnsubscribePrice: 0x14,
   /** Error message (UTF-8 string) */
   Error: 0xff,
 } as const;
@@ -214,6 +224,42 @@ export interface QuoteSubscribedMessage {
   };
 }
 
+/**
+ * Single decoded price entry (shared by PriceUpdate, PriceBatch, PriceSnapshot)
+ */
+export 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)
+ */
+export interface PriceUpdateMessage {
+  type: 'price_update';
+  data: PriceEntry;
+}
+
+/**
+ * Batched price updates from binary message (0x12)
+ */
+export interface PriceBatchMessage {
+  type: 'price_batch';
+  data: PriceEntry[];
+}
+
+/**
+ * Initial price snapshot from binary message (0x13)
+ * Same binary format as PriceBatch — sent once after subscribe_price
+ */
+export interface PriceSnapshotMessage {
+  type: 'price_snapshot';
+  data: PriceEntry[];
+}
+
 /**
  * Error message from server
  */
@@ -243,6 +289,9 @@ export type DecodedMessage =
   | BlockStatsMessage
   | BlockhashMessage
   | QuoteMessage
+  | PriceUpdateMessage
+  | PriceBatchMessage
+  | PriceSnapshotMessage
   | HeartbeatMessage
   | SubscribedMessage
   | QuoteSubscribedMessage