@temple-digital-group/temple-canton-js 1.0.39-beta.0 → 1.0.39-beta.2

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
 
@@ -49,7 +49,7 @@ await initialize({
 	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_EMAIL: "user@example.com",
 	API_PASSWORD: "password",
 });
 ```
@@ -57,19 +57,19 @@ await initialize({
 | 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                |
+| `VALIDATOR_API_URL`       | No       | Base URL of the Canton validator ledger API          |
+| `VALIDATOR_SCAN_API_URL`  | No       | Base URL of the Canton Scan API                      |
+| `VALIDATOR_USER_PARTY_ID` | No       | The user's party ID on the network                   |
+| `JWT_TOKEN`               | No\*     | Pre-authenticated JWT token for ledger API calls     |
+| `AUTH0_TOKEN_URL`         | No\*     | Auth0 OAuth token endpoint                           |
+| `AUTH0_CLIENT_ID`         | No\*     | Auth0 application client ID                          |
+| `AUTH0_CLIENT_SECRET`     | No\*     | Auth0 application client secret                      |
+| `AUTH0_AUDIENCE`          | No\*     | Auth0 API audience identifier                        |
+| `AUTH0_USER_ID`           | No\*     | 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.
+\* Provide either `JWT_TOKEN` (browser) or the `AUTH0_*` fields (server-side). The SDK fetches and caches JWT tokens automatically when Auth0 credentials are provided. Only needed when using a custom validator.
 
 To update the JWT token later without re-initializing:
 
@@ -87,18 +87,12 @@ 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({
 	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:
@@ -120,137 +114,218 @@ setWalletAdapter(loop);
 
 ## Supported Instruments
 
-| Asset | Type        | Networks         |
-| ----- | ----------- | ---------------- |
-| CC    | Canton Coin | testnet, mainnet |
-| USDCx | Utility     | testnet, mainnet |
-| CBTC  | Utility     | testnet, mainnet |
+| Asset  | Type        | Networks         |
+| ------ | ----------- | ---------------- |
+| CC     | Canton Coin | testnet, mainnet |
+| USDCx  | Utility     | testnet, mainnet |
+| CBTC   | Utility     | testnet, mainnet |
+
+> **Symbol normalization:** `CC` is automatically normalized to `Amulet` in all API methods that accept a symbol (e.g. `CC/USDCx` becomes `Amulet/USDCx`).
 
 ## 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      →  depositFunds({ sender, assetId, amount, holdingCids, ... })
 
-// 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) {
+	await onboardUser(party);
 }
 ```
 
-> **Note:** `utilityContext` is only resolved when using a custom validator (ledger API access). When using a wallet provider, it will be `null`.
+### 2. Deposit Funds
 
-### Create an Order
+Deposit funds into the user's trading balance. Use `prepareDepositHoldings` to resolve the holdings for the deposit amount.
 
 ```javascript
-import { createOrderProposal } from "@temple-digital-group/temple-canton-js";
+import { prepareDepositHoldings, depositFunds } 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",
-});
+// Prepare holdings for the deposit
+const depositOpts = await prepareDepositHoldings(100, "USDCx");
+
+// Submit the deposit
+const result = await depositFunds(depositOpts);
 ```
 
-#### Handling Stale Holdings (Wallet Provider)
+`depositFunds` accepts:
 
-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.
+| 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       | Ledger API user ID (falls back to wallet adapter / config)    |
 
-**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.
+For Amulet deposits without direct ledger or Scan API access, the SDK fetches disclosures from `/api/amulet/disclosures` automatically. You can also pass them manually via `opts.disclosures`.
 
-**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
-}
+### 4. Place Orders
+
+```javascript
+import { createOrderRequest } from "@temple-digital-group/temple-canton-js";
+
+const result = await createOrderRequest({
+	symbol: "Amulet/USDCx",
+	side: "buy",
+	quantity: 10.5,
+	price: 1.25,
+	order_type: "limit",
+	expires_at: new Date(Date.now() + 24 * 60 * 60 * 1000).toISOString(),
+});
+```
 
-await waitForProviderSync(holdingContractId, party, walletProvider);
-// Safe to create next order
+### 5. Cancel Orders
+
+```javascript
+import { cancelOrder, cancelAllOrders } from "@temple-digital-group/temple-canton-js";
+
+// Cancel a specific order
+await cancelOrder("order-id-123");
+
+// Cancel all orders for a symbol
+await cancelAllOrders({ symbol: "Amulet/USDCx" });
+
+// Cancel ALL orders
+await cancelAllOrders();
 ```
 
-> `holdingContractId` is included in success responses, error responses, and `returnCommand` responses.
+### 6. Withdraw Funds
 
