@temple-digital-group/temple-canton-js 2.0.1 → 2.0.3-beta.0

package/README.md

@@ -1,455 +1,457 @@
-# Temple Canton JS
-
-JavaScript SDK for interacting with the Temple Canton blockchain exchange. Supports Amulet (CC), USDCx, and CBTC tokens on the Canton network.
-
-## Installation
-
-```bash
-npm install @temple-digital-group/temple-canton-js
-```
-
-## Configuration
-
-Call `initialize()` before using any SDK functions. It sets up the config and optionally authenticates with the Temple REST API.
-
-### Wallet Adapter
-
-For apps using Loop Wallet. Pass the Loop SDK instance as `WALLET_ADAPTER` — the SDK auto-detects server vs client mode.
-
-- **Server-side:** uses `loop.executeTransaction()` (signs locally with private key)
-- **Client-side:** uses `loop.provider.submitTransaction()` (delegates signing to Loop Wallet via WebSocket)
-
-```javascript
-import { initialize } from "@temple-digital-group/temple-canton-js";
-
-initialize({
-	API_KEY: "your-api-key",
-	NETWORK: "mainnet",
-	WALLET_ADAPTER: loop, // Pass the Loop SDK instance
-});
-```
-
-You can also set or change the wallet adapter after init:
-
-```javascript
-import { setWalletAdapter } from "@temple-digital-group/temple-canton-js";
-
-setWalletAdapter(loop);
-```
-
-| Key              | Required | Description                                                     |
-| ---------------- | -------- | --------------------------------------------------------------- |
-| `API_KEY`        | Yes      | Temple REST API key                                             |
-| `NETWORK`        | Yes      | `mainnet` or `testnet`                                          |
-| `WALLET_ADAPTER` | Yes      | Loop SDK instance — auto-detects server/client mode for signing |
-
-## Supported Instruments
-
-| Asset | Type        | Networks         |
-| ----- | ----------- | ---------------- |
-| CC    | Canton Coin | testnet, mainnet |
-| USDCx | Utility     | testnet, mainnet |
-| CBTC  | Utility     | testnet, mainnet |
-
-> **Symbol normalization:** Use `CC` for Canton Coin in all SDK methods. The SDK handles the internal conversion to `Amulet` where required by the ledger. The `Amulet` symbol is deprecated — all API responses now return `CC`.
-
-## Supported Trading Pairs
-
-- `CC/USDCx`
-- `CBTC/USDCx`
-
-## v2 Trading Flow
-
-The v2 flow covers the full trading lifecycle: onboarding, deposits, trading, and withdrawals.
-
-```
-1. Check onboarding   →  isUserOnboarded(party)
-   If NOT onboarded   →  onboardUser(party)
-
-2. Deposit funds      →  deposit(amount, symbol)
-
-3. Check balance      →  getTradingBalance()
-
-4. Place orders       →  createOrderRequest({ symbol, side, quantity, price, ... })
-
-5. Cancel orders      →  cancelOrder(orderId) or cancelAllOrders({ symbol })
-
-6. Withdraw funds     →  withdrawFunds({ asset_id, amount })
-
-7. Withdraw delegation → withdrawDelegation(delegationId, user)
-```
-
-### 1. Onboarding
-
-Check if a user has a delegation contract, and create one if not:
-
-```javascript
-import { isUserOnboarded, onboardUser } from "@temple-digital-group/temple-canton-js";
-
-const delegation = await isUserOnboarded(party);
-if (!delegation) {
-	const result = await onboardUser({ partyId: party });
-	// result.delegation — the confirmed delegation contract
-	// result.warning    — set if onboarding was submitted but not confirmed within 60s
-}
-```
-
-`onboardUser` submits the onboarding request and then polls `isUserOnboarded` every 5 seconds for up to 60 seconds. It returns once the delegation is confirmed, or with a `warning` field if the timeout is reached.
-
-### 2. Deposit Funds
-
-The simplest way to deposit is the `deposit()` helper — pass the amount and symbol, and it handles everything:
-
-```javascript
-import { deposit } from "@temple-digital-group/temple-canton-js";
-
-const result = await deposit(100, "USDCx");
-// or
-const result = await deposit(10, "CC");
-```
-
-`deposit()` requires the wallet adapter to be connected. It:
-
-1. Checks your CC balance to ensure at least 10 CC is reserved for transaction fees
-2. For utility deposits (USDCx, CBTC), verifies you have enough of the token **and** 10 CC for fees
-3. Selects the right UTXOs from your wallet
-4. Submits the deposit allocation
-
-If you need more control, use `prepareDepositHoldings` + `depositFunds` directly:
-
-```javascript
-import { prepareDepositHoldings, depositFunds } from "@temple-digital-group/temple-canton-js";
-
-const depositOpts = await prepareDepositHoldings(100, "USDCx");
-const result = await depositFunds(depositOpts);
-```
-
-### 3. Trading Balance
-
-```javascript
-import { getTradingBalance } from "@temple-digital-group/temple-canton-js";
-
-const balances = await getTradingBalance();
-// Returns { balances: [{ asset, unlocked, locked, in_flight, ... }] }
-```
-
-Use this to check available funds before placing orders or withdrawals.
-
-### 4. Place Orders
-
-```javascript
-import { createOrderRequest } from "@temple-digital-group/temple-canton-js";
-
-const result = await createOrderRequest({
-	symbol: "CC/USDCx",
-	side: "buy",
-	quantity: 10.5,
-	price: 1.25,
-	order_type: "limit",
-});
-
-// Post-only order (rejected if it would match immediately)
-const postOnly = await createOrderRequest({
-	symbol: "CC/USDCx",
-	side: "buy",
-	quantity: 10.5,
-	price: 1.25,
-	order_type: "limit",
-	order_subtype: "post_only",
-});
-```
-
-### 5. Cancel Orders
-
-```javascript
-import { cancelOrder, cancelAllOrders } from "@temple-digital-group/temple-canton-js";
-
-// Cancel a specific order
-await cancelOrder("ord_abc123");
-
-// Cancel all orders for a symbol
-await cancelAllOrders({ symbol: "CC/USDCx" });
-
-// Cancel ALL orders
-await cancelAllOrders();
-```
-
-### 6. Withdraw Funds
-
-Withdraws available (unlocked, non-in-flight) trading balance back to the user's wallet.
-
-```javascript
-import { withdrawFunds } from "@temple-digital-group/temple-canton-js";
-
-const result = await withdrawFunds({
-	asset_id: "USDCx",
-	amount: "250.50",
-});
-```
-
-### 7. Withdraw Delegation
-
-Archives the user's delegation contract. The user must re-onboard to trade again.
-
-```javascript
-import { withdrawDelegation } from "@temple-digital-group/temple-canton-js";
-
-// Auto-fetches delegation from API if not passed
-await withdrawDelegation();
-
-// Or pass explicitly
-await withdrawDelegation(delegationContractId, partyId);
-```
-
-### Get User Balances
-
-```javascript
-import { getUserBalances } from "@temple-digital-group/temple-canton-js";
-
-// Both params are optional — falls back to wallet adapter / config
-const balances = await getUserBalances();
-
-// Or pass explicitly
-const balances = await getUserBalances(partyId);
-const balances = await getUserBalances(partyId, walletProvider);
-```
-
-Each entry in the returned array contains:
-
-```javascript
-{
-  asset: 'USDCx',
-  total_balance: 170.5,
-  available_balance: 150.5,
-  locked_balance: 20.0,
-  dso: null,
-  registrar: '...',
-  operator: '...',
-  provider: '...',
-  merge_warning: true,
-  holdings: [...],
-  locked_holdings: [...],
-  utilityContext: { ... }
-}
-```
-
-### Merge Holdings
-
-```javascript
-import { mergeAmuletHoldingsForParty, mergeUtilityHoldingsForParty, getAmuletDisclosures, getUtxoCount } from "@temple-digital-group/temple-canton-js";
-
-// Merge all Amulet or utility holdings
-await mergeAmuletHoldingsForParty(partyId);
-await mergeUtilityHoldingsForParty(partyId, "USDCx");
-
-// Wallet Provider — merge up to 5 smallest USDCx UTXOs
-const command = await mergeUtilityHoldingsForParty(partyId, "USDCx", true, walletProvider, 5);
-const result = await walletProvider.submitTransaction(command);
-
-// Wallet Provider — merge CC (requires disclosures)
-const disclosures = await getAmuletDisclosures(partyId);
-const cmd = await mergeAmuletHoldingsForParty(partyId, true, walletProvider, 5, disclosures);
-const res = await walletProvider.submitTransaction(cmd);
-
-// Check UTXO status after merge
-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.
-
-### Configuration
-
-| Function                    | Description                                                                   |
-| --------------------------- | ----------------------------------------------------------------------------- |
-| `initialize(config)`        | Initialize the SDK, set config, and optionally authenticate with the REST API |
-| `setWalletAdapter(adapter)` | Set or update the Loop SDK instance for all wallet-aware functions            |
-
-### Instrument Catalog
-
-| Function                     | Description                             |
-| ---------------------------- | --------------------------------------- |
-| `getSupportedTradingPairs()` | Get the list of supported trading pairs |
-| `getInstrumentCatalog()`     | Get the full instrument catalog         |
-
-### 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) |
-
-### Deposits & Withdrawals
-
-| Function                                  | Provider | Description                                                |
-| ----------------------------------------- | -------- | ---------------------------------------------------------- |
-| `deposit(amount, symbol)`                 | **W**    | Deposit funds (validates balance, reserves 10 CC for fees) |
-| `prepareDepositHoldings(amount, assetId)` | **W**    | Resolve holdings for a deposit amount (low-level)          |
-| `depositFunds(opts)`                      | **W**    | Submit deposit allocation (low-level)                      |
-| `withdrawFunds({ asset_id, amount })`     | **W**    | Withdraw available trading balance back to wallet          |
-| `bulkWithdrawFunds(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 |
-
-### Holding Operations
-
-| 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
-
-> These functions call the Temple REST API. Pass `API_KEY` in `initialize()` or call `setApiKey()` to authenticate.
-
-#### Auth
-
-| Function         | Description                                 |
-| ---------------- | ------------------------------------------- |
-| `setApiKey(key)` | Set the API key for REST API authentication |
-| `getUserId()`    | Get the stored user ID                      |
-
-#### Market Data
-
-| Function                            | Description                                               |
-| ----------------------------------- | --------------------------------------------------------- |
-| `getTicker(symbol?)`                | Get ticker data for one or all trading pairs              |
-| `getOrderBook(symbol, options?)`    | Get the order book (options: `levels`, `precision`)       |
-| `getSymbolConfig(symbol)`           | Get symbol configuration (paused, decimals, min quantity) |
-| `getOpenInterest(symbol)`           | Get open interest for a trading pair                      |
-| `getRecentTrades(symbol, options?)` | Get recent trades (options: `limit`, max 500)             |
-
-#### 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`)         |
-
-#### Withdrawals
-
-| Function                                   | Description                                |
-| ------------------------------------------ | ------------------------------------------ |
-| `createWithdrawalRequest(assetId, amount)` | Submit a withdrawal request to the backend |
-| `getWithdrawalRequestStatus(requestId)`    | Poll withdrawal status until ready         |
-
-#### Disclosures & Delegation
-
-| Function           | Description                                                                  |
-| ------------------ | ---------------------------------------------------------------------------- |
-| `getDisclosures()` | 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                   |
+# Temple Canton JS
+
+JavaScript SDK for interacting with the Temple Canton blockchain exchange. Supports Amulet (CC), USDCx, and CBTC tokens on the Canton network.
+
+## Installation
+
+```bash
+npm install @temple-digital-group/temple-canton-js
+```
+
+## Configuration
+
+Call `initialize()` before using any SDK functions. It sets up the config and optionally authenticates with the Temple REST API.
+
+### Wallet Adapter
+
+For apps using Loop Wallet. Pass the Loop SDK instance as `WALLET_ADAPTER` — the SDK auto-detects server vs client mode.
+
+- **Server-side:** uses `loop.executeTransaction()` (signs locally with private key)
+- **Client-side:** uses `loop.provider.submitTransaction()` (delegates signing to Loop Wallet via WebSocket)
+
+```javascript
+import { initialize } from "@temple-digital-group/temple-canton-js";
+
+initialize({
+	API_KEY: "your-api-key",
+	NETWORK: "mainnet",
+	WALLET_ADAPTER: loop, // Pass the Loop SDK instance
+});
+```
+
+You can also set or change the wallet adapter after init:
+
+```javascript
+import { setWalletAdapter } from "@temple-digital-group/temple-canton-js";
+
+setWalletAdapter(loop);
+```
+
+| Key              | Required | Description                                                     |
+| ---------------- | -------- | --------------------------------------------------------------- |
+| `API_KEY`        | Yes      | Temple REST API key                                             |
+| `NETWORK`        | Yes      | `mainnet` or `testnet`                                          |
+| `WALLET_ADAPTER` | Yes      | Loop SDK instance — auto-detects server/client mode for signing |
+
+## Supported Instruments
+
+| Asset | Type        | Networks         |
+| ----- | ----------- | ---------------- |
+| CC    | Canton Coin | testnet, mainnet |
+| USDCx | Utility     | testnet, mainnet |
+| CBTC  | Utility     | testnet, mainnet |
+
+> **Symbol normalization:** Use `CC` for Canton Coin in all SDK methods. The SDK handles the internal conversion to `Amulet` where required by the ledger. The `Amulet` symbol is deprecated — all API responses now return `CC`.
+
+## Supported Trading Pairs
+
+- `CC/USDCx`
+- `CBTC/USDCx`
+
+## v2 Trading Flow
+
+The v2 flow covers the full trading lifecycle: onboarding, deposits, trading, and withdrawals.
+
+```
+1. Check onboarding   →  isUserOnboarded(party)
+   If NOT onboarded   →  onboardUser(party)
+
+2. Deposit funds      →  deposit(amount, symbol)
+
+3. Check balance      →  getTradingBalance()
+
+4. Place orders       →  createOrderRequest({ symbol, side, quantity, price, ... })
+
+5. Cancel orders      →  cancelOrder(orderId) or cancelAllOrders({ symbol })
+
+6. Withdraw funds     →  withdrawFunds({ asset_id, amount })
+
+7. Withdraw delegation → withdrawDelegation(delegationId, user)
+```
+
+### 1. Onboarding
+
+Check if a user has a delegation contract, and create one if not:
+
+```javascript
+import { isUserOnboarded, onboardUser } from "@temple-digital-group/temple-canton-js";
+
+const delegation = await isUserOnboarded(party);
+if (!delegation) {
+	const result = await onboardUser({ partyId: party });
+	// result.delegation — the confirmed delegation contract
+	// result.warning    — set if onboarding was submitted but not confirmed within 60s
+}
+```
+
+`onboardUser` submits the onboarding request and then polls `isUserOnboarded` every 5 seconds for up to 60 seconds. It returns once the delegation is confirmed, or with a `warning` field if the timeout is reached.
+
+### 2. Deposit Funds
+
+The simplest way to deposit is the `deposit()` helper — pass the amount and symbol, and it handles everything:
+
+```javascript
+import { deposit } from "@temple-digital-group/temple-canton-js";
+
+const result = await deposit(100, "USDCx");
+// or
+const result = await deposit(10, "CC");
+```
+
+`deposit()` requires the wallet adapter to be connected. It:
+1. Checks your CC balance to ensure at least 10 CC is reserved for transaction fees
+2. For utility deposits (USDCx, CBTC), verifies you have enough of the token **and** 10 CC for fees
+3. Selects the right UTXOs from your wallet
+4. Submits the deposit allocation
+
+If you need more control, use `prepareDepositHoldings` + `depositFunds` directly:
+
+```javascript
+import { prepareDepositHoldings, depositFunds } from "@temple-digital-group/temple-canton-js";
+
+const depositOpts = await prepareDepositHoldings(100, "USDCx");
+const result = await depositFunds(depositOpts);
+```
+
+### 3. Trading Balance
+
+```javascript
+import { getTradingBalance } from "@temple-digital-group/temple-canton-js";
+
+const balances = await getTradingBalance();
+// Returns { balances: [{ asset, unlocked, locked, in_flight, ... }] }
+```
+
+Use this to check available funds before placing orders or withdrawals.
+
+### 4. Place Orders
+
+```javascript
+import { createOrderRequest } from "@temple-digital-group/temple-canton-js";
+
+const result = await createOrderRequest({
+	symbol: "CC/USDCx",
+	side: "buy",
+	quantity: 10.5,
+	price: 1.25,
+	order_type: "limit",
+});
+
+// Post-only order (rejected if it would match immediately)
+const postOnly = await createOrderRequest({
+	symbol: "CC/USDCx",
+	side: "buy",
+	quantity: 10.5,
+	price: 1.25,
+	order_type: "limit",
+	order_subtype: "post_only",
+});
+```
+
+### 5. Cancel Orders
+
+```javascript
+import { cancelOrder, cancelAllOrders } from "@temple-digital-group/temple-canton-js";
+
+// Cancel a specific order
+await cancelOrder("ord_abc123");
+
+// Cancel all orders for a symbol
+await cancelAllOrders({ symbol: "CC/USDCx" });
+
+// Cancel ALL orders
+await cancelAllOrders();
+```
+
+### 6. Withdraw Funds
+
+Withdraws available (unlocked, non-in-flight) trading balance back to the user's wallet.
+
+```javascript
+import { withdrawFunds } from "@temple-digital-group/temple-canton-js";
+
+const result = await withdrawFunds({
+	asset_id: "USDCx",
+	amount: "250.50",
+});
+```
+
+### 7. Withdraw Delegation
+
+Archives the user's delegation contract. The user must re-onboard to trade again.
+
+```javascript
+import { withdrawDelegation } from "@temple-digital-group/temple-canton-js";
+
+// Auto-fetches delegation from API if not passed
+await withdrawDelegation();
+
+// Or pass explicitly
+await withdrawDelegation(delegationContractId, partyId);
+```
+
+### Get User Balances
+
+```javascript
+import { getUserBalances } from "@temple-digital-group/temple-canton-js";
+
+// Both params are optional — falls back to wallet adapter / config
+const balances = await getUserBalances();
+
+// Or pass explicitly
+const balances = await getUserBalances(partyId);
+const balances = await getUserBalances(partyId, walletProvider);
+```
+
+Each entry in the returned array contains:
+
+```javascript
+{
+  asset: 'USDCx',
+  total_balance: 170.5,
+  available_balance: 150.5,
+  locked_balance: 20.0,
+  dso: null,
+  registrar: '...',
+  operator: '...',
+  provider: '...',
+  merge_warning: true,
+  holdings: [...],
+  locked_holdings: [...],
+  utilityContext: { ... }
+}
+```
+
+### Merge Holdings
+
+```javascript
+import { mergeAmuletHoldingsForParty, mergeUtilityHoldingsForParty, getAmuletDisclosures, getUtxoCount } from "@temple-digital-group/temple-canton-js";
+
+// Merge all Amulet or utility holdings
+await mergeAmuletHoldingsForParty(partyId);
+await mergeUtilityHoldingsForParty(partyId, "USDCx");
+
+// Wallet Provider — merge up to 5 smallest USDCx UTXOs
+const command = await mergeUtilityHoldingsForParty(partyId, "USDCx", true, walletProvider, 5);
+const result = await walletProvider.submitTransaction(command);
+
+// Wallet Provider — merge CC (requires disclosures)
+const disclosures = await getAmuletDisclosures(partyId);
+const cmd = await mergeAmuletHoldingsForParty(partyId, true, walletProvider, 5, disclosures);
+const res = await walletProvider.submitTransaction(cmd);
+
+// Check UTXO status after merge
+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.
+
+### Configuration
+
+| Function                    | Description                                                                   |
+| --------------------------- | ----------------------------------------------------------------------------- |
+| `initialize(config)`        | Initialize the SDK, set config, and optionally authenticate with the REST API |
+| `setWalletAdapter(adapter)` | Set or update the Loop SDK instance for all wallet-aware functions            |
+
+### Instrument Catalog
+
+| Function                     | Description                             |
+| ---------------------------- | --------------------------------------- |
+| `getSupportedTradingPairs()` | Get the list of supported trading pairs |
+| `getInstrumentCatalog()`     | Get the full instrument catalog         |
+
+### 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) |
+
+### Deposits & Withdrawals
+
+| Function                                  | Provider | Description                                           |
+| ----------------------------------------- | -------- | ----------------------------------------------------- |
+| `deposit(amount, symbol)`                 | **W**    | Deposit funds (validates balance, reserves 10 CC for fees) |
+| `prepareDepositHoldings(amount, assetId)` | **W**    | Resolve holdings for a deposit amount (low-level)     |
+| `depositFunds(opts)`                      | **W**    | Submit deposit allocation (low-level)                 |
+| `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 |
+
+### Holding Operations
+
+| 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
+
+> These functions call the Temple REST API. Pass `API_KEY` in `initialize()` or call `setApiKey()` to authenticate.
+
+#### Auth
+
+| Function         | Description                                 |
+| ---------------- | ------------------------------------------- |
+| `setApiKey(key)` | Set the API key for REST API authentication |
+| `getUserId()`    | Get the stored user ID                      |
+
+#### Market Data
+
+| Function                            | Description                                               |
+| ----------------------------------- | --------------------------------------------------------- |
+| `getTicker(symbol?)`                | Get ticker data for one or all trading pairs              |
+| `getOrderBook(symbol, options?)`    | Get the order book (options: `levels`, `precision`)       |
+| `getSymbolConfig(symbol)`           | Get symbol configuration (paused, decimals, min quantity) |
+| `getOpenInterest(symbol)`           | Get open interest for a trading pair                      |
+| `getRecentTrades(symbol, options?)` | Get recent trades (options: `limit`, max 500)             |
+
+#### 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`)          |
+
+#### Withdrawals
+
+| 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                              |
+
+### 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)|