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

# Perps Collateral

> Move collateral into perps, inspect parent margin accounts, use risk buckets, and preview margin impact.

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.

```typescript theme={null}
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`. An isolated risk bucket with one open position can give back more: `maxRemovableCollateral` adds the position's margin above its initial margin at the mark, and a removal past `withdrawableCollateral` takes that difference out of the position's margin, raising its leverage and moving its liquidation price toward the mark.

```typescript theme={null}
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.

```typescript theme={null}
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.

```typescript theme={null}
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.

```typescript theme={null}
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](/trading-mechanics/perps#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.

```typescript theme={null}
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.

```typescript theme={null}
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.

```typescript theme={null}
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.

## Related Pages

* [Vault Deposits & Withdrawals](/developers/vault) for moving assets across the wallet boundary.
* [Positions](/developers/positions) for position risk, liquidation state, and close flows.
* [Order Management](/developers/trade#risk-buckets-and-pre-trade-simulation) for perp order validation.


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