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

# V0.8.10

# Monaco Protocol SDK v0.8.10

This release closes the remaining gaps between the SDK surfaces and the live API: several new client surfaces (withdrawals, sub-accounts, faucet, application reporting), a reworked margin-account provisioning model, and full REST↔gRPC parity now that both transports share one set of handlers. It also removes a handful of dead endpoints and methods.

## Breaking changes

### Margin account provisioning is now implicit

The public `POST /api/v1/margin/accounts` provisioning endpoint and the SDK methods that called it (`createMarginAccount` / `ensureParentMarginAccount`) are **removed**. There is one parent margin account per wallet per application scope, and it is created automatically the first time you move collateral into a margin bucket.

Fund (and implicitly provision) a margin account with a collateral transfer-in:

```typescript theme={null}
await sdk.marginAccounts.transferCollateralToAutoMarginAccount({
  asset: "USDC",
  amount: "100",
  tradingPairId: "<margin-pair-uuid>",
});
```

`listMarginAccounts()` now returns the parent account row plus separate risk-bucket rows, and `getMarginAccountSummary(marginAccountId)` returns the parent summary — pass `{ tradingPairId }` to get a specific bucket summary. Summaries carry `margin_bucket_id` and `margin_mode` (`ISOLATED` / `CROSS`); parent rows leave the bucket fields unset.

### Standalone conditional-order creation removed

`tradingAPI.createConditionalOrder()`, the React `useTrade().createConditionalOrder` method, and `POST /api/v1/orders/conditional` are **removed** (the endpoint had no handler and returned 404). Attach take-profit / stop-loss when placing the order, or use `sdk.positions.attachPositionTpSl(...)` (`POST /api/v1/positions/{position_id}/tp-sl`). Listing and cancelling conditional orders is unchanged.

### `GET /api/v1/trades/user` removed from REST

This endpoint duplicated `GET /api/v1/accounts/trades` and is now **gRPC-only** (`TradesService.ListUserTrades`). REST clients should use `sdk.profile.getUserTrades()` / `GET /api/v1/accounts/trades`.

### Rust REST SDK: `refresh_token` → `refresh_session`

The Rust REST SDK auth method is renamed `refresh_session` (the endpoint, `POST /api/v1/auth/refresh`, is unchanged). This completes the JWT→session-key naming cutover started in v0.8.8.

## Added

### Withdrawals client

A low-level `sdk.withdrawals` surface plus REST `POST /api/v1/withdrawals` and `GET /api/v1/withdrawals/{withdrawal_index}` (and a gRPC `WithdrawalsService`):

* `initiateWithdrawal({ assetId, amount, destination })` (authenticated) debits the balance and returns `{ withdrawal_index, vault_address, calldata }` — the signed `executeSignedWithdrawal` calldata.
* `getWithdrawal(withdrawalIndex)` (public) re-fetches that signed calldata.

These return signed calldata without broadcasting. `sdk.vault.withdraw` remains the high-level flow that also submits the on-chain transaction.

### Delegated-agent owner reverse-lookup

`sdk.delegatedAgents.listDelegatedOwners()` (`GET /api/v1/delegated-agents/owners`) lets an agent discover which owners have an active delegation to it — keyed on the agent's own wallet address. Each entry carries the `owner_user_id` to pass into `createDelegatedSession`, so the owner id no longer has to be supplied out of band. The full delegated-agents surface is now proto-first and appears in the OpenAPI spec and the gRPC SDK.

### New account-management surfaces

* **Sub-accounts** — `sdk.subAccounts`: `list()`, `createLimit()`, `getLimits()`, `updateLimit()`, `deleteLimit()` (limit mutations require the `ManageSubAccounts` permission).
* **Faucet** — `sdk.faucet.mint()` (testnet-only, rate-limited).
* **Funding payments** — `sdk.profile.listFundingPayments(params?)` (`GET /api/v1/accounts/funding-payments`).
* **Application reporting** (backend / `x-server-key` auth) — `applications.listApplicationOrders()`, `listApplicationUsers()`, `listApplicationMovements()`, `listApplicationBalances()`, and `getApplicationStats()`.

### Market

* `sdk.market.getTradingPair(tradingPairId)` — fetch a single pair by UUID.
* `sdk.market.getScreener(params?)` — paginated market screener with 1h/24h/7d quote-volume and price-change windows plus a 7-day daily snapshot.

### Trades

* `sdk.trades.getTradeById(tradeId)` — fetch a single public trade.

### gRPC AccountsService implemented

`GetUserTrades`, `GetPortfolioStats`, and `GetPortfolioChart` are now implemented over gRPC (previously `UNIMPLEMENTED`) and mirror the REST endpoints exactly.

### Generated wire-types

`@0xmonaco/types` now ships a generated `@0xmonaco/types/wire` namespace (raw request/response schemas generated from the canonical OpenAPI spec) plus an `OPERATION_IDS` list. The hand-written ergonomic types assert field coverage against the wire schemas, so a missing field becomes a compile error.

### Rust REST SDK resync

The Rust REST SDK (`monaco-sdk`) was resynced from the canonical OpenAPI spec, adding \~38 previously-absent methods across margin accounts, positions, perp markets, screener / open-interest, trades, portfolio, applications, delegated-agents, and withdrawals. The vendored spec is now regenerated automatically and drift-gated in CI.

## Changed

### REST and gRPC now share one set of handlers

The market, orders, positions, fees, accounts, and health surfaces are now served by shared handler logic on both transports, with the REST gateway as the source of truth. REST request/response wire shapes are unchanged; the gRPC surface is aligned to match REST — including error codes (business-rule violations return `INVALID_ARGUMENT`), decimal precision, and normalized amounts.

* `GetMarketMetadata` no longer returns live `mark_price` / `index_price`; read live pricing from `getMarkPrice` / `getIndexPrice`.
* gRPC `AuthService` now records the caller's origin / IP / user-agent on the session and enforces the application's allowed-origins list on `Challenge`, matching REST.

### `createDelegatedSession` response

The response no longer includes `access_token` (it never did over the wire). It carries `expires_at`, `delegation_id`, `owner_user_id`, and `agent_address`. The request now requires the agent's `sessionPublicKey` alongside `ownerUserId`.

### User-trade timestamp format

`executed_at` on user trades (`GET /api/v1/accounts/trades`) now serializes with an explicit `+00:00` UTC offset (e.g. `2025-01-15T10:30:00+00:00`) instead of a trailing `Z`. Both denote the same instant; any RFC 3339 / ISO 8601 parser is unaffected.

### Spec and wire-type corrections

The OpenAPI spec and generated wire-types now document fields the REST API has always returned but previously under-described — additional order fields (`quantity_raw`, lifecycle timestamps, `client_order_id`, `quote_volume`, …), user-trade detail fields, and the `order_by` query parameter on `GET /api/v1/orders`. The embedded match-result field `order_status` is renamed to `status`, and the public trade wire shape is now an envelope (`{ data, event_type, trading_pair_id, trading_mode }`). REST JSON responses are byte-for-byte unchanged.

## Upgrade

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


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