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

# V1.0.45

# Monaco Protocol SDK v1.0.45

This release adds a public `instrument` WebSocket channel that streams trading-pair lifecycle and configuration changes — new listings, delistings, and edits to tick size, step size, order-size bounds, or category — with each frame carrying the market's full current configuration, perp leverage and margin-rate bounds included. Positions gain a `cumFees` field carrying the position's whole-life trading fees (opening fills included). Two separate fixes also land: closed-position `netRealizedPnl` / `realizedRoe` now net opening-fill fees, and faucet history returns one entry per on-chain deposit. One thing to act on: closed-position `netRealizedPnl` and `realizedRoe` now fold in opening-fill fees, so those figures shift — usually down, but up where the opening fills earned a maker rebate (fees are signed) — read the fix below before you rely on them.

## Added

### Public `instrument` WebSocket channel

A new public, unauthenticated channel streams trading-pair lifecycle and configuration changes: new listings, delistings, and non-activation edits to tick size, quantity step, order-size bounds, or category. Each frame carries the market's full current configuration — including, for perp markets, leverage and margin-rate bounds — but those margin parameters are payload only: they are read into every frame, and an edit to them alone does not itself emit one. Subscribe to `instrument:<tradingPairId>` for one market, or the bare `instrument` channel (`instrument:*`) for every market; a subscribe-time snapshot of the current active-pair configuration precedes the live diffs.

Each live `Event` frame carries one market's **full current configuration**, not just the changed fields, so consume it as a per-market terminal-state snapshot rather than an additive delta — `changedFields` names which fields the mutation touched, for callers that want to react selectively. The subscribe-time baseline arrives as a single `Snapshot` frame whose `data` is an array of those same per-market config objects (each a `listing`). The lag policy is conflate: a subscriber that falls behind is fast-forwarded to the latest frame rather than disconnected. `@0xmonaco/types` ships the `InstrumentEvent`, `InstrumentEventData`, and `InstrumentChangeKind` types; there is no typed `sdk.ws` helper yet, so subscribe over the raw WebSocket protocol and map the snake\_case wire keys onto `InstrumentEventData`. See [WebSockets](/reference/websockets#instrument).

### `cumFees` on positions

`sdk.positions.listPositions()` and `sdk.positions.getPosition()` (`GET /api/v1/positions`, `GET /api/v1/positions/{positionId}`; gRPC `PositionsService.ListPositions` / `GetPosition`) add `cumFees` (decimal string, signed) to `Position` in `@0xmonaco/types`. It is the position's **total lifetime trading fees** — opening-fill fees plus every reducing execution (decreases, close, and any liquidation penalty) — negative when net rebated, and inclusive of the application-fee component. Unlike `feesPaid`, which is only the closing-side reducing-execution portion and omits opening fills, `cumFees` is the complete figure, present on open and terminal rows alike. It is `null` when the whole-life total cannot be completed — before the position's first PnL sample, after its samples age out of PnL retention, for positions predating the PnL service, or when a legacy reducing row carries a null fee. Unlike `feesPaid`, `cumFees` is not gated on the reducing-history completeness check, so in the rare case where a reducing-history row is entirely absent (a legacy data gap) it can be non-null and understated.

## Fixed

### Closed-position realized PnL and ROE net opening-fill fees

`netRealizedPnl` and `realizedRoe` on terminal positions (`GET /api/v1/positions`, `GET /api/v1/positions/{positionId}`; gRPC `PositionsService.ListPositions` / `GetPosition`) now subtract the position's opening-fill fees as well, not only its closing-side reducing-execution fees. A closed position's entry fees were previously ignored, mis-stating net realized PnL and the realized return; terminal rows now read net of the full fee life **whenever the opening PnL sample is available**. Opening-fill fees are signed, so the figure usually drops, but rises where those fills earned a maker rebate. Rows whose sample has aged out of PnL retention, or that predate the PnL service, keep the previous closing-execution net (opening fees not folded in) — `cumFees` is `null` for those — so not every historical row is fully fee-netted. `realizedRoe` follows `netRealizedPnl`. If you render realized PnL or ROE on closed positions, expect the values to shift.

### Faucet history returns one entry per on-chain deposit

Faucet history (the `recentRequests` list on faucet info; `GET /api/v1/faucet/info`) now returns one `minted` entry per on-chain deposit: the 1000 USDC spot mint and the 1000 USDC margin mint appear as separate entries, each with its own `amount` and — for a confirmed leg — its own `txHash`, and the margin leg labelled `USDC (margin)` — mirroring the mint response. A leg submitted but not yet confirmed carries no hash. A session was previously squashed into a single 2000 entry that carried only the spot transaction hash.

## Upgrade

```bash theme={null}
npm install @0xmonaco/core@1.0.45 @0xmonaco/types@1.0.45 @0xmonaco/react@1.0.45 @0xmonaco/contracts@1.0.45
# or bun
bun add @0xmonaco/core@1.0.45 @0xmonaco/types@1.0.45 @0xmonaco/react@1.0.45 @0xmonaco/contracts@1.0.45
```

The MCP server ships at `1.0.45` too; it runs via `npx -y @0xmonaco/mcp-server`, so restarting your assistant picks up the new version. Every SDK bump is a patch release. The new surfaces are additive — a `cumFees` field on positions and the new raw `instrument` WebSocket channel — so existing request and wire shapes are unchanged and the upgrade is drop-in; adopt the new field and channel only if you want them (a raw `instrument` client must handle the `Snapshot` baseline frame as well as `Event` diffs — see [WebSockets](/reference/websockets#instrument)). The one behavioral change to check is closed-position `netRealizedPnl` and `realizedRoe`, which now net opening-fill fees when the opening PnL sample is available, so stored or displayed realized-PnL figures for closed positions shift — usually lower, but higher where the opening fills earned a maker rebate.


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