Monaco Protocol SDK v0.5.6

Real-Time Balance Updates & API Improvements

This release introduces real-time balance tracking via WebSocket, refines the batch cancel API with two dedicated methods for clearer usage, and improves error handling for vault operations.

New Features

Real-Time Balance Updates via WebSocket

Track your account balances in real-time with the new WebSocket balance channel and React hook. Core SDK:

New Method: sdk.ws.balances() for subscribing to live balance changes
Authenticated Channel: Requires valid JWT token (user-specific updates)
Detailed Events: Includes available, locked, and total balances (both normalized and raw values)
Update Reasons: Know why balances changed (lock, unlock, deposit, withdrawal, trade)

React SDK:

New Hook: useUserBalances() for real-time balance tracking
Hybrid Approach: Fetches initial balances via REST, then subscribes to WebSocket for live updates
Manual Refresh: Built-in refresh() function for on-demand balance reload
Connection Status: Track if WebSocket subscription is active

Use Cases:

Display live balance updates during trading
Show real-time locked balance as orders execute
Monitor deposits and withdrawals instantly
Track fee deductions from trades
Update balance UI without polling

Example: WebSocket Balance Subscription

import { MonacoSDK } from "@0xmonaco/core";

// Authenticate first
await sdk.login('your-client-id');

// Subscribe to balance updates
const unsubscribe = sdk.ws.balances((event) => {
  console.log('Balance updated:', event.data.reason);
  console.log('Token:', event.data.tokenSymbol);
  console.log('Available:', event.data.available);
  console.log('Locked:', event.data.locked);
  console.log('Total:', event.data.total);

  // Update UI with new balances
  updateBalanceDisplay(event.data);
});

// Later, to unsubscribe:
unsubscribe();

Example: React Hook

import { useUserBalances } from "@0xmonaco/react";

function BalanceDashboard() {
  const { balances, loading, subscribed, error, refresh } = useUserBalances();

  if (loading) return <div>Loading balances...</div>;
  if (error) return <div>Error: {error.message}</div>;

  return (
    <div>
      <div className="header">
        <h2>Your Balances</h2>
        {subscribed && <span className="live-badge">● Live</span>}
        <button onClick={refresh}>Refresh</button>
      </div>

      {balances.map(balance => (
        <div key={balance.asset_id} className="balance-row">
          <span>{balance.symbol}</span>
          <div>
            <div>Available: {balance.available_balance}</div>
            <div>Locked: {balance.locked_balance}</div>
            <div>Total: {balance.total_balance}</div>
          </div>
        </div>
      ))}
    </div>
  );
}

Event Structure:

interface UserBalanceEvent {
  eventType: "balance_update";
  userId: string;
  data: {
    tokenAddress: string;           // Token contract address
    tokenSymbol: string | null;     // Token symbol (e.g., "USDC")
    available: string;              // Available balance (normalized)
    availableRaw: string;           // Available balance (raw/wei)
    locked: string;                 // Locked in orders (normalized)
    lockedRaw: string;              // Locked in orders (raw/wei)
    total: string;                  // Total balance (normalized)
    totalRaw: string;               // Total balance (raw/wei)
    reason: "lock" | "unlock" | "deposit" | "withdrawal" | "trade";
    referenceId: string | null;     // Related order/movement ID
    updatedAt: string;              // ISO 8601 timestamp
  };
}

Learn more about WebSocket API →

Batch Cancel API Split

The batchCancelOrders() method has been split into two dedicated methods for clearer intent and simpler usage. What Changed:

// Before (v0.5.5)
// Cancel specific orders
await sdk.trading.batchCancelOrders({
  orderIds: ['order-1', 'order-2', 'order-3']
});

// Cancel all orders
await sdk.trading.batchCancelOrders({ cancelAll: true });

// After (v0.5.6)
// Cancel specific orders - dedicated method
await sdk.trading.batchCancel(['order-1', 'order-2', 'order-3']);

// Cancel all orders - dedicated method
await sdk.trading.batchCancelAll();

// NEW: Cancel all orders for a specific trading pair
await sdk.trading.batchCancelAll(tradingPairId);

Core SDK:

New Method: batchCancel(orderIds: string[]) - Cancel specific orders by ID
New Method: batchCancelAll(tradingPairId?: string) - Cancel all active orders, optionally filtered by trading pair
Clearer Intent: Method names explicitly indicate what they do
Simpler Parameters: No more object wrappers - just pass the array or trading pair ID

React SDK:

Both methods available in useTrade() hook
Same signatures as Core SDK

Example:

// Cancel specific orders
const result = await sdk.trading.batchCancel([
  'order-id-1',
  'order-id-2',
  'order-id-3'
]);

console.log(`Cancelled: ${result.total_cancelled}/${result.total_requested}`);

// Check individual results
result.results.forEach(r => {
  if (r.success) {
    console.log(`Order ${r.order_id} cancelled`);
  } else {
    console.log(`Order ${r.order_id} failed: ${r.error.message}`);
  }
});

