@temple-digital-group/temple-canton-js 1.0.40 → 2.0.0-beta.10

package/README.md

@@ -1,6 +1,6 @@
 # Temple Canton JS
 
-JavaScript SDK for interacting with the Temple Canton blockchain exchange. Supports CC, USDCx, and CBTC tokens on the Canton network.
+JavaScript SDK for interacting with the Temple Canton blockchain exchange. Supports Amulet (CC), USDCx, and CBTC tokens on the Canton network.
 
 ## Installation
 
@@ -12,73 +12,6 @@ npm install @temple-digital-group/temple-canton-js
 
 Call `initialize()` before using any SDK functions. It sets up the config and optionally authenticates with the Temple REST API.
 
-### Custom Validator
-
-For apps connecting to your own validator (browser or server-side):
-
-```javascript
-import { initialize } from "@temple-digital-group/temple-canton-js";
-
-await initialize({
-	NETWORK: "mainnet",
-	VALIDATOR_API_URL: "https://your-validator-url",
-	VALIDATOR_SCAN_API_URL: "https://your-scan-api-url",
-	VALIDATOR_USER_PARTY_ID: "your-user-party-id",
-	AUTH0_TOKEN_URL: "https://your-auth0-domain/oauth/token",
-	AUTH0_USER_ID: "your-auth0-user-id",
-	AUTH0_CLIENT_ID: "your-client-id",
-	AUTH0_CLIENT_SECRET: "your-client-secret",
-	AUTH0_AUDIENCE: "your-audience",
-});
-```
-
-### Custom Validator + REST API
-
-To also authenticate with the Temple REST API at init time, pass `API_EMAIL`/`API_PASSWORD`:
-
-```javascript
-import { initialize } from "@temple-digital-group/temple-canton-js";
-
-await initialize({
-	NETWORK: "mainnet",
-	VALIDATOR_API_URL: "https://your-validator-url",
-	VALIDATOR_SCAN_API_URL: "https://your-scan-api-url",
-	VALIDATOR_USER_PARTY_ID: "your-user-party-id",
-	AUTH0_TOKEN_URL: "https://your-auth0-domain/oauth/token",
-	AUTH0_USER_ID: "your-auth0-user-id",
-	AUTH0_CLIENT_ID: "your-client-id",
-	AUTH0_CLIENT_SECRET: "your-client-secret",
-	AUTH0_AUDIENCE: "your-audience",
-	API_EMAIL: "user@example.com", // REST API login (optional)
-	API_PASSWORD: "password",
-});
-```
-
-| Key                       | Required | Description                                          |
-| ------------------------- | -------- | ---------------------------------------------------- |
-| `NETWORK`                 | Yes      | `mainnet`, `testnet`, or `localhost`                 |
-| `VALIDATOR_API_URL`       | Yes      | Base URL of the Canton validator ledger API          |
-| `VALIDATOR_SCAN_API_URL`  | Yes      | Base URL of the Canton Scan API                      |
-| `VALIDATOR_USER_PARTY_ID` | Yes      | The user's party ID on the network                   |
-| `JWT_TOKEN`               | Yes\*    | Pre-authenticated JWT token for ledger API calls     |
-| `AUTH0_TOKEN_URL`         | Yes\*    | Auth0 OAuth token endpoint                           |
-| `AUTH0_CLIENT_ID`         | Yes\*    | Auth0 application client ID                          |
-| `AUTH0_CLIENT_SECRET`     | Yes\*    | Auth0 application client secret                      |
-| `AUTH0_AUDIENCE`          | Yes\*    | Auth0 API audience identifier                        |
-| `AUTH0_USER_ID`           | Yes\*    | Auth0 user ID for the service account                |
-| `API_EMAIL`               | No       | Temple REST API email (triggers login at init)       |
-| `API_PASSWORD`            | No       | Temple REST API password (required with `API_EMAIL`) |
-
-\* Provide either `JWT_TOKEN` (browser) or the `AUTH0_*` fields (server-side). The SDK fetches and caches JWT tokens automatically when Auth0 credentials are provided.
-
-To update the JWT token later without re-initializing:
-
-```javascript
-import { setJWTToken } from "@temple-digital-group/temple-canton-js";
-
-setJWTToken(newToken);
-```
-
 ### Wallet Adapter
 
 For apps using Loop Wallet. Pass the Loop SDK instance as `WALLET_ADAPTER` — the SDK auto-detects server vs client mode.
