Perps Collateral

Perps collateral sits beside spot balances, not inside them. Users deposit assets into Monaco first, then move supported collateral into the parent margin account or deposit directly to margin from the vault flow.

Surface Map

Surface	Use
REST	`GET /api/v1/margin/parent-margin-account`, `POST /api/v1/margin/parent-margin-account/collateral/transfer-in`, `POST /api/v1/margin/parent-margin-account/collateral/transfer-out`, `GET /api/v1/margin/collateral/available`, `POST /api/v1/margin/risk-buckets/*`
TypeScript SDK	`sdk.marginAccounts.getParentMarginAccountSummary()`, `transferCollateralToParentMarginAccount()`, `transferCollateralFromParentMarginAccount()`, `getAvailableCollateral()`, `transferCollateralToRiskBucket()`, `simulateRiskBucketOrderRisk()`
React SDK	Use `usePositions()` for position state; call `sdk.marginAccounts` directly for collateral actions
WebSocket	`balances`, `movements`, raw `positions:{tradingPairId}`, raw `liquidations:{tradingPairId}`
gRPC	`MarginAccountsService`

Collateral Model

Surface	What it tracks
Wallet	On-chain assets and SEI gas for deposit or withdrawal transactions
Monaco spot balance	Deposited assets available for spot trading or transfer into perps collateral
Parent margin account	Collateral, equity, free collateral, margin requirements, PnL, funding, and liquidation state
Risk bucket	Pair-scoped exposure, margin, liquidation price, and optional `strategyKey` routing

For first-time margin funding, use the parent transfer method. Monaco creates the parent margin account internally when needed.

await sdk.marginAccounts.transferCollateralToParentMarginAccount({
  asset: "USDC",
  amount: "1000",
});

const summary = await sdk.marginAccounts.getParentMarginAccountSummary();
console.log(summary.freeCollateral, summary.withdrawableCollateral);

Transfer Out

Move collateral back to the user’s Monaco balance only when it is withdrawable. withdrawableCollateral can be lower than freeCollateral because initial margin (resting-order reserve included), pending fees, funding, or unrealized losses can reserve collateral, and an unrealized gain does not raise it — size a transfer-out from withdrawableCollateral, not freeCollateral.

await sdk.marginAccounts.transferCollateralFromParentMarginAccount({
  asset: "USDC",
  amount: "250",
});

Available Collateral

Use getAvailableCollateral before showing a perps funding form so the UI knows what can actually move.

const collateral = await sdk.marginAccounts.getAvailableCollateral({
  asset: "USDC",
});

console.log({
  walletAvailable: collateral.walletAvailable,
  walletLocked: collateral.walletLocked,
  marginTransferable: collateral.marginTransferable,
  marginAvailableCollateral: collateral.marginAvailableCollateral,
});

walletLocked includes spot funds locked by open orders or pending withdrawals. Do not use total spot balance as the max transfer amount. The two margin* fields point in opposite directions. marginTransferable is how much can move into margin; marginAvailableCollateral is how much can come back out, and is the same bound as MarginAccountSummary.withdrawableCollateral. Size a transfer-out or withdrawal from marginAvailableCollateral. A new isolated or first-use position allocates principal through the same gate this field measures, so size those from it too. The summary’s freeCollateral remains the trading-margin headroom for existing cross exposure — it credits unrealized gains, which are initial margin against that exposure but cannot fund an exit or a new principal allocation.

Risk Buckets

Risk buckets route collateral and risk by trading pair and optional strategyKey. Use them when an integration needs pair-scoped allocation or per-strategy accounting.

await sdk.marginAccounts.transferCollateralToRiskBucket({
  asset: "USDC",
  amount: "500",
  tradingPairId,
  strategyKey: "basis-v1",
});

When the isolated bucket already holds an open position, say what the money is for with applyToPositionMargin. Omitted or true (the default — the “Adjust Margin” gesture) commits the amount to the position’s stored margin: leverage drops and stays down, initial margin required rises by exactly the amount at the current mark, free collateral is unchanged. false keeps it a plain, spendable allocation: free collateral rises for the next order — pass false from any funding loop that targets a free-collateral level, or each top-up converts into requirement and the loop never converges. Both improve the liquidation cushion identically; a flat bucket is a plain allocation either way, and the response’s positionMarginCredited reports what actually happened. To show how much a risk bucket can still commit to new orders, read the bucket summary row’s availableOrderCollateral: the risk engine admission gate’s own bound, automatic top-up from the parent’s unallocated capacity included. It already contains the bucket’s live free collateral and credits unrealized gains in full, so don’t add either on top — and don’t use withdrawableCollateral for this, which answers the transfer-out question instead. It is collateral, not notional (divide by the market’s initial margin rate), and it is not additive across buckets: every bucket row includes the same parent headroom. A bucket below its initial margin still takes new orders: the parent funds each new order’s own margin and fee in full, so the figure there is the parent headroom alone, and the bucket stays below its initial margin by the gap its existing positions made. The parent never fills that gap; transfer collateral in or reduce to close it. The field is optional. It is served only from a live risk engine snapshot, so it is absent right after a transfer while the bucket row is still being projected, and on any degraded read — treat undefined as “unavailable”, never as zero.

