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

# Monaco Protocol SDK v0.8.22

This release ships the full unrealized-PnL surface — new `unrealizedPnl`, `totalPnl`, and `pnlBreakdown` fields on portfolio stats, six new chart metrics, and a new per-position PnL history endpoint — adds `quantityStepSize` to trading pairs, and fixes position endpoints to return position-scoped margin requirements instead of the parent-account aggregate.

## Added

### Quantity step size on trading pairs

`TradingPair` now exposes `quantityStepSize` (string): the base-token lot-size increment used to validate order quantity precision. Available on all trading-pair reads:

* **REST** — `GET /api/v1/market/pairs`, `GET /api/v1/market/pairs/{tradingPairId}`
* **TypeScript SDK** — `market.getPaginatedTradingPairs()`, `market.getTradingPair(tradingPairId)`
* **gRPC** — `MarketService.ListTradingPairs`, `MarketService.GetTradingPair`

`minOrderSize` values that were below the provider or base-asset lot boundary have been raised to the next executable lot. `maxOrderSize` and `tickSize` semantics are unchanged.

```typescript theme={null}
const pair = await sdk.market.getTradingPair(tradingPairId);
console.log(pair.quantityStepSize); // e.g. "0.001"
```

### Expanded PnL surface

#### Portfolio stats — unrealized PnL and breakdown

`getPortfolioStats` returns three new fields:

| Field | Type | Description |
| - | - | - |
| `unrealizedPnl` | string | Mark-to-market PnL on all open positions |
| `totalPnl` | string | `realizedPnl + unrealizedPnl − fundingPaid − fees` |
| `pnlBreakdown` | object | Component breakdown (see below) |

`pnlBreakdown` contains: `spotRealized`, `spotUnrealized`, `perpsRealized`, `perpsUnrealized`, `fundingPaid`, `fees`. `fundingPaid` is cost-positive (positive means paid out); negate it when displaying as a PnL contribution.

#### Portfolio chart — new metrics

`getPortfolioChart` now accepts six additional metric values: `"unrealized_pnl"`, `"total_pnl"`, `"realized_pnl"`, `"funding_paid"`, `"fees"`, `"equity"`. Each is served from PnL history snapshots with per-bucket forward-fill.

```typescript theme={null}
const chart = await sdk.profile.getPortfolioChart("1D", "total_pnl");
```

#### Position PnL history

A new endpoint returns bucketed PnL state samples for a single owned position:

* **REST** — `GET /api/v1/positions/{positionId}/pnl/history?interval=&startTime=&endTime=`
* **TypeScript SDK** — `positions.getPositionPnlHistory(positionId, { interval, startTime?, endTime? })`
* **React SDK** — `usePositionPnlHistory(positionId, { interval, startTime?, endTime? })`
* **gRPC** — `PositionsService.GetPositionPnlHistory`

`interval` accepts: `"1m"`, `"5m"`, `"15m"`, `"1h"`, `"4h"`, `"1d"`. Returns an array of `PositionPnlPoint` samples forward-filled within the requested window.

```typescript theme={null}
const history = await sdk.positions.getPositionPnlHistory(positionId, {
  interval: "1h",
  startTime: "2026-07-01T00:00:00Z",
});
for (const point of history.points) {
  console.log(point.timestamp, point.unrealizedPnl, point.realizedPnl);
}
```

## Fixed

### Per-position `initialMarginRequired` and `maintenanceMarginRequired`

`listPositions`, `getPosition`, and `getPositionRisk` now return values scoped to the individual position rather than repeating the parent margin-account aggregate. Initial margin honors effective leverage and the market initial-margin floor; maintenance margin uses the market maintenance-margin rate. Positions with no open exposure return `"0"` for both fields. Request and response field names, types, and authentication requirements are unchanged.

## Upgrade

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

All changes in this release are additive or behavioral corrections with no field-shape changes.


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