-### Get Orders and Proposals
+Withdraws available (unlocked, non-in-flight) trading balance back to the user's wallet.
 
 ```javascript
-import { getOrdersForParty, getOrderProposalsForParty } from "@temple-digital-group/temple-canton-js";
+import { withdrawFunds } from "@temple-digital-group/temple-canton-js";
 
-const orders = await getOrdersForParty(partyId);
-const proposals = await getOrderProposalsForParty(partyId);
+const result = await withdrawFunds({
+	asset_id: "USDCx",
+	amount: "250.50",
+});
 ```
 
-### REST API (Optional) — Market Data and Orders
+### 7. Emergency Withdraw
 
-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.
+Cancels ALL orders, rolls back pending settlements, and withdraws everything immediately.
 
 ```javascript
-import { initialize, getTicker, getOrderBook, getActiveOrders, cancelOrder } from "@temple-digital-group/temple-canton-js";
+import { emergencyWithdrawFunds } from "@temple-digital-group/temple-canton-js";
 
-await initialize({
-	NETWORK: "mainnet",
-	API_EMAIL: "user@example.com",
-	API_PASSWORD: "password",
+const result = await emergencyWithdrawFunds({
+	allocationId: "allocation-contract-id",
+	sender: partyId,
+	assetId: "USDCx",
 });
+```
+
+### 8. Withdraw Delegation
+
+Archives the user's delegation contract. The user must re-onboard to trade again.
 
-// Market data
-const ticker = await getTicker("CC/USDCx");
-const book = await getOrderBook("CC/USDCx", { levels: 10 });
+```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);
+```
+
+## Wallet Balances
+
+### 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: { ... }
 }
 ```
 
+## Legacy Order Creation
+
+> `createOrderProposal` is the legacy on-ledger order creation method. For v2 trading, use `createOrderRequest` instead.
+
+```javascript
+import { createOrderProposal } 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,
+	orderType: "limit",
+});
+```
+
 ### Merge Holdings
 
 ```javascript
@@ -269,17 +344,13 @@ 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
-}
 ```
 
 ## 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
 
@@ -296,17 +367,43 @@ if (counts.largestUnlocked >= requiredAmount) {
 | `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                                                  |
+| ---------------------------------------- | -------- | ------------------------------------------------------------ |
+| `prepareDepositHoldings(amount, assetId)` | **W**   | Resolve holdings for a deposit amount                        |
+| `depositFunds(opts)`                     | **W**    | Deposit funds into the user's trading balance                |
+| `withdrawFunds({ asset_id, amount })`    | **W**    | Withdraw available trading balance back to wallet            |
+| `emergencyWithdrawFunds(opts)`           | **W**    | Cancel all orders and withdraw everything immediately        |
+
 ### Holdings
 
 | Function                                                          | Provider | Description                                                    |
 | ----------------------------------------------------------------- | -------- | -------------------------------------------------------------- |
-| `getUserBalances(party?, provider?)`                              | **W**    | Get all balances grouped by asset (CC, locked CC, and utility) |
-| `getAmuletHoldingsForParty(party, returnCommand, provider)`      | **W**    | Get CC holdings                                                |
-| `getLockedAmuletHoldingsForParty(party, returnCommand, provider)`| **W**    | Get locked CC holdings                                         |
+| `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 |
 
-### Orders
+### 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 |
+| `splitAmuletHoldingForParty(party, outputQuantity)`                                        |          | Split an Amulet holding        |
+| `unlockLockedAmulets(party)`                                                               |          | Unlock locked Amulet holdings  |
+
+### Legacy Orders (On-Ledger)
 
 | Function                              | Provider | Description                 |
 | ------------------------------------- | -------- | --------------------------- |
@@ -314,18 +411,9 @@ if (counts.largestUnlocked >= requiredAmount) {
 | `getOrderProposalsForParty(party)`    |          | Get pending order proposals |
 | `getOrdersForParty(party)`            |          | Get active orders           |
 
-### Holding Operations
-
-| Function                                                                                   | Provider | Description                 |
-| ------------------------------------------------------------------------------------------ | -------- | --------------------------- |
-| `mergeAmuletHoldingsForParty(party, returnCommand, provider, maxUtxos, amuletDisclosures)` | **W**    | Merge CC 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
 
-### Temple REST API (Optional)
-
-> 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_EMAIL`/`API_PASSWORD` in `initialize()`, or call `login()` directly — tokens are stored and auto-refreshed.
 
 #### Auth
 
@@ -334,7 +422,7 @@ if (counts.largestUnlocked >= requiredAmount) {
 | `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`) |
