Skip to main content
For high-level concepts, see Perps Collateral for collateral, Order Management for risk simulation, and Positions for account state.

​
Lifecycle

Parent margin account creation is handled internally. Use transferCollateralToParentMarginAccount for first-time margin funding; it does not take a tradingPairId and does not open a risk bucket. Orders and risk simulation can use the accountless methods below without storing a marginAccountId.
​
(params?: ListMarginAccountsParams) => Promise<ListMarginAccountsResponse>
Paginated list of the user’s margin accounts. The result includes the parent account row plus a separate row per risk bucket (risk bucket rows carry riskBucketId, marginMode, and tradingPairId).Parameters:
  • params?: ListMarginAccountsParams
    • page?: number — defaults to 1
    • pageSize?: number — defaults to 20, max 100
    • state?: string — filter by accountState
    • tradingPairId?: string — filter to bucket rows scoped to a specific trading pair
Returns: ListMarginAccountsResponse:
  • accounts: MarginAccountSummary[]
  • total: number
  • page: number
  • pageSize: number
​
(params?: GetMarginAccountSummaryParams) => Promise<MarginAccountSummary>
Live state of the authenticated wallet’s parent margin account. Monaco resolves the parent account from the wallet and application scope; no marginAccountId lookup is required. Passing tradingPairId returns the summary for that pair’s risk bucket under the parent — the risk bucket fields (riskBucketId, marginMode, tradingPairId) are populated on risk bucket summaries and left unset on the parent.Parameters:
  • params?: GetMarginAccountSummaryParams
    • tradingPairId?: string — return the bucket summary scoped to this trading pair
Returns: MarginAccountSummary:
  • marginAccountId: string
  • label?: string
  • riskBucketId?: string — set on risk bucket summaries; unset on the parent
  • marginMode?: "ISOLATED" | "CROSS" — set on risk bucket summaries; unset on the parent
  • tradingPairId?: string — trading pair this risk bucket is scoped to, if set
  • selectedTradingPairIds?: string[] — on the cross risk-bucket row only: the bucket’s recorded scope. A pair joins when a cross order on it succeeds. After its positions close, removal is lazy: it remains listed until a later successful cross order on a different pair reconciles the bucket. Pairs declared before scope became derived follow the same delayed pruning after they trade and close. Omitted on the parent row and isolated rows; it may also be omitted when a cross bucket has no recorded scope
  • strategyKey?: string — strategy tag, if set
  • accountState: string — "NORMAL" | "PENDING_LIQUIDATION" | "BAD_DEBT"
  • equity: string
  • initialMarginRequired: string
  • maintenanceMarginRequired: string
  • freeCollateral: string — trading-margin headroom for existing cross exposure
  • withdrawableCollateral: string — the largest amount the withdrawal gate will accept (capped by unearmarked principal as well as margin requirements, funding, and PnL; an unrealized gain does not raise it). Size transfers — and new isolated/first-use positions, which allocate principal through the same gate — from this field, not freeCollateral
  • totalPositionNotional: string
  • unrealizedPnl: string
  • realizedPnl: string
  • updatedAt: string — ISO 8601
  • availableOrderCollateral?: string — the collateral still available to open new orders in this risk bucket: the largest increase in the bucket’s worst-case order reserve the risk engine’s admission gate accepts, automatic top-up from the parent’s unallocated capacity included. Unlike withdrawableCollateral it credits an unrealized gain in full, and it already contains the bucket’s live free collateral — don’t add freeCollateral or unrealizedPnl on top (it can legitimately differ from this row’s freeCollateral, a persisted reconstruction that can’t see resting-order reserves). Not additive across rows: every bucket’s figure includes the same parent headroom. A requirement budget, not an order size — a reducing, reduce-only, or opposite-side order sheltered by a larger resting ladder needs less or none of it (and can be admitted when this is zero). Collateral, not notional (divide by the market’s initial margin rate). Present only on risk-bucket rows served from a live risk engine snapshot — absent on parent rows and fallback reads, so handle undefined; the per-order authority remains simulateRiskBucketOrderRisk
