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

# Monaco Protocol SDK v1.0.21

This release adds an authoritative portfolio-analytics API (`sdk.portfolio`), removes the standalone backend-authentication endpoint in favor of the `x-server-key` header, and corrects the fee totals behind the portfolio chart and stats. It rolls up the consumer-facing changes shipped since v1.0.16.

## Added

### Portfolio analytics API

A new `sdk.portfolio` namespace exposes five authenticated, application-scoped portfolio queries backed by `GET /api/v1/accounts/me/portfolio/*` (gRPC `AccountsService.GetPortfolio*`). Calculations run in Core, so every caller sees the same authoritative numbers.

| Method | Endpoint | Returns |
| - | - | - |
| `getSummary({ period })` | `GET .../portfolio/summary` | Current equity split plus period activity (volume, trade/order counts, fees paid) |
| `getPerformance({ period })` | `GET .../portfolio/performance` | Transfer-neutral dollar PnL, sampled time-weighted return, max drawdown, and an equity series |
| `getRealizedPnl({ period })` | `GET .../portfolio/realized-pnl` | Realized PnL split into perp closes, spot trades, funding, and fees, with closed-trade stats and a bucketed series |
| `getAssets({ period })` | `GET .../portfolio/assets` | Per-asset balances priced by asset ID, with allocation percentages and total spot equity |
| `getMargin()` | `GET .../portfolio/margin` | Current parent-account margin totals and per-risk-bucket projections |

The four historical methods accept an optional `period` — `"1d"`, `"1w"`, `"1m"`, or `"all"` — and default to `all` when omitted. `getMargin()` is current-only and takes no period.

Every response carries an explicit query cutoff and retained-history coverage, so partial windows are surfaced rather than silently truncated. Decimal amounts and percentages are strings. Dependent values that cannot be computed — a return for a window with no starting equity, or a value for an asset with no spot price — are omitted rather than reported as `0`.

```typescript theme={null}
const summary = await sdk.portfolio.getSummary({ period: "1m" });
console.log(summary.current.totalEquity, summary.activity.feesPaid);

const perf = await sdk.portfolio.getPerformance({ period: "1w" });
console.log(perf.returnPct, perf.maxDrawdown?.pct);

const margin = await sdk.portfolio.getMargin();
console.log(margin.total.parentAvailableCollateral, margin.riskBuckets.length);
```

See the [Portfolio Analytics](/sdk/typescript/portfolio) SDK guide for the full response shapes.

## Removed

### Standalone backend authentication (breaking)

The dedicated backend-auth exchange is gone from the wire contract:

* REST `POST /api/v1/auth/backend` (operation `authenticate_backend`) is removed
* gRPC `AuthService.BackendAuth` and its generated client method are removed
* The `BackendAuthRequest { secret_key }` and `BackendAuthResponse { app_id, client_id, name }` messages are removed from the protobuf contract and the generated OpenAPI schema

Backend applications already authenticate every request with their `sk_` secret key in the `x-server-key` header (gRPC metadata); nothing there changes. The TypeScript SDK's `authenticateBackend()` helper was removed back in v0.8.10 — set the key once with `sdk.setServerKey("sk_live_...")`. Only integrations that still call the raw `POST /api/v1/auth/backend` endpoint or the `BackendAuth` RPC need to migrate: drop the exchange and send `x-server-key` directly.

## Fixed

### Portfolio stats fee totals

`getPortfolioStats` (`GET /api/v1/accounts/me/portfolio`) now sources `pnlBreakdown.fees` and `totalPnl` from the authoritative trade-ledger fee total — the same source as `feesPaid` — instead of the PnL service's cumulative fee counter. That counter under-recorded margin fills whose order carried no margin position id, which understated fees and overstated `totalPnl`. Because stats read the ledger directly, the correction applies across all history, not just data recorded after this release. The realized headline `pnl` field was already correct and is unchanged.

### Portfolio chart fee metrics

`getPortfolioChart` reads persisted per-account fee snapshots rather than the trade ledger, and those snapshots are now recorded correctly. Two fixes to the PnL service:

* every margin fill's fee is attributed to its owning margin account, including closing and reducing fills whose order carries no position id (previously dropped), and
* margin taker fees now include the `application_taker_fee` component, matching the spot path and `feesPaid`.

This corrects the chart's `fees`, `realizedPnl`, and `totalPnl` series metrics for data recorded after the fix; earlier buckets are not retroactively restated.

### SDK sends an explicit User-Agent header

`@0xmonaco/core` now sets a `User-Agent` header (`@0xmonaco/core`) on every REST request. Monaco's edge rejects requests with an empty or absent `User-Agent`, so SDK traffic could intermittently be blocked. In the browser the runtime controls `User-Agent` and this value is ignored, since it is a forbidden header there.

## Upgrade

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

`sdk.portfolio` is additive — no existing method or response field changed shape. If any integration still calls `POST /api/v1/auth/backend` or the gRPC `BackendAuth` RPC, remove that call and send the `sk_` secret key in the `x-server-key` header on each backend request instead. If you reconcile against portfolio stats `fees` / `totalPnl`, expect corrected values across all history (higher fees, lower `totalPnl`); the chart's `fees` / `realizedPnl` / `totalPnl` series are corrected only for data recorded after this release.


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