> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cdp.coinbase.com/llms.txt
> Use this file to discover all available pages before exploring further.
# private/simulate_portfolio
> Calculates portfolio margin requirements and risk metrics for simulated positions or the current portfolio. This method helps you understand margin requirements before opening new positions or assess the impact of potential trades.
You can simulate adding new positions to the current portfolio or calculate margin for a completely simulated portfolio. The response includes initial margin, maintenance margin, available funds, and other risk metrics.
**Note:** This method has a restricted rate limit of not more than once per second due to the computational complexity of portfolio margin calculations.
**📖 Related Article:** [Portfolio Margin](https://support.deribit.com/hc/en-us/articles/25944756247837-Portfolio-Margin)
**Scope:** `rat#view` or `wallet:accounts:read`
[Try in API console](https://test.deribit.com/api_console?method=%2Fprivate%2Fsimulate_portfolio)
## OpenAPI
````yaml /api-reference/coinbase-deribit-app-api/adv-starbase-openapi.json get /private/simulate_portfolio
openapi: 3.0.0
info:
description: Coinbase Retail Advanced Trade API for derivatives trading.
title: Coinbase Retail Advanced Trade (Deribit) API
version: 2.1.1
servers:
- url: https://drb.coinbase.com/api/v2
security: []
tags:
- description: Can only be used over websockets.
name: WebSocket Only
- description: Public methods can be used without authentication.
name: Public
- description: >-
Private methods require authentication. All requests must include a
valid OAuth2 token.
A token can be requested using the /public/auth method.
When using the websockets protocol, the token must be included as a
parameter access_token in the message. When using REST (HTTP
GET), the token may also be passed in the Authorization
header.
name: Private
- name: Authentication
- name: Session Management
- description: >-
Subscription works as [notifications](#notifications), so users will
automatically (after subscribing) receive messages from the server.
Overview for each channel response format is described in
[subscriptions](#subscriptions) section.
name: Subscription Management
- name: Account Management
- name: Trading
- name: Market Data
paths:
/private/simulate_portfolio:
get:
tags:
- Account Management
- Private
description: >+
Calculates portfolio margin requirements and risk metrics for simulated
positions or the current portfolio. This method helps you understand
margin requirements before opening new positions or assess the impact of
potential trades.
You can simulate adding new positions to the current portfolio or
calculate margin for a completely simulated portfolio. The response
includes initial margin, maintenance margin, available funds, and other
risk metrics.
**Note:** This method has a restricted rate limit of not more than once
per second due to the computational complexity of portfolio margin
calculations.
**📖 Related Article:** [Portfolio
Margin](https://support.deribit.com/hc/en-us/articles/25944756247837-Portfolio-Margin)
**Scope:** `rat#view` or `wallet:accounts:read`
[Try in API
console](https://test.deribit.com/api_console?method=%2Fprivate%2Fsimulate_portfolio)
parameters:
- description: The currency symbol
in: query
name: currency
required: true
schema:
$ref: '#/components/schemas/currency'
example: BTC
- description: >-
If `true`, adds simulated positions to current positions, otherwise
uses only simulated positions. By default `true`
in: query
name: add_positions
required: false
schema:
type: boolean
- description: >-
Object with positions in following form: `{InstrumentName1:
Position1, InstrumentName2: Position2...}`, for example
`{"BTC-PERPETUAL": -1000.0}` (or corresponding URI-encoding for
GET). For futures in USD, for options in base currency.
in: query
name: simulated_positions
required: false
schema:
description: 'JSON string containing: object data'
type: string
requestBody:
content:
application/json:
examples:
request:
description: JSON-RPC Request Example
value:
id: 22222
jsonrpc: '2.0'
method: private/simulate_portfolio
params:
add_positions: true
currency: BTC
simulated_positions:
BTC-PERPETUAL: 1
description: JSON-RPC request body
responses:
'200':
$ref: '#/components/responses/PrivateSimulatePortfolioResponse'
components:
schemas:
currency:
description: Currency, i.e `"BTC"`, `"ETH"`, `"USDC"`
enum:
- BTC
- ETH
- USDC
- USDT
- EURR
type: string
PrivateSimulatePortfolioResponse:
properties:
id:
description: The id that was sent in the request
type: integer
jsonrpc:
description: The JSON-RPC version (2.0)
enum:
- '2.0'
type: string
result:
description: Portfolio margin simulation result
properties:
additional_reserve:
$ref: '#/components/schemas/additional_reserve'
available_funds:
description: >-
The account's available funds. When cross collateral is enabled,
this aggregated value is calculated by converting the sum of
each cross collateral currency's value to the given currency,
using each cross collateral currency's index.
example: 115871741.76065847
type: number
available_subaccount_transfer_funds:
description: The account's available funds for subaccount transfers
example: 0
type: number
available_withdrawal_funds:
description: The account's available to withdrawal funds
example: 115871741.76065847
type: number
balance:
description: The account's balance
example: 150076473.4995114
type: number
cross_collateral_enabled:
description: When `true` cross collateral is enabled for user
example: true
type: boolean
currency:
description: Currency of the simulation
example: BTC
type: string
delta_total:
$ref: '#/components/schemas/delta_total'
delta_total_map:
description: Map of total deltas per index
type: object
equity:
description: The account's current equity
example: 150075253.91354558
type: number
fee_balance:
$ref: '#/components/schemas/fee_balance'
futures_pl:
description: Futures profit and loss
example: 39497.54616685
type: number
futures_session_rpl:
description: Futures session realized profit and loss
example: 1.309136
type: number
futures_session_upl:
description: Futures session unrealized profit and loss
example: -164.48253509
type: number
initial_margin:
description: >-
The account's initial margin. When cross collateral is enabled,
this aggregated value is calculated by converting the sum of
each cross collateral currency's value to the given currency,
using each cross collateral currency's index.
example: 37662472.03416069
type: number
locked_balance:
description: The account's locked balance
example: 0
type: number
maintenance_margin:
description: >-
The maintenance margin. When cross collateral is enabled, this
aggregated value is calculated by converting the sum of each
cross collateral currency's value to the given currency, using
each cross collateral currency's index.
example: 30129215.84817124
type: number
margin_balance:
description: >-
The account's margin balance. When cross collateral is enabled,
this aggregated value is calculated by converting the sum of
each cross collateral currency's value to the given currency,
using each cross collateral currency's index.
example: 153534213.79481918
type: number
margin_model:
description: Name of user's currently enabled margin model
example: cross_pm
type: string
options_delta:
description: Options summary delta
example: 2883.38481
type: number
options_gamma:
description: Options summary gamma
example: -0.03907
type: number
options_gamma_map:
description: Map of options' gammas per index
type: object
options_pl:
description: Options profit and loss
example: 921.55562578
type: number
options_session_rpl:
description: Options session realized profit and loss
example: 0
type: number
options_session_upl:
description: Options session unrealized profit and loss
example: -174.67960675
type: number
options_theta:
description: Options summary theta
example: 142583.29246
type: number
options_theta_map:
description: Map of options' thetas per index
type: object
options_value:
description: Options value
example: -1056.41256672
type: number
options_vega:
description: Options summary vega
example: -39322.23046
type: number
options_vega_map:
description: Map of options' vegas per index
type: object
portfolio_margining_enabled:
description: '`true` when portfolio margining is enabled for user'
example: true
type: boolean
projected_delta_total:
$ref: '#/components/schemas/projected_delta_total'
projected_initial_margin:
$ref: '#/components/schemas/projected_initial_margin'
projected_maintenance_margin:
$ref: '#/components/schemas/projected_maintenance_margin'
session_rpl:
$ref: '#/components/schemas/rpl'
session_upl:
$ref: '#/components/schemas/upl'
spot_reserve:
description: The account's balance reserved in active spot orders
example: 0
type: number
total_delta_total_usd:
description: >-
Optional (only for users using cross margin). The account's
total delta total in all cross collateral currencies, expressed
in USD
example: 6157454218.3753195
type: number
total_equity_usd:
description: >-
Optional (only for users using cross margin). The account's
total equity in all cross collateral currencies, expressed in
USD
example: 13075634611389.318
type: number
total_initial_margin_usd:
description: >-
Optional (only for users using cross margin). The account's
total initial margin in all cross collateral currencies,
expressed in USD
example: 3139528603778.822
type: number
total_maintenance_margin_usd:
description: >-
Optional (only for users using cross margin). The account's
total maintenance margin in all cross collateral currencies,
expressed in USD
example: 2511559381417.215
type: number
total_margin_balance_usd:
description: >-
Optional (only for users using cross margin). The account's
total margin balance in all cross collateral currencies,
expressed in USD
example: 12798550648250.61
type: number
total_pl:
description: Profit and loss
example: 40419.10179263
type: number
type: object
required:
- jsonrpc
- result
type: object
additional_reserve:
description: The account's balance reserved in other orders
example: 0.3
type: number
delta_total:
description: >
The sum of position deltas.
**DeltaTotal = Net Transaction Delta of options + BTC Position of
Futures**
The DeltaTotal uses the Net Transaction Delta (or price adjusted Delta)
of the options, where Net Transaction Delta = Black Scholes Delta - Mark
Price of Options.
This is because, from a risk perspective, we are interested in the
change in Bitcoin price as the underlying changes.
You should actually treat your delta as **Equity + Delta Total** if you
want to have less risk for your USD PnL.
⚠️ **During the 30 minute settlement period we decay your Delta.** See
[Delta decay during
settlement](https://support.deribit.com/hc/en-us/articles/25944751433757-Delta-decay-during-settlement)
for more details.
example: 0.1334
type: number
fee_balance:
description: The account's fee balance (it can be used to pay for fees)
type: number
projected_delta_total:
description: >-
The sum of position deltas without positions that will expire during
closest expiration
example: 0.1334
type: number
projected_initial_margin:
description: >-
Projected initial margin. When cross collateral is enabled, this
aggregated value is calculated by converting the sum of each cross
collateral currency's value to the given currency, using each cross
collateral currency's index.
example: 1
type: number
projected_maintenance_margin:
description: >-
Projected maintenance margin. When cross collateral is enabled, this
aggregated value is calculated by converting the sum of each cross
collateral currency's value to the given currency, using each cross
collateral currency's index.
example: 1
type: number
rpl:
description: Session realized profit and loss
example: 0.1
type: number
upl:
description: Session unrealized profit and loss
example: 0.846863
type: number
responses:
PrivateSimulatePortfolioResponse:
content:
application/json:
examples:
response:
description: Response example
value:
id: 2
jsonrpc: '2.0'
result:
additional_reserve: 0
available_funds: 115871741.76065847
available_subaccount_transfer_funds: 0
available_withdrawal_funds: 115871741.76065847
balance: 150076473.4995114
cross_collateral_enabled: true
currency: BTC
delta_total: 69080.932029
delta_total_map:
btc_usd: 68024.519462366
equity: 150075253.91354558
fee_balance: 0
futures_pl: 39497.54616685
futures_session_rpl: 1.309136
futures_session_upl: -164.48253509
initial_margin: 37662472.03416069
locked_balance: 0
maintenance_margin: 30129215.84817124
margin_balance: 153534213.79481918
margin_model: cross_pm
options_delta: 2883.38481
options_gamma: -0.03907
options_gamma_map:
btc_usd: -0.03907
options_pl: 921.55562578
options_session_rpl: 0
options_session_upl: -174.67960675
options_theta: 142583.29246
options_theta_map:
btc_usd: 142583.29246
options_value: -1056.41256672
options_vega: -39322.23046
options_vega_map:
btc_usd: -39322.23046
portfolio_margining_enabled: true
projected_delta_total: 69080.932029
projected_initial_margin: 37662472.03416069
projected_maintenance_margin: 30129215.84817124
session_rpl: 1.309136
session_upl: -339.16214185
spot_reserve: 0
total_delta_total_usd: 6157454218.3753195
total_equity_usd: 13075634611389.318
total_initial_margin_usd: 3139528603778.822
total_maintenance_margin_usd: 2511559381417.215
total_margin_balance_usd: 12798550648250.61
total_pl: 40419.10179263
testnet: true
usDiff: 13650
usIn: 1742210019774525
usOut: 1742210019788175
schema:
$ref: '#/components/schemas/PrivateSimulatePortfolioResponse'
description: Success response
````