Example:
​
(marginAccountId: string, params?: GetMarginAccountSummaryParams) => Promise<MarginAccountSummary>
Legacy compatibility method for callers that already store a marginAccountId. Prefer getParentMarginAccountSummary for new integrations.

​
Funding

​
(marginAccountId: string, request: TransferCollateralRequest) => Promise<TransferCollateralResponse>
deprecated
Deprecated. This endpoint overloads two unrelated operations: with tradingPairId it allocates into that pair’s isolated risk bucket (crediting the sole open position’s stored margin), without it it performs a wallet-debiting deposit to the parent. Use transferCollateralToRiskBucket for bucket funding — which now applies the same position-margin credit — and transferCollateralToParentMarginAccount for wallet-to-margin deposits. Kept for backward compatibility; no removal date scheduled.When tradingPairId is omitted the transfer is scoped to the parent account, even if an active cross-risk bucket exists. Previously omitting tradingPairId could route the transfer into an active cross-risk bucket — this is now fixed.Parameters:
  • marginAccountId: string
  • request: TransferCollateralRequest
    • asset: string — e.g. "USDC"
    • amount: string — decimal string in collateral units
    • tradingPairId?: string — target a specific bucket under the parent; omit to target the parent
    • strategyKey?: string — strategy tag for the bucket
Returns: TransferCollateralResponse:
  • movementId: string
  • marginAccountId: string
  • strategyKey?: string — the bucket’s strategy tag, if set
  • asset: string
  • amount: string
  • status: string
  • newEquity: string — equity after the transfer
  • newTotalCollateralValue: string — total collateral value in the account after the transfer
  • newWithdrawableCollateral: string — amount available to withdraw after the transfer
Use newTotalCollateralValue and newWithdrawableCollateral to update the UI immediately without a separate read.
​
(marginAccountId: string, request: TransferCollateralRequest) => Promise<TransferCollateralResponse>
Release collateral from a risk bucket, or move it from a known margin account back to the wallet.Which of those happens depends on how the bucket is named (0XM-2414):
  • tradingPairId — releases that pair’s isolated bucket. The collateral returns to the parent margin account, where it can be redeployed; it does not reach the wallet.
  • marginMode: "CROSS" — releases the account’s cross bucket, which has no trading pair and cannot be named any other way. Also returns to the parent. The two are mutually exclusive.
  • neither — a parent-scoped transfer to the wallet. Prefer transferCollateralFromParentMarginAccount for new integrations.
Constrained by withdrawableCollateral. Trying to withdraw more will fail with a 400.Parameters:
  • marginAccountId: string
  • request: TransferCollateralRequest
    • asset: string — e.g. "USDC"
    • amount: string — decimal string in collateral units
    • tradingPairId?: string — release that pair’s isolated risk bucket to the parent; omit to target the parent
    • marginMode?: "ISOLATED" | "CROSS" — pass "CROSS" to select the account’s cross risk bucket, which has no trading pair and cannot be named by tradingPairId; the released collateral returns to the parent margin account. Mutually exclusive with tradingPairId — passing both is rejected client-side
    • strategyKey?: string — strategy tag for the bucket
Same response shape as transferCollateralToMarginAccount, including newTotalCollateralValue and newWithdrawableCollateral.
​
(request: TransferCollateralToParentMarginAccountRequest) => Promise<TransferCollateralResponse>
Move collateral from the user’s wallet into the parent margin account without specifying a marginAccountId. This endpoint does not accept tradingPairId and does not open a risk bucket.Parameters:
  • request: TransferCollateralToParentMarginAccountRequest
    • asset: string — e.g. "USDC"
    • amount: string — decimal string
