Skip to main content

Monaco Protocol SDK v0.5.5

Batch Cancel Orders & Order Status Simplification

This release introduces batch order cancellation for efficient multi-order management and simplifies order statuses by removing deprecated intermediate states.

New Features

Batch Cancel Orders

Cancel multiple orders in a single API call, or cancel all active orders at once. Core SDK:
  • New Method: sdk.trading.batchCancelOrders() for cancelling multiple orders efficiently
  • Cancel All: Use { cancelAll: true } to cancel all active orders for the user
  • Detailed Results: Returns individual success/failure status for each order
Use Cases:
  • Emergency position exit (cancel all orders instantly)
  • Bulk order management for market makers
  • Portfolio rebalancing with clean slate
  • Efficient cleanup of stale orders

Real-time Order Tracking

Track all your orders in real-time with the new useUserOrders React hook. Automatically syncs with WebSocket for instant order updates. React SDK:
  • New Hook: useUserOrders() for real-time order tracking
  • Automatic Sync: Fetches initial orders via REST, then subscribes to WebSocket updates
  • Smart Deduplication: Merges REST and WebSocket data without duplicates
  • Manual Refresh: Built-in refresh() function for on-demand updates
Features:
  • Real-time order status updates (placed, filled, cancelled, etc.)
  • Automatic state management with configurable history limit
  • Authentication-aware (requires valid JWT token)
  • Built-in error handling and retry support
Example:
Learn more about useUserOrders → Example:
Learn more about batch cancel →

Breaking Changes

Order Status Simplification

The PENDING and ACKNOWLEDGED order statuses have been removed from the API. Orders now transition directly to SUBMITTED status. What Changed:
Migration Guide: If you were filtering or checking for PENDING or ACKNOWLEDGED statuses, update your code:
Why this change:
  • Simplifies order lifecycle
  • Reduces intermediate states that caused confusion
  • Improves consistency across REST and WebSocket APIs
  • Orders now have a cleaner state machine

Breaking Change: vault.getBalance() Deprecated

The vault.getBalance() method has been deprecated and no longer functions. Use the Profile API for balance queries instead. What Changed:
Why this change:
  • Profile API provides more detailed balance information (available, locked, total)
  • Consolidates balance queries with other profile data
  • Improves performance with backend optimizations
  • Simplifies SDK architecture by removing duplicate functionality
Migration Guide: Replace sdk.vault.getBalance(assetId) with sdk.profile.getUserBalanceByAssetId(assetId):
For getting all balances:
Learn more about Profile API →

Breaking Change: TypeScript Type Updates

Several TypeScript interfaces have been updated for better consistency and to expose raw balance fields. These are breaking changes if you’re using TypeScript.

GetUserBalancesResponse: Pagination Field Renamed

What Changed:
Migration:

AccountBalance: New Required Fields

What Changed:
New fields:
  • asset_id - Asset UUID for API operations
  • available_balance_raw - Available balance in raw format (wei/smallest unit)
  • locked_balance_raw - Locked balance in raw format (wei/smallest unit)
Why this change:
  • Enables precise balance calculations without floating-point errors
  • Provides asset_id for direct use in deposit/withdraw operations
  • Matches backend API response structure

LedgerMovement: Extended Metadata

What Changed: The LedgerMovement interface has been extended with additional fields:
Why this change:
  • More accurate representation of on-ledger movements
  • Aligns with WebSocket event payloads
  • Provides raw values for precise calculations

MarketMetadata: Nullable Fields

What Changed: MarketMetadata fields are now nullable to reflect API behavior for markets without trade history:
Migration: Add null checks when accessing MarketMetadata fields:
Why this change:
  • Accurately represents markets that haven’t had any trades yet
  • Prevents displaying misleading zero or undefined values
  • Matches actual API response behavior

API Reference

New Endpoint:
  • POST /api/v1/orders/batch-cancel - Cancel multiple orders in a single request
New Types:
Query Parameters:
  • cancel_all (boolean) - Set to true to cancel all active orders

Upgrade Instructions

  1. Update your dependencies:
  1. Update balance queries:
    • Replace sdk.vault.getBalance(assetId) with sdk.profile.getUserBalanceByAssetId(assetId)
    • Update response handling to use new balance structure (available_balance, locked_balance, total_balance)
    • See Account Vault for examples
  2. Update order status checks:
    • Remove checks for PENDING status
    • Remove checks for ACKNOWLEDGED status
    • Use SUBMITTED as the initial active order state
  3. Consider using batch cancel:
    • Replace loops calling cancelOrder() with batchCancelOrders()
    • Use cancelAll: true for emergency exits
  4. Handle nullable MarketMetadata fields:
    • Add null checks when accessing last_price, high_24h, low_24h, etc.
    • Markets without trade history will return null for these fields
  5. Test your flows:
    • Verify balance queries work correctly
    • Verify order status transitions work correctly
    • Test batch cancellation with multiple orders
    • Test handling of new markets with no trade history

For complete documentation, see Order Management.