​

Monaco Protocol SDK v0.5.4

​

Real-Time User Movements & Trade Feed Improvements

​

New Features

​

Real-Time User Movements WebSocket

• New WebSocket Method: sdk.ws.movements(handler) for subscribing to authenticated balance change events
• New Event Types: UserMovementEvent and UserMovementEventData for ledger movement events
• Track deposits, withdrawals, trades, fees, locks, and unlocks in real-time

• New Hook: useUserMovements() with automatic deduplication and configurable history limit
• Seamless integration with MonacoProvider for automatic connection management
• Built-in state management for movement history

• Display real-time balance updates in your UI
• Show live transaction feeds
• Track deposit confirmations instantly
• Monitor trade settlements in real-time

// TypeScript SDK
const unsubscribe = sdk.ws.movements((event) => {
  console.log(`${event.data.transactionType}: ${event.data.amount}`);
  console.log(`Balance: ${event.data.balanceBefore} → ${event.data.balanceAfter}`);
});

// React Hook
function MovementsFeed() {
  const { movements, loading } = useUserMovements(50); // Optional: max movements (default: 50)

  return (
    <div>
      {loading && <p>Loading movements...</p>}
      {movements.map(movement => (
        <div key={movement.data.id}>
          {movement.data.transactionType}: {movement.data.amount}
        </div>
      ))}
    </div>
  );
}

​

Breaking Changes

​

useTradeFeed Hook Refactored

// Before (v0.5.3)
const { trades, error, clearError } = useTradeFeed({
  tradingPairId: "pair-uuid",
  maxTrades: 100, // Custom limit
});

// After (v0.5.4)
const { trades, error } = useTradeFeed({
  tradingPairId: "pair-uuid",
  // maxTrades removed - fixed at 50 trades
  // clearError removed
});

• maxTrades parameter (now fixed at 50 trades)
• clearError function

• Shared Subscriptions: Multiple components using the same tradingPairId now share both the WebSocket connection and trade state
• Optimized Performance: Initial trades are fetched only once when the first component subscribes
• Automatic Cleanup: Reference-counted subscriptions automatically clean up when the last subscriber unmounts
• TradeFeedProvider: Wrapped by MonacoProvider to manage shared trade feed subscriptions

// Before
const { trades } = useTradeFeed({ tradingPairId, maxTrades: 100 });

// After - limit to 50 in your component
const { trades } = useTradeFeed({ tradingPairId });
const limitedTrades = trades.slice(0, 50); // Handle limiting in UI

// Before
const { error, clearError } = useTradeFeed({ tradingPairId });

// After - handle errors differently
const { error } = useTradeFeed({ tradingPairId });
// Errors are now handled by the shared provider

​

Bug Fixes

• Fixed self-referential import in useOrderbook hook
• Fixed circular dependency between provider and hooks modules
• WebSocket now supports multiple handlers per channel, enabling shared subscriptions across consumers
• Subscribe/Unsubscribe messages are only sent on first subscriber and last unsubscriber for each channel

​

Technical Details

• Multiple handlers per channel support
• Improved subscription management
• Better error handling and connection state management
• Reduced message overhead by batching subscribe/unsubscribe operations

• TradeFeedProvider automatically wrapped by MonacoProvider
• Shared state management across all trade feed consumers
• Reference counting for automatic resource cleanup
• Optimized initial data fetching

​

Upgrade Instructions

1. Update your dependencies:

npm install @0xmonaco/[email protected] @0xmonaco/[email protected]

2. Update useTradeFeed usage:
   • Remove maxTrades parameter
   • Remove clearError usage
   • Handle trade limiting in your UI if needed
3. Test WebSocket connections:
   • Multiple components with the same tradingPairId should share the same connection
   • Verify automatic cleanup when components unmount
4. Explore new movements WebSocket:
   • Try the new sdk.ws.movements() method
   • Use useUserMovements() hook in React applications

​

API Reference

• UserMovementEvent - WebSocket event structure for movements
• UserMovementEventData - Detailed movement data including balances, amounts, and references

• useTradeFeed - Shared subscription pattern with fixed trade limit
• useUserMovements - New hook for real-time ledger movements

• sdk.ws.movements(handler) - Subscribe to user movement events