+| `getUserId()`                       | Get the stored user ID from login                      |
 
 #### Market Data
 
@@ -346,16 +434,26 @@ if (counts.largestUnlocked >= requiredAmount) {
 | `getOpenInterest(symbol)`           | Get open interest for a trading pair                      |
 | `getRecentTrades(symbol, options?)` | Get recent trades (options: `limit`, max 500)             |
 
-#### Orders
+#### 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                                    |
-| --------------------------- | ---------------------------------------------- |
-| `getActiveOrders(options?)` | Get active orders (options: `symbol`, `limit`) |
-| `cancelOrder(orderId)`      | Cancel a specific order                        |
-| `cancelAllOrders(options?)` | Cancel all orders (options: `symbol` filter)   |
+| Function                                    | Description                                            |
+| ------------------------------------------- | ------------------------------------------------------ |
+| `createWithdrawalRequest(assetId, amount)`  | Submit a withdrawal request to the backend             |
+| `getWithdrawalRequestStatus(requestId)`     | Poll withdrawal status until ready                     |
 
-#### Disclosures
+#### Disclosures & Delegation
 
 | Function                  | Description                                                                     |
 | ------------------------- | ------------------------------------------------------------------------------- |
-| `getDisclosures(partyId)` | Get CC disclosure data (amulet rules, open mining rounds, external party rules) |
+| `getDisclosures(partyId)` | Get Amulet disclosure data (factory ID, choice context, disclosed contracts)    |
+| `getDelegation()`         | Get the user's delegation contract from the API                                 |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@temple-digital-group/temple-canton-js",
-  "version": "1.0.39-beta.0",
+  "version": "1.0.39-beta.2",
   "description": "JavaScript library for interacting with Temple Canton blockchain",
   "type": "module",
   "main": "index.js",

package/src/canton/index.js

@@ -2847,11 +2847,15 @@ export async function unlockLockedAmulets(party, returnCommand = false) {
  * @param {Object|null} [provider=null] - Optional wallet provider.
  * @returns {Promise<Object>} Object matching depositFunds opts shape, or { error }.
  */
-export async function prepareDepositHoldings(amount, symbol, provider = null) {
-	provider = resolveProvider(provider);
+export async function prepareDepositHoldings(amount, symbol) {
+	const provider = resolveProvider(null);
+	if (!provider && !config.VALIDATOR_SCAN_API_URL) {
+		return { error: "prepareDepositHoldings: wallet provider is required to prepare holdings. Connect a wallet adapter." };
+	}
+
 	const party = getAdapterPartyId() ?? config.VALIDATOR_USER_PARTY_ID;
 	if (!party) {
-		return { error: "prepareDepositHoldings: party ID is required. Set WALLET_ADAPTER or configure VALIDATOR_USER_PARTY_ID." };
+		return { error: "prepareDepositHoldings: party ID is required. Connect a wallet adapter or configure VALIDATOR_USER_PARTY_ID." };
 	}
 
 	// Normalize symbol: CC → Amulet
@@ -2880,6 +2884,10 @@ export async function prepareDepositHoldings(amount, symbol, provider = null) {
 		const createdEvent = h.contractEntry?.JsActiveContract?.createdEvent;
 		if (!createdEvent) continue;
 
+		// Skip asset types that don't match the requested symbol
+		const createdAssetId = createdEvent.createArgument?.instrument?.id || (isAmulet ? "Amulet" : null);
+		if (createdAssetId !== assetId) continue;
+
 		// Skip locked utility holdings
 		if (!isAmulet && createdEvent.createArgument?.lock) continue;
 
@@ -3752,9 +3760,14 @@ export async function isUserOnboarded(user = null, returnCommand = false) {
  */
 export async function getUserBalances(party = null, provider = null) {
 	provider = resolveProvider(provider);
+	if (!provider && !config.VALIDATOR_API_URL) {
+		const msg = "getUserBalances: no provider or API URL configured. Set up a wallet adapter or configure VALIDATOR_API_URL.";
+		console.error(msg);
+		return { error: msg };
+	}
 	party = party ?? getAdapterPartyId() ?? config.VALIDATOR_USER_PARTY_ID;
 	if (!party) {
-		return { error: "Party ID is required. Pass it directly, set WALLET_ADAPTER, or configure VALIDATOR_USER_PARTY_ID." };
+		return { error: "Party ID is required. Pass it directly, connect a wallet adapter, or configure VALIDATOR_USER_PARTY_ID." };
 	}
 	// Get all supported instrument IDs from the catalog
 	const supportedInstruments = new Set(Object.keys(instrumentCatalog));