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

# 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

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

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`).


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