Returns: Same TransferCollateralResponse shape as transferCollateralToMarginAccount.Example:
​
(request: TransferCollateralToRiskBucketRequest) => Promise<TransferCollateralResponse>
Move collateral into a specific risk bucket without specifying a marginAccountId. Monaco resolves the parent account and ensures the risk bucket exists automatically.What the money becomes when the isolated bucket holds an open position is stated by applyToPositionMargin — the two intents want opposite fates for the same dollars, and either way the liquidation cushion improves identically:
  • Omitted or true (the default is the human “Adjust Margin” gesture): the amount is committed to the position’s stored margin. Effective leverage drops and stays down, initial margin required rises by the amount, and free collateral is unchanged — new orders cannot spend it.
  • false: a plain allocation. Free collateral rises and the next order can spend it. Programmatic funding loops that top a bucket up to a free-collateral target must pass false — under the default, each top-up converts into requirement and the loop never converges.
A flat isolated bucket has nothing to credit (both values are a plain allocation). The cross form does not take the field at all — cross risk is pooled at bucket equity, so TransferCollateralToCrossRiskBucketRequest types it never and the request validator rejects it even as false; omit it entirely on a cross transfer. (The raw REST and gRPC bodies are laxer, rejecting only an explicit true.) The response’s positionMarginCredited reports what actually happened: true — the credit landed; false — it degraded to a plain allocation because the persisted position row was stale (close/reopen race; re-issue the Adjust Margin once the new row lands); absent — no credit was in play.Parameters:
  • request: TransferCollateralToRiskBucketRequest — a union on marginMode:
    • Isolated (marginMode omitted or "ISOLATED"):
      • asset: string — e.g. "USDC"
      • amount: string — decimal string
      • tradingPairId: string — UUID of the trading pair
      • strategyKey?: string — omit to target the default risk bucket for the pair
      • applyToPositionMargin?: boolean — see above; omitted means true (commit to the open position’s stored margin), false keeps the amount as spendable free collateral
    • Cross (marginMode: "CROSS"):
      • asset: string
      • amount: string
      • nothing else. A cross transfer names no pairs: the cross bucket’s scope is derived from trading — a pair joins the bucket when a cross order on it succeeds — so funding has nothing to declare. After that pair’s positions close, removal is lazy: it remains listed until a later successful cross order on a different pair reconciles the bucket. Read the current scope from the cross bucket’s row in listMarginAccounts() (selectedTradingPairIds) or from this call’s response; the parent summary row carries no scope. Pairs declared before scope became derived follow the same delayed pruning after they trade and close. Because scope no longer needs declaring, simulateParentMarginOrderRisk and the pair-filtered summaries resolve a never-traded pair to the account’s cross bucket instead of refusing it.
selectedTradingPairIds is no longer part of the cross request. It used to declare — and on every top-up replace — the bucket’s scope, which meant a top-up that restated a partial list silently evicted every flat pair it forgot. The raw REST and gRPC bodies still accept the field for pre-deprecation clients and ignore it; the SDK types it never and its validator rejects it so the mistake is caught at compile time rather than believed to have taken effect.
Returns: Same TransferCollateralResponse shape as transferCollateralToMarginAccount.Example:
​
(request: TransferCollateralFromParentMarginAccountRequest) => Promise<TransferCollateralResponse>
Move collateral from the parent margin account back to the user’s wallet without specifying a marginAccountId.Parameters:
  • request: TransferCollateralFromParentMarginAccountRequest
    • asset: string — e.g. "USDC"
    • amount: string — decimal string
Returns: Same TransferCollateralResponse shape as transferCollateralFromMarginAccount.
​
(params?: GetAvailableCollateralParams) => Promise<GetAvailableCollateralResponse>
Check what’s actually movable from the user’s wallet into a margin account, and what can come back out. The two directions are separate fields: marginTransferable is wallet-to-margin capacity, marginAvailableCollateral is the largest amount that can currently leave the parent margin account.Parameters:
  • params?: GetAvailableCollateralParams
    • asset?: string — defaults to USDC
