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

package/README.md

@@ -22,7 +22,8 @@ For apps using Loop Wallet. Pass the Loop SDK instance as `WALLET_ADAPTER` — t
 ```javascript
 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
 });
@@ -38,19 +39,19 @@ setWalletAdapter(loop);
 
 | Key              | Required | Description                                                     |
 | ---------------- | -------- | --------------------------------------------------------------- |
-| `NETWORK`        | Yes      | `mainnet`, `testnet`, or `localhost`                            |
+| `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 |
-| `API_KEY`        | No       | Temple REST API key for authenticated endpoints                 |
 
 ## 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`).
+> **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
 
@@ -65,7 +66,7 @@ The v2 flow covers the full trading lifecycle: onboarding, deposits, trading, an
 1. Check onboarding   →  isUserOnboarded(party)
    If NOT onboarded   →  onboardUser(party)
 
-2. Deposit funds      →  depositFunds({ sender, assetId, amount, holdingCids, ... })
+2. Deposit funds      →  deposit(amount, symbol)
 
 3. Check balance      →  getTradingBalance()
 
@@ -87,41 +88,40 @@ import { isUserOnboarded, onboardUser } from "@temple-digital-group/temple-canto
 
 const delegation = await isUserOnboarded(party);
 if (!delegation) {
-	await onboardUser(party);
+	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
 
-Deposit funds into the user's trading balance. Use `prepareDepositHoldings` to resolve the holdings for the deposit amount.
+The simplest way to deposit is the `deposit()` helper — pass the amount and symbol, and it handles everything:
 
 ```javascript
-import { prepareDepositHoldings, depositFunds } from "@temple-digital-group/temple-canton-js";
-
-// Prepare holdings for the deposit
-const depositOpts = await prepareDepositHoldings(100, "USDCx");
+import { deposit } from "@temple-digital-group/temple-canton-js";
 
-// Submit the deposit
-const result = await depositFunds(depositOpts);
+const result = await deposit(100, "USDCx");
+// or
+const result = await deposit(10, "CC");
 ```
 
-`depositFunds` accepts:
+`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:
 
-| 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)               |
+```javascript
+import { prepareDepositHoldings, depositFunds } from "@temple-digital-group/temple-canton-js";
 
-For Amulet deposits, the SDK fetches disclosures automatically. You can also pass them manually via `opts.disclosures`.
+const depositOpts = await prepareDepositHoldings(100, "USDCx");
+const result = await depositFunds(depositOpts);
+```
 
 ### 3. Trading Balance
 
@@ -132,18 +132,29 @@ 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: "Amulet/USDCx",
+	symbol: "CC/USDCx",
 	side: "buy",
 	quantity: 10.5,
 	price: 1.25,
 	order_type: "limit",
-	expires_at: new Date(Date.now() + 24 * 60 * 60 * 1000).toISOString(),
+});
+
+// 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",
 });
 ```
 
@@ -153,10 +164,10 @@ const result = await createOrderRequest({
 import { cancelOrder, cancelAllOrders } from "@temple-digital-group/temple-canton-js";
 
 // Cancel a specific order
-await cancelOrder("order-id-123");
+await cancelOrder("ord_abc123");
 
 // Cancel all orders for a symbol
-await cancelAllOrders({ symbol: "Amulet/USDCx" });
+await cancelAllOrders({ symbol: "CC/USDCx" });
 
 // Cancel ALL orders
 await cancelAllOrders();
@@ -221,8 +232,6 @@ Each entry in the returned array contains:
 }
 ```
 
-
-
 ### Merge Holdings
 
 ```javascript
@@ -245,6 +254,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.
@@ -265,36 +362,37 @@ 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                                           |
+| ----------------------------------------- | -------- | ----------------------------------------------------- |
+| `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 |
+| 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
@@ -303,10 +401,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
 
@@ -320,24 +418,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/api/index.d.ts

@@ -1,13 +1,12 @@
 import type { ApiError, Ticker, OrderBook, OrderBookOptions, SymbolConfig, OpenInterest, Trade, RecentTradesOptions, ActiveOrder, ActiveOrdersOptions, CancelOrderResponse, CancelAllOrdersOptions, CancelAllOrdersResponse, CreateOrderRequestOpts, CreateOrderRequestResponse, DelegationResponse, WithdrawalResponse, WithdrawalStatusResponse, TradingBalanceResponse, AmuletDisclosure, DisclosuresResponse } from "./types.js";
 export type { ApiError, Ticker, OrderBook, OrderBookOptions, SymbolConfig, OpenInterest, Trade, RecentTradesOptions, ActiveOrder, ActiveOrdersOptions, CancelOrderResponse, CancelAllOrdersOptions, CancelAllOrdersResponse, CreateOrderRequestResponse, DelegationResponse, WithdrawalResponse, WithdrawalStatusResponse, TradingBalanceResponse, AmuletDisclosure, DisclosuresResponse, };
-export { setApiKey, getUserId } from "./tokenStore.js";
+export { getUserId } from "./tokenStore.js";
 export { setWalletAdapter } from "../../src/config/index.js";
 /**
- * Initialize the Temple SDK — sets config and authenticates with the REST API via API key.
- *
- * @returns null (config-only init). Throws no errors.
+ * Initialize the Temple SDK.
+ * API_KEY is required. Throws if not provided.
  */
-export declare function initialize(cfg: Record<string, unknown>): Promise<null>;
+export declare function initialize(cfg: Record<string, unknown>): void;
 /**
  * Get ticker data for one or all trading pairs.
  * @param symbol - Optional symbol filter (e.g., "Amulet/USDCx")

package/dist/api/index.js

@@ -1,28 +1,25 @@
 import axios from "axios";
 import config, { initializeConfig, setWalletAdapter } from "../../src/config/index.js";
-import { getApiKey, setApiKey as setApiKeyFromConfig, getAuthHeader, setUserId, } from "./tokenStore.js";
-export { setApiKey, getUserId } from "./tokenStore.js";
+import { getAuthHeader, setUserId, } from "./tokenStore.js";
+export { getUserId } from "./tokenStore.js";
 export { setWalletAdapter } from "../../src/config/index.js";
 // ── Initialization ──
 /**
- * Initialize the Temple SDK — sets config and authenticates with the REST API via API key.
- *
- * @returns null (config-only init). Throws no errors.
+ * Initialize the Temple SDK.
+ * API_KEY is required. Throws if not provided.
  */
-export async function initialize(cfg) {
+export function initialize(cfg) {
+    if (!cfg.API_KEY) {
+        throw new Error("initialize: API_KEY is required.");
+    }
     initializeConfig(cfg);
     if (cfg.WALLET_ADAPTER) {
         setWalletAdapter(cfg.WALLET_ADAPTER);
     }
-    const apiKey = cfg.API_KEY;
-    if (apiKey) {
-        setApiKeyFromConfig(apiKey);
-    }
     const userIdValue = cfg.USER_ID;
     if (userIdValue) {
         setUserId(userIdValue);
     }
-    return null;
 }
 // ── Internal helpers ──
 function handleApiError(error, context) {
@@ -37,14 +34,9 @@ function handleApiError(error, context) {
     return { error: true, status, code, message };
 }
 function ensureAuthenticated() {
-    // API key from config if not already set
-    const configApiKey = config.API_KEY;
-    if (!getApiKey() && configApiKey) {
-        setApiKeyFromConfig(configApiKey);
-    }
-    if (getApiKey())
+    if (config.API_KEY)
         return null;
-    return { error: true, status: 401, code: "NOT_AUTHENTICATED", message: "API key required. Pass API_KEY in initialize() or call setApiKey()." };
+    return { error: true, status: 401, code: "NOT_AUTHENTICATED", message: "API key required. Pass API_KEY in initialize()." };
 }
 async function authenticatedGet(path, params) {
     const authError = ensureAuthenticated();
@@ -204,12 +196,14 @@ export async function getDelegation() {
  * @param opts - Order parameters: symbol, side, quantity, price, order_type, expires_at
  */
 export async function createOrderRequest(opts) {
-    const { symbol: rawSymbol, side, quantity, price, order_type = "limit", expires_at } = opts || {};
+    const { symbol: rawSymbol, side, quantity, price, order_type = "limit", order_subtype, expires_at } = opts || {};
     if (!rawSymbol || !side || quantity == null || price == null) {
         return { error: true, status: null, code: "INVALID_PARAMS", message: "symbol, side, quantity, and price are required." };
     }
     const symbol = normalizeSymbol(rawSymbol);
     const body = { symbol, side, quantity: Number(quantity), price: Number(price), order_type };
+    if (order_subtype)
+        body.order_subtype = order_subtype;
     if (expires_at)
         body.expires_at = expires_at;
     return authenticatedPost("/api/trading/orders", body);

package/dist/api/tokenStore.d.ts

@@ -8,15 +8,7 @@ export declare function getUserId(): string | null;
  */
 export declare function setUserId(id: string): void;
 /**
- * Set an API key for authentication.
- */
-export declare function setApiKey(key: string): void;
-/**
- * Get the stored API key, or null if not set.
- */
-export declare function getApiKey(): string | null;
-/**
- * Get the authorization header using the API key.
- * Returns null if no API key is set.
+ * Get the authorization header using the API key from config.
+ * Returns null if no API key is configured.
  */
 export declare function getAuthHeader(): AuthHeaders | null;

package/dist/api/tokenStore.js

@@ -1,4 +1,4 @@
-let apiKey = null;
+import config from "../../src/config/index.js";
 let userId = null;
 /**
  * Get the stored user ID, or null if not set.
@@ -13,24 +13,13 @@ export function setUserId(id) {
     userId = id;
 }
 /**
- * Set an API key for authentication.
- */
-export function setApiKey(key) {
-    apiKey = key;
-}
-/**
- * Get the stored API key, or null if not set.
- */
-export function getApiKey() {
-    return apiKey;
-}
-/**
- * Get the authorization header using the API key.
- * Returns null if no API key is set.
+ * Get the authorization header using the API key from config.
+ * Returns null if no API key is configured.
  */
 export function getAuthHeader() {
+    const apiKey = config.API_KEY;
     if (apiKey) {
-        return { Authorization: `Bearer ${apiKey}` };
+        return { "X-API-Key": apiKey };
     }
     return null;
 }

package/dist/api/types.d.ts

@@ -96,6 +96,7 @@ export interface CreateOrderRequestOpts {
     quantity: number;
     price: number;
     order_type?: string;
+    order_subtype?: "post_only";
     expires_at?: string;
 }
 export interface CreateOrderRequestResponse {
@@ -145,5 +146,5 @@ export interface ApiError {
     message: string;
 }
 export interface AuthHeaders {
-    Authorization: string;
+    "X-API-Key": string;
 }

package/dist/canton/deposits.d.ts

@@ -0,0 +1,52 @@
+export interface DepositFundsOpts {
+    sender: string;
+    receiver?: string;
+    assetId: string;
+    amount: string | number;
+    holdingCids?: string[];
+    settlementId?: string;
+    transferLegId?: string;
+    allocateBefore?: string;
+    settleBefore?: string;
+    disclosures?: Record<string, unknown>;
+    userId?: string;
+}
+export interface PreparedDeposit {
+    sender: string;
+    receiver: string;
+    assetId: string;
+    amount: string;
+    holdingCids: string[];
+}
+/**
+ * Prepare holdings for a deposit by selecting UTXOs from the wallet provider.
+ *
+ * Queries the provider for holdings, filters and sorts them, then greedily
+ * selects until the requested amount is covered.
+ */
+export declare function prepareDepositHoldings(amount: number | string, symbol: string): Promise<PreparedDeposit | {
+    error: string;
+    data?: Record<string, unknown>;
+}>;
+/**
+ * High-level deposit helper.
+ *
+ * Wraps `prepareDepositHoldings` and `depositFunds` into a single call.
+ * Validates the user has sufficient balance and reserves 10 CC for transaction fees.
+ *
+ * Requires:
+ * - Wallet adapter (for reading balances and submitting)
+ * - API connection (for disclosures on Amulet deposits)
+ */
+export declare function deposit(amount: number | string, symbol: string): Promise<Record<string, unknown>>;
+/**
+ * Create a CIP-56 Allocation.
+ * Fetches the AllocationFactory, then exercises AllocationFactory_Allocate
+ * to lock holdings for a settlement leg.
+ *
+ * Three resolution paths:
+ * 1. Localhost: resolve factory and context from ledger directly
+ * 2. Amulet via disclosures (FE/proxy path — no Scan API access)
+ * 3. Remote: Scan API / Registry API
+ */
+export declare function depositFunds(opts: DepositFundsOpts, returnCommand?: boolean): Promise<Record<string, unknown>>;