@@ -87,18 +20,13 @@ For apps using Loop Wallet. Pass the Loop SDK instance as `WALLET_ADAPTER` — t
 - **Client-side:** uses `loop.provider.submitTransaction()` (delegates signing to Loop Wallet via WebSocket)
 
 ```javascript
-import { initialize, createOrderProposal } from "@temple-digital-group/temple-canton-js";
+import { initialize } from "@temple-digital-group/temple-canton-js";
 
-await initialize({
+initialize({
+	API_KEY: "your-api-key",
 	NETWORK: "mainnet",
 	WALLET_ADAPTER: loop, // Pass the Loop SDK instance
 });
-
-// Auto-submit: SDK handles signing and submission
-const result = await createOrderProposal(orderArgs);
-
-// Or get the raw command back for manual submission
-const command = await createOrderProposal(orderArgs, true);
 ```
 
 You can also set or change the wallet adapter after init:
@@ -111,12 +39,9 @@ setWalletAdapter(loop);
 
 | Key              | Required | Description                                                     |
 | ---------------- | -------- | --------------------------------------------------------------- |
-| `NETWORK`        | Yes      | `mainnet`, `testnet`, or `localhost`                            |
-| `WALLET_ADAPTER` | No       | Loop SDK instance — auto-detects server/client mode for signing |
-
-> You can optionally pass `API_EMAIL`/`API_PASSWORD` to any `initialize()` call to also authenticate with the REST API at init time.
-
-> **Legacy:** `initializeConfig()` is still available as a sync-only alternative (no REST API auth). `initialize()` is the recommended approach.
+| `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
 
@@ -126,128 +51,184 @@ setWalletAdapter(loop);
 | 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`
 
-## Usage
+## v2 Trading Flow
 
-### Get User Balances
+The v2 flow covers the full trading lifecycle: onboarding, deposits, trading, and withdrawals.
 
-```javascript
-import { getUserBalances } from "@temple-digital-group/temple-canton-js";
+```
+1. Check onboarding   →  isUserOnboarded(party)
+   If NOT onboarded   →  onboardUser(party)
 
-// Both params are optional — falls back to wallet adapter / config
-const balances = await getUserBalances();
+2. Deposit funds      →  deposit(amount, symbol)
 
-// Or pass explicitly
-const balances = await getUserBalances(partyId);
-const balances = await getUserBalances(partyId, walletProvider);
+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)
 ```
 
-Each entry in the returned array contains:
+### 1. Onboarding
+
+Check if a user has a delegation contract, and create one if not:
 
 ```javascript
-{
-  asset: 'USDCx',              // Catalog symbol
-  total_balance: 170.5,        // Unlocked + locked combined
-  available_balance: 150.5,    // Unlocked balance (usable for orders)
-  locked_balance: 20.0,        // Locked balance
-  dso: null,                   // DSO party (CC only)
-  registrar: '...',            // Registrar party (utility tokens)
-  operator: '...',             // Operator party
-  provider: '...',             // Provider party
-  merge_warning: true,         // true if multiple unlocked holdings exist
-  holdings: [...],             // Unlocked holding contracts
-  locked_holdings: [...],      // Locked holding contracts
-  utilityContext: { ... }      // CIP-56 context (null when using wallet provider)
+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
 }
 ```
 
-> **Note:** `utilityContext` is only resolved when using a custom validator (ledger API access). When using a wallet provider, it will be `null`.
+`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.
 
-### Create an Order
+### 2. Deposit Funds
+
+The simplest way to deposit is the `deposit()` helper — pass the amount and symbol, and it handles everything:
 
 ```javascript
-import { createOrderProposal } from "@temple-digital-group/temple-canton-js";
+import { deposit } from "@temple-digital-group/temple-canton-js";
 
-const result = await createOrderProposal({
-	party: partyId,
-	symbol: "CC/USDCx",
-	side: "Buy",
-	quantity: "100",
-	pricePerUnit: "1.5",
-	expiration: new Date(Date.now() + 3600000).toISOString(),
-	userId: auth0UserId, // Optional if authenticated via REST API — auto-resolved from login
-	orderType: "limit",
-});
+const result = await deposit(100, "USDCx");
+// or
+const result = await deposit(10, "CC");
 ```
 
