Skip to main content

​
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. 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.
See the Portfolio Analytics 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

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.