@temple-digital-group/temple-canton-js 2.0.0-beta.4 → 2.0.0-beta.5

package/README.md

@@ -45,11 +45,11 @@ setWalletAdapter(loop);
 
 ## Supported Instruments
 
-| Asset  | Type        | Networks         |
-| ------ | ----------- | ---------------- |
-| CC     | Canton Coin | testnet, mainnet |
-| USDCx  | Utility     | testnet, mainnet |
-| CBTC   | Utility     | testnet, mainnet |
+| Asset | Type        | Networks         |
+| ----- | ----------- | ---------------- |
+| CC    | Canton Coin | testnet, mainnet |
+| USDCx | Utility     | testnet, mainnet |
+| CBTC  | Utility     | testnet, mainnet |
 
 > **Symbol normalization:** `CC` is automatically normalized to `Amulet` in all API methods that accept a symbol (e.g. `CC/USDCx` becomes `Amulet/USDCx`).
 
@@ -112,19 +112,19 @@ const result = await depositFunds(depositOpts);
 
 `depositFunds` accepts:
 
-| Option           | Required | Description                                                   |
-| ---------------- | -------- | ------------------------------------------------------------- |
-| `sender`         | Yes      | Party allocating the assets                                   |
-| `assetId`        | Yes      | Instrument symbol (`USDCx`, `Amulet`, `CBTC`)                |
-| `amount`         | Yes      | Amount to allocate                                            |
-| `holdingCids`    | Yes      | Holding contract IDs that fund the allocation                 |
-| `receiver`       | No       | Counterparty (defaults to sender)                             |
-| `settlementId`   | No       | Reference ID for the settlement                               |
-| `transferLegId`  | No       | Unique ID for this transfer leg                               |
-| `allocateBefore` | No       | ISO timestamp; allocation deadline (default: +1h)             |
-| `settleBefore`   | No       | ISO timestamp; settlement deadline (default: +2h)             |
-| `disclosures`    | No       | Pre-fetched Amulet disclosures (for FE without API access)    |
-| `userId`         | No       | User ID (falls back to wallet adapter / config)               |
+| Option           | Required | Description                                                |
+| ---------------- | -------- | ---------------------------------------------------------- |
+| `sender`         | Yes      | Party allocating the assets                                |
+| `assetId`        | Yes      | Instrument symbol (`USDCx`, `Amulet`, `CBTC`)              |
+| `amount`         | Yes      | Amount to allocate                                         |
+| `holdingCids`    | Yes      | Holding contract IDs that fund the allocation              |
+| `receiver`       | No       | Counterparty (defaults to sender)                          |
+| `settlementId`   | No       | Reference ID for the settlement                            |
+| `transferLegId`  | No       | Unique ID for this transfer leg                            |
+| `allocateBefore` | No       | ISO timestamp; allocation deadline (default: +1h)          |
+| `settleBefore`   | No       | ISO timestamp; settlement deadline (default: +2h)          |
+| `disclosures`    | No       | Pre-fetched Amulet disclosures (for FE without API access) |
+| `userId`         | No       | User ID (falls back to wallet adapter / config)            |
 
 For Amulet deposits, the SDK fetches disclosures automatically. You can also pass them manually via `opts.disclosures`.
 
@@ -228,8 +228,6 @@ Each entry in the returned array contains:
 }
 ```
 
-
-
 ### Merge Holdings
 
 ```javascript