// Cancel ALL active orders globally
const allResult = await sdk.trading.batchCancelAll();
console.log(`Emergency exit: cancelled ${allResult.total_cancelled} orders`);

// Cancel all orders for a specific trading pair
const pair = await sdk.market.getTradingPairBySymbol('ETH/USDC');
const pairResult = await sdk.trading.batchCancelAll(pair.id);
console.log(`Cancelled ${pairResult.total_cancelled} ETH/USDC orders`);

Migration Guide: Replace batchCancelOrders() calls with the appropriate new method:

// Old: Cancel specific orders
await sdk.trading.batchCancelOrders({ orderIds: [id1, id2, id3] });

// New: Use batchCancel with direct array
await sdk.trading.batchCancel([id1, id2, id3]);

// Old: Cancel all orders
await sdk.trading.batchCancelOrders({ cancelAll: true });

// New: Use batchCancelAll (no parameters)
await sdk.trading.batchCancelAll();

Why this change:

Clearer API: Method names explicitly describe the action
Simpler Usage: No need to wrap parameters in objects
Better TypeScript: Type inference works better with direct parameters
Trading Pair Filter: New capability to cancel all orders for a specific pair

Learn more about trading API →

Technical Updates

viem Peer Dependency

The viem package has been moved from a direct dependency to a peer dependency (version ^2.45.2) in both @0xmonaco/core and @0xmonaco/types packages. What this means:

Your application must now install viem directly
Prevents type duplication issues when consuming the SDK
Ensures consistent viem version across your entire application

Installation:

# Install viem alongside Monaco SDK
npm install @0xmonaco/[email protected] viem@^2.45.2

# Or for React
npm install @0xmonaco/[email protected] @0xmonaco/[email protected] viem@^2.45.2

React Hook Count Correction

Monaco Protocol React SDK now has 14 hooks (not 13 as previously documented):

useAuth - Authentication
useFees - Fee simulation
useMarket - Market data
useMonacoSDK - SDK instance access
useOHLCV - Real-time candlesticks
useOrderbook - Real-time orderbook
useProfile - User profile
useTokenLifecycle - Token management
useTrade - Trading operations
useTradeFeed - Real-time trades
useUserBalances - Real-time balances (NEW in v0.5.6)
useUserMovements - Account movements
useUserOrders - Real-time orders
useVault - Vault operations

Bug Fixes

Proto-Generated API Contract Alignment

This release also fixes several mismatches between the proto-generated API surface and the live service behavior. What Changed:

Implemented gRPC market metadata so the published contract no longer points to an unimplemented endpoint
Defined gRPC batch order operations for batch create, batch replace, batch cancel, and cancel-all flows in the published contract; server-side handlers remain stubbed and return UNIMPLEMENTED in this release
Aligned gRPC market pair filtering with the HTTP API by treating base_token and quote_token as token symbols instead of contract addresses
Removed transport-only source fields from account balance and movement responses so generated contracts match the HTTP API
Relaxed generated order status query constraints so comma-separated filters like FILLED,PARTIALLY_FILLED remain valid
Replaced a panic path in get_balance_by_asset with proper invalid_argument validation for malformed asset UUIDs

Vault Operations: Clear Error When No Account Available

Vault operations now throw a clear InvalidConfigError when the wallet client has no account connected, instead of failing with an unclear error message later in the transaction flow. What Changed: Previously, if you initialized the SDK with a wallet client but no account was connected, vault operations would fail with unclear errors during transaction execution. Now, you’ll receive an immediate, actionable error.

import { MonacoSDK, InvalidConfigError } from "@0xmonaco/core";
import { createWalletClient, http } from "viem";
import { seiTestnet } from "viem/chains";

// Wallet client without account
const walletClient = createWalletClient({
  chain: seiTestnet,
  transport: http()
  // No account specified
});

const sdk = new MonacoSDK({
  walletClient,
  network: "staging",
  seiRpcUrl: "https://evm-rpc-testnet.sei-apis.com"
});

try {
  // v0.5.6+: Clear error immediately
  await sdk.vault.deposit(assetId, 1000000000n);
} catch (error) {
  if (error instanceof InvalidConfigError && error.field === "account") {
    console.error("No account available in wallet client");
    console.error("Suggestion:", error.suggestion);
    // Handle: prompt user to connect wallet or provide account
  }
}

When This Error Occurs: This error is thrown when calling any vault operation if:

Wallet client is provided to SDK but account property is undefined or null
User has disconnected their wallet after SDK initialization
Wallet client was created without specifying an account

Affected Operations:

sdk.vault.deposit()
sdk.vault.withdraw()
sdk.vault.approve()
sdk.vault.getAllowance()
sdk.vault.needsApproval()

Error Details:

InvalidConfigError: "No account available in wallet client"
  field: "account"
  code: "INVALID_CONFIG"
  suggestion: "Ensure wallet is connected and account is available"

