@temple-digital-group/temple-canton-js 2.0.0-beta.5 → 2.0.0-beta.7

package/README.md

@@ -51,7 +51,7 @@ setWalletAdapter(loop);
 | 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
 
@@ -66,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()
 
@@ -98,35 +98,30 @@ if (!delegation) {
 
 ### 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
 
@@ -144,14 +139,21 @@ Use this to check available funds before placing orders or withdrawals.
 ```javascript
 import { createOrderRequest } from "@temple-digital-group/temple-canton-js";
 
+// Single order
 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(),
 });
+
+// Batch orders (max 20)
+const batchResult = await createOrderRequest([
+	{ symbol: "CC/USDCx", side: "buy", quantity: 100, price: 1.25, order_type: "limit" },
+	{ symbol: "CC/USDCx", side: "sell", quantity: 50, price: 1.50, order_type: "limit" },
+]);
+// Returns { success, request_ids, count, message }
 ```
 
 ### 5. Cancel Orders
@@ -159,11 +161,15 @@ const result = await createOrderRequest({
 ```javascript
 import { cancelOrder, cancelAllOrders } from "@temple-digital-group/temple-canton-js";
 
-// Cancel a specific order
-await cancelOrder("order-id-123");
+// Cancel a single order
+await cancelOrder("ord_abc123");
+
+// Cancel multiple orders (max 20)
+await cancelOrder(["ord_abc123", "ord_def456", "ord_ghi789"]);
+// Returns { success, canceled, already_queued, not_found, message }
 
 // Cancel all orders for a symbol
-await cancelAllOrders({ symbol: "Amulet/USDCx" });
+await cancelAllOrders({ symbol: "CC/USDCx" });
 
 // Cancel ALL orders
 await cancelAllOrders();
@@ -368,8 +374,9 @@ const unsubOrder = ws.onUserEvent("user_order", (data) => { ... });
 
 | Function                                  | Provider | Description                                           |
 | ----------------------------------------- | -------- | ----------------------------------------------------- |
-| `prepareDepositHoldings(amount, assetId)` | **W**    | Resolve holdings for a deposit amount                 |
-| `depositFunds(opts)`                      | **W**    | Deposit funds into the user's trading balance         |
+| `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 |
 
@@ -413,13 +420,15 @@ const unsubOrder = ws.onUserEvent("user_order", (data) => { ... });
 
 #### 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 single order                                   |
+| `createOrderRequest(opts[])`        | Place up to 20 orders in one request                   |
+| `cancelOrder(orderId)`              | Cancel a single order                                  |
+| `cancelOrder(orderIds[])`           | Cancel up to 20 orders in one request                  |
+| `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
 

package/dist/api/index.d.ts

@@ -1,5 +1,5 @@
-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, };
+import type { ApiError, Ticker, OrderBook, OrderBookOptions, SymbolConfig, OpenInterest, Trade, RecentTradesOptions, ActiveOrder, ActiveOrdersOptions, CancelOrderResponse, BatchCancelOrdersResponse, CancelAllOrdersOptions, CancelAllOrdersResponse, CreateOrderRequestOpts, CreateOrderRequestResponse, BatchCreateOrderRequestResponse, DelegationResponse, WithdrawalResponse, WithdrawalStatusResponse, TradingBalanceResponse, AmuletDisclosure, DisclosuresResponse } from "./types.js";
+export type { ApiError, Ticker, OrderBook, OrderBookOptions, SymbolConfig, OpenInterest, Trade, RecentTradesOptions, ActiveOrder, ActiveOrdersOptions, CancelOrderResponse, BatchCancelOrdersResponse, CancelAllOrdersOptions, CancelAllOrdersResponse, CreateOrderRequestResponse, BatchCreateOrderRequestResponse, DelegationResponse, WithdrawalResponse, WithdrawalStatusResponse, TradingBalanceResponse, AmuletDisclosure, DisclosuresResponse, };
 export { getUserId } from "./tokenStore.js";
 export { setWalletAdapter } from "../../src/config/index.js";
 /**
@@ -40,10 +40,15 @@ export declare function getRecentTrades(symbol: string, options?: RecentTradesOp
  */
 export declare function getActiveOrders(options?: ActiveOrdersOptions): Promise<ActiveOrder[] | ApiError>;
 /**
- * Cancel a specific order by ID.
+ * Cancel a single order by ID.
  * @param orderId - The order ID to cancel
  */
 export declare function cancelOrder(orderId: string): Promise<CancelOrderResponse | ApiError>;
+/**
+ * Cancel multiple orders by ID (max 20).
+ * @param orderIds - Array of order IDs to cancel
+ */
+export declare function cancelOrder(orderIds: string[]): Promise<BatchCancelOrdersResponse | ApiError>;
 /**
  * Cancel all active orders, optionally filtered by symbol.
  * @param options - Optional symbol filter
@@ -61,9 +66,10 @@ export declare function getDisclosures(partyId: string): Promise<DisclosuresResp
 export declare function getDelegation(): Promise<DelegationResponse | ApiError>;
 /**
  * Create an order request (limit buy/sell) on the Temple trading backend.
- * @param opts - Order parameters: symbol, side, quantity, price, order_type, expires_at
+ * @param opts - Single order or array of orders (max 20)
  */
 export declare function createOrderRequest(opts: CreateOrderRequestOpts): Promise<CreateOrderRequestResponse | ApiError>;
+export declare function createOrderRequest(opts: CreateOrderRequestOpts[]): Promise<BatchCreateOrderRequestResponse | ApiError>;
 /**
  * Create a withdrawal request.
  * @param assetId - Instrument symbol (e.g. "USDCx", "Amulet")

package/dist/api/index.js

@@ -154,15 +154,20 @@ export async function getActiveOrders(options = {}) {
         limit: options.limit,
     });
 }
-/**
- * Cancel a specific order by ID.
- * @param orderId - The order ID to cancel
- */
-export async function cancelOrder(orderId) {
-    if (!orderId) {
+export async function cancelOrder(orderIdOrIds) {
+    if (Array.isArray(orderIdOrIds)) {
+        if (orderIdOrIds.length === 0) {
+            return { error: true, status: null, code: "INVALID_PARAMS", message: "At least one order ID is required." };
+        }
+        if (orderIdOrIds.length > 20) {
+            return { error: true, status: null, code: "INVALID_PARAMS", message: "Maximum 20 order IDs per batch." };
+        }
+        return authenticatedPost("/api/trading/orders/cancel", { order_ids: orderIdOrIds });
+    }
+    if (!orderIdOrIds) {
         return { error: true, status: null, code: "INVALID_PARAMS", message: "Order ID is required." };
     }
-    return authenticatedPost(`/api/trading/orders/${encodeURIComponent(orderId)}/cancel`);
+    return authenticatedPost("/api/trading/orders/cancel", { order_id: orderIdOrIds });
 }
 /**
  * Cancel all active orders, optionally filtered by symbol.
@@ -190,12 +195,23 @@ export async function getDisclosures(partyId) {
 export async function getDelegation() {
     return authenticatedGet("/api/trading/delegation");
 }
-// ── Order Requests ──
-/**
- * Create an order request (limit buy/sell) on the Temple trading backend.
- * @param opts - Order parameters: symbol, side, quantity, price, order_type, expires_at
- */
 export async function createOrderRequest(opts) {
+    if (Array.isArray(opts)) {
+        if (opts.length === 0) {
+            return { error: true, status: null, code: "INVALID_PARAMS", message: "At least one order is required." };
+        }
+        if (opts.length > 20) {
+            return { error: true, status: null, code: "INVALID_PARAMS", message: "Maximum 20 orders per batch." };
+        }
+        const body = opts.map((o) => {
+            const { symbol: rawSymbol, side, quantity, price, order_type = "limit", expires_at } = o;
+            const order = { symbol: normalizeSymbol(rawSymbol), side, quantity: Number(quantity), price: Number(price), order_type };
+            if (expires_at)
+                order.expires_at = expires_at;
+            return order;
+        });
+        return authenticatedPost("/api/trading/orders", body);
+    }
     const { symbol: rawSymbol, side, quantity, price, order_type = "limit", 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." };

package/dist/api/types.d.ts

@@ -72,6 +72,13 @@ export interface CancelOrderResponse {
     already_queued: boolean;
     message: string;
 }
+export interface BatchCancelOrdersResponse {
+    success: boolean;
+    canceled: string[];
+    already_queued: string[];
+    not_found: string[];
+    message: string;
+}
 export interface CancelAllOrdersOptions {
     symbol?: string;
 }
@@ -98,6 +105,12 @@ export interface CreateOrderRequestOpts {
     order_type?: string;
     expires_at?: string;
 }
+export interface BatchCreateOrderRequestResponse {
+    success: boolean;
+    request_ids: number[];
+    count: number;
+    message: string;
+}
 export interface CreateOrderRequestResponse {
     [key: string]: unknown;
 }

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>>;