> ## 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.0

# Monaco Protocol SDK v0.5.0

> [!NOTE]
>
> The examples below show this release's API. Reaching Monaco mainnet needs `@0xmonaco/core` v1.0.83 or later, where the `mainnet` preset resolves the production REST and WebSocket hosts. See [TypeScript SDK setup](/sdk/typescript/intro) for current initialization.

## WebSocket API Refresh & Trades Endpoint

This release introduces a new Trades REST API, real-time trades WebSocket channel, and updates the WebSocket SDK to use a cleaner functional pattern.

### What's New

**Trades API**

* **REST Endpoint**: `GET /api/v1/trades/{trading_pair_id}` for fetching recent trade history
* **WebSocket Channel**: `trades:{trading_pair_id}` for real-time trade event streaming
* **Paginated Results**: Support for `skip` and `limit` query parameters

**WebSocket SDK Improvements**

* **Functional Pattern**: New cleaner API with `sdk.ws.orders()`, `sdk.ws.orderbook()`, `sdk.ws.ohlcv()`, `sdk.ws.trades()`
* **Unsubscribe Functions**: All subscription methods now return cleanup functions
* **Required wsUrl**: WebSocket URL is now a required configuration parameter

**Documentation Updates**

* Complete WebSocket documentation rewrite with updated examples
* New Trades API reference documentation
* Fixed balance endpoint path parameter (`asset_id` instead of `token`)

### Breaking Changes

**WebSocket Channels Now Use UUIDs**

All WebSocket channels (orders, orderbook, ohlcv, trades) now require trading pair IDs (UUIDs) instead of symbols:

```typescript theme={null}
// Before (v0.4.x)
sdk.websocket.ohlcv.subscribeToOHLCV('BTC/USDC', 'SPOT', '1m', handler);

// After (v0.5.0)
const pair = await sdk.market.getTradingPairBySymbol('BTC-USDC');
sdk.ws.ohlcv(pair.id, 'SPOT', '1m', handler);  // Use UUID
```

**WebSocket API Pattern Change**

The WebSocket SDK has been refactored from a class-based pattern to a functional pattern:

```typescript theme={null}
// Before (v0.4.x)
await sdk.websocket.orders.connect();
sdk.websocket.orders.subscribeToOrderEvents('BTC/USDC', 'SPOT', handler);

// After (v0.5.0)
await sdk.ws.connect();
const unsubscribe = sdk.ws.orders('trading-pair-id', 'SPOT', handler);
// Later: unsubscribe();
```

**Required wsUrl Parameter**

The `wsUrl` parameter is now required when initializing the SDK:

```typescript theme={null}
const sdk = new MonacoSDK({
  walletClient,
  network: 'testnet',
  seiRpcUrl: 'https://evm-rpc.sei-apis.com',
  wsUrl: 'wss://ws.apimonaco.xyz/ws'  // Now required
});
```

### New Features

**Trades REST API**

Fetch recent trades for any trading pair:

```typescript theme={null}
const trades = await sdk.trades.getTrades(tradingPairId, {
  skip: 0,
  limit: 25
});

// Response
{
  trades: [{
    eventType: 'trade',
    pairId: '...',
    tradingMode: 'SPOT',
    data: {
      tradeId: '...',
      price: '50000.00',
      quantity: '0.5',
      makerSide: 'BUY',
      executedAt: '2024-01-15T10:30:00Z'
    }
  }],
  skip: 0,
  limit: 25
}
```

**Trades WebSocket Channel**

Subscribe to real-time trade events:

```typescript theme={null}
await sdk.ws.connect();

const unsubscribe = sdk.ws.trades(tradingPairId, (event) => {
  console.log('Trade:', event.data.price, event.data.quantity);
});

// Later, to unsubscribe:
unsubscribe();
```

**Updated WebSocket Subscriptions**

All WebSocket channels now follow the same functional pattern:

```typescript theme={null}
// Orders (requires authentication)
const unsubOrders = sdk.ws.orders(tradingPairId, 'SPOT', (event) => {
  console.log('Order event:', event.eventType);
});

// Orderbook (public)
const unsubOrderbook = sdk.ws.orderbook(tradingPairId, 'SPOT', 1, 'BASE', (event) => {
  console.log('Best bid:', event.bestBid);
});

// OHLCV (public)
const unsubOHLCV = sdk.ws.ohlcv(tradingPairId, 'SPOT', '1m', (event) => {
  console.log('Candle:', event.candlestick);
});

// Trades (public)
const unsubTrades = sdk.ws.trades(tradingPairId, (event) => {
  console.log('Trade:', event.data);
});
```

### Migration Guide

**1. Update SDK Initialization**

Add the required `wsUrl` parameter:

```typescript theme={null}
const sdk = new MonacoSDK({
  walletClient,
  network: 'testnet',
  seiRpcUrl: 'https://evm-rpc.sei-apis.com',
  wsUrl: 'wss://ws.apimonaco.xyz/ws'  // Add this
});
```

**2. Update WebSocket Code**

Replace the old pattern with the new functional approach:

```typescript theme={null}
// Old
await sdk.websocket.orders.connect();
sdk.websocket.orders.subscribeToOrderEvents('BTC/USDC', 'SPOT', handler);

// New
await sdk.ws.connect();
const unsubscribe = sdk.ws.orders(tradingPairId, 'SPOT', handler);
```

**3. Use Trading Pair IDs**

WebSocket subscriptions now use trading pair IDs (UUIDs) instead of symbols:

```typescript theme={null}
// Get trading pair ID first
const pair = await sdk.market.getTradingPairBySymbol('BTC-USDC');

// Use the ID for subscriptions
sdk.ws.orders(pair.id, 'SPOT', handler);
```

### Packages Updated

* `@0xmonaco/core@0.5.0`
* `@0xmonaco/types@0.5.0`
* `@0xmonaco/react@0.5.0`

### Installation

```bash theme={null}
npm install @0xmonaco/core@0.5.0
npm install @0xmonaco/react@0.5.0  # For React applications
```

***

*This release includes breaking changes to the WebSocket API. Please review the migration guide before upgrading.*


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