Skip to main content
POST 

/us/charges/margin

Margin Calculator

API to calculate how much money you need for up to 20 US stocks orders, and whether your US wallet has enough balance to place them all. This is only a check: no orders are placed. All amounts are in USD.

  • For a BUY order, the required margin is the trade value plus brokerage and GST.
  • For a SELL order, the required margin is 0.
  • A MARKET order is valued at the last traded price.

US stocks are bought with full cash. The required margin is always the full trade value plus charges.

Request​

curl --location --request POST 'https://api.upstox.com/v2/us/charges/margin' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {your_access_token}' \
--data '{
"instruments": [
{
"instrument_key": "US_EQ|AAPL",
"transaction_type": "BUY",
"order_type": "LIMIT",
"quantity": 1,
"price": 180
},
{
"instrument_key": "US_EQ|MSFT",
"transaction_type": "BUY",
"order_type": "MARKET",
"quantity": 0.5
}
]
}'

For samples in other languages, see the Sample Code section on this page.

Request Body​

NameRequiredTypeDescription
instrumentsRequiredobject[]Orders to check, up to 20. Each entry has the same fields as the Estimate Order Charges request body.
instruments[].instrument_keyRequiredstringUS instrument key from the US instruments file, for example US_EQ|AAPL.
instruments[].transaction_typeRequiredstringPossible values: BUY, SELL.
instruments[].order_typeRequiredstringPossible values: MARKET, LIMIT.
instruments[].quantityRequirednumberNumber of shares, up to 9 decimal places. Fractions are allowed only for stocks with fractionable: true. Maximum 999999.
instruments[].priceOptionalnumberLimit price in USD. Required for a LIMIT order. Optional for a MARKET order, which is valued at the last traded price; price is used only when the last traded price is unavailable. Up to 2 decimal places at or above $1, and up to 4 below $1.

Responses​

Response Body​

{
"status": "success",
"data": {
"margins": [
{
"instrument_key": "US_EQ|AAPL",
"transaction_type": "BUY",
"trade_value": 180,
"brokerage": 0.45,
"gst": 0.08,
"required_margin": 180.53
},
{
"instrument_key": "US_EQ|MSFT",
"transaction_type": "BUY",
"trade_value": 210.5,
"brokerage": 0.53,
"gst": 0.1,
"required_margin": 211.13
}
],
"required_margin": 391.66,
"available_to_invest": 909.45,
"shortfall": 0,
"sufficient": true
}
}
NameTypeDescription
statusstringOutcome of the request. Typically success.
dataobjectRequired margin for the orders and whether the wallet covers them.
data.marginsobject[]One entry per order, in request order.
data.margins[].instrument_keystringUS instrument key of the order.
data.margins[].transaction_typestringPossible values: BUY, SELL.
data.margins[].trade_valuenumberQuantity × limit price, or quantity × last traded price for a MARKET order.
data.margins[].brokeragenumberUpstox brokerage.
data.margins[].gstnumberGST on brokerage.
data.margins[].required_marginnumberFor a BUY: trade value + brokerage + GST. For a SELL: 0.
data.required_marginnumberSum of the required margin across all orders.
data.available_to_investnumberBuying power in the US wallet. Same as available_to_trade in the Get Funds response.
data.shortfallnumberrequired_margin minus available_to_invest. Never below 0.
data.sufficientbooleantrue when available_to_invest covers required_margin.

Sample Code​

Calculate margin for a basket of orders​

import requests

url = 'https://api.upstox.com/v2/us/charges/margin'
headers = {
'Content-Type': 'application/json',
'Accept': 'application/json',
'Authorization': 'Bearer {your_access_token}',
}
data = {
'instruments': [
{
'instrument_key': 'US_EQ|AAPL',
'transaction_type': 'BUY',
'order_type': 'LIMIT',
'quantity': 1,
'price': 180
},
{
'instrument_key': 'US_EQ|MSFT',
'transaction_type': 'BUY',
'order_type': 'MARKET',
'quantity': 0.5
}
]
}

response = requests.post(url, json=data, headers=headers)

print(response.status_code)
print(response.json())