Returns: GetAvailableCollateralResponse:
  • asset: string
  • walletAvailable: string — unlocked spot balance
  • walletLocked: string — locked by spot orders / pending withdrawals
  • marginTransferable?: string — eligible to transfer in
  • marginAvailableCollateral?: string — the largest amount that can currently leave the parent margin account, matching MarginAccountSummary.withdrawableCollateral. Not trading headroom for existing cross exposure: it is capped by unearmarked principal as well as by margin requirements, and an unrealized gain does not raise it. The summary’s freeCollateral remains the trading-margin headroom for existing cross exposure — but a new isolated or first-use position allocates principal through the same gate this field measures, so size those from this field (or withdrawableCollateral), not from freeCollateral.

​
Activity

​
(params?: GetMarginAccountMovementsParams) => Promise<GetMarginAccountMovementsResponse>
Collateral movements (transfers in / out) recorded against the authenticated wallet’s parent margin account. PnL, funding, and fees are tracked through other endpoints (getPaginatedUserMovements and GET /api/v1/accounts/funding-payments).Parameters:
  • params?: GetMarginAccountMovementsParams
    • movementType?: "TRANSFER_IN" | "TRANSFER_OUT"
    • page?: number — at most 10,000; a larger page is rejected
    • pageSize?: number
Returns: GetMarginAccountMovementsResponse:
  • movements: MarginAccountMovement[] — each with movementId, movementType, asset, amount, createdAt
  • total: number — bounded by the pagination reach: exact up to pageSize × 10,000 rows and saturating there, so a caller with more movements than page-number mode can page through reads the cap, not its lifetime total
  • page: number
  • pageSize: number
​
(marginAccountId: string, params?: GetMarginAccountMovementsParams) => Promise<GetMarginAccountMovementsResponse>
Legacy compatibility method for callers that already store a marginAccountId. Prefer getParentMarginAccountMovements for new integrations.

​
Pre-trade simulation

​
(request: SimulateOrderRiskRequest) => Promise<SimulateOrderRiskResponse>
Preflight a perp order against the authenticated wallet’s parent margin account without placing it. Monaco resolves the parent account from the wallet and application scope.Parameters:
  • request: SimulateOrderRiskRequest
    • tradingPairId: string
    • side: "BUY" | "SELL"
    • positionSide?: "LONG" | "SHORT" | "NONE" — deprecated compatibility field; if supplied, it must agree with side
    • orderType: "LIMIT" | "MARKET"
    • price?: string — required for LIMIT
    • quantity: string
    • leverage: string — decimal string, e.g. "10"
    • reduceOnly?: boolean
    • slippageToleranceBps?: number — MARKET only, 0–1000, the rule the server applies to a placed MARKET order (a LIMIT preview carrying it is rejected with the placement’s message). Tightens the previewed walk to the band the real order will run under, so expectedMatchResult and estimatedFee price under it. Omit for the placement default; it never widens the band. To carry a previewed value into placement, note that placeMarketOrder and the batch helpers take slippageTolerance as a ratio (0.05 = 500 bps): pass slippageToleranceBps / 10_000 — a slippageToleranceBps key on those calls is not forwarded. On a first-use isolated preview the value is also forwarded to the bucket’s auto-funding for parity with placement; that path floors it at 1,000 bps, so today it does not change the funded figure.