Why This Change:

Earlier Detection: Catch configuration issues before attempting blockchain transactions
Clearer Errors: Specific error message indicates exactly what’s wrong
Better DX: Developers can handle this case explicitly and provide better UX
Actionable Suggestions: Error includes suggestion on how to fix the issue

Error Handling Example:

try {
  await sdk.vault.deposit(assetId, amount);
} catch (error) {
  if (error instanceof InvalidConfigError) {
    // New in v0.5.6: Handle wallet configuration errors
    if (error.field === "account") {
      alert("Please connect your wallet to continue");
    }
  } else if (error instanceof APIError) {
    // Existing error handling
    console.error("API error:", error.message);
  }
}

Internal Improvements

This release includes internal code quality improvements:

Added TypeScript override keywords to error class methods for better type safety
Improved null safety checks in React hooks (useOHLCV, useUserOrders, useUserBalances)
Simplified network URL resolution logic
Updated build tooling and linting configuration

These changes have no impact on the public API or usage patterns.

Upgrade Instructions

Install New Versions

# NPM
npm install @0xmonaco/[email protected] @0xmonaco/[email protected] @0xmonaco/[email protected] viem@^2.45.2

# Bun
bun add @0xmonaco/[email protected] @0xmonaco/[email protected] @0xmonaco/[email protected] viem@^2.45.2

Migration Steps

1. Ensure viem is installed

# Check if viem is already installed
npm list viem

# If not, install it
npm install viem@^2.45.2

2. Update batch cancel calls

Find all occurrences of batchCancelOrders() and replace with the appropriate method:

// Replace specific order cancellations
- await sdk.trading.batchCancelOrders({ orderIds: [id1, id2] });
+ await sdk.trading.batchCancel([id1, id2]);

// Replace cancel-all calls
- await sdk.trading.batchCancelOrders({ cancelAll: true });
+ await sdk.trading.batchCancelAll();

3. (Optional) Add balance tracking

Take advantage of the new real-time balance updates:

// TypeScript SDK
const unsubscribe = sdk.ws.balances((event) => {
  updateBalanceUI(event.data);
});

// React SDK
import { useUserBalances } from "@0xmonaco/react";

function Component() {
  const { balances, subscribed } = useUserBalances();
  // Your component logic
}

4. (Optional) Improve vault error handling

Add explicit error handling for vault operations:

import { InvalidConfigError } from "@0xmonaco/core";

try {
  await sdk.vault.deposit(assetId, amount);
} catch (error) {
  if (error instanceof InvalidConfigError && error.field === "account") {
    // Prompt user to connect wallet
    alert("Please connect your wallet to continue");
  }
}

Testing Recommendations

Test batch cancel migrations: Verify updated calls work correctly
Test viem dependency: Ensure your app builds with the peer dependency
Test balance updates: Verify WebSocket balance subscriptions work in your environment
Test vault error handling: Confirm improved error messages display correctly

For complete documentation, see the WebSocket API guide, Trading guide, Vault Operations guide, and Error Handling guide.

Learn

Build

Libraries

APIs

Resources

V0.5.6

Monaco Protocol SDK v0.5.6

Real-Time Balance Updates & API Improvements

New Features

Real-Time Balance Updates via WebSocket

Batch Cancel API Split

Technical Updates

viem Peer Dependency

React Hook Count Correction

Bug Fixes

Proto-Generated API Contract Alignment

Vault Operations: Clear Error When No Account Available

Internal Improvements

Upgrade Instructions

Install New Versions

Migration Steps

1. Ensure viem is installed

2. Update batch cancel calls

3. (Optional) Add balance tracking

4. (Optional) Improve vault error handling

Testing Recommendations

​Monaco Protocol SDK v0.5.6

​Real-Time Balance Updates & API Improvements

​New Features

​Real-Time Balance Updates via WebSocket

​Batch Cancel API Split

​Technical Updates

​viem Peer Dependency

​React Hook Count Correction

​Bug Fixes

​Proto-Generated API Contract Alignment

​Vault Operations: Clear Error When No Account Available

​Internal Improvements

​Upgrade Instructions

​Install New Versions

​Migration Steps

​1. Ensure viem is installed

​2. Update batch cancel calls

​3. (Optional) Add balance tracking

​4. (Optional) Improve vault error handling

​Testing Recommendations

Monaco Protocol SDK v0.5.6

Real-Time Balance Updates & API Improvements

New Features

Real-Time Balance Updates via WebSocket

Batch Cancel API Split

Technical Updates

viem Peer Dependency

React Hook Count Correction

Bug Fixes

Proto-Generated API Contract Alignment

Vault Operations: Clear Error When No Account Available

Internal Improvements

Upgrade Instructions

Install New Versions

Migration Steps

1. Ensure viem is installed

2. Update batch cancel calls

3. (Optional) Add balance tracking

4. (Optional) Improve vault error handling

Testing Recommendations