-#### Handling Stale Holdings (Wallet Provider)
+`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:
 
-When a holding is used in an order, the contract is archived on-ledger and a new one is created. If the wallet provider hasn't caught up yet, it may still return the old (archived) holding, causing the next order to fail.
+```javascript
+import { prepareDepositHoldings, depositFunds } from "@temple-digital-group/temple-canton-js";
 
-**Auto-submit (`returnCommand = false`):** The SDK handles this automatically. If a stale holding error is detected, it waits for the provider to sync and retries up to 3 times.
+const depositOpts = await prepareDepositHoldings(100, "USDCx");
+const result = await depositFunds(depositOpts);
+```
 
-**Manual submit (`returnCommand = true`):** You are responsible for handling stale holdings. `createOrderProposal` returns a `holdingContractId` — the contract ID of the holding that was selected. You can poll until it disappears from the provider's active contracts:
+### 3. Trading Balance
 
 ```javascript
-import { createOrderProposal, getAmuletHoldingsForParty } from "@temple-digital-group/temple-canton-js";
+import { getTradingBalance } from "@temple-digital-group/temple-canton-js";
 
-const { command, holdingContractId } = await createOrderProposal(orderArgs, true);
-const result = await walletProvider.submitTransaction(command);
+const balances = await getTradingBalance();
+// Returns { balances: [{ asset, unlocked, locked, in_flight, ... }] }
+```
 
-// Poll until the provider catches up before creating next order
-async function waitForProviderSync(contractId, party, provider, interval = 500, maxAttempts = 20) {
-	for (let i = 0; i < maxAttempts; i++) {
-		const holdings = await getAmuletHoldingsForParty(party, false, provider);
-		const stillActive = holdings?.some((h) => h.contractEntry?.JsActiveContract?.createdEvent?.contractId === contractId);
-		if (!stillActive) return true; // Provider caught up
-		await new Promise((r) => setTimeout(r, interval));
-	}
-	return false; // Timed out
-}
+Use this to check available funds before placing orders or withdrawals.
 
-await waitForProviderSync(holdingContractId, party, walletProvider);
-// Safe to create next order
-```
+### 4. Place Orders
 
-> `holdingContractId` is included in success responses, error responses, and `returnCommand` responses.
+```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",
+});
 
-### Get Orders and Proposals
+// 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 { getOrdersForParty, getOrderProposalsForParty } from "@temple-digital-group/temple-canton-js";
+import { cancelOrder, cancelAllOrders } from "@temple-digital-group/temple-canton-js";
+
+// Cancel a specific order
+await cancelOrder("ord_abc123");
 
-const orders = await getOrdersForParty(partyId);
-const proposals = await getOrderProposalsForParty(partyId);
+// Cancel all orders for a symbol
+await cancelAllOrders({ symbol: "CC/USDCx" });
+
+// Cancel ALL orders
+await cancelAllOrders();
 ```
 
-### REST API (Optional) — Market Data and Orders
+### 6. Withdraw Funds
 
-The REST API functions are optional. If you pass `API_EMAIL`/`API_PASSWORD` in `initialize()`, the SDK authenticates at init time. You can also call `login()` directly.
+Withdraws available (unlocked, non-in-flight) trading balance back to the user's wallet.
 
 ```javascript
-import { initialize, getTicker, getOrderBook, getActiveOrders, cancelOrder } from "@temple-digital-group/temple-canton-js";
+import { withdrawFunds } from "@temple-digital-group/temple-canton-js";
 
-await initialize({
-	NETWORK: "mainnet",
-	API_EMAIL: "user@example.com",
-	API_PASSWORD: "password",
+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);
+```
 
-// Market data
-const ticker = await getTicker("CC/USDCx");
-const book = await getOrderBook("CC/USDCx", { levels: 10 });
+### Get User Balances
 
-// Orders
-const orders = await getActiveOrders({ symbol: "CC/USDCx" });
-const result = await cancelOrder("order-id-123");
+```javascript
+import { getUserBalances } from "@temple-digital-group/temple-canton-js";
 
-// All functions return { error: true, status, code, message } on failure
-if (result.error) {
-	console.log(`Failed: ${result.message}`);
+// 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: { ... }
 }
 ```
 
