Preview Margin Order Impact
Preview Margin Order Impact
POSThttps://api.gemini.com/v1/margin/order/preview
Previews the margin impact of a hypothetical spot order without placing it. Returns pre-order and post-order margin risk statistics.
Account Type
This endpoint is only available for margin trading accounts.
POSTv1/margin/order/preview
curl --request POST \
--url https://api.gemini.com/v1/margin/order/preview \
--header 'Content-Type: application/json' \
--header 'X-GEMINI-APIKEY: <string>' \
--header 'X-GEMINI-PAYLOAD: <string>' \
--header 'X-GEMINI-SIGNATURE: <string>' \
--data '
{
"request": "/v1/margin/order/preview",
"nonce": "<nonce>",
"symbol": "btcusd",
"side": "buy",
"type": "limit",
"amount": "0.5",
"price": "50000.00"
}
'Roles
The API key you use to access this endpoint must have the Trader or Auditor role assigned. See Roles for more information.
The OAuth scope must have orders:read assigned to access this endpoint. See OAuth Scopes for more information.
Headers
X-GEMINI-APIKEYstring·required
Your API keyX-GEMINI-SIGNATUREstring·required
HEX-encoded HMAC-SHA384 of payload signed with API secretX-GEMINI-PAYLOADstring·required
Base64-encoded JSON payloadContent-Typestring
Default: text/plainContent-Lengthstring
Default: 0Cache-Controlstring
Default: no-cacheRequest Body
requeststring·required
The literal string "/v1/margin/order/preview"nonceTimestampType | integer·required
timestampExample: 1495127793000symbolstring·required
The trading pair symbol (e.g., "btcusd")Example: btcusdsidestring·enum·required
The order sideEnum values: buysellExample: buytypestring·enum·required
The order typeEnum values: marketlimitExample: limitamountstring (decimal)
The order amount in base currency (required for limit orders and sell market orders)Example: 0.5pricestring (decimal)
The limit price (required for limit orders)Example: 50000.00totalSpendstring (decimal)
Total spend in quote currency (required for buy market orders)Example: 25000.00accountstring
Required for Master API keys as described in [Private API Invocation](/authentication/api-key#private-api-invocation). The name of the account within the subaccount group.Example request body
{
"request": "/v1/margin/order/preview",
"nonce": "<nonce>",
"symbol": "btcusd",
"side": "buy",
"type": "limit",
"amount": "0.5",
"price": "50000.00"
}Responses
Pre-order and post-order margin risk statistics
preorderobject·required
Margin risk statistics before the order would be executedpreorder.marginAssetValueobject·required
The total value of all assets available in the margin accountpreorder.marginAssetValue.currencystring·required
The currency code (e.g., "USD", "BTC", "ETH")Example: USDpreorder.marginAssetValue.valuestring (decimal)·required
The amount in the specified currencyExample: 10000.00preorder.availableCollateralobject·required
The amount of collateral available for new positionspreorder.availableCollateral.currencystring·required
The currency code (e.g., "USD", "BTC", "ETH")Example: USDpreorder.availableCollateral.valuestring (decimal)·required
The amount in the specified currencyExample: 10000.00preorder.notionalValueobject·required
The total value of all open positionspreorder.notionalValue.currencystring·required
The currency code (e.g., "USD", "BTC", "ETH")Example: USDpreorder.notionalValue.valuestring (decimal)·required
The amount in the specified currencyExample: 10000.00preorder.totalBorrowedobject·required
The total amount currently borrowedpreorder.totalBorrowed.currencystring·required
The currency code (e.g., "USD", "BTC", "ETH")Example: USDpreorder.totalBorrowed.valuestring (decimal)·required
The amount in the specified currencyExample: 10000.00preorder.leveragestring (decimal)·required
The leverage ratioExample: 1.5preorder.reservedBuyOrdersobject·required
Collateral reserved for open buy orderspreorder.reservedBuyOrders.currencystring·required
The currency code (e.g., "USD", "BTC", "ETH")Example: USDpreorder.reservedBuyOrders.valuestring (decimal)·required
The amount in the specified currencyExample: 10000.00preorder.reservedSellOrdersobject·required
Collateral reserved for open sell orderspreorder.reservedSellOrders.currencystring·required
The currency code (e.g., "USD", "BTC", "ETH")Example: USDpreorder.reservedSellOrders.valuestring (decimal)·required
The amount in the specified currencyExample: 10000.00preorder.buyingPowerobject·required
The maximum value that can be purchasedpreorder.buyingPower.currencystring·required
The currency code (e.g., "USD", "BTC", "ETH")Example: USDpreorder.buyingPower.valuestring (decimal)·required
The amount in the specified currencyExample: 10000.00preorder.sellingPowerobject·required
The maximum value that can be soldpreorder.sellingPower.currencystring·required
The currency code (e.g., "USD", "BTC", "ETH")Example: USDpreorder.sellingPower.valuestring (decimal)·required
The amount in the specified currencyExample: 10000.00preorder.liquidationRiskobject
Liquidation risk information (only present if applicable)preorder.liquidationRisk.lossPercentagestring (decimal)·required
The percentage loss from current value that would trigger liquidation, formatted as decimal (e.g., "0.1550" = 15.50%)Example: 0.1550preorder.liquidationRisk.liquidationPriceobject
The estimated price at which liquidation would occur (optional, may not be present for all positions)preorder.liquidationRisk.liquidationPrice.currencystring·required
The currency code (e.g., "USD", "BTC", "ETH")Example: USDpreorder.liquidationRisk.liquidationPrice.valuestring (decimal)·required
The amount in the specified currencyExample: 10000.00postorderobject·required
Margin risk statistics after the order would be executedpostorder.marginAssetValueobject·required
The total value of all assets available in the margin accountpostorder.marginAssetValue.currencystring·required
The currency code (e.g., "USD", "BTC", "ETH")Example: USDpostorder.marginAssetValue.valuestring (decimal)·required
The amount in the specified currencyExample: 10000.00postorder.availableCollateralobject·required
The amount of collateral available for new positionspostorder.availableCollateral.currencystring·required
The currency code (e.g., "USD", "BTC", "ETH")Example: USDpostorder.availableCollateral.valuestring (decimal)·required
The amount in the specified currencyExample: 10000.00postorder.notionalValueobject·required
The total value of all open positionspostorder.notionalValue.currencystring·required
The currency code (e.g., "USD", "BTC", "ETH")Example: USDpostorder.notionalValue.valuestring (decimal)·required
The amount in the specified currencyExample: 10000.00postorder.totalBorrowedobject·required
The total amount currently borrowedpostorder.totalBorrowed.currencystring·required
The currency code (e.g., "USD", "BTC", "ETH")Example: USDpostorder.totalBorrowed.valuestring (decimal)·required
The amount in the specified currencyExample: 10000.00postorder.leveragestring (decimal)·required
The leverage ratioExample: 1.5postorder.reservedBuyOrdersobject·required
Collateral reserved for open buy orderspostorder.reservedBuyOrders.currencystring·required
The currency code (e.g., "USD", "BTC", "ETH")Example: USDpostorder.reservedBuyOrders.valuestring (decimal)·required
The amount in the specified currencyExample: 10000.00postorder.reservedSellOrdersobject·required
Collateral reserved for open sell orderspostorder.reservedSellOrders.currencystring·required
The currency code (e.g., "USD", "BTC", "ETH")Example: USDpostorder.reservedSellOrders.valuestring (decimal)·required
The amount in the specified currencyExample: 10000.00postorder.buyingPowerobject·required
The maximum value that can be purchasedpostorder.buyingPower.currencystring·required
The currency code (e.g., "USD", "BTC", "ETH")Example: USDpostorder.buyingPower.valuestring (decimal)·required
The amount in the specified currencyExample: 10000.00postorder.sellingPowerobject·required
The maximum value that can be soldpostorder.sellingPower.currencystring·required
The currency code (e.g., "USD", "BTC", "ETH")Example: USDpostorder.sellingPower.valuestring (decimal)·required
The amount in the specified currencyExample: 10000.00postorder.liquidationRiskobject
Liquidation risk information (only present if applicable)postorder.liquidationRisk.lossPercentagestring (decimal)·required
The percentage loss from current value that would trigger liquidation, formatted as decimal (e.g., "0.1550" = 15.50%)Example: 0.1550postorder.liquidationRisk.liquidationPriceobject
The estimated price at which liquidation would occur (optional, may not be present for all positions)postorder.liquidationRisk.liquidationPrice.currencystring·required
The currency code (e.g., "USD", "BTC", "ETH")Example: USDpostorder.liquidationRisk.liquidationPrice.valuestring (decimal)·required
The amount in the specified currencyExample: 10000.00Example Responses
{
"preorder": {
"marginAssetValue": {
"currency": "USD",
"value": "10000.00"
},
"availableCollateral": {
"currency": "USD",
"value": "8500.00"
},
"notionalValue": {
"currency": "USD",
"value": "15000.00"
},
"totalBorrowed": {
"currency": "USD",
"value": "5000.00"
},
"leverage": "1.5",
"reservedBuyOrders": {
"currency": "USD",
"value": "0.00"
},
"reservedSellOrders": {
"currency": "USD",
"value": "0.00"
},
"buyingPower": {
"currency": "USD",
"value": "8500.00"
},
"sellingPower": {
"currency": "USD",
"value": "8500.00"
}
},
"postorder": {
"marginAssetValue": {
"currency": "USD",
"value": "10000.00"
},
"availableCollateral": {
"currency": "USD",
"value": "6000.00"
},
"notionalValue": {
"currency": "USD",
"value": "40000.00"
},
"totalBorrowed": {
"currency": "USD",
"value": "30000.00"
},
"leverage": "4.0",
"reservedBuyOrders": {
"currency": "USD",
"value": "0.00"
},
"reservedSellOrders": {
"currency": "USD",
"value": "0.00"
},
"buyingPower": {
"currency": "USD",
"value": "6000.00"
},
"sellingPower": {
"currency": "USD",
"value": "6000.00"
},
"liquidationRisk": {
"lossPercentage": "0.6000",
"liquidationPrice": {
"currency": "USD",
"value": "30000.00"
}
}
}
}