POST/us/order/estimate
Estimate Order Charges
API to estimate the charges for a US stocks order before you place it. No order is placed. All amounts are in USD.
A MARKET order is valued at the stock's last traded price. If the last traded price is unavailable, the price in the request is used instead.
Request
curl --location --request POST 'https://api.upstox.com/v2/us/order/estimate' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {your_access_token}' \
--data '{
"instrument_key": "US_EQ|AAPL",
"transaction_type": "BUY",
"order_type": "LIMIT",
"quantity": 1,
"price": 180
}'
For samples in other languages, see the Sample Code section on this page.
Request Body
| Name | Required | Type | Description |
|---|---|---|---|
| instrument_key | Required | string | US instrument key from the US instruments file, for example US_EQ|AAPL. |
| transaction_type | Required | string | Possible values: BUY, SELL. |
| order_type | Required | string | Possible values: MARKET, LIMIT. |
| quantity | Required | number | Number of shares, up to 9 decimal places. Fractions are allowed only for stocks with fractionable: true. Maximum 999999. |
| price | Optional | number | Limit 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
- 200
- 4XX
Response Body
{
"status": "success",
"data": {
"trade_value": 180,
"brokerage": 0.45,
"gst": 0.08,
"regulatory_fee": 0.01,
"taf_fee": 0.01,
"cat_fee": 0.01,
"total_charges": 0.56,
"estimated_total": 180.56
}
}
| Name | Type | Description |
|---|---|---|
| status | string | Outcome of the request. Typically success. |
| data | object | Estimated charges for the order. |
| data.trade_value | number | Quantity × price. For a LIMIT order, the price is the limit price. For a MARKET order, it is the last traded price, or the request price when no last traded price is available. |
| data.brokerage | number | Upstox brokerage. |
| data.gst | number | GST on brokerage. |
| data.regulatory_fee | number | Regulatory fee. |
| data.taf_fee | number | FINRA Trading Activity Fee (TAF). |
| data.cat_fee | number | Consolidated Audit Trail (CAT) fee. |
| data.total_charges | number | Sum of all charges above. |
| data.estimated_total | number | For a BUY: trade value plus charges. For a SELL: trade value minus charges. null when the estimate returns no charges. |
Error codes
| Error code | Description |
|---|---|
| UDAPI1026 | Instrument key is required - Provide instrument_key. |
| UDAPI1009 | TransactionType is required - Provide transaction_type. |
| UDAPI1057 | The 'transaction_type' is invalid - Only BUY and SELL are accepted. |
| UDAPI1004 | Valid order type is required - Provide order_type. |
| UDAPI1056 | The 'order_type' is invalid - Only MARKET and LIMIT are accepted. |
| UDAPI1313 | Quantity is required. |
| UDAPI1300 | Invalid US instrument - The instrument_key is not in the US instruments file. |
| UDAPI1301 | This US stock is not tradable - The stock is listed but not currently tradable. |
| UDAPI1303 | Quantity must be greater than 0 with at most 9 decimal places. |
| UDAPI1304 | Fractional quantity is not allowed for this stock - The stock has fractionable: false. Send a whole-share quantity. |
| UDAPI1311 | Order size cannot exceed 999,999 - Applies to both quantity and amount. |
| UDAPI1307 | Price must be greater than 0 for a limit order. |
| UDAPI1314 | Price must be greater than 0. |
| UDAPI1309 | Price allows 2 decimal places at or above $1 and 4 below $1. |
| UDAPI1310 | Order value must be at least $1. |
| UDAPI1316 | US stocks is not activated for this account - Returned with HTTP 403. |
| UDAPI1317 | US stocks order service is unavailable. Please try again later. - Returned with HTTP 423. |
| UDAPI1318 | US stocks trading is in its daily maintenance window. Please try again later. - Returned with HTTP 423. |
| UDAPI100500 | US order was rejected - The US broker rejected the request. The error message carries the broker's reason. |
| UDAPI1321 | Last traded price is unavailable for this US stock. Send a price or try again later. - Returned with HTTP 423. |
Sample Code
Estimate charges for an order
- Python
- Node.js
- Java
- PHP
- Python SDK
- Node.js SDK
- Java SDK
- PHP SDK
- .NET SDK
import requests
url = 'https://api.upstox.com/v2/us/order/estimate'
headers = {
'Content-Type': 'application/json',
'Accept': 'application/json',
'Authorization': 'Bearer {your_access_token}',
}
data = {
'instrument_key': 'US_EQ|AAPL',
'transaction_type': 'BUY',
'order_type': 'LIMIT',
'quantity': 1,
'price': 180
}
response = requests.post(url, json=data, headers=headers)
print(response.status_code)
print(response.json())
const axios = require('axios');
const url = 'https://api.upstox.com/v2/us/order/estimate';
const headers = {
'Content-Type': 'application/json',
'Accept': 'application/json',
'Authorization': 'Bearer {your_access_token}',
};
const data = {
"instrument_key": "US_EQ|AAPL",
"transaction_type": "BUY",
"order_type": "LIMIT",
"quantity": 1,
"price": 180
};
axios.post(url, data, { headers })
.then(response => {
console.log(response.data);
})
.catch(error => {
console.error(error.response ? error.response.data : error.message);
});
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
public class Main {
public static void main(String[] args) throws Exception {
String body = """
{
"instrument_key": "US_EQ|AAPL",
"transaction_type": "BUY",
"order_type": "LIMIT",
"quantity": 1,
"price": 180
}
""";
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://api.upstox.com/v2/us/order/estimate"))
.header("Content-Type", "application/json")
.header("Accept", "application/json")
.header("Authorization", "Bearer {your_access_token}")
.method("POST", HttpRequest.BodyPublishers.ofString(body))
.build();
HttpResponse<String> response = HttpClient.newHttpClient()
.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.statusCode());
System.out.println(response.body());
}
}
<?php
$url = 'https://api.upstox.com/v2/us/order/estimate';
$headers = [
'Content-Type: application/json',
'Accept: application/json',
'Authorization: Bearer {your_access_token}',
];
$data = [
'instrument_key' => 'US_EQ|AAPL',
'transaction_type' => 'BUY',
'order_type' => 'LIMIT',
'quantity' => 1,
'price' => 180
];
$ch = curl_init($url);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
if (curl_errno($ch)) {
echo 'Error: ' . curl_error($ch);
} else {
echo $response;
}
curl_close($ch);
?>
import upstox_client
from upstox_client.rest import ApiException
configuration = upstox_client.Configuration()
configuration.access_token = '{your_access_token}'
api_instance = upstox_client.UsStocksOrderApi(upstox_client.ApiClient(configuration))
body = upstox_client.UsOrderEstimateRequest(
instrument_key='US_EQ|AAPL',
transaction_type='BUY',
order_type='LIMIT',
quantity=1,
price=180.0
)
try:
api_response = api_instance.estimate_us_order(body)
print(api_response)
except ApiException as e:
print("Exception when calling UsStocksOrderApi->estimate_us_order: %s\n" % e)
let UpstoxClient = require('upstox-js-sdk');
let defaultClient = UpstoxClient.ApiClient.instance;
var OAUTH2 = defaultClient.authentications['OAUTH2'];
OAUTH2.accessToken = "{your_access_token}";
let apiInstance = new UpstoxClient.USStocksOrderApi();
let body = new UpstoxClient.UsOrderEstimateRequest(1, "US_EQ|AAPL", "BUY", "LIMIT");
body.price = 180.0;
apiInstance.estimateUsOrder(body, (error, data, response) => {
if (error) {
console.error(error);
} else {
console.log('API called successfully. Returned data: ' + JSON.stringify(data));
}
});
import com.upstox.ApiClient;
import com.upstox.ApiException;
import com.upstox.Configuration;
import com.upstox.api.UsOrderEstimateRequest;
import com.upstox.api.UsOrderEstimateResponse;
import com.upstox.auth.OAuth;
import io.swagger.client.api.UsStocksOrderApi;
import java.math.BigDecimal;
public class Main {
public static void main(String[] args) {
ApiClient defaultClient = Configuration.getDefaultApiClient();
OAuth OAUTH2 = (OAuth) defaultClient.getAuthentication("OAUTH2");
OAUTH2.setAccessToken("{your_access_token}");
UsStocksOrderApi apiInstance = new UsStocksOrderApi();
UsOrderEstimateRequest body = new UsOrderEstimateRequest();
body.setInstrumentKey("US_EQ|AAPL");
body.setQuantity(new BigDecimal("1"));
body.setPrice(new BigDecimal("180.0"));
body.setOrderType(UsOrderEstimateRequest.OrderTypeEnum.LIMIT);
body.setTransactionType(UsOrderEstimateRequest.TransactionTypeEnum.BUY);
try {
UsOrderEstimateResponse result = apiInstance.estimateUsOrder(body);
System.out.println(result);
} catch (ApiException e) {
System.err.println("Exception when calling UsStocksOrderApi#estimateUsOrder");
e.printStackTrace();
}
}
}
<?php
$config = (new Upstox\Client\Configuration())
->setAccessToken('{your_access_token}');
$apiInstance = new Upstox\Client\Api\USStocksOrderApi(
new GuzzleHttp\Client(),
$config
);
$body = new Upstox\Client\Model\UsOrderEstimateRequest();
$body->setInstrumentKey('US_EQ|AAPL');
$body->setQuantity(1);
$body->setPrice(180.0);
$body->setTransactionType('BUY');
$body->setOrderType('LIMIT');
try {
$result = $apiInstance->estimateUsOrder($body);
print_r($result);
} catch (Exception $e) {
echo 'Exception when calling USStocksOrderApi->estimateUsOrder: ' . $e->getMessage();
}
using UpstoxClient.Api;
using UpstoxClient.Client;
using UpstoxClient.Extensions;
using UpstoxClient.Model;
using Microsoft.Extensions.Hosting;
using Microsoft.Extensions.DependencyInjection;
var host = Host.CreateDefaultBuilder()
.ConfigureApi((context, services, options) =>
{
options.AddTokens(new OAuthToken("{your_access_token}"));
}).Build();
await host.StartAsync();
var apiInstance = host.Services.GetRequiredService<IUSStocksOrderApi>();
try
{
var response = await apiInstance.EstimateUsOrderAsync(new UsOrderEstimateRequest(
quantity: 1m,
price: 180.0m,
instrumentKey: "US_EQ|AAPL",
transactionType: UsOrderEstimateRequest.TransactionTypeEnum.BUY,
orderType: UsOrderEstimateRequest.OrderTypeEnum.LIMIT));
Console.WriteLine(response.RawContent);
}
catch (Exception e)
{
Console.WriteLine("Exception: " + e.Message);
}
await host.StopAsync();