---
title: "Simulate Portfolio Margin"
method: POST
path: "/v1/simulate-portfolio-margin"
tags: ["portfolio-margin-simulator"]
---

# Simulate Portfolio Margin

`POST /v1/simulate-portfolio-margin`

## Request

- Base URL: `https://api.exchange.bullish.com/trading-api`
- URL: `https://api.exchange.bullish.com/trading-api/v1/simulate-portfolio-margin`
- Auth: HTTP bearer
- TypeScript: <https://skmtc.dev/bullish/apis/bullish-trading-api/docs/v1/simulate-portfolio-margin/post.ts> (a function with typed inputs; its response is checked against the schema)

Use Portfolio margin simulator to determine your margin requirements and risk levels based on your current portfolio balances. 
You can also append position details on top of your portfolio specifics to see simulated results.

## Query parameters

- `includeExisting` boolean

## Request body

- PortfolioSimulationRequest
  - `tradingAccountId` string, required: unique trading account ID
  - `positions` SimulationPosition[]: portfolio position to be used in simulation
    - `symbol` string, required: asset or market symbol. E.g. `USDC` for asset and `BTCUSDC` for market
    - `quantity` string, required: size of the position
  - `orders` SimulationOrder[]: pending orders to be used in simulation
    - `symbol` string, required: market symbol. E.g. `BTCUSDC`
    - `quantity` string, required: quantity placed for order
    - `limitPrice` string: limit price for order
    - `timeInForce` string: time in force can have the following string values `"GTC"`, `"FOK"`, `"IOC"`, `"GTX"` (Good Till Crossing - for auction orders), see [details](/rest/general/order-type)
  - `referencePrices` ReferencePrice[]: reference price to be used in simulation
    - `symbol` string: asset or market symbol. E.g. `USDC` for asset and `BTCUSDC` for market
    - `price` string: reference price for asset or market
  - `priceVolOffsetParams` PriceVolOffsetParams: Parameters for adjusting prices and volatility in portfolio simulation
    - `cryptoPriceMultipliers` object: Symbol-specific price multipliers. When specified for a symbol, overrides the global multiplier
    - `globalCryptoPriceMultiplier` number, double: Global price multiplier applied to all crypto assets (except stablecoins and symbols with explicit multipliers)
    - `volOffset` number, double: Offset to add to implied volatility for options pricing. Can be positive or negative

## Response `200`

OK

- PortfolioSimulationResponse: Simulation result
  - `collateralUSD` string: total collateral across all assets in this trading account displayed in the reference asset in USD
  - `borrowedUSD` string: total borrowed across all assets in this trading account displayed in the reference asset in USD
  - `initialMarginUSD` string: The minimum margin one must maintain in order to be able to purposefully increase risk
  - `warningMarginUSD` string: The minimum margin when the customer will receive warning via email/notifications over UI
  - `liquidationMarginUSD` string: The minimum value of margin one must maintain in order to avoid liquidation
  - `fullLiquidationMarginUSD` string: The value of margin when full liquidation occurs
  - `defaultedMarginUSD` string: The value of margin when this trading account will be moved into a Defaulted state
  - `liquidityAddonUSD` string: expected market impact of unwinding the portfolio in the case of a liquidation event
  - `marketRiskUSD` string: the worst possible loss on the portfolio based on scenario analysis

## Other responses

- `400`: Bad Request
- `401`: Not Authenticated
- `403`: Access Forbidden
- `429`: Too Many Requests
- `500`: Internal Server Error

---

[API](https://skmtc.dev/bullish/apis/bullish-trading-api.md) - [All operations](https://skmtc.dev/bullish/apis/bullish-trading-api/llms.txt) - [OpenAPI document](https://skmtc.dev/bullish/apis/bullish-trading-api/revisions/df5d69ccedcf?raw)