Returns: SimulateOrderRiskResponse:
  • accepted: boolean
  • rejectReason?: string — human-readable when accepted: false
  • marginAccountId: string — the resolved margin account the simulation ran against
  • strategyKey?: string — the bucket’s strategy tag, if set
  • marginMode?: "ISOLATED" | "CROSS" — the resolved risk-bucket mode, if set
  • riskBucketId?: string — the risk bucket the simulation resolved against, if any
  • selectedTradingPairIds?: string[] — cross previews only, never a caller’s list: from simulateRiskBucketOrderRisk the derived scope the preview ran against (the cross bucket’s recorded pairs — including any still listed after their positions closed — every pair with an open position in it, and the previewed pair; the previewed pair alone before the first cross order); from simulateOrderRisk and simulateParentMarginOrderRisk, the recorded pairs plus the previewed pair
  • equityAfter: string
  • initialMarginRequiredAfter: string
  • maintenanceMarginRequiredAfter: string
  • freeCollateralAfter: string
  • estimatedFee?: string — what the order pays in fees once its whole size has executed: the taker rate (plus the application’s additional taker fee) on the quantity that would cross immediately, the maker rate on the quantity that would rest. One figure whether the order fills, rests, or splits between the two. Signed — negative is a net rebate, which is what a resting order earns on a pair whose maker fee is negative. Populated even when accepted: false, and for reduce-only orders. Assumes the resting part eventually fills. Absent — never 0 — when the engine could not price the order; treat absence as unknown, not free.
  • estimatedLiquidationPrice?: string — isolated simulated position/risk-bucket threshold; cross conditional per-target-position estimate, not a whole-account scalar. Absent or blank means unavailable, never 0.
  • expectedMatchResult?: MatchResult — the simulated match the engine ran to admit the order: the same MatchResult shape a placement’s matchResult carries, from the same walk over the live book at the moment of the preview, under slippageToleranceBps merged tighter-wins with the 1,000 bps protective band and your wallet’s self-trade-prevention default (the preview runs under your wallet, as placement does). Not a client-side re-walk, so preflight and placement read the same numbers. totalFilled is what would execute; remainingQuantity what the band or the depth leaves unfilled — the partial-fill indicator, a MARKET preview with a non-zero remainder is a warning that the size does not clear the previewed book — placement runs against a later book, so read the placement’s own status and quantities rather than treating this as the fill it will get; averageFillPrice and executionPriceRange.worstPrice are the fill levels (highest ask a BUY takes, lowest bid a SELL hits), null 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 remainingQuantity for the partial fill), SUBMITTED for a LIMIT that rests, PARTIALLY_FILLED for a LIMIT that crosses partly and rests the remainder; actualSlippageBps is the realized slippage against referencePrice — for a LIMIT or IOC preview, against the limit price, null when every fill improved on it; maxSlippageBps echoes your tolerance. A preview cannot carry postOnly, TP/SL legs or a per-order self-trade-prevention override, so a post-only order that would cross is refused by placement, not here. Present only when accepted is true; null on every refused preview (accepted: false with a rejectReason), including the post-match maker-risk rejection — treat absence as unknown, not as a zero fill.
  • referencePrice?: string — the touch on the taking side when a MARKET preview ran (best ask for a BUY, best bid for a SELL), which expectedMatchResult 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.
These price against the book right now. A take-profit or stop-loss closes later, on a different book, under the wider 1,200 bps band a triggered market leg carries and anchored at trigger time — so to size a TP/SL target, preview the close as a reduce-only MARKET order of the position’s size and apply expectedMatchResult.actualSlippageBps to your trigger price as an impact figure, rather than displaying this call’s absolute expectedMatchResult.averageFillPrice. The fee tier the preview reads can lag the engine’s own copy by one refresh interval, so estimatedFee and the fee settled moments later can differ by a tier step in that window.Example:
Common pattern: run on every order-form change with debouncing, and disable the place-order button when accepted === false.
​
(marginAccountId: string, request: SimulateOrderRiskRequest) => Promise<SimulateOrderRiskResponse>
Legacy compatibility method for callers that already store a marginAccountId. Prefer simulateParentMarginOrderRisk for new integrations.
​
(request: SimulateRiskBucketOrderRiskRequest) => Promise<SimulateOrderRiskResponse>
Preflight an order against a risk bucket without storing a marginAccountId. Accepts both isolated and cross modes via a discriminated union on marginMode.Isolated (marginMode?: "ISOLATED"):
  • tradingPairId: string
  • marginMode?: "ISOLATED" — default when omitted
  • strategyKey?: string — omit for the default risk bucket
  • side, orderType, price?, quantity, leverage, reduceOnly?
