> ## 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. # Get portfolio margin > Get the current authoritative parent margin and risk-bucket projection. ## OpenAPI ````yaml /proto-openapi/api/openapi.yaml get /api/v1/accounts/me/portfolio/margin 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/accounts/me/portfolio/margin: get: tags: - AccountsService - Accounts summary: Get portfolio margin description: Get the current authoritative parent margin and risk-bucket projection. operationId: get_portfolio_margin parameters: - name: marginAccountId in: query description: >- One of the caller's margin accounts (the default one or a sub-account) to describe instead of the default one: `total`, `positions` and `risk_buckets` are then that account's own. schema: type: string - name: includeAccounts in: query description: >- Also return `accounts`, one row per open margin account of the caller, and `owner_total`, their sum: the owner rollup across sub-accounts. schema: type: boolean responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/GetPortfolioMarginResponse' '401': description: Authentication required '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 '500': description: Internal server error '503': description: Portfolio data unavailable security: - monacoSignature: [] - monacoHttpSignature: [] components: schemas: GetPortfolioMarginResponse: type: object properties: asOf: type: string nullable: true total: $ref: '#/components/schemas/PortfolioMarginTotal' positions: $ref: '#/components/schemas/PortfolioMarginPositionCounts' riskBuckets: type: array items: $ref: '#/components/schemas/PortfolioRiskBucket' nullable: true marginAccountId: type: string description: |- The margin account `total`, `positions` and `risk_buckets` describe; absent when the caller has no margin account yet. nullable: true accounts: type: array items: $ref: '#/components/schemas/PortfolioMarginAccount' description: >- With `include_accounts`: every open margin account of the caller, the default one first, then sub-accounts by key. nullable: true ownerTotal: allOf: - $ref: '#/components/schemas/PortfolioMarginTotal' description: 'With `include_accounts`: the sum of `accounts`'' totals.' nullable: true PortfolioMarginTotal: type: object properties: equity: type: string nullable: true collateralBalance: type: string nullable: true parentAvailableCollateral: type: string nullable: true initialMarginRequired: type: string nullable: true maintenanceMarginRequired: type: string nullable: true unrealizedPnl: type: string nullable: true withdrawableCollateral: type: string description: >- The largest amount that can actually leave the parent margin account — the bound the engine enforces on transfers-out and withdrawals, and therefore also the effective ceiling on funding new isolated or first-use order capacity, because allocating collateral to a risk bucket passes through the same capacity-gated door. NOT a clamped `parent_available_collateral`. That field is `free_collateral`, an equity figure: it credits mark-to-market gains and realized PnL still held in open risk buckets, which a transfer-out of the parent cannot move, so the two can differ without limit. This bound never credits an unrealized gain. It counts net deposits plus the account's settled realized PnL and funding, less what risk buckets have allocated: `min(net deposits + settled realized PnL - bucket allocations, free_collateral - max(unrealized_pnl, 0))`, floored at zero. This is the bound the engine's gates actually enforce. The same figure as `MarginAccountSummary.withdrawable_collateral`: both surfaces truncate it toward zero at the quote asset's precision. Size transfers-out, withdrawals, and new isolated/first-use positions from this field; `parent_available_collateral` remains the trading-margin headroom for existing cross exposure. nullable: true PortfolioMarginPositionCounts: type: object properties: total: type: string nullable: true cross: type: string nullable: true isolated: type: string nullable: true PortfolioRiskBucket: required: - marginMode type: object properties: riskBucketId: type: string nullable: true format: uuid collateral: type: string nullable: true freeCollateral: type: string nullable: true initialMarginRequired: type: string nullable: true maintenanceMarginRequired: type: string nullable: true unrealizedPnl: type: string nullable: true positionCount: type: string nullable: true withdrawableCollateral: type: string description: >- The largest transfer-out of this risk bucket the engine accepts without lowering a position's posted margin — the bound enforced on bucket collateral withdrawals that leave the positions' leverage alone. A removal from an isolated risk bucket with one open position can take more: see `max_removable_collateral`. NOT a clamped `free_collateral`: free collateral is equity headroom and credits mark-to-market gains that a transfer-out cannot move. This bound is the bucket's allocated collateral plus its realized PnL, less funding paid, unrealized losses and the margin its positions and resting orders require. Realized profit can leave a live bucket this way (the bucket's allocation may go negative); an unrealized gain never raises it. This is the largest accepted transfer-out, and every smaller amount is accepted too. It is zero on a risk bucket that is not `NORMAL` and on one whose realized loss has used up its allocation. The same figure as the risk-bucket rows' `MarginAccountSummary.withdrawable_collateral`. nullable: true availableOrderCollateral: type: string description: >- The collateral still available to open NEW orders in this risk bucket — the same engine-served admission bound as `MarginAccountSummary.available_order_collateral` (see that field for the full semantics: an envelope delta with parent auto top-up included, NOT additive across rows, zero while frozen), truncated toward zero at quote decimals like `withdrawable_collateral` beside it. Present only when a live risk engine snapshot served the bound; absent on persisted-fallback reads, where neither of the gate's terms is reconstructable. nullable: true marginMode: example: CROSS enum: - ISOLATED - CROSS type: string description: >- The mode this risk bucket is margined under. Always present: every row here is a risk bucket and its mode is a non-null column, unlike MarginAccountSummary.marginMode which is optional because that shape also models a parent row belonging to no bucket. Labels each row so bucket margin can be attributed to cross or isolated from this response alone, instead of resolving the opaque riskBucketId against the margin-accounts surface. It does NOT reconcile with the positions.cross / positions.isolated counts beside it: those are counted by a separate query over every margin account for the caller's user/application pair (these rows come from the single oldest, parent account), and they attribute a legacy position carrying no risk-bucket reference to CROSS whether or not a cross bucket row exists. Treat the counts as account-wide totals, not as a checksum over these rows. tradingPairId: type: string description: >- Trading pair UUID this bucket is scoped to. Present for ISOLATED buckets; absent for CROSS, which spans the pairs selected into it and is scoped to none of them individually — the same invariant the transfer-in endpoint enforces by rejecting a `trading_pair_id` in CROSS mode. Read the cross bucket's membership from `MarginAccountSummary.selected_trading_pair_ids`; it is not carried here because it lives in a separate table and would cost this endpoint an extra query per request. These labels do NOT make this response row-for-row joinable with the margin-accounts surface on (mode, pair). That surface emits rows this one has no counterpart for — a provisioned-but-unfunded auto bucket, and a parent row with no mode at all — and on a persisted-fallback read (no live risk engine snapshot) the two surfaces attribute a legacy position carrying no risk-bucket reference to OPPOSITE buckets: this endpoint reads it as cross, the margin-accounts summary as isolated on pair match. Use these fields to label and group this response, not to cross-foot it against another. format: uuid nullable: true copyFollowId: type: string description: >- On a copy risk bucket row, the id of the follow (copy account) that funds it format: uuid nullable: true copyLeaderHandle: type: string description: >- On a copy risk bucket row, the followed leader's custom TraderCode handle, when they still hold one nullable: true maxRemovableCollateral: type: string description: >- The largest removal from this risk bucket the engine accepts when the removal may also lower the posted margin of the bucket's one open position, down to its initial margin at the mark — the same figure as `MarginAccountSummary.max_removable_collateral`. Equal to `withdrawable_collateral` for a cross risk bucket and for an isolated one with no open position or several. Present only when a live risk engine snapshot served it; truncated toward zero at quote decimals. nullable: true PortfolioMarginAccount: type: object properties: marginAccountId: type: string nullable: true subaccountKey: type: string description: >- `default` for the default margin account, else the sub-account's key. nullable: true total: allOf: - $ref: '#/components/schemas/PortfolioMarginTotal' description: >- The account's totals. `withdrawable_collateral` here is the persisted reconstruction of the engine's bound. nullable: true description: One of the caller's open margin accounts in the owner rollup. 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.