> ## 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. # Post apiv1marginrisk bucketssimulate order risk ## OpenAPI ````yaml /proto-openapi/api/openapi.yaml post /api/v1/margin/risk-buckets/simulate-order-risk openapi: 3.0.3 info: title: Monaco Protocol API description: REST API for the Monaco Protocol hybrid CLOB exchange. version: 1.0.0 servers: - url: https://staging.apimonaco.xyz description: Staging server (Testnet) security: [] tags: - name: AccountsService - name: ApplicationsService - name: AuthService - name: BuildercodeRewardsService - name: CopyTradingService - name: DelegatedAgentsService - name: FaucetService - name: FeesService - name: HealthService - name: ManagedMarketsService description: |- Wallet-authenticated maker assignments. The signed session must match both configured maker user and application. Owner IDs are process fences, never auth. Only wallet sessions are supported; delegated-agent sessions receive 403. - name: MarginAccountsService description: |- Current public isolated-margin semantics: - a user has one parent margin account per application scope - opening orders create or reuse isolated position buckets under that parent - parent account creation is handled internally by margin workflows - name: MarketService - name: OrderbookService - name: OrdersService - name: PositionsService description: |- Current public isolated-margin semantics: - positions link to a parent margin account and, when applicable, a bucket id - opening orders create or reuse isolated position buckets under the parent - users can open another isolated position by reusing the parent account with a different market bucket - name: PulseService - name: SweeperService - name: TraderCodeService - name: TradesService - name: WhitelistService - name: WithdrawalsService paths: /api/v1/margin/risk-buckets/simulate-order-risk: post: tags: - MarginAccountsService operationId: simulate_risk_bucket_order_risk requestBody: content: application/json: schema: $ref: '#/components/schemas/SimulateRiskBucketOrderRiskRequest' required: true responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/SimulateOrderRiskResponse' '429': description: >- Read rate limit exceeded — every authenticated read draws one request from the account's read budget; retry after the interval in details.retryAfter security: - monacoSignature: [] - monacoHttpSignature: [] components: schemas: SimulateRiskBucketOrderRiskRequest: type: object properties: tradingPairId: type: string nullable: true format: uuid strategyKey: type: string nullable: true side: type: string nullable: true positionSide: type: string description: Deprecated compatibility value; `side` is authoritative. nullable: true orderType: type: string nullable: true price: type: string nullable: true quantity: type: string nullable: true leverage: type: string description: Required for normal orders; optional and ignored for reduce-only. nullable: true reduceOnly: type: boolean nullable: true marginMode: type: string description: 'Risk bucket mode. Defaults to ISOLATED. Values: ISOLATED, CROSS.' nullable: true selectedTradingPairIds: deprecated: true type: array items: type: string minLength: 1 format: uuid description: >- Deprecated: accepted and ignored. Cross scope is derived from trading (a pair joins the cross bucket when a cross order on it succeeds; after its positions close it stays listed until a later successful cross order on another pair reconciles the bucket), so a cross preview has nothing to declare: it runs against the account's active cross bucket — or the deterministic bucket a first cross order would create — and the previewed pair is in scope by construction. Rejected for ISOLATED, as before. The response's selectedTradingPairIds reports the derived scope (recorded pairs, pairs with open positions in the bucket, and the previewed pair), never this list. nullable: true slippageToleranceBps: maximum: 1000 type: integer description: >- MARKET only: client slippage tolerance in basis points, 0..1000, the same rule placement enforces — a LIMIT or IOC preview carrying it is rejected. Tightens the previewed walk to the band the real order will run under and never widens it; omit for the placement default. format: int32 nullable: true marginAccountId: type: string description: >- The margin account the preview runs against: the default margin account (the default) or any of the caller's open sub-accounts, previewing that account's own risk buckets. nullable: true SimulateOrderRiskResponse: type: object properties: accepted: type: boolean nullable: true rejectReason: type: string nullable: true equityAfter: type: string nullable: true initialMarginRequiredAfter: type: string nullable: true maintenanceMarginRequiredAfter: type: string nullable: true freeCollateralAfter: type: string nullable: true estimatedFee: type: string description: >- What this order pays in fees once its WHOLE size has executed, priced by the role each part of it plays against the book right now: the taker rate (plus the application's additional taker fee) on the quantity that would cross immediately, and the maker rate on the quantity that would rest and be filled later. Both rates are the caller's own tier-resolved rates. One figure covers both cases — an order that crosses entirely, one that rests entirely, and every split in between. Signed: NEGATIVE means a net rebate, which is the honest answer for a resting order on a pair whose maker fee is negative. Populated even when `accepted` is false, and populated for reduce-only orders — closing a position pays fees like any other fill. It assumes the resting part eventually fills, so it states what the order costs if it runs to completion, not a probability-weighted figure: cancel before the remainder fills and only the crossing part was ever charged. ABSENT — never zero — when the engine could not price the order: it was refused before it could be matched, or its resolved maker tier exceeds the pair's cap. Absence means unknown, so do not render it as a free order. nullable: true estimatedLiquidationPrice: type: string description: |- Estimated liquidation mark-price. In ISOLATED mode, this is the position/risk-bucket threshold. In CROSS mode, it is conditional: it varies only the target position's mark while all other marks in the cross risk bucket remain unchanged. Other position marks, funding, realized PnL, fees/reserves, and collateral can change it. Treat an absent or blank value as unavailable, never as zero. nullable: true marginAccountId: type: string description: >- The margin account the simulation was resolved against. Always populated; useful for auto-resolved buckets where the caller didn't supply the id. nullable: true strategyKey: type: string description: Populated when the simulated account is an auto-resolved bucket. nullable: true riskBucketId: type: string description: Present when the simulation resolved against a risk bucket. nullable: true marginMode: type: string description: >- Present when the simulation resolved against a risk bucket. Values: ISOLATED, CROSS. nullable: true selectedTradingPairIds: type: array items: type: string minLength: 1 format: uuid description: >- The cross scope the preview ran against; absent for isolated previews and never a request's deprecated list. `SimulateRiskBucketOrderRisk` in CROSS mode reports the DERIVED scope: the active cross bucket's recorded pairs (a pair whose positions have closed stays recorded until a later cross order on another pair reconciles the bucket), every pair with an open position in that bucket, and the previewed pair — the previewed pair alone before the first cross order. `SimulateOrderRisk` and `SimulateParentMarginOrderRisk` report the recorded pairs plus the previewed pair. nullable: true expectedMatchResult: allOf: - $ref: '#/components/schemas/MatchResult' description: >- The simulated match the engine ran to admit this order (0XM-2746): the same `MatchResult` shape `CreateOrderResponse.match_result` carries for a real placement, produced by the same `simulate_match_with_stp` walk over the live book at the moment of the preview — under the caller's `slippage_tolerance_bps` merged tighter-wins with the mandatory 1,000 bps protective band, the caller's own self-trade-prevention default (the preview runs under the caller's wallet, as placement does) and reduce-only sizing. Not a handler-side re-walk of an orderbook snapshot, so a preflight and the placement it precedes read the same numbers — the reason this rides the risk simulation rather than a separate quote endpoint. What a preview cannot carry: a post-only flag, TP/SL legs and a per-order self-trade-prevention override, so a post-only placement that would cross is refused by placement, not by this preview. Fields: `total_filled` is what the walk fills; `remaining_quantity` what it could NOT fill inside the merged band — the partial-fill / band-cut indicator (0 means the whole size executes; a MARKET preview with a non-zero remainder comes back partially filled when placed); `average_fill_price` is the quantity-weighted fill price and `execution_price_range.worst_price` the worst level reached (highest ask a BUY takes, lowest bid a SELL hits), both absent when nothing crosses; `status` is the status placement would end in: FILLED for a full fill, CANCELLED for a MARKET order the band or the depth cuts short (a MARKET remainder cannot rest, so the fills execute and the rest is cancelled — read `remaining_quantity` for the partial fill), SUBMITTED for a LIMIT that rests, PARTIALLY_FILLED for a LIMIT that crosses partly and rests the remainder; `actual_slippage_bps` the realized slippage against `reference_price` as the engine computes it for a placement, absent when nothing crosses; `max_slippage_bps` echoes the caller's tolerance, not the merged band. A LIMIT preview that would rest reports 0 filled, the full size remaining and no prices. For a LIMIT or IOC preview the engine measures slippage against the LIMIT price and reports none when every fill improved on it, exactly as the placement's `match_result` does; `reference_price` below is therefore published for MARKET previews only. Priced against the book RIGHT NOW. For a take-profit / stop-loss the close runs later, on a different book, under the wider 1,200 bps band the engine stamps on a triggered market leg and anchored at trigger time — so for a TP/SL estimate apply `actual_slippage_bps` to the TRIGGER price as an impact figure rather than displaying this call's absolute average price. Fees for this walk are `estimated_fee` above, at the caller's own tier, which can lag the engine's copy by one refresh interval. PRESENT ONLY when `accepted` is true. Absent — never zeros — on every refused preview (`accepted: false` with a `reject_reason`): validation, an unknown market or account, insufficient margin, a maker-risk constraint, a MARKET order with nothing fillable inside the band, and the post-match maker-risk revalidation, whose match the engine discards. Such previews may still carry `estimated_fee`, which is priced independently of risk state. Treat absence as unknown, not as "fills at zero". nullable: true referencePrice: example: '100.25' type: string description: >- The touch on the taking side when a MARKET preview ran (best ask for a BUY, best bid for a SELL) — what expectedMatchResult's walk and its actualSlippageBps are measured from. Present only when accepted is true and the preview is a MARKET order; a LIMIT or IOC preview is measured against its own limit price and publishes nothing here. nullable: true rejectCode: example: MARGIN_MODE_CONFLICT type: string description: >- Structured code of the refusal behind rejectReason, the same code placing the order would return in the error envelope (e.g. MARGIN_MODE_CONFLICT when the margin account holds the pair in its other margin mode; INVALID_ORDER for the catch-all). Present for client-class refusals; absent on an accepted preview, and absent when the preview failed on a server-side fault (rejectReason is then a generic retry message). nullable: true MatchResult: type: object properties: tradesCount: example: 2 type: integer description: Number of trades generated by this order format: int32 nullable: true totalFilled: example: '0.2' type: string description: Total quantity filled nullable: true remainingQuantity: example: '0.3' type: string description: Remaining unfilled quantity nullable: true averageFillPrice: example: '35100.00' type: string description: Volume-weighted average fill price nullable: true status: example: PARTIALLY_FILLED type: string description: Resulting order status after matching nullable: true actualSlippageBps: example: 15 type: integer description: Actual slippage incurred in basis points format: int32 nullable: true maxSlippageBps: example: 50 type: integer description: Maximum slippage tolerance that was set format: int32 nullable: true executionPriceRange: $ref: '#/components/schemas/ExecutionPriceRange' ExecutionPriceRange: type: object properties: bestPrice: example: '2045.00' type: string description: Best execution price achieved nullable: true worstPrice: example: '2052.00' type: string description: Worst execution price in the fill nullable: true securitySchemes: monacoSignature: type: apiKey description: >- Ed25519 session-key request signing. Every authenticated request carries three headers: `X-Monaco-PublicKey` (64-char lowercase-hex session public key), `X-Monaco-Timestamp` (Unix milliseconds, within 30s of server time), and `X-Monaco-Signature` (hex ed25519 signature). The signature is over `METHOD\npath?query\ntimestamp_ms\nSHA256_hex(body)`, where the body hash is the SHA-256 of the empty byte string when there is no body. Obtain the session keypair from `POST /api/v1/auth/challenge` followed by `POST /api/v1/auth/verify`. name: X-Monaco-Signature in: header monacoHttpSignature: type: apiKey description: >- RFC 9421 Ed25519 session-key request signatures. Send Signature-Input, Signature, and Content-Digest together; never combine them with X-Monaco-* credentials. The monaco signature covers @method, @path, @query, and content-digest in that order, with created (Unix seconds within 30s of server time), keyid (registered lowercase-hex session public key), and alg=ed25519 parameters. Content-Digest uses RFC 9530 sha-256 over the exact body bytes, including the empty body. Query coverage retains ordering and percent encoding. Timestamp freshness does not reject repeated identical requests; use endpoint idempotency where supported. Existing legacy signing remains supported during server-first migration; SDK RFC 9421 signing is opt-in. See https://docs.0xmonaco.com/reference/http-message-signatures for the complete profile and trust model. name: Signature in: header ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.