@@ -252,6 +250,94 @@ const res = await walletProvider.submitTransaction(cmd);
 const counts = await getUtxoCount(partyId, "USDCx", walletProvider);
 ```
 
+## WebSocket — Real-Time Data
+
+Subscribe to live market data and user events via WebSocket. Works in both Node.js and browsers.
+
+The server has two types of data:
+
+- **Market data** — public channels you explicitly subscribe to (orderbook, trades, ticker, candles, oracle)
+- **User data** — automatically pushed after authentication, no subscribe needed (orders, trades, balances)
+
+```javascript
+import {
+	subscribeOrderbook,
+	subscribeTrades,
+	subscribeTicker,
+	subscribeCandles,
+	subscribeUserOrders,
+	subscribeUserTrades,
+	subscribeUserBalances,
+	disconnectWebSocket,
+} from "@temple-digital-group/temple-canton-js";
+
+// Market data — sends a subscribe message to the server
+const unsub = subscribeOrderbook("Amulet/USDCx", (data) => {
+	console.log("Orderbook update:", data);
+});
+subscribeTrades("Amulet/USDCx", (data) => console.log("Trade:", data));
+subscribeTicker("CBTC/USDCx", (data) => console.log("Ticker:", data));
+subscribeCandles("Amulet/USDCx", 60, (data) => console.log("1m candle:", data));
+
+// User data — auto-delivered after auth, no subscribe message needed
+subscribeUserOrders((data) => console.log("Order update:", data));
+subscribeUserTrades((data) => console.log("Trade fill:", data));
+subscribeUserBalances((data) => console.log("Balance update:", data));
+
+// Unsubscribe from a specific channel
+unsub();
+
+// Disconnect everything
+disconnectWebSocket();
+```
+
+### Market Data Channels
+
+These require an explicit subscribe message. The SDK handles this automatically.
+
+| Function                                    | Channel                          | Example                   |
+| ------------------------------------------- | -------------------------------- | ------------------------- |
+| `subscribeOrderbook(symbol, cb)`            | `orderbook:{symbol}`             | `orderbook:Amulet/USDCx` |
+| `subscribeTrades(symbol, cb)`               | `trades:{symbol}`                | `trades:Amulet/USDCx`    |
+| `subscribeTicker(symbol, cb)`               | `ticker:{symbol}`                | `ticker:CBTC/USDCx`      |
+| `subscribeCandles(symbol, granularity, cb)` | `candles:{symbol}:{granularity}` | `candles:Amulet/USDCx:60`|
+| `subscribeOracle(symbol, cb)`               | `oracle:{symbol}`                | `oracle:cc`               |
+| `subscribeOracleVolume(symbol, cb)`         | `oracle_volume:{symbol}`         | `oracle_volume:cc`        |
+
+**Candle granularity values:** `60` (1m), `300` (5m), `900` (15m), `3600` (1h), `14400` (4h), `86400` (1d)
+
+### User Data Events
+
+Pushed automatically by the server after authentication. No subscribe message is sent — you just register a local handler. Requires `API_KEY` (Node.js) or cookie auth (browser).
+
+| Function                   | Server Event   | Description                                        |
+| -------------------------- | -------------- | -------------------------------------------------- |
+| `subscribeUserOrders(cb)`  | `user_order`   | Order lifecycle updates (created, filled, cancelled)|
+| `subscribeUserTrades(cb)`  | `user_trade`   | Trade fill confirmations                           |
+| `subscribeUserBalances(cb)`| `user_balance` | Balance changes                                    |
+
+### Advanced Usage
+
+Use the `TempleWebSocket` class directly for full control:
+
+```javascript
+import { TempleWebSocket } from "@temple-digital-group/temple-canton-js";
+
+const ws = new TempleWebSocket();
+ws.onConnect = () => console.log("Connected");
+ws.onDisconnect = (code, reason) => console.log("Disconnected:", code, reason);
+ws.onAuth = (success, userId) => console.log("Auth:", success, userId);
+ws.onError = (err) => console.error("WS error:", err);
+ws.autoReconnect = true; // default — reconnects with exponential backoff
+ws.connect();
+
+// Market data — sends subscribe to server
+const unsub = ws.subscribe("orderbook:Amulet/USDCx", (data) => { ... });
+
+// User data — no subscribe message, just local handler
+const unsubOrder = ws.onUserEvent("user_order", (data) => { ... });
+```
+
 ## API Reference
 
 > Functions marked with **W** support Loop Wallet via the wallet adapter.
@@ -272,36 +358,36 @@ const counts = await getUtxoCount(partyId, "USDCx", walletProvider);
 
 ### Onboarding & Delegation
 
-| Function                              | Provider | Description                                            |
-| ------------------------------------- | -------- | ------------------------------------------------------ |
-| `isUserOnboarded(party)`              | **W**    | Check if user has a delegation contract on ledger      |
-| `onboardUser(party)`                  | **W**    | Create the delegation contract needed for trading      |
-| `withdrawDelegation(delegationId?, user?)` | **W** | Archive the delegation contract (user must re-onboard) |
+| Function                                   | Provider | Description                                            |
+| ------------------------------------------ | -------- | ------------------------------------------------------ |
+| `isUserOnboarded(party)`                   | **W**    | Check if user has a delegation contract on ledger      |
+| `onboardUser(party)`                       | **W**    | Create the delegation contract needed for trading      |
+| `withdrawDelegation(delegationId?, user?)` | **W**    | Archive the delegation contract (user must re-onboard) |
 
 ### Deposits & Withdrawals
 
-| Function                                 | Provider | Description                                                  |
-| ---------------------------------------- | -------- | ------------------------------------------------------------ |
-| `prepareDepositHoldings(amount, assetId)` | **W**   | Resolve holdings for a deposit amount                        |
-| `depositFunds(opts)`                     | **W**    | Deposit funds into the user's trading balance                |
-| `withdrawFunds({ asset_id, amount })`    | **W**    | Withdraw available trading balance back to wallet            |
-| `emergencyWithdrawFunds(opts)`           | **W**    | Cancel all orders and withdraw everything immediately        |
+| Function                                  | Provider | Description                                           |
+| ----------------------------------------- | -------- | ----------------------------------------------------- |
+| `prepareDepositHoldings(amount, assetId)` | **W**    | Resolve holdings for a deposit amount                 |
+| `depositFunds(opts)`                      | **W**    | Deposit funds into the user's trading balance         |
+| `withdrawFunds({ asset_id, amount })`     | **W**    | Withdraw available trading balance back to wallet     |
+| `emergencyWithdrawFunds(opts)`            | **W**    | Cancel all orders and withdraw everything immediately |
 
 ### Holdings
 
-| Function                                                          | Provider | Description                                                    |
-| ----------------------------------------------------------------- | -------- | -------------------------------------------------------------- |
-| `getUserBalances(party?, provider?)`                              | **W**    | Get all balances grouped by asset (Amulet, locked, and utility) |
-| `getAmuletHoldingsForParty(party, returnCommand, provider)`      | **W**    | Get Amulet holdings                                            |
-| `getLockedAmuletHoldingsForParty(party, returnCommand, provider)`| **W**    | Get locked Amulet holdings                                     |
-| `getUtilityHoldingsForParty(party, returnCommand, provider)`     | **W**    | Get utility token holdings                                     |
-| `getUtxoCount(party, assetId, provider)`                         | **W**    | Get UTXO summary: counts, largest unlocked amount, and total unlocked balance |
+| Function                                                          | Provider | Description                                                                   |
+| ----------------------------------------------------------------- | -------- | ----------------------------------------------------------------------------- |
+| `getUserBalances(party?, provider?)`                              | **W**    | Get all balances grouped by asset (Amulet, locked, and utility)               |
+| `getAmuletHoldingsForParty(party, returnCommand, provider)`       | **W**    | Get Amulet holdings                                                           |
+| `getLockedAmuletHoldingsForParty(party, returnCommand, provider)` | **W**    | Get locked Amulet holdings                                                    |
+| `getUtilityHoldingsForParty(party, returnCommand, provider)`      | **W**    | Get utility token holdings                                                    |
+| `getUtxoCount(party, assetId, provider)`                          | **W**    | Get UTXO summary: counts, largest unlocked amount, and total unlocked balance |
 
 ### Holding Operations
 
-| Function                                                                                   | Provider | Description                    |
-| ------------------------------------------------------------------------------------------ | -------- | ------------------------------ |
-| `mergeAmuletHoldingsForParty(party, returnCommand, provider, maxUtxos, amuletDisclosures)` | **W**    | Merge Amulet holdings into one |
+| Function                                                                                   | Provider | Description                     |
+| ------------------------------------------------------------------------------------------ | -------- | ------------------------------- |
+| `mergeAmuletHoldingsForParty(party, returnCommand, provider, maxUtxos, amuletDisclosures)` | **W**    | Merge Amulet holdings into one  |
 | `mergeUtilityHoldingsForParty(party, utilityAsset, returnCommand, provider, maxUtxos)`     | **W**    | Merge utility holdings into one |
 
 ### Temple REST API
@@ -310,10 +396,10 @@ const counts = await getUtxoCount(partyId, "USDCx", walletProvider);
 
 #### Auth
 
-| Function                            | Description                                         |
-| ----------------------------------- | --------------------------------------------------- |
-| `setApiKey(key)`                    | Set the API key for REST API authentication         |
-| `getUserId()`                       | Get the stored user ID                              |
+| Function         | Description                                 |
+| ---------------- | ------------------------------------------- |
+| `setApiKey(key)` | Set the API key for REST API authentication |
+| `getUserId()`    | Get the stored user ID                      |
 
 #### Market Data
 
@@ -327,24 +413,40 @@ const counts = await getUtxoCount(partyId, "USDCx", walletProvider);
 
 #### Trading
 
-| Function                                    | Description                                    |
-| ------------------------------------------- | ---------------------------------------------- |
-| `createOrderRequest(opts)`                  | Place a buy/sell order via the trading backend  |
-| `cancelOrder(orderId)`                      | Cancel a specific order                        |
-| `cancelAllOrders(options?)`                 | Cancel all orders (options: `symbol` filter)   |
-| `getTradingBalance()`                       | Get user's trading balance (unlocked/locked/in-flight) |
-| `getActiveOrders(options?)`                 | Get active orders (options: `symbol`, `limit`) |
+| Function                    | Description                                            |
+| --------------------------- | ------------------------------------------------------ |
+| `createOrderRequest(opts)`  | Place a buy/sell order via the trading backend         |
+| `cancelOrder(orderId)`      | Cancel a specific order                                |
+| `cancelAllOrders(options?)` | Cancel all orders (options: `symbol` filter)           |
+| `getTradingBalance()`       | Get user's trading balance (unlocked/locked/in-flight) |
+| `getActiveOrders(options?)` | Get active orders (options: `symbol`, `limit`)         |
 
 #### Withdrawals
 
-| Function                                    | Description                                            |
-| ------------------------------------------- | ------------------------------------------------------ |
-| `createWithdrawalRequest(assetId, amount)`  | Submit a withdrawal request to the backend             |
-| `getWithdrawalRequestStatus(requestId)`     | Poll withdrawal status until ready                     |
+| Function                                   | Description                                |
+| ------------------------------------------ | ------------------------------------------ |
+| `createWithdrawalRequest(assetId, amount)` | Submit a withdrawal request to the backend |
+| `getWithdrawalRequestStatus(requestId)`    | Poll withdrawal status until ready         |
 
 #### Disclosures & Delegation
 
-| Function                  | Description                                                                     |
-| ------------------------- | ------------------------------------------------------------------------------- |
-| `getDisclosures(partyId)` | Get Amulet disclosure data (factory ID, choice context, disclosed contracts)    |
-| `getDelegation()`         | Get the user's delegation contract from the API                                 |
+| Function                  | Description                                                                  |
+| ------------------------- | ---------------------------------------------------------------------------- |
+| `getDisclosures(partyId)` | Get Amulet disclosure data (factory ID, choice context, disclosed contracts) |
+| `getDelegation()`         | Get the user's delegation contract from the API                              |
+
+### WebSocket
+
+| Function                                    | Description                                                    |
+| ------------------------------------------- | -------------------------------------------------------------- |
+| `createWebSocket()`                         | Get or create the shared WS instance (auto-connects)           |
+| `disconnectWebSocket()`                     | Disconnect and destroy the shared WS instance                  |
+| `subscribeOrderbook(symbol, cb)`            | Subscribe to orderbook updates                                 |
+| `subscribeTrades(symbol, cb)`               | Subscribe to trade updates                                     |
+| `subscribeTicker(symbol, cb)`               | Subscribe to ticker updates                                    |
+| `subscribeCandles(symbol, granularity, cb)` | Subscribe to candle updates                                    |
+| `subscribeOracle(symbol, cb)`               | Subscribe to oracle price updates                              |
+| `subscribeOracleVolume(symbol, cb)`         | Subscribe to oracle volume updates                             |
+| `subscribeUserOrders(cb)`                   | Listen to user order events (auto-pushed, no subscribe needed) |
+| `subscribeUserTrades(cb)`                   | Listen to user trade events (auto-pushed, no subscribe needed) |
+| `subscribeUserBalances(cb)`                 | Listen to user balance events (auto-pushed, no subscribe needed)|

package/dist/canton/helpers.js

@@ -2,7 +2,7 @@ import config from "../../src/config/index.js";
 import axios from "axios";
 import { getJWTToken } from "../../src/auth0/index.js";
 import { getAdapterProvider } from "../../src/canton/walletAdapter.js";
-import { instrumentCatalog } from "../../src/canton/instrumentCatalog.js";
+import { instrumentCatalog, normalizeAssetId } from "../../src/canton/instrumentCatalog.js";
 // ─── Constants ───────────────────────────────────────────────────────────────
 export const DEFAULT_AMULET_CONTEXT_KEYS = {
     amuletRules: "amulet-rules",
@@ -98,7 +98,7 @@ export function resolveProvider(provider) {
 export function resolveInstrumentDefinition(assetId) {
     if (!assetId || typeof assetId !== "string")
         return null;
-    return instrumentCatalog[assetId.trim()] || null;
+    return instrumentCatalog[normalizeAssetId(assetId)] || null;
 }
 /** Get the registrar for a utility instrument from the catalog. */
 export function getInstrumentRegistrar(assetId) {

package/dist/canton/withdrawals.js

@@ -5,6 +5,7 @@ import { getUserId } from "../api/tokenStore.js";
 import { getAdapterPartyId, getWalletAdapter, submitCommand } from "../../src/canton/walletAdapter.js";
 import { randomUUID, shouldUseLedgerForMetadata, normalizeContractId, resolveInstrumentDefinition, getInstrumentRegistrar, dedupeDisclosedContracts, buildHeaders, DEFAULT_AMULET_CONTEXT_KEYS, DEFAULT_UTILITY_CONTEXT_KEYS, } from "./helpers.js";
 import { resolveAmuletContext, resolveUtilityInstrumentConfiguration, resolveUtilityAllocationFactory, } from "../../src/canton/index.js";
+import { normalizeAssetId } from "../../src/canton/instrumentCatalog.js";
 // ─── Withdrawal Functions ────────────────────────────────────────────────────
 /**
  * Finalize a withdrawal by exercising the Allocation_Withdraw choice.
@@ -260,7 +261,8 @@ export async function finalizeWithdrawFunds(opts, returnCommand = false) {
  * 3. Exercises Allocation_Withdraw on the allocation contract to release holdings back to the user.
  */
 export async function withdrawFunds(opts, returnCommand = false) {
-    const { asset_id, amount, pollIntervalMs = 2000, maxPollAttempts = 30 } = opts || {};
+    const { amount, pollIntervalMs = 2000, maxPollAttempts = 30 } = opts || {};
+    const asset_id = normalizeAssetId(opts?.asset_id);
     const sender = getAdapterPartyId() ?? config.VALIDATOR_USER_PARTY_ID;
     if (!sender) {
         const msg = "withdrawFunds: sender party is required. Connect a wallet adapter or configure VALIDATOR_USER_PARTY_ID.";
@@ -309,7 +311,7 @@ export async function withdrawFunds(opts, returnCommand = false) {
     }
     // 3. Exercise Allocation_Withdraw to release held funds back to the user
     console.log(`withdrawFunds: exercising Allocation_Withdraw on ${allocationCid}...`);
-    const assetId = asset_id === "CC" ? "Amulet" : asset_id;
+    const assetId = asset_id;
     const withdrawResult = await finalizeWithdrawFunds({ allocationId: allocationCid, sender, assetId }, returnCommand);
     if (withdrawResult?.error) {
         console.error(`withdrawFunds: Allocation_Withdraw failed for request ${requestId}: ${withdrawResult.error}`);

package/dist/websocket/index.d.ts

@@ -0,0 +1,70 @@
+type MessageCallback = (data: unknown) => void;
+export type Granularity = 60 | 300 | 900 | 3600 | 14400 | 86400;
+export declare class TempleWebSocket {
+    private ws;
+    /** Channel subscriptions — require a subscribe message to the server */
+    private subscriptions;
+    /** User event subscriptions — auto-delivered after auth, no subscribe message needed */
+    private userEventSubscribers;
+    private reconnectTimer;
+    private pingInterval;
+    private reconnectAttempts;
+    private maxReconnectDelay;
+    private authenticated;
+    /** Whether to automatically reconnect on close/error */
+    autoReconnect: boolean;
+    /** Event callbacks */
+    onConnect: (() => void) | null;
+    onDisconnect: ((code: number, reason: string) => void) | null;
+    onError: ((error: unknown) => void) | null;
+    onAuth: ((success: boolean, userId?: number) => void) | null;
+    get connected(): boolean;
+    /**
+     * Connect to the Temple WebSocket server.
+     * Auth is handled automatically via header (Node.js) or message (browser).
+     */
+    connect(): void;
+    /** Disconnect and stop auto-reconnect. */
+    disconnect(): void;
+    /**
+     * Subscribe to a market data channel. Sends a subscribe message to the server.
+     * Returns an unsubscribe function.
+     *
+     * @param channel - Channel pattern (e.g. "orderbook:Amulet/USDCx", "trades:Amulet/USDCx")
+     * @param callback - Called with parsed message data for this channel
+     * @returns Unsubscribe function
+     */
+    subscribe(channel: string, callback: MessageCallback): () => void;
+    /**
+     * Unsubscribe a callback (or all callbacks) from a market data channel.
+     */
+    unsubscribe(channel: string, callback?: MessageCallback): void;
+    /**
+     * Subscribe to user events (auto-delivered after auth, no subscribe message sent).
+     * The server pushes these automatically once authenticated.
+     * Returns an unsubscribe function.
+     *
+     * @param event - Event name (e.g. "trade", "order", "balance")
+     * @param callback - Called with the event data
+     * @returns Unsubscribe function
+     */
+    onUserEvent(event: string, callback: MessageCallback): () => void;
+    private send;
+    private handleMessage;
+    private scheduleReconnect;
+    private cleanup;
+}
+/** Get or create the shared WebSocket instance. Auto-connects if not already. */
+export declare function createWebSocket(): TempleWebSocket;
+/** Disconnect and destroy the shared WebSocket instance. */
+export declare function disconnectWebSocket(): void;
+export declare function subscribeOrderbook(symbol: string, cb: MessageCallback): () => void;
+export declare function subscribeTrades(symbol: string, cb: MessageCallback): () => void;
+export declare function subscribeTicker(symbol: string, cb: MessageCallback): () => void;
+export declare function subscribeCandles(symbol: string, granularity: Granularity, cb: MessageCallback): () => void;
+export declare function subscribeOracle(symbol: string, cb: MessageCallback): () => void;
+export declare function subscribeOracleVolume(symbol: string, cb: MessageCallback): () => void;
+export declare function subscribeUserOrders(cb: MessageCallback): () => void;
+export declare function subscribeUserTrades(cb: MessageCallback): () => void;
+export declare function subscribeUserBalances(cb: MessageCallback): () => void;
+export {};

package/dist/websocket/index.js

@@ -0,0 +1,295 @@
+import config from "../../src/config/index.js";
+import NodeWebSocket from "ws";
+// Environment-aware WebSocket constructor
+const WS = typeof WebSocket !== "undefined" ? WebSocket : NodeWebSocket;
+// Whether we're in Node.js (can set headers on upgrade) vs browser (must auth via message)
+const isNode = typeof process !== "undefined" && typeof process.versions?.node === "string";
+/** Normalize CC → Amulet in symbol strings */
+function normalizeSymbol(symbol) {
+    return symbol.replace(/\bCC\b/g, "Amulet");
+}
+export class TempleWebSocket {
+    constructor() {
+        this.ws = null;
+        /** Channel subscriptions — require a subscribe message to the server */
+        this.subscriptions = new Map();
+        /** User event subscriptions — auto-delivered after auth, no subscribe message needed */
+        this.userEventSubscribers = new Map();
+        this.reconnectTimer = null;
+        this.pingInterval = null;
+        this.reconnectAttempts = 0;
+        this.maxReconnectDelay = 30000;
+        this.authenticated = false;
+        /** Whether to automatically reconnect on close/error */
+        this.autoReconnect = true;
+        /** Event callbacks */
+        this.onConnect = null;
+        this.onDisconnect = null;
+        this.onError = null;
+        this.onAuth = null;
+    }
+    get connected() {
+        return this.ws?.readyState === WS.OPEN;
+    }
+    /**
+     * Connect to the Temple WebSocket server.
+     * Auth is handled automatically via header (Node.js) or message (browser).
+     */
+    connect() {
+        if (this.ws && (this.ws.readyState === WS.OPEN || this.ws.readyState === WS.CONNECTING)) {
+            return;
+        }
+        const url = config.WS_URL;
+        const apiKey = config.API_KEY;
+        if (isNode && apiKey) {
+            // Node.js: auth via HTTP upgrade header
+            this.ws = new WS(url, { headers: { "X-API-Key": apiKey } });
+        }
+        else {
+            this.ws = new WS(url);
+        }
+        this.ws.onopen = () => {
+            this.reconnectAttempts = 0;
+            // Browser: auth via message after connect
+            if (!isNode && apiKey) {
+                this.send({ type: "auth", api_key: apiKey });
+            }
+            else {
+                this.authenticated = true;
+            }
+            // Re-subscribe to all active channels (market data only, not user events)
+            const channels = [...this.subscriptions.keys()];
+            if (channels.length > 0) {
+                this.send({ type: "subscribe", channels });
+            }
+            // Keepalive ping every 30s
+            this.pingInterval = setInterval(() => {
+                if (this.connected) {
+                    this.send({ type: "ping" });
+                }
+            }, 30000);
+            this.onConnect?.();
+        };
+        this.ws.onmessage = (event) => {
+            this.handleMessage(typeof event.data === "string" ? event.data : String(event.data));
+        };
+        this.ws.onclose = (event) => {
+            this.cleanup();
+            this.onDisconnect?.(event.code, event.reason);
+            if (this.autoReconnect) {
+                this.scheduleReconnect();
+            }
+        };
+        this.ws.onerror = (event) => {
+            this.onError?.(event);
+        };
+    }
+    /** Disconnect and stop auto-reconnect. */
+    disconnect() {
+        this.autoReconnect = false;
+        this.cleanup();
+        if (this.ws) {
+            this.ws.close(1000, "client disconnect");
+            this.ws = null;
+        }
+    }
+    /**
+     * Subscribe to a market data channel. Sends a subscribe message to the server.
+     * Returns an unsubscribe function.
+     *
+     * @param channel - Channel pattern (e.g. "orderbook:Amulet/USDCx", "trades:Amulet/USDCx")
+     * @param callback - Called with parsed message data for this channel
+     * @returns Unsubscribe function
+     */
+    subscribe(channel, callback) {
+        if (!this.subscriptions.has(channel)) {
+            this.subscriptions.set(channel, new Set());
+            // Send subscribe if already connected
+            if (this.connected) {
+                this.send({ type: "subscribe", channels: [channel] });
+            }
+        }
+        this.subscriptions.get(channel).add(callback);
+        // Return unsubscribe function
+        return () => this.unsubscribe(channel, callback);
+    }
+    /**
+     * Unsubscribe a callback (or all callbacks) from a market data channel.
+     */
+    unsubscribe(channel, callback) {
+        const callbacks = this.subscriptions.get(channel);
+        if (!callbacks)
+            return;
+        if (callback) {
+            callbacks.delete(callback);
+        }
+        if (!callback || callbacks.size === 0) {
+            this.subscriptions.delete(channel);
+            if (this.connected) {
+                this.send({ type: "unsubscribe", channels: [channel] });
+            }
+        }
+    }
+    /**
+     * Subscribe to user events (auto-delivered after auth, no subscribe message sent).
+     * The server pushes these automatically once authenticated.
+     * Returns an unsubscribe function.
+     *
+     * @param event - Event name (e.g. "trade", "order", "balance")
+     * @param callback - Called with the event data
+     * @returns Unsubscribe function
+     */
+    onUserEvent(event, callback) {
+        if (!this.userEventSubscribers.has(event)) {
+            this.userEventSubscribers.set(event, new Set());
+        }
+        this.userEventSubscribers.get(event).add(callback);
+        return () => {
+            const handlers = this.userEventSubscribers.get(event);
+            if (handlers) {
+                handlers.delete(callback);
+                if (handlers.size === 0) {
+                    this.userEventSubscribers.delete(event);
+                }
+            }
+        };
+    }
+    send(msg) {
+        if (this.ws && this.ws.readyState === WS.OPEN) {
+            this.ws.send(JSON.stringify(msg));
+        }
+    }
+    handleMessage(raw) {
+        let parsed;
+        try {
+            parsed = JSON.parse(raw);
+        }
+        catch {
+            return;
+        }
+        const type = parsed.type;
+        // Handle auth response
+        if (type === "authenticated") {
+            this.authenticated = true;
+            this.onAuth?.(true, parsed.user_id);
+            return;
+        }
+        if (type === "auth_expired") {
+            this.authenticated = false;
+            this.onAuth?.(false);
+            return;
+        }
+        // Handle pong
+        if (type === "pong")
+            return;
+        // Handle subscribed/unsubscribed confirmations
+        if (type === "subscribed" || type === "unsubscribed")
+            return;
+        // Handle server errors
+        if (type === "error") {
+            this.onError?.(parsed);
+            return;
+        }
+        // Route user data (auto-pushed after auth, keyed by event name)
+        if (type === "user_data") {
+            const event = parsed.event;
+            if (event && this.userEventSubscribers.has(event)) {
+                const handlers = this.userEventSubscribers.get(event);
+                for (const cb of handlers) {
+                    try {
+                        cb(parsed.data ?? parsed);
+                    }
+                    catch {
+                        // Don't let one bad callback kill the others
+                    }
+                }
+            }
+            return;
+        }
+        // Route channel data (market data from subscriptions)
+        if (type === "data") {
+            const channel = parsed.channel;
+            if (channel && this.subscriptions.has(channel)) {
+                const callbacks = this.subscriptions.get(channel);
+                for (const cb of callbacks) {
+                    try {
+                        cb(parsed.data ?? parsed);
+                    }
+                    catch {
+                        // Don't let one bad callback kill the others
+                    }
+                }
+            }
+            return;
+        }
+    }
+    scheduleReconnect() {
+        if (this.reconnectTimer)
+            return;
+        const delay = Math.min(1000 * Math.pow(2, this.reconnectAttempts), this.maxReconnectDelay);
+        this.reconnectAttempts++;
+        this.reconnectTimer = setTimeout(() => {
+            this.reconnectTimer = null;
+            this.connect();
+        }, delay);
+    }
+    cleanup() {
+        if (this.pingInterval) {
+            clearInterval(this.pingInterval);
+            this.pingInterval = null;
+        }
+        if (this.reconnectTimer) {
+            clearTimeout(this.reconnectTimer);
+            this.reconnectTimer = null;
+        }
+        this.authenticated = false;
+    }
+}
+// ─── Singleton & Convenience API ─────────────────────────────────────────────
+let instance = null;
+/** Get or create the shared WebSocket instance. Auto-connects if not already. */
+export function createWebSocket() {
+    if (!instance) {
+        instance = new TempleWebSocket();
+    }
+    if (!instance.connected) {
+        instance.connect();
+    }
+    return instance;
+}
+/** Disconnect and destroy the shared WebSocket instance. */
+export function disconnectWebSocket() {
+    if (instance) {
+        instance.disconnect();
+        instance = null;
+    }
+}
+// ─── Market Data Subscriptions ───────────────────────────────────────────────
+export function subscribeOrderbook(symbol, cb) {
+    return createWebSocket().subscribe(`orderbook:${normalizeSymbol(symbol)}`, cb);
+}
+export function subscribeTrades(symbol, cb) {
+    return createWebSocket().subscribe(`trades:${normalizeSymbol(symbol)}`, cb);
+}
+export function subscribeTicker(symbol, cb) {
+    return createWebSocket().subscribe(`ticker:${normalizeSymbol(symbol)}`, cb);
+}
+export function subscribeCandles(symbol, granularity, cb) {
+    return createWebSocket().subscribe(`candles:${normalizeSymbol(symbol)}:${granularity}`, cb);
+}
+export function subscribeOracle(symbol, cb) {
+    return createWebSocket().subscribe(`oracle:${symbol}`, cb);
+}
+export function subscribeOracleVolume(symbol, cb) {
+    return createWebSocket().subscribe(`oracle_volume:${symbol}`, cb);
+}
+// ─── User Data Subscriptions (auto-delivered after auth) ─────────────────────
+export function subscribeUserOrders(cb) {
+    return createWebSocket().onUserEvent("user_order", cb);
+}
+export function subscribeUserTrades(cb) {
+    return createWebSocket().onUserEvent("user_trade", cb);
+}
+export function subscribeUserBalances(cb) {
+    return createWebSocket().onUserEvent("user_balance", cb);
+}

package/index.js

@@ -10,3 +10,6 @@ export * from './src/config/index.js';
 // Export Temple REST API functions
 export * from './dist/api/index.js';
 
+// Export WebSocket client
+export * from './dist/websocket/index.js';
+

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@temple-digital-group/temple-canton-js",
-  "version": "2.0.0-beta.4",
+  "version": "2.0.0-beta.5",
   "description": "JavaScript library for interacting with Temple Canton blockchain",
   "type": "module",
   "main": "index.js",
@@ -38,10 +38,12 @@
   },
   "dependencies": {
     "axios": "^1.13.1",
-    "dotenv": "^17.2.3"
+    "dotenv": "^17.2.3",
+    "ws": "^8.19.0"
   },
   "devDependencies": {
     "@types/node": "^25.3.3",
+    "@types/ws": "^8.18.0",
     "typescript": "^5.9.3"
   }
 }

package/src/api/tokenStore.ts

@@ -1,30 +1,30 @@
-import config from "../../src/config/index.js";
-import type { AuthHeaders } from "./types.js";
-
-let userId: string | null = null;
-
-/**
- * Get the stored user ID, or null if not set.
- */
-export function getUserId(): string | null {
-	return userId;
-}
-
-/**
- * Set the user ID directly (e.g. from config at init time).
- */
-export function setUserId(id: string): void {
-	userId = id;
-}
-
-/**
- * Get the authorization header using the API key from config.
- * Returns null if no API key is configured.
- */
-export function getAuthHeader(): AuthHeaders | null {
-	const apiKey = config.API_KEY;
-	if (apiKey) {
-		return { "X-API-Key": apiKey };
-	}
-	return null;
-}
+import config from "../../src/config/index.js";
+import type { AuthHeaders } from "./types.js";
+
+let userId: string | null = null;
+
+/**
+ * Get the stored user ID, or null if not set.
+ */
+export function getUserId(): string | null {
+	return userId;
+}
+
+/**
+ * Set the user ID directly (e.g. from config at init time).
+ */
+export function setUserId(id: string): void {
+	userId = id;
+}
+
+/**
+ * Get the authorization header using the API key from config.
+ * Returns null if no API key is configured.
+ */
+export function getAuthHeader(): AuthHeaders | null {
+	const apiKey = config.API_KEY;
+	if (apiKey) {
+		return { "X-API-Key": apiKey };
+	}
+	return null;
+}

package/src/canton/helpers.ts

@@ -2,7 +2,7 @@ import config from "../../src/config/index.js";
 import axios from "axios";
 import { getJWTToken } from "../../src/auth0/index.js";
 import { getAdapterProvider } from "../../src/canton/walletAdapter.js";
-import { instrumentCatalog } from "../../src/canton/instrumentCatalog.js";
+import { instrumentCatalog, normalizeAssetId } from "../../src/canton/instrumentCatalog.js";
 
 // ─── Constants ───────────────────────────────────────────────────────────────
 
@@ -151,7 +151,7 @@ export function resolveProvider(provider: unknown): unknown {
 /** Resolve an instrument definition from the catalog. */
 export function resolveInstrumentDefinition(assetId: string): Record<string, unknown> | null {
 	if (!assetId || typeof assetId !== "string") return null;
-	return (instrumentCatalog as Record<string, Record<string, unknown>>)[assetId.trim()] || null;
+	return (instrumentCatalog as Record<string, Record<string, unknown>>)[normalizeAssetId(assetId)] || null;
 }
 
 /** Get the registrar for a utility instrument from the catalog. */

package/src/canton/index.js

@@ -26,6 +26,7 @@ import {
 
 // Re-export helpers that are part of the public API
 export { resolveInstrumentDefinition, getInstrumentRegistrar };
+export { normalizeAssetId } from "./instrumentCatalog.js";
 
 // Import JSON schemas
 import createOrderProposalAmuletSchema from "./request_schemas/create_order_proposal_amulet.json" with { type: "json" };
@@ -44,7 +45,7 @@ import unlockAmuletSchema from "./request_schemas/unlock_amulet.json" with { typ
 import createUtilityCredentialSchema from "./request_schemas/create_utility_credential.json" with { type: "json" };
 
 // Import instrument catalog
-import { RegistrarInternalScheme, instrumentCatalog, instrumentIdToSymbol, supportedTradingPairs, supportedSymbols } from "./instrumentCatalog.js";
+import { RegistrarInternalScheme, instrumentCatalog, instrumentIdToSymbol, supportedTradingPairs, supportedSymbols, normalizeAssetId } from "./instrumentCatalog.js";
 
 
 /**
@@ -827,6 +828,8 @@ function replaceTemplateVariables(schema, variables) {
  * @returns {boolean|null} True if Amulet context is needed, false if not, null if invalid symbol
  */
 export function checkAmuletContext(baseAsset, quoteAsset, side) {
+	baseAsset = normalizeAssetId(baseAsset);
+	quoteAsset = normalizeAssetId(quoteAsset);
 	const symbolPair = supportedSymbols[`${baseAsset}/${quoteAsset}`];
 	if (!symbolPair) {
 		return null; // Invalid symbol
@@ -1596,6 +1599,7 @@ export async function getUtilityHoldingsForParty(party, returnCommand = false, p
  * @returns {Promise<{total: number, unlocked: number, locked: number, largestUnlocked: number, unlockedBalance: number}>} UTXO summary
  */
 export async function getUtxoCount(party, assetId, provider = null) {
+	assetId = normalizeAssetId(assetId);
 	provider = resolveProvider(provider);
 	const isAmulet = assetId === "Amulet";
 	const holdings = isAmulet ? await getAmuletHoldingsForParty(party, false, provider) : await getUtilityHoldingsForParty(party, false, provider);
@@ -1770,6 +1774,7 @@ export async function getUtilitySenderCredentials(sender, returnCommand = false)
  * @returns {Promise<Object>} Holding data with contractId, quantity, dso/registrar, or an error object
  */
 export async function getCandidateHoldingForOrderCreation(party, isAmulet, requiredQuantity, expectedAssetId = null, returnCommand = false, provider = null) {
+	if (expectedAssetId) expectedAssetId = normalizeAssetId(expectedAssetId);
 	provider = resolveProvider(provider);
 	const holdings = isAmulet ? await getAmuletHoldingsForParty(party, false, provider) : await getUtilityHoldingsForParty(party, false, provider);
 
@@ -2166,6 +2171,7 @@ export async function mergeAmuletHoldingsForParty(party, returnCommand = false,
  * @returns {Promise<Object|null>} Merge result data, or {command, endpoint} when returnCommand is true, or null on failure
  */
 export async function mergeUtilityHoldingsForParty(party, utilityAsset, returnCommand = false, provider = null, maxUtxos = null) {
+	utilityAsset = normalizeAssetId(utilityAsset);
 	provider = resolveProvider(provider);
 	if (provider) {
 		returnCommand = true;
@@ -2651,9 +2657,7 @@ export async function prepareDepositHoldings(amount, symbol) {
 		return { error: "prepareDepositHoldings: party ID is required. Connect a wallet adapter or configure VALIDATOR_USER_PARTY_ID." };
 	}
 
-	// Normalize symbol: CC → Amulet
-	let assetId = symbol?.trim();
-	if (assetId === "CC") assetId = "Amulet";
+	let assetId = normalizeAssetId(symbol);
 
 	if (!instrumentCatalog[assetId]) {
 		return { error: `prepareDepositHoldings: unsupported symbol "${symbol}"` };
@@ -2760,7 +2764,8 @@ export async function prepareDepositHoldings(amount, symbol) {
  * @returns {Promise<Object|null>} Ledger API response (or { error } on failure).
  */
 export async function depositFunds(opts, returnCommand = false) {
-	const { sender, receiver, assetId, amount, holdingCids = [], settlementId, transferLegId, allocateBefore, settleBefore, disclosures, userId } = opts;
+	const { sender, receiver, amount, holdingCids = [], settlementId, transferLegId, allocateBefore, settleBefore, disclosures, userId } = opts;
+	const assetId = normalizeAssetId(opts.assetId);
 
 	if (!sender || !assetId || !amount) {
 		const msg = "depositFunds: sender, assetId, and amount are required";

package/src/canton/instrumentCatalog.d.ts

@@ -3,3 +3,4 @@ export const instrumentCatalog: Record<string, Record<string, unknown>>;
 export const instrumentIdToSymbol: Record<string, string>;
 export const supportedTradingPairs: Array<{ baseAsset: string; quoteAsset: string }>;
 export const supportedSymbols: Record<string, unknown>;
+export function normalizeAssetId(symbol: string): string;

package/src/canton/instrumentCatalog.js

@@ -172,3 +172,12 @@ export const supportedSymbols = supportedTradingPairs.reduce((acc, pair) => {
 
 // Add CC as an alias for Amulet so users can pass "CC/USDCx"
 supportedSymbols["CC/USDCx"] = supportedSymbols["Amulet/USDCx"];
+
+/**
+ * Normalize asset aliases to their canonical names.
+ * "CC" (any case) → "Amulet". Also works inside trading pairs: "CC/USDCx" → "Amulet/USDCx".
+ */
+export function normalizeAssetId(symbol) {
+	if (!symbol || typeof symbol !== "string") return symbol;
+	return symbol.trim().replace(/\bcc\b/gi, "Amulet");
+}

package/src/canton/withdrawals.ts

@@ -25,6 +25,7 @@ import {
 	resolveUtilityInstrumentConfiguration,
 	resolveUtilityAllocationFactory,
 } from "../../src/canton/index.js";
+import { normalizeAssetId } from "../../src/canton/instrumentCatalog.js";
 
 // ─── Types ───────────────────────────────────────────────────────────────────
 
@@ -333,7 +334,8 @@ export async function withdrawFunds(
 	opts: WithdrawFundsOpts,
 	returnCommand = false,
 ): Promise<Record<string, unknown>> {
-	const { asset_id, amount, pollIntervalMs = 2000, maxPollAttempts = 30 } = opts || {};
+	const { amount, pollIntervalMs = 2000, maxPollAttempts = 30 } = opts || {};
+	const asset_id = normalizeAssetId(opts?.asset_id);
 
 	const sender = getAdapterPartyId() ?? config.VALIDATOR_USER_PARTY_ID;
 	if (!sender) {
@@ -393,7 +395,7 @@ export async function withdrawFunds(
 
 	// 3. Exercise Allocation_Withdraw to release held funds back to the user
 	console.log(`withdrawFunds: exercising Allocation_Withdraw on ${allocationCid}...`);
-	const assetId = asset_id === "CC" ? "Amulet" : asset_id;
+	const assetId = asset_id;
 	const withdrawResult = await finalizeWithdrawFunds({ allocationId: allocationCid, sender, assetId }, returnCommand);
 
 	if (withdrawResult?.error) {

package/src/config/index.d.ts

@@ -58,4 +58,5 @@ export namespace config {
     const PACKAGE_NAME_SETTLEMENT_INTERFACE: any;
     const PACKAGE_NAME_SETTLEMENT_IMPL: any;
     const API_KEY: any;
+    const WS_URL: string;
 }

package/src/config/index.js

@@ -123,6 +123,13 @@ const config = {
 	get API_PASSWORD() { return getConfigValue("API_PASSWORD"); },
 	get API_KEY() { return getConfigValue("API_KEY"); },
 
+	// WebSocket
+	get WS_URL() {
+		const network = getConfigValue("NETWORK") || NETWORK_MAINNET;
+		if (network === NETWORK_TESTNET) return "wss://ws-dev.templedigitalgroup.com/v1/stream";
+		return "wss://ws.templedigitalgroup.com/v1/stream";
+	},
+
 	// Validator connection settings
 	get VALIDATOR_API_URL() { return getConfigValue("VALIDATOR_API_URL"); },
 	get VALIDATOR_SCAN_API_URL() { return getConfigValue("VALIDATOR_SCAN_API_URL"); },

package/src/websocket/index.ts

@@ -0,0 +1,341 @@
+import config from "../../src/config/index.js";
+import NodeWebSocket from "ws";
+
+// Environment-aware WebSocket constructor
+const WS: typeof globalThis.WebSocket =
+	typeof WebSocket !== "undefined" ? WebSocket : (NodeWebSocket as unknown as typeof WebSocket);
+
+// Whether we're in Node.js (can set headers on upgrade) vs browser (must auth via message)
+const isNode = typeof process !== "undefined" && typeof process.versions?.node === "string";
+
+type MessageCallback = (data: unknown) => void;
+
+export type Granularity = 60 | 300 | 900 | 3600 | 14400 | 86400;
+
+/** Normalize CC → Amulet in symbol strings */
+function normalizeSymbol(symbol: string): string {
+	return symbol.replace(/\bCC\b/g, "Amulet");
+}
+
+export class TempleWebSocket {
+	private ws: InstanceType<typeof WS> | null = null;
+	/** Channel subscriptions — require a subscribe message to the server */
+	private subscriptions: Map<string, Set<MessageCallback>> = new Map();
+	/** User event subscriptions — auto-delivered after auth, no subscribe message needed */
+	private userEventSubscribers: Map<string, Set<MessageCallback>> = new Map();
+	private reconnectTimer: ReturnType<typeof setTimeout> | null = null;
+	private pingInterval: ReturnType<typeof setInterval> | null = null;
+	private reconnectAttempts = 0;
+	private maxReconnectDelay = 30_000;
+	private authenticated = false;
+
+	/** Whether to automatically reconnect on close/error */
+	autoReconnect = true;
+
+	/** Event callbacks */
+	onConnect: (() => void) | null = null;
+	onDisconnect: ((code: number, reason: string) => void) | null = null;
+	onError: ((error: unknown) => void) | null = null;
+	onAuth: ((success: boolean, userId?: number) => void) | null = null;
+
+	get connected(): boolean {
+		return this.ws?.readyState === WS.OPEN;
+	}
+
+	/**
+	 * Connect to the Temple WebSocket server.
+	 * Auth is handled automatically via header (Node.js) or message (browser).
+	 */
+	connect(): void {
+		if (this.ws && (this.ws.readyState === WS.OPEN || this.ws.readyState === WS.CONNECTING)) {
+			return;
+		}
+
+		const url = config.WS_URL;
+		const apiKey = config.API_KEY;
+
+		if (isNode && apiKey) {
+			// Node.js: auth via HTTP upgrade header
+			this.ws = new WS(url, { headers: { "X-API-Key": apiKey } } as unknown as string[]);
+		} else {
+			this.ws = new WS(url);
+		}
+
+		this.ws.onopen = () => {
+			this.reconnectAttempts = 0;
+
+			// Browser: auth via message after connect
+			if (!isNode && apiKey) {
+				this.send({ type: "auth", api_key: apiKey });
+			} else {
+				this.authenticated = true;
+			}
+
+			// Re-subscribe to all active channels (market data only, not user events)
+			const channels = [...this.subscriptions.keys()];
+			if (channels.length > 0) {
+				this.send({ type: "subscribe", channels });
+			}
+
+			// Keepalive ping every 30s
+			this.pingInterval = setInterval(() => {
+				if (this.connected) {
+					this.send({ type: "ping" });
+				}
+			}, 30_000);
+
+			this.onConnect?.();
+		};
+
+		this.ws.onmessage = (event: MessageEvent) => {
+			this.handleMessage(typeof event.data === "string" ? event.data : String(event.data));
+		};
+
+		this.ws.onclose = (event: CloseEvent) => {
+			this.cleanup();
+			this.onDisconnect?.(event.code, event.reason);
+			if (this.autoReconnect) {
+				this.scheduleReconnect();
+			}
+		};
+
+		this.ws.onerror = (event: Event) => {
+			this.onError?.(event);
+		};
+	}
+
+	/** Disconnect and stop auto-reconnect. */
+	disconnect(): void {
+		this.autoReconnect = false;
+		this.cleanup();
+		if (this.ws) {
+			this.ws.close(1000, "client disconnect");
+			this.ws = null;
+		}
+	}
+
+	/**
+	 * Subscribe to a market data channel. Sends a subscribe message to the server.
+	 * Returns an unsubscribe function.
+	 *
+	 * @param channel - Channel pattern (e.g. "orderbook:Amulet/USDCx", "trades:Amulet/USDCx")
+	 * @param callback - Called with parsed message data for this channel
+	 * @returns Unsubscribe function
+	 */
+	subscribe(channel: string, callback: MessageCallback): () => void {
+		if (!this.subscriptions.has(channel)) {
+			this.subscriptions.set(channel, new Set());
+			// Send subscribe if already connected
+			if (this.connected) {
+				this.send({ type: "subscribe", channels: [channel] });
+			}
+		}
+		this.subscriptions.get(channel)!.add(callback);
+
+		// Return unsubscribe function
+		return () => this.unsubscribe(channel, callback);
+	}
+
+	/**
+	 * Unsubscribe a callback (or all callbacks) from a market data channel.
+	 */
+	unsubscribe(channel: string, callback?: MessageCallback): void {
+		const callbacks = this.subscriptions.get(channel);
+		if (!callbacks) return;
+
+		if (callback) {
+			callbacks.delete(callback);
+		}
+
+		if (!callback || callbacks.size === 0) {
+			this.subscriptions.delete(channel);
+			if (this.connected) {
+				this.send({ type: "unsubscribe", channels: [channel] });
+			}
+		}
+	}
+
+	/**
+	 * Subscribe to user events (auto-delivered after auth, no subscribe message sent).
+	 * The server pushes these automatically once authenticated.
+	 * Returns an unsubscribe function.
+	 *
+	 * @param event - Event name (e.g. "trade", "order", "balance")
+	 * @param callback - Called with the event data
+	 * @returns Unsubscribe function
+	 */
+	onUserEvent(event: string, callback: MessageCallback): () => void {
+		if (!this.userEventSubscribers.has(event)) {
+			this.userEventSubscribers.set(event, new Set());
+		}
+		this.userEventSubscribers.get(event)!.add(callback);
+
+		return () => {
+			const handlers = this.userEventSubscribers.get(event);
+			if (handlers) {
+				handlers.delete(callback);
+				if (handlers.size === 0) {
+					this.userEventSubscribers.delete(event);
+				}
+			}
+		};
+	}
+
+	private send(msg: Record<string, unknown>): void {
+		if (this.ws && this.ws.readyState === WS.OPEN) {
+			this.ws.send(JSON.stringify(msg));
+		}
+	}
+
+	private handleMessage(raw: string): void {
+		let parsed: Record<string, unknown>;
+		try {
+			parsed = JSON.parse(raw);
+		} catch {
+			return;
+		}
+
+		const type = parsed.type as string | undefined;
+
+		// Handle auth response
+		if (type === "authenticated") {
+			this.authenticated = true;
+			this.onAuth?.(true, parsed.user_id as number | undefined);
+			return;
+		}
+		if (type === "auth_expired") {
+			this.authenticated = false;
+			this.onAuth?.(false);
+			return;
+		}
+
+		// Handle pong
+		if (type === "pong") return;
+
+		// Handle subscribed/unsubscribed confirmations
+		if (type === "subscribed" || type === "unsubscribed") return;
+
+		// Handle server errors
+		if (type === "error") {
+			this.onError?.(parsed);
+			return;
+		}
+
+		// Route user data (auto-pushed after auth, keyed by event name)
+		if (type === "user_data") {
+			const event = parsed.event as string | undefined;
+			if (event && this.userEventSubscribers.has(event)) {
+				const handlers = this.userEventSubscribers.get(event)!;
+				for (const cb of handlers) {
+					try {
+						cb(parsed.data ?? parsed);
+					} catch {
+						// Don't let one bad callback kill the others
+					}
+				}
+			}
+			return;
+		}
+
+		// Route channel data (market data from subscriptions)
+		if (type === "data") {
+			const channel = parsed.channel as string | undefined;
+			if (channel && this.subscriptions.has(channel)) {
+				const callbacks = this.subscriptions.get(channel)!;
+				for (const cb of callbacks) {
+					try {
+						cb(parsed.data ?? parsed);
+					} catch {
+						// Don't let one bad callback kill the others
+					}
+				}
+			}
+			return;
+		}
+	}
+
+	private scheduleReconnect(): void {
+		if (this.reconnectTimer) return;
+		const delay = Math.min(1000 * Math.pow(2, this.reconnectAttempts), this.maxReconnectDelay);
+		this.reconnectAttempts++;
+		this.reconnectTimer = setTimeout(() => {
+			this.reconnectTimer = null;
+			this.connect();
+		}, delay);
+	}
+
+	private cleanup(): void {
+		if (this.pingInterval) {
+			clearInterval(this.pingInterval);
+			this.pingInterval = null;
+		}
+		if (this.reconnectTimer) {
+			clearTimeout(this.reconnectTimer);
+			this.reconnectTimer = null;
+		}
+		this.authenticated = false;
+	}
+}
+
+// ─── Singleton & Convenience API ─────────────────────────────────────────────
+
+let instance: TempleWebSocket | null = null;
+
+/** Get or create the shared WebSocket instance. Auto-connects if not already. */
+export function createWebSocket(): TempleWebSocket {
+	if (!instance) {
+		instance = new TempleWebSocket();
+	}
+	if (!instance.connected) {
+		instance.connect();
+	}
+	return instance;
+}
+
+/** Disconnect and destroy the shared WebSocket instance. */
+export function disconnectWebSocket(): void {
+	if (instance) {
+		instance.disconnect();
+		instance = null;
+	}
+}
+
+// ─── Market Data Subscriptions ───────────────────────────────────────────────
+
+export function subscribeOrderbook(symbol: string, cb: MessageCallback): () => void {
+	return createWebSocket().subscribe(`orderbook:${normalizeSymbol(symbol)}`, cb);
+}
+
+export function subscribeTrades(symbol: string, cb: MessageCallback): () => void {
+	return createWebSocket().subscribe(`trades:${normalizeSymbol(symbol)}`, cb);
+}
+
+export function subscribeTicker(symbol: string, cb: MessageCallback): () => void {
+	return createWebSocket().subscribe(`ticker:${normalizeSymbol(symbol)}`, cb);
+}
+
+export function subscribeCandles(symbol: string, granularity: Granularity, cb: MessageCallback): () => void {
+	return createWebSocket().subscribe(`candles:${normalizeSymbol(symbol)}:${granularity}`, cb);
+}
+
+export function subscribeOracle(symbol: string, cb: MessageCallback): () => void {
+	return createWebSocket().subscribe(`oracle:${symbol}`, cb);
+}
+
+export function subscribeOracleVolume(symbol: string, cb: MessageCallback): () => void {
+	return createWebSocket().subscribe(`oracle_volume:${symbol}`, cb);
+}
+
+// ─── User Data Subscriptions (auto-delivered after auth) ─────────────────────
+
+export function subscribeUserOrders(cb: MessageCallback): () => void {
+	return createWebSocket().onUserEvent("user_order", cb);
+}
+
+export function subscribeUserTrades(cb: MessageCallback): () => void {
+	return createWebSocket().onUserEvent("user_trade", cb);
+}
+
+export function subscribeUserBalances(cb: MessageCallback): () => void {
+	return createWebSocket().onUserEvent("user_balance", cb);
+}

package/src/websocket/ws.d.ts

@@ -0,0 +1,24 @@
+declare module "ws" {
+	import { EventEmitter } from "events";
+
+	class WebSocket extends EventEmitter {
+		static readonly CONNECTING: 0;
+		static readonly OPEN: 1;
+		static readonly CLOSING: 2;
+		static readonly CLOSED: 3;
+
+		readonly readyState: number;
+
+		constructor(address: string, options?: { headers?: Record<string, string> });
+
+		close(code?: number, reason?: string): void;
+		send(data: string | Buffer): void;
+
+		onopen: ((event: { target: WebSocket }) => void) | null;
+		onclose: ((event: { code: number; reason: string; target: WebSocket }) => void) | null;
+		onmessage: ((event: { data: unknown; target: WebSocket }) => void) | null;
+		onerror: ((event: { error: unknown; target: WebSocket }) => void) | null;
+	}
+
+	export default WebSocket;
+}