> ## Documentation Index
> Fetch the complete documentation index at: https://docs.0xmonaco.com/llms.txt
> Use this file to discover all available pages before exploring further.

# V0.5.4

# Monaco Protocol SDK v0.5.4

## Real-Time User Movements & Trade Feed Improvements

This release introduces real-time user movement events via WebSocket and refactors the `useTradeFeed` React hook for better performance and shared state management.

### New Features

#### Real-Time User Movements WebSocket

Track real-time user ledger movements (deposits, withdrawals, trades, fees, and balance changes) with the new movements WebSocket channel.

**Core SDK:**

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

**React SDK:**

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

**Use Cases:**

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

**Example:**

```typescript theme={null}
// 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>
  );
}
```

[Learn more about WebSocket Movements →](/websocket#movement-events)

***

### Breaking Changes

#### `useTradeFeed` Hook Refactored

The `useTradeFeed` React hook has been refactored to share WebSocket subscriptions and state across components, improving performance and eliminating duplicate connections.

**What Changed:**

```typescript theme={null}
// 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
});
```

**Removed:**

* `maxTrades` parameter (now fixed at 50 trades)
* `clearError` function

**New Features:**

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

**Migration Guide:**

If you were using `maxTrades`:

```typescript theme={null}
// 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
```

If you were using `clearError`:

```typescript theme={null}
// Before
const { error, clearError } = useTradeFeed({ tradingPairId });

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

***

### Bug Fixes

**Core SDK:**

* 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

**WebSocket Enhancements:**

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

**React Provider Architecture:**

* `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:**

```bash theme={null}
npm install @0xmonaco/core@0.5.4 @0xmonaco/react@0.5.4
```

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

**New Types:**

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

**Updated Hooks:**

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

**Updated SDK Methods:**

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

***

*For complete documentation, see the [WebSocket API reference](/websocket) and [React SDK documentation](/sdk/react/intro).*


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.