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

# Monaco Protocol SDK v1.0.33

This release scopes the MCP server behind capability profiles — a breaking change for authenticated MCP sessions — adds 36 MCP tools spanning perps, positions, portfolio, margin accounts, and related account/market data, and makes batch order replacement cancel-first across the TypeScript, Rust REST, and Rust gRPC clients. It also fixes `Retry-After` parsing on `APIError` and the `request_faucet` MCP tool, and corrects stale JWT references in client JSDoc. The MCP capability default is the one action item worth reviewing before you upgrade.

## Breaking: authenticated MCP sessions are scoped by a capability profile

Authenticated MCP sessions are now bounded by `MONACO_CAPABILITY` (`read` | `market-maker` | `full`, default `read`). Supplying a private key no longer unlocks the entire authenticated tool set: by default a key grants read-only tools, order placement/cancel/replace require `market-maker`, and fund-movement or privilege tools (vault approve/deposit/withdraw and `transfer_rewards`) require `full` or an explicit `MONACO_TOOL_ALLOWLIST` entry.

`MONACO_NETWORK` is now **required** whenever a private key is configured — the server no longer silently defaults an authenticated session to `mainnet`. New `MONACO_TOOL_ALLOWLIST` and `MONACO_TOOL_DENYLIST` variables give per-tool overrides, with the denylist winning over both the profile and the allowlist. See [Capability profiles](/sdk/mcp-server#capability-profiles) for the full policy.

## Added

### 36 new MCP tools

The MCP server adds 36 tools covering perps, positions, portfolio, margin accounts, and related account/market data that were previously absent from the MCP surface:

* **Perp market data** — `get_perp_market_config`, `get_perp_market_summary`, `get_mark_price`, `get_index_price`, `get_funding_state`, `get_open_interest`, `get_funding_history`, `get_all_funding_history`
* **Market** — `get_screener`, `get_market_stats`
* **Positions** — `get_positions`, `get_position`, `get_position_risk`, `get_position_history`, `get_position_pnl_history`
* **Portfolio** — `get_portfolio_summary`, `get_portfolio_performance`, `get_portfolio_realized_pnl`, `get_portfolio_assets`, `get_portfolio_margin`
* **Margin accounts** — `get_margin_accounts`, `get_parent_margin_account_summary`, `get_available_collateral`, `get_parent_margin_account_movements`, and the `simulate_parent_margin_order_risk` / `simulate_risk_bucket_order_risk` risk previews
* **Account & market data** — `get_user_trades`, `get_funding_payments`, `get_pending_withdrawals`, and the public `get_pulse` news feed

All of these are read tools under the default `read` profile, except `close_position` (which requires `market-maker`) and the collateral-movement tools (`add_position_margin`, `reduce_position_margin`, and the parent- and risk-bucket transfers), which are fund-movement and require `full`. The `@deprecated` per-margin-account forms are intentionally not exposed; their non-deprecated parent/risk-bucket equivalents are. Tool input/output schemas mirror the SDK's camelCase ergonomic types and cross-field refinements. See the [full MCP tool list](/sdk/mcp-server#available-tools).

## Changed

### Batch order replacement is cancel-first

`sdk.trading.batchReplace` / `batchReplaceMarginLimitOrders` — and the Rust REST/gRPC `batch_replace_orders` — are now **cancel-first**: the matching engine cancels every item's original before placing any replacement, in request order. A two-sided quote can shift across its own resting prices in one call without tripping self-trade prevention, and a replacement may lock funds freed by any original in the batch.

Failure semantics changed with it. An item whose replacement fails to **place** (insufficient balance, self-trade against an order outside the batch, risk rejection) now reports the error with its original **already cancelled** — previously a failed item left its original resting. Items that fail validation, or whose original cannot be found, still leave the original untouched.

### MCP tool inventory generated from a manifest

The tool inventory in the MCP README is now generated from a single deterministic manifest (`src/manifest.ts`) that classifies every tool by category, auth mode, capability profile, network restriction, and side effect. The capability policy and the test profile buckets derive from this manifest, and a CI drift gate fails if the documented tool set diverges from the tools the server actually registers. No tool behavior changed.

## Fixed

### `Retry-After` HTTP-date parsing on `APIError`

`APIError.retryAfter` now also parses the HTTP-date form of the `Retry-After` response header, converting it to the remaining delay in **seconds** (past dates clamp to `0`); previously an HTTP-date was dropped. All three RFC 7231 HTTP-date formats are accepted (IMF-fixdate, RFC 850, and asctime), timestamps are built as UTC, and impossible calendar dates (e.g. 31 Feb) or malformed values are ignored rather than coerced into a bogus delay. The numeric form is unchanged. The value is in **seconds** — multiply by `1000` before passing it to `setTimeout`. See [error handling](/sdk/typescript/error-handling).

### `request_faucet` MCP tool

The `request_faucet` MCP tool was dead: it referenced the removed `accessToken` auth wiring and always failed with "No access token available". It now calls the current faucet SDK path (`sdk.faucet.mint`) and takes the required Cloudflare Turnstile `turnstileToken` input. The tool remains network-restricted and is never registered on `mainnet`.

### Session-key auth documented in client JSDoc

The WebSocket client (`subscribeUserOrders`, `subscribeBalances`, `subscribeMovements`, `sendAuthenticate`), the React hooks (`useUserBalances`, `useUserMovements`, `useUserOrders`), and the WebSocket balance/movement event types no longer reference JWT/token authentication in their JSDoc. They now document that the user is identified from the signed session-key `Authenticate` handshake over `WS-AUTH\n<public_key>\n<timestamp>`, matching the tokenless v0.8.8 model, and that the handshake timestamp is bound into the signature and validated within a ±30s skew window (re-signed on every reconnect). Behavior and signatures are unchanged; these are documentation-only corrections.

## Upgrade

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

The MCP server ships at `1.0.33` too; it runs via `npx -y @0xmonaco/mcp-server`, so a restart of your assistant picks up the new version and the capability-profile behavior below.

Action items to review:

1. **Authenticated MCP sessions default to read-only.** After upgrading, an authenticated MCP server started without `MONACO_CAPABILITY` exposes read tools only — set `MONACO_CAPABILITY=market-maker` to place, cancel, and replace orders, or `full` for vault fund movement. `MONACO_NETWORK` is now required whenever a private key is set; the server no longer defaults to `mainnet`.
2. **Batch replace is cancel-first.** A replacement that fails to place now leaves its original **already cancelled**, not resting. Re-check any batch-replace error handling that assumed a failed item kept its original order live.
3. **`Retry-After` is in seconds.** `APIError.retryAfter` is delay-seconds (now also derived from HTTP-date headers); multiply by `1000` before passing it to `setTimeout`.


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