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

package/README.md

@@ -1,361 +1,361 @@
-# Temple Canton JS
-
-JavaScript SDK for interacting with the Temple Canton blockchain exchange. Supports CC, USDCx, and CBTC tokens on the Canton network.
-
-## Installation
-
-```bash
-npm install @temple-digital-group/temple-canton-js
-```
-
-## Configuration
-
-Call `initialize()` before using any SDK functions. It sets up the config and optionally authenticates with the Temple REST API.
-
-### 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.
-
-- **Server-side:** uses `loop.executeTransaction()` (signs locally with private key)
-- **Client-side:** uses `loop.provider.submitTransaction()` (delegates signing to Loop Wallet via WebSocket)
-
-```javascript
-import { initialize, createOrderProposal } 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:
-
-```javascript
-import { setWalletAdapter } from "@temple-digital-group/temple-canton-js";
-
-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.
-
-## Supported Instruments
-
-| Asset | Type        | Networks         |
-| ----- | ----------- | ---------------- |
-| CC    | Canton Coin | testnet, mainnet |
-| USDCx | Utility     | testnet, mainnet |
-| CBTC  | Utility     | testnet, mainnet |
-
-## Supported Trading Pairs
-
-- `CC/USDCx`
-- `CBTC/USDCx`
-
-## Usage
-
-### Get User Balances
-
-```javascript
-import { getUserBalances } from "@temple-digital-group/temple-canton-js";
-
-// Both params are optional — falls back to wallet adapter / config
-const balances = await getUserBalances();
-
-// Or pass explicitly
-const balances = await getUserBalances(partyId);
-const balances = await getUserBalances(partyId, walletProvider);
-```
-
-Each entry in the returned array contains:
-
-```javascript
-{
-  asset: 'USDCx',              // 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)
-}
-```
-
-> **Note:** `utilityContext` is only resolved when using a custom validator (ledger API access). When using a wallet provider, it will be `null`.
-
-### Create an Order
-
-```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, // Optional if authenticated via REST API — auto-resolved from login
-	orderType: "limit",
-});
-```
-
-#### Handling Stale Holdings (Wallet Provider)
-
-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.
-
-**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.
-
-**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:
-
-```javascript
-import { createOrderProposal, getAmuletHoldingsForParty } from "@temple-digital-group/temple-canton-js";
-
-const { command, holdingContractId } = await createOrderProposal(orderArgs, true);
-const result = await walletProvider.submitTransaction(command);
-
-// 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
-}
-
-await waitForProviderSync(holdingContractId, party, walletProvider);
-// Safe to create next order
-```
-
-> `holdingContractId` is included in success responses, error responses, and `returnCommand` responses.
-
-### Get Orders and Proposals
-
-```javascript
-import { getOrdersForParty, getOrderProposalsForParty } from "@temple-digital-group/temple-canton-js";
-
-const orders = await getOrdersForParty(partyId);
-const proposals = await getOrderProposalsForParty(partyId);
-```
-
-### REST API (Optional) — Market Data and Orders
-
-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.
-
-```javascript
-import { initialize, getTicker, getOrderBook, getActiveOrders, cancelOrder } from "@temple-digital-group/temple-canton-js";
-
-await initialize({
-	NETWORK: "mainnet",
-	API_EMAIL: "user@example.com",
-	API_PASSWORD: "password",
-});
-
-// Market data
-const ticker = await getTicker("CC/USDCx");
-const book = await getOrderBook("CC/USDCx", { levels: 10 });
-
-// Orders
-const orders = await getActiveOrders({ symbol: "CC/USDCx" });
-const result = await cancelOrder("order-id-123");
-
-// All functions return { error: true, status, code, message } on failure
-if (result.error) {
-	console.log(`Failed: ${result.message}`);
-}
-```
-
-### Merge Holdings
-
-```javascript
-import { mergeAmuletHoldingsForParty, mergeUtilityHoldingsForParty, getAmuletDisclosures, getUtxoCount } from "@temple-digital-group/temple-canton-js";
-
-// Custom Validator (server-side)
-await mergeAmuletHoldingsForParty(partyId);
-await mergeUtilityHoldingsForParty(partyId, "USDCx");
-
-// Wallet Provider — merge up to 5 smallest USDCx UTXOs
-const command = await mergeUtilityHoldingsForParty(partyId, "USDCx", true, walletProvider, 5);
-const result = await walletProvider.submitTransaction(command);
-
-// Wallet Provider — merge CC (requires disclosures)
-const disclosures = await getAmuletDisclosures(partyId);
-const cmd = await mergeAmuletHoldingsForParty(partyId, true, walletProvider, 5, disclosures);
-const res = await walletProvider.submitTransaction(cmd);
-
-// Check UTXO status after merge — confirm the order amount is now covered
-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`).
-
-### 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
-
-| Function                     | Description                             |
-| ---------------------------- | --------------------------------------- |
-| `getSupportedTradingPairs()` | Get the list of supported trading pairs |
-| `getInstrumentCatalog()`     | Get the full instrument catalog         |
-
-### 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                                         |
-| `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
-
-| Function                              | Provider | Description                 |
-| ------------------------------------- | -------- | --------------------------- |
-| `createOrderProposal(orderArguments)` | **W**    | Create an order proposal    |
-| `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 (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.
-
-#### 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`) |
-
-#### Market Data
-
-| Function                            | Description                                               |
-| ----------------------------------- | --------------------------------------------------------- |
-| `getTicker(symbol?)`                | Get ticker data for one or all trading pairs              |
-| `getOrderBook(symbol, options?)`    | Get the order book (options: `levels`, `precision`)       |
-| `getSymbolConfig(symbol)`           | Get symbol configuration (paused, decimals, min quantity) |
-| `getOpenInterest(symbol)`           | Get open interest for a trading pair                      |
-| `getRecentTrades(symbol, options?)` | Get recent trades (options: `limit`, max 500)             |
-
-#### 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) |
+# Temple Canton JS
+
+JavaScript SDK for interacting with the Temple Canton blockchain exchange. Supports CC, USDCx, and CBTC tokens on the Canton network.
+
+## Installation
+
+```bash
+npm install @temple-digital-group/temple-canton-js
+```
+
+## Configuration
+
+Call `initialize()` before using any SDK functions. It sets up the config and optionally authenticates with the Temple REST API.
+
+### 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.
+
+- **Server-side:** uses `loop.executeTransaction()` (signs locally with private key)
+- **Client-side:** uses `loop.provider.submitTransaction()` (delegates signing to Loop Wallet via WebSocket)
+
+```javascript
+import { initialize, createOrderProposal } 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:
+
+```javascript
+import { setWalletAdapter } from "@temple-digital-group/temple-canton-js";
+
+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.
+
+## Supported Instruments
+
+| Asset | Type        | Networks         |
+| ----- | ----------- | ---------------- |
+| CC    | Canton Coin | testnet, mainnet |
+| USDCx | Utility     | testnet, mainnet |
+| CBTC  | Utility     | testnet, mainnet |
+
+## Supported Trading Pairs
+
+- `CC/USDCx`
+- `CBTC/USDCx`
+
+## Usage
+
+### Get User Balances
+
+```javascript
+import { getUserBalances } from "@temple-digital-group/temple-canton-js";
+
+// Both params are optional — falls back to wallet adapter / config
+const balances = await getUserBalances();
+
+// Or pass explicitly
+const balances = await getUserBalances(partyId);
+const balances = await getUserBalances(partyId, walletProvider);
+```
+
+Each entry in the returned array contains:
+
+```javascript
+{
+  asset: 'USDCx',              // 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)
+}
+```
+
+> **Note:** `utilityContext` is only resolved when using a custom validator (ledger API access). When using a wallet provider, it will be `null`.
+
+### Create an Order
+
+```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, // Optional if authenticated via REST API — auto-resolved from login
+	orderType: "limit",
+});
+```
+
+#### Handling Stale Holdings (Wallet Provider)
+
+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.
+
+**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.
+
+**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:
+
+```javascript
+import { createOrderProposal, getAmuletHoldingsForParty } from "@temple-digital-group/temple-canton-js";
+
+const { command, holdingContractId } = await createOrderProposal(orderArgs, true);
+const result = await walletProvider.submitTransaction(command);
+
+// 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
+}
+
+await waitForProviderSync(holdingContractId, party, walletProvider);
+// Safe to create next order
+```
+
+> `holdingContractId` is included in success responses, error responses, and `returnCommand` responses.
+
+### Get Orders and Proposals
+
+```javascript
+import { getOrdersForParty, getOrderProposalsForParty } from "@temple-digital-group/temple-canton-js";
+
+const orders = await getOrdersForParty(partyId);
+const proposals = await getOrderProposalsForParty(partyId);
+```
+
+### REST API (Optional) — Market Data and Orders
+
+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.
+
+```javascript
+import { initialize, getTicker, getOrderBook, getActiveOrders, cancelOrder } from "@temple-digital-group/temple-canton-js";
+
+await initialize({
+	NETWORK: "mainnet",
+	API_EMAIL: "user@example.com",
+	API_PASSWORD: "password",
+});
+
+// Market data
+const ticker = await getTicker("CC/USDCx");
+const book = await getOrderBook("CC/USDCx", { levels: 10 });
+
+// Orders
+const orders = await getActiveOrders({ symbol: "CC/USDCx" });
+const result = await cancelOrder("order-id-123");
+
+// All functions return { error: true, status, code, message } on failure
+if (result.error) {
+	console.log(`Failed: ${result.message}`);
+}
+```
+
+### Merge Holdings
+
+```javascript
+import { mergeAmuletHoldingsForParty, mergeUtilityHoldingsForParty, getAmuletDisclosures, getUtxoCount } from "@temple-digital-group/temple-canton-js";
+
+// Custom Validator (server-side)
+await mergeAmuletHoldingsForParty(partyId);
+await mergeUtilityHoldingsForParty(partyId, "USDCx");
+
+// Wallet Provider — merge up to 5 smallest USDCx UTXOs
+const command = await mergeUtilityHoldingsForParty(partyId, "USDCx", true, walletProvider, 5);
+const result = await walletProvider.submitTransaction(command);
+
+// Wallet Provider — merge CC (requires disclosures)
+const disclosures = await getAmuletDisclosures(partyId);
+const cmd = await mergeAmuletHoldingsForParty(partyId, true, walletProvider, 5, disclosures);
+const res = await walletProvider.submitTransaction(cmd);
+
+// Check UTXO status after merge — confirm the order amount is now covered
+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`).
+
+### 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
+
+| Function                     | Description                             |
+| ---------------------------- | --------------------------------------- |
+| `getSupportedTradingPairs()` | Get the list of supported trading pairs |
+| `getInstrumentCatalog()`     | Get the full instrument catalog         |
+
+### 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                                         |
+| `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
+
+| Function                              | Provider | Description                 |
+| ------------------------------------- | -------- | --------------------------- |
+| `createOrderProposal(orderArguments)` | **W**    | Create an order proposal    |
+| `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 (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.
+
+#### 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`) |
+
+#### Market Data
+
+| Function                            | Description                                               |
+| ----------------------------------- | --------------------------------------------------------- |
+| `getTicker(symbol?)`                | Get ticker data for one or all trading pairs              |
+| `getOrderBook(symbol, options?)`    | Get the order book (options: `levels`, `precision`)       |
+| `getSymbolConfig(symbol)`           | Get symbol configuration (paused, decimals, min quantity) |
+| `getOpenInterest(symbol)`           | Get open interest for a trading pair                      |
+| `getRecentTrades(symbol, options?)` | Get recent trades (options: `limit`, max 500)             |
+
+#### 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) |