cURL

curl --request GET \
  --url https://test.deribit.com/api/v2/private/simulate_portfolio \
  --header 'Content-Type: application/json' \
  --data '
{
  "jsonrpc": "2.0",
  "id": 22222,
  "method": "private/simulate_portfolio",
  "params": {
    "currency": "BTC",
    "add_positions": true,
    "simulated_positions": {
      "BTC-PERPETUAL": 1
    }
  }
}
'

import requests

url = "https://test.deribit.com/api/v2/private/simulate_portfolio"

payload = {
    "jsonrpc": "2.0",
    "id": 22222,
    "method": "private/simulate_portfolio",
    "params": {
        "currency": "BTC",
        "add_positions": True,
        "simulated_positions": { "BTC-PERPETUAL": 1 }
    }
}
headers = {"Content-Type": "application/json"}

response = requests.get(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'GET',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({
    jsonrpc: '2.0',
    id: 22222,
    method: 'private/simulate_portfolio',
    params: {
      currency: 'BTC',
      add_positions: true,
      simulated_positions: {'BTC-PERPETUAL': 1}
    }
  })
};

fetch('https://test.deribit.com/api/v2/private/simulate_portfolio', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://test.deribit.com/api/v2/private/simulate_portfolio",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_POSTFIELDS => json_encode([
    'jsonrpc' => '2.0',
    'id' => 22222,
    'method' => 'private/simulate_portfolio',
    'params' => [
        'currency' => 'BTC',
        'add_positions' => true,
        'simulated_positions' => [
                'BTC-PERPETUAL' => 1
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://test.deribit.com/api/v2/private/simulate_portfolio"

	payload := strings.NewReader("{\n  \"jsonrpc\": \"2.0\",\n  \"id\": 22222,\n  \"method\": \"private/simulate_portfolio\",\n  \"params\": {\n    \"currency\": \"BTC\",\n    \"add_positions\": true,\n    \"simulated_positions\": {\n      \"BTC-PERPETUAL\": 1\n    }\n  }\n}")

	req, _ := http.NewRequest("GET", url, payload)

	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.get("https://test.deribit.com/api/v2/private/simulate_portfolio")
  .header("Content-Type", "application/json")
  .body("{\n  \"jsonrpc\": \"2.0\",\n  \"id\": 22222,\n  \"method\": \"private/simulate_portfolio\",\n  \"params\": {\n    \"currency\": \"BTC\",\n    \"add_positions\": true,\n    \"simulated_positions\": {\n      \"BTC-PERPETUAL\": 1\n    }\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://test.deribit.com/api/v2/private/simulate_portfolio")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n  \"jsonrpc\": \"2.0\",\n  \"id\": 22222,\n  \"method\": \"private/simulate_portfolio\",\n  \"params\": {\n    \"currency\": \"BTC\",\n    \"add_positions\": true,\n    \"simulated_positions\": {\n      \"BTC-PERPETUAL\": 1\n    }\n  }\n}"

response = http.request(request)
puts response.read_body

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "projected_initial_margin": 37662472.03416069,
    "initial_margin": 37662472.03416069,
    "total_pl": 40419.10179263,
    "additional_reserve": 0,
    "available_withdrawal_funds": 115871741.76065847,
    "options_pl": 921.55562578,
    "delta_total_map": {
      "btc_usd": 68024.519462366
    },
    "available_subaccount_transfer_funds": 0,
    "projected_delta_total": 69080.932029,
    "projected_maintenance_margin": 30129215.84817124,
    "total_equity_usd": 13075634611389.318,
    "options_gamma": -0.03907,
    "currency": "BTC",
    "options_theta": 142583.29246,
    "spot_reserve": 0,
    "total_initial_margin_usd": 3139528603778.822,
    "options_vega": -39322.23046,
    "margin_balance": 153534213.79481918,
    "futures_session_rpl": 1.309136,
    "options_gamma_map": {
      "btc_usd": -0.03907
    },
    "available_funds": 115871741.76065847,
    "futures_pl": 39497.54616685,
    "cross_collateral_enabled": true,
    "delta_total": 69080.932029,
    "options_session_rpl": 0,
    "total_margin_balance_usd": 12798550648250.61,
    "options_value": -1056.41256672,
    "options_session_upl": -174.67960675,
    "maintenance_margin": 30129215.84817124,
    "total_maintenance_margin_usd": 2511559381417.215,
    "options_vega_map": {
      "btc_usd": -39322.23046
    },
    "session_rpl": 1.309136,
    "locked_balance": 0,
    "session_upl": -339.16214185,
    "margin_model": "cross_pm",
    "portfolio_margining_enabled": true,
    "equity": 150075253.91354558,
    "balance": 150076473.4995114,
    "total_delta_total_usd": 6157454218.3753195,
    "fee_balance": 0,
    "options_delta": 2883.38481,
    "options_theta_map": {
      "btc_usd": 142583.29246
    },
    "futures_session_upl": -164.48253509
  },
  "usIn": 1742210019774525,
  "usOut": 1742210019788175,
  "usDiff": 13650,
  "testnet": true
}

Account Management

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

Scope: account:read

Try in API console

cURL

curl --request GET \
  --url https://test.deribit.com/api/v2/private/simulate_portfolio \
  --header 'Content-Type: application/json' \
  --data '
{
  "jsonrpc": "2.0",
  "id": 22222,
  "method": "private/simulate_portfolio",
  "params": {
    "currency": "BTC",
    "add_positions": true,
    "simulated_positions": {
      "BTC-PERPETUAL": 1
    }
  }
}
'

import requests

url = "https://test.deribit.com/api/v2/private/simulate_portfolio"

payload = {
    "jsonrpc": "2.0",
    "id": 22222,
    "method": "private/simulate_portfolio",
    "params": {
        "currency": "BTC",
        "add_positions": True,
        "simulated_positions": { "BTC-PERPETUAL": 1 }
    }
}
headers = {"Content-Type": "application/json"}

response = requests.get(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'GET',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({
    jsonrpc: '2.0',
    id: 22222,
    method: 'private/simulate_portfolio',
    params: {
      currency: 'BTC',
      add_positions: true,
      simulated_positions: {'BTC-PERPETUAL': 1}
    }
  })
};

fetch('https://test.deribit.com/api/v2/private/simulate_portfolio', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://test.deribit.com/api/v2/private/simulate_portfolio",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_POSTFIELDS => json_encode([
    'jsonrpc' => '2.0',
    'id' => 22222,
    'method' => 'private/simulate_portfolio',
    'params' => [
        'currency' => 'BTC',
        'add_positions' => true,
        'simulated_positions' => [
                'BTC-PERPETUAL' => 1
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://test.deribit.com/api/v2/private/simulate_portfolio"

	payload := strings.NewReader("{\n  \"jsonrpc\": \"2.0\",\n  \"id\": 22222,\n  \"method\": \"private/simulate_portfolio\",\n  \"params\": {\n    \"currency\": \"BTC\",\n    \"add_positions\": true,\n    \"simulated_positions\": {\n      \"BTC-PERPETUAL\": 1\n    }\n  }\n}")

	req, _ := http.NewRequest("GET", url, payload)

	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.get("https://test.deribit.com/api/v2/private/simulate_portfolio")
  .header("Content-Type", "application/json")
  .body("{\n  \"jsonrpc\": \"2.0\",\n  \"id\": 22222,\n  \"method\": \"private/simulate_portfolio\",\n  \"params\": {\n    \"currency\": \"BTC\",\n    \"add_positions\": true,\n    \"simulated_positions\": {\n      \"BTC-PERPETUAL\": 1\n    }\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://test.deribit.com/api/v2/private/simulate_portfolio")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n  \"jsonrpc\": \"2.0\",\n  \"id\": 22222,\n  \"method\": \"private/simulate_portfolio\",\n  \"params\": {\n    \"currency\": \"BTC\",\n    \"add_positions\": true,\n    \"simulated_positions\": {\n      \"BTC-PERPETUAL\": 1\n    }\n  }\n}"

response = http.request(request)
puts response.read_body

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "projected_initial_margin": 37662472.03416069,
    "initial_margin": 37662472.03416069,
    "total_pl": 40419.10179263,
    "additional_reserve": 0,
    "available_withdrawal_funds": 115871741.76065847,
    "options_pl": 921.55562578,
    "delta_total_map": {
      "btc_usd": 68024.519462366
    },
    "available_subaccount_transfer_funds": 0,
    "projected_delta_total": 69080.932029,
    "projected_maintenance_margin": 30129215.84817124,
    "total_equity_usd": 13075634611389.318,
    "options_gamma": -0.03907,
    "currency": "BTC",
    "options_theta": 142583.29246,
    "spot_reserve": 0,
    "total_initial_margin_usd": 3139528603778.822,
    "options_vega": -39322.23046,
    "margin_balance": 153534213.79481918,
    "futures_session_rpl": 1.309136,
    "options_gamma_map": {
      "btc_usd": -0.03907
    },
    "available_funds": 115871741.76065847,
    "futures_pl": 39497.54616685,
    "cross_collateral_enabled": true,
    "delta_total": 69080.932029,
    "options_session_rpl": 0,
    "total_margin_balance_usd": 12798550648250.61,
    "options_value": -1056.41256672,
    "options_session_upl": -174.67960675,
    "maintenance_margin": 30129215.84817124,
    "total_maintenance_margin_usd": 2511559381417.215,
    "options_vega_map": {
      "btc_usd": -39322.23046
    },
    "session_rpl": 1.309136,
    "locked_balance": 0,
    "session_upl": -339.16214185,
    "margin_model": "cross_pm",
    "portfolio_margining_enabled": true,
    "equity": 150075253.91354558,
    "balance": 150076473.4995114,
    "total_delta_total_usd": 6157454218.3753195,
    "fee_balance": 0,
    "options_delta": 2883.38481,
    "options_theta_map": {
      "btc_usd": 142583.29246
    },
    "futures_session_upl": -164.48253509
  },
  "usIn": 1742210019774525,
  "usOut": 1742210019788175,
  "usDiff": 13650,
  "testnet": true
}

Query Parameters

currency

enum<string>

required

The currency symbol Currency, i.e "BTC", "ETH", "USDC"

Available options:

BTC,

ETH,

USDC,

USDT,

EURR

Example:

"BTC"

add_positions

boolean

If true, adds simulated positions to current positions, otherwise uses only simulated positions. By default true

simulated_positions

string

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. JSON string containing: object data

Response

200 - application/json

Success response

jsonrpc

enum<string>

required

The JSON-RPC version (2.0)

Available options:

2.0

result

object

required

Portfolio margin simulation result

Hide child attributes

result.currency

string

Currency of the simulation

Example:

"BTC"

result.equity

number

The account's equity in the selected currency: balance + futures (session UPL + RPL) + options mark value (plus any external/implied equity). Related: margin_balance excludes options mark value under standard margin.

Example:

150075253.91354558

result.balance

number

The account's cash balance in the selected currency (deposits, withdrawals, transfers, option premiums, settlements/deliveries, corrections, costs, and insurance refills). Does not include open futures PnL or options mark value.

Example:

150076473.4995114

result.margin_balance

number

Collateral available against margin requirements. Under standard margin (SM): equity - options_value (cash balance plus futures session UPL and RPL). Under portfolio margin (PM): equal to equity. 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

result.initial_margin

number

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

result.maintenance_margin

number

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

result.projected_initial_margin

number

Initial margin calculated as if instruments expiring at the nearest expiration were excluded, so it shows the requirement that will remain once those instruments have expired. 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

result.projected_maintenance_margin

number

Maintenance margin calculated as if instruments expiring at the nearest expiration were excluded, so it shows the requirement that will remain once those instruments have expired. 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

result.available_funds

number

Funds available to increase margin usage (open or enlarge positions). Equal to margin_balance - initial_margin, floored at 0 in the API response. When initial margin usage exceeds 100%, this is 0 and only reducing orders can be placed. 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

result.available_withdrawal_funds

number

Funds available to withdraw in the selected currency. Typically lower than available_funds because withdrawals also exclude positive session profit, locked balance, spot_reserve, additional_reserve, and non-withdrawable external/implied equity components. Always ≥ 0.

Example:

115871741.76065847

result.available_subaccount_transfer_funds

number

The account's available funds for subaccount transfers

Example:

0

result.total_pl

number

Total profit and loss of all open positions since each position was opened (not limited to the current session). Differs from session_rpl + session_upl, which reset at daily settlement.

Example:

40419.10179263

result.session_rpl

number

Realized profit and loss accrued in the current trading session (since the last daily settlement). Resets at each daily settlement.

Example:

0.1

result.session_upl

number

Unrealized profit and loss on open positions in the current trading session (since the last daily settlement).

Example:

0.846863

result.futures_pl

number

Futures profit and loss

Example:

39497.54616685

result.futures_session_rpl

number

Futures session realized profit and loss

Example:

1.309136

result.futures_session_upl

number

Futures session unrealized profit and loss

Example:

-164.48253509

result.options_pl

number

Options profit and loss

Example:

921.55562578

result.options_session_rpl

number

Options session realized profit and loss

Example:

0

result.options_session_upl

number

Options session unrealized profit and loss

Example:

-174.67960675

result.options_value

number

Mark value of all open options positions in the selected currency. Under standard margin, margin_balance = equity - options_value.

Example:

-1056.41256672

result.options_delta

number

Sum of the deltas of all options positions. For inverse (coin-margined) options this is the Black-Scholes delta; for linear options it is the index-price-adjusted delta. Unlike account-level delta_total, the options mark value is not subtracted.

Example:

2883.38481

result.options_gamma

number

Sum of options position gammas (Black-Scholes).

Example:

-0.03907

result.options_theta

number

Sum of the thetas of all options positions. Theta is expressed per day; for options with less than one day left to expiry it is scaled down to the fraction of a day remaining.

Example:

142583.29246

result.options_vega

number

Sum of options position vegas (Black-Scholes).

Example:

-39322.23046

result.options_gamma_map

object

Map of options' gammas per index

Hide child attributes

result.options_gamma_map.{key}

number

result.options_theta_map

object

Map of options' thetas per index

Hide child attributes

result.options_theta_map.{key}

number

result.options_vega_map

object

Map of options' vegas per index

Hide child attributes

result.options_vega_map.{key}

number

result.delta_total

number

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 for more details.

Example:

0.1334

result.delta_total_map

object

Map of total deltas per index

Hide child attributes

result.delta_total_map.{key}

number

result.projected_delta_total

number

The sum of position deltas excluding positions that expire at the nearest expiration, so it shows the delta that will remain once those positions have expired. Calculated on the same Net Transaction Delta basis as delta_total, including delta decay during the settlement period.

Example:

0.1334

result.additional_reserve

number

The account's balance reserved for open buy option orders and option combo orders (the premium payable if they fill). Only non-zero on the cross_sm margin model; balance reserved by spot orders is reported separately in spot_reserve.

Example:

0.3

result.spot_reserve

number

The account's balance reserved in active spot orders

Example:

0

result.fee_balance

number

The account's fee balance (it can be used to pay for fees)

result.locked_balance

number

The account's locked balance

Example:

0

result.margin_model

string

Name of user's currently enabled margin model

Example:

"cross_pm"

result.portfolio_margining_enabled

boolean

true when portfolio margining is enabled for user

Example:

true

result.cross_collateral_enabled

boolean

When true cross collateral is enabled for user

Example:

true

result.total_equity_usd

number

Optional (only for users using cross margin). The account's total equity in all cross collateral currencies, expressed in USD

Example:

13075634611389.318

result.total_initial_margin_usd

number

Optional (only for users using cross margin). The account's total initial margin in all cross collateral currencies, expressed in USD

Example:

3139528603778.822

result.total_maintenance_margin_usd

number

Optional (only for users using cross margin). The account's total maintenance margin in all cross collateral currencies, expressed in USD

Example:

2511559381417.215

result.total_margin_balance_usd

number

Optional (only for users using cross margin). The account's total margin balance in all cross collateral currencies, expressed in USD

Example:

12798550648250.61

result.total_delta_total_usd

number

Optional (only for users using cross margin). The account's total delta total in all cross collateral currencies, expressed in USD

Example:

6157454218.3753195

integer

The id that was sent in the request

Methods overview

Methods

private/simulate_portfolio

Query Parameters

Response