@@ -256,7 +237,7 @@ if (result.error) {
 ```javascript
 import { mergeAmuletHoldingsForParty, mergeUtilityHoldingsForParty, getAmuletDisclosures, getUtxoCount } from "@temple-digital-group/temple-canton-js";
 
-// Custom Validator (server-side)
+// Merge all Amulet or utility holdings
 await mergeAmuletHoldingsForParty(partyId);
 await mergeUtilityHoldingsForParty(partyId, "USDCx");
 
@@ -269,24 +250,107 @@ 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 — confirm the order amount is now covered
+// Check UTXO status after merge
 const counts = await getUtxoCount(partyId, "USDCx", walletProvider);
-// { total: 5, unlocked: 1, locked: 4, largestUnlocked: 27.26, unlockedBalance: 27.26 }
-if (counts.largestUnlocked >= requiredAmount) {
-	// Safe to retry createOrderProposal
-}
+```
+
+## 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. All other functions require a custom validator (ledger access via `VALIDATOR_API_URL` and `JWT_TOKEN`).
+> 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 |
-| `setJWTToken(token)`        | Update the JWT token without re-initializing the config                       |
 | `setWalletAdapter(adapter)` | Set or update the Loop SDK instance for all wallet-aware functions            |
 
 ### Instrument Catalog
@@ -296,45 +360,51 @@ if (counts.largestUnlocked >= requiredAmount) {
 | `getSupportedTradingPairs()` | Get the list of supported trading pairs |
 | `getInstrumentCatalog()`     | Get the full instrument catalog         |
 
-### Holdings
+### 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                                                    |
-| ----------------------------------------------------------------- | -------- | -------------------------------------------------------------- |
-| `getUserBalances(party?, provider?)`                              | **W**    | Get all balances grouped by asset (CC, locked CC, and utility) |
-| `getAmuletHoldingsForParty(party, returnCommand, provider)`      | **W**    | Get CC holdings                                                |
-| `getLockedAmuletHoldingsForParty(party, returnCommand, provider)`| **W**    | Get locked CC 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 |
+### Deposits & Withdrawals
 
-### Orders
+| 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                 |
-| ------------------------------------- | -------- | --------------------------- |
-| `createOrderProposal(orderArguments)` | **W**    | Create an order proposal    |
-| `getOrderProposalsForParty(party)`    |          | Get pending order proposals |
-| `getOrdersForParty(party)`            |          | Get active orders           |
+| 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 CC 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 |
-| `splitAmuletHoldingForParty(party, outputQuantity)`                                        |          | Split a CC holding          |
-| `unlockLockedAmulets(party)`                                                               |          | Unlock locked CC holdings   |
 
-### Temple REST API (Optional)
+### Temple REST API
 
-> These functions call the Temple public REST API and are entirely optional. Pass `API_EMAIL`/`API_PASSWORD` in `initialize()`, or call `login()` directly — tokens are stored and auto-refreshed.
+> These functions call the Temple REST API. Pass `API_KEY` in `initialize()` or call `setApiKey()` to authenticate.
 
 #### Auth
 
-| Function                            | Description                                         |
-| ----------------------------------- | --------------------------------------------------- |
-| `login(email, password)`            | Login and store access/refresh tokens and user profile |
-| `refreshAccessToken(refreshToken?)` | Refresh the access token (auto-called when expired)    |
-| `logout()`                          | Clear stored tokens                                    |
-| `getUserId()`                       | Get the stored user ID from login (used automatically by `createOrderProposal`) |
+| Function         | Description                                 |
+| ---------------- | ------------------------------------------- |
+| `setApiKey(key)` | Set the API key for REST API authentication |
+| `getUserId()`    | Get the stored user ID                      |
 
 #### Market Data
 
@@ -346,16 +416,42 @@ if (counts.largestUnlocked >= requiredAmount) {
 | `getOpenInterest(symbol)`           | Get open interest for a trading pair                      |
 | `getRecentTrades(symbol, options?)` | Get recent trades (options: `limit`, max 500)             |
 
-#### Orders
-
-| Function                    | Description                                    |
-| --------------------------- | ---------------------------------------------- |
-| `getActiveOrders(options?)` | Get active orders (options: `symbol`, `limit`) |
-| `cancelOrder(orderId)`      | Cancel a specific order                        |
-| `cancelAllOrders(options?)` | Cancel all orders (options: `symbol` filter)   |
-
-#### Disclosures
-
-| Function                  | Description                                                                     |
-| ------------------------- | ------------------------------------------------------------------------------- |
-| `getDisclosures(partyId)` | Get CC disclosure data (amulet rules, open mining rounds, external party rules) |
+#### 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)|