Cross (marginMode: "CROSS"):
  • tradingPairId: string — the pair being previewed
  • marginMode: "CROSS" — required
  • side, orderType, price?, quantity, leverage, reduceOnly?
  • nothing else. A cross preview names no pairs: the cross bucket’s scope is derived from trading — a pair joins the bucket when a cross order on it succeeds; after its positions close, removal is lazy: it remains listed until a later successful cross order on a different pair reconciles the bucket — so the previewed pair is in scope by construction and there is nothing to declare. The response’s selectedTradingPairIds reports the derived scope the preview ran against: the active cross bucket’s recorded pairs (including any still listed after their positions closed), every pair with an open position in it, and the previewed pair (the previewed pair alone before the first cross order).
selectedTradingPairIds is no longer part of the cross request. It used to be required (non-empty, containing tradingPairId, covering every pair with an open cross position) while the server never priced anything from it — the engine prices the positions it holds whatever the caller declared — so it only ever produced 400s. The raw REST and gRPC bodies still accept the field for pre-deprecation clients and ignore it; the SDK types it never and its validator rejects it so the mistake is caught at compile time rather than believed to have taken effect.
Isolated simulation works before that pair’s risk bucket exists: the API models the first-use bucket virtually and funds it with the collateral live placement would auto-attach. Cross simulation likewise works before the user has placed their first cross order — the API resolves the deterministic cross risk bucket and estimates auto-collateral, matching live placement.For cross simulation, estimatedLiquidationPrice is conditional per target position, not a whole-account scalar: 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. Render it as a conditional liquidation price; an absent or blank value is unavailable, never 0.Returns: Same SimulateOrderRiskResponse shape as simulateOrderRisk.Isolated example:
Cross example:

​
Errors

  • 400 on transferCollateralFromParentMarginAccount or transferCollateralFromMarginAccount when amount exceeds withdrawableCollateral
  • 400 on simulateParentMarginOrderRisk, simulateRiskBucketOrderRisk, simulateOrderRisk, and order placement: accepted: false with rejectReason (e.g., “Requested leverage exceeds max leverage for trading pair”). Market-order simulations apply the same 1,000 bps price band as placement and can return a rejectReason for no liquidity inside the band or no usable reference price
  • 400 on simulateParentMarginOrderRisk, simulateRiskBucketOrderRisk and simulateOrderRisk when slippageToleranceBps is sent on a non-MARKET preview or falls outside 0–1000 (it is an integer bps value; a negative tolerance is refused by the same schema as one above 1000) — the SDK raises ValidationError before the request is sent; a raw REST or gRPC caller gets placement’s own message (gRPC INVALID_ARGUMENT)
  • 403 when the account belongs to a different user
  • 404 when the marginAccountId does not exist
  • 429 on simulateParentMarginOrderRisk, simulateRiskBucketOrderRisk and simulateOrderRisk — every authenticated read draws one request from the account’s read budget. Enforcement is gated per environment by the read_rate_limit_enforced flag, which is off by default: until it is enabled the budget is measured and over-budget reads are admitted, so treat the 429 as a contract to handle rather than one you can rely on observing. When enforced, REST carries the retry horizon in details.retryAfter while gRPC returns RESOURCE_EXHAUSTED with a google.rpc.RetryInfo detail — the hint is transport-specific, so a gRPC caller reads RetryInfo rather than looking for a retryAfter field. See Rate limits
For end-to-end usage and UI patterns, see Perps Collateral, Order Management, and Positions.