const bucket = await sdk.marginAccounts.getParentMarginAccountSummary({
  tradingPairId,
});
if (bucket.availableOrderCollateral !== undefined) {
  console.log(`Can commit ${bucket.availableOrderCollateral} USDC to new orders`);
}

Before placing a meaningful perp order, simulate the account impact — availableOrderCollateral is the display figure, the simulation is the per-order authority (an order is charged the increase it causes in the bucket’s worst-case reserve, so a reducing or opposite-side order needs less margin or none, fees reserve on top, and margin rates differ per market and by notional bracket — see Margin ladders). A leverage above what a market’s riskTiers bracket allows at the order’s projected notional is rejected rather than silently capped; read getPerpMarketConfig().riskTiers to check a market’s caps before submitting.

const risk = await sdk.marginAccounts.simulateRiskBucketOrderRisk({
  tradingPairId,
  side: "BUY",
  orderType: "LIMIT",
  quantity: "1.5",
  price: "65000",
  leverage: "5",
});

console.log(risk.accepted, risk.freeCollateralAfter, risk.estimatedLiquidationPrice);

Margin Sub-Accounts

A wallet can hold several margin accounts per application, one per sub-account key. The key default is the parent margin account above: it keeps its id and is the only account that deposits, withdrawals and wallet transfers touch. Every sub-account holds its own collateral and its own risk buckets, so a loss in one sub-account never draws on another.

const hedge = await sdk.marginAccounts.createMarginSubAccount({ subaccountKey: "hedge" });
const parent = await sdk.marginAccounts.getParentMarginAccountSummary();

// Fund the sub-account from the default margin account: one atomic step, no wallet movement.
await sdk.marginAccounts.transferMarginCollateral({
  asset: "USDC",
  amount: "250",
  from: { marginAccountId: parent.marginAccountId },
  to: { marginAccountId: hedge.marginAccountId },
});

// A sub-account funds and previews its own risk buckets from its own collateral.
await sdk.marginAccounts.transferCollateralToRiskBucket({
  asset: "USDC",
  amount: "100",
  marginMode: "CROSS",
  marginAccountId: hedge.marginAccountId,
});

// Per-account reads: one account's PnL, one account's portfolio, or the owner rollup.
const pnl = await sdk.marginAccounts.getMarginAccountPnl(hedge.marginAccountId);
const rollup = await sdk.portfolio.getMargin({ includeAccounts: true });

// Close it once it is flat; its risk buckets fold back and its collateral returns to the default account.
await sdk.marginAccounts.closeMarginSubAccount(hedge.marginAccountId);

Keys are up to 64 letters, digits, _, -, . or :. Keys starting with copy: are reserved.
The number of open sub-accounts per owner is capped by the owner’s weighted 14-day volume tier: 10 at the first tier, rising with the fee-tier floors to 50, or an admin-set override. Copy-trading sub-accounts do not count.
Closing needs a flat sub-account: no position and no resting, conditional or TWAP order. Its flat, solvent risk buckets close in the same step; a risk bucket in liquidation or bad debt refuses the close. Re-creating the key re-opens the same account.
POST /api/v1/margin/collateral/transfer moves wallet ↔ default account and account ↔ account. The older transfer routes keep working unchanged.
POST /api/v1/margin/sub-accounts/{marginAccountId}/collateral/transfer-in and /transfer-out (transferCollateralToSubAccount / transferCollateralFromSubAccount) move collateral between the default margin account and the named sub-account, with a body of just { amount }.
listMarginAccounts() rows carry subaccountKey and marginAccountState; private order events carry marginAccountId.
A delegated agent listing one margin account in allowedMarginAccountIds is that sub-account’s own key: it trades that account only.

Movements

Collateral transfers are available through parent margin account movements.

const { movements, nextPageToken } = await sdk.marginAccounts.getParentMarginAccountMovements({
  pageSize: 50,
  movementType: "TRANSFER_IN",
});

PnL, funding payments, and fees are tracked through user movements and funding-payment history.

Vault Deposits & Withdrawals for moving assets across the wallet boundary.
Positions for position risk, liquidation state, and close flows.
Order Management for perp order validation.

Learn

Build

Libraries

APIs

Resources

Surface Map

Collateral Model

Transfer Out

Available Collateral

Risk Buckets

Margin Sub-Accounts

Movements

​Surface Map

​Collateral Model

​Transfer Out

​Available Collateral

​Risk Buckets

​Margin Sub-Accounts

​Movements

​Related Pages

Surface Map

Collateral Model

Transfer Out

Available Collateral

Risk Buckets

Margin Sub-Accounts

Movements

Related Pages