Skip to main content

​
Monaco Protocol SDK v1.0.32

This release makes cursor pagination the default for order and trade history and adds full-history iterators, completes the position and funding types, fixes two portfolio and margin accuracy issues, and points the mainnet WebSocket preset at its dedicated ingress. The changes span the TypeScript, Rust REST, and Rust gRPC clients. Upgrading is recommended; the pagination default is the one action item worth reviewing before you deploy.

​
Added

​
Full-history iterators for orders and trades

New sdk.trading.iterateOrders(params?) and sdk.profile.iterateUserTrades(params?) async generators walk the entire history (hot and archived rows merged) for you: they take the existing filters plus pageSize, manage the pageToken/nextPageToken cursor internally, and yield one order or trade at a time until the walk is exhausted — so you no longer hand-roll the cursor loop.

​
Multi-status order filter

sdk.trading.getPaginatedOrders accepts an array of statuses for its status filter (OrderStatusFilter, for example ["SUBMITTED", "PARTIALLY_FILLED"]), sent as a single comma-separated request instead of one call per status. A single status string keeps working unchanged.

​
Completed position and funding types

PositionStatus now includes the terminal statuses LIQUIDATED and EXPIRED (previously OPEN | CLOSED | LIQUIDATING), and a new PositionStatusFilter narrows the list-positions status filter to the values the endpoint accepts (OPEN/CLOSED/LIQUIDATING/LIQUIDATED; an EXPIRED position matches under a CLOSED filter). FundingRecord now types the per-window fields the wire already returned — epoch, fundingDeltaPerUnit, referencePrice, sampleCount, windowStartedAt, windowClosedAt, and settledAt (the sort key for listAllFundingHistory). No wire behavior changed; these values are now readable type-safely.

​
Changed

​
Cursor pagination is now the default for orders and trades

sdk.trading.getPaginatedOrders (GET /api/v1/orders) and sdk.profile.getUserTrades (GET /api/v1/accounts/trades) are cursor-paginated by default. When you pass neither page nor pageToken, the SDK now starts a cursor walk (sending pageToken: "") over full history — hot and archived rows merged, newest first — instead of returning a legacy page-number window. Legacy page-number (offset) pagination is deprecated but still available:
  • Pass the deprecated page to opt back into offset mode — it reads the recent hot window only and populates the legacy counts.
  • The response total, page, and totalPages fields are deprecated and return 0 in cursor mode (which has no exact total) — drive “load more” UIs on nextPageToken, not “page N of M”.
  • pageSize now allows up to 1000 in cursor mode; the 100 cap applies only to legacy page-number mode.
The same deprecations are annotated on the Rust REST and gRPC clients (page on ListOrdersRequest/GetUserTradesRequest/ListUserTradesRequest, and total/page/total_pages on their responses) and in the generated OpenAPI spec.

​
React hooks and MCP tools follow the cursor default

useUserOrders and useProfile now fetch with cursor pagination internally; they read the newest rows only, so returned data is unchanged, but the underlying responses no longer carry exact totals (total/page/totalPages are 0). On the MCP server, get_orders gains an optional pageToken cursor (with page deprecated).

​
Mainnet WebSocket ingress

The mainnet network preset now connects WebSockets to the dedicated ingress wss://ws.apimonaco.xyz/ws. The previous wss://api.monaco.xyz/ws host never resolved, so this is not a behavior change for any working client. Custom wsUrl overrides are unaffected.

​
Fixed

​
Spot equity marks at the live trade print

Spot holdings in the portfolio endpoints (GET /api/v1/portfolio/stats and GET /api/v1/portfolio/chart — spotEquity, totalEquity, and the equity series) are now marked at the last trade print on the asset’s preferred spot pair, matching how the streaming PnL feed already valued them. They were previously marked at the latest one-minute candle close, which lagged the live print. Spot equity values shift accordingly, and an asset whose only trades have aged into the trade archive is now priced instead of being valued at zero. Perpetual positions were unaffected. No request or response fields changed.

​
First-use cross risk-bucket order preview

POST /api/v1/margin/risk-buckets/simulate-order-risk (and gRPC SimulateRiskBucketOrderRisk) no longer returns 400/INVALID_ARGUMENT for a first-use CROSS risk bucket. The preview now snapshots the not-yet-created deterministic cross risk bucket virtually — funded from the parent margin account’s unallocated collateral, matching live order placement — including after the previous cross risk bucket was fully closed. No request or response fields changed.

​
Upgrade

Action items to review:
  1. Order and trade history is cursor-paginated by default. Omitting page/pageToken now returns a cursor walk over full history, not a recent page-number window, and total/page/totalPages are 0 in cursor mode. Move “page N of M” UIs onto nextPageToken, or pass the deprecated page to keep the old behavior for now.
  2. Use the iterators for full history. trading.iterateOrders() and profile.iterateUserTrades() manage the cursor for you.
  3. Larger cursor pages. pageSize can go up to 1000 in cursor mode.
  4. Spot equity values shift. Portfolio spotEquity/totalEquity now track the live spot print; expect small differences from the previous candle-close marking.
  5. Mainnet WebSocket host. If you hard-coded wss://api.monaco.xyz/ws, switch to the mainnet preset (or wss://ws.apimonaco.xyz/ws).