Futures Smartlist

API for retrieving a ranked list of futures contracts filtered by asset type and category. Each entry includes the instrument key, live price data, and the category-specific metric used for ranking.

A smartlist is a curated, real-time ranked list of instruments grouped by a specific market signal — such as highest traded value, biggest open interest change, or largest premium/discount. Instead of scanning the entire futures market, you get a focused subset of contracts that are most relevant to a given category at that moment.

Request

curl --location 'https://api.upstox.com/v2/market/smartlist/futures?asset_type=INDEX&category=TOP_TRADED&page_number=1&page_size=20' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {your_access_token}'

For additional samples in various languages, please refer to the Sample code section on this page.

Query Parameters

Name	Required	Description
asset_type	true	Asset type. Accepted values: INDEX, STOCK, COMMODITY.
category	true	Ranking category. Accepted values depend on asset_type — see the table below.
page_number	false	Page number, 1-indexed. Defaults to 1.
page_size	false	Number of records per page. Maximum 50.

Accepted category values by asset_type:

asset_type	Accepted category values
INDEX, STOCK	TOP_TRADED, MOST_ACTIVE, OI_GAINERS, OI_LOSERS, PRICE_GAINERS, PRICE_LOSERS, PREMIUM, DISCOUNT
COMMODITY	TOP_TRADED, MOST_ACTIVE, OI_GAINERS, OI_LOSERS

The metric_key field in the response indicates which metric was used for ranking:

category	metric_key
TOP_TRADED	total_traded_value
MOST_ACTIVE	volume_traded_today
OI_GAINERS, OI_LOSERS	open_interest
PRICE_GAINERS, PRICE_LOSERS	price
PREMIUM	premium
DISCOUNT	discount

Responses

• 200
• 4XX

---

Response body

{
    "status": "success",
    "data": {
        "asset_type": "INDEX",
        "category": "TOP_TRADED",
        "time_stamp": 1780045636752,
        "metric_key": "total_traded_value",
        "smartlist": [
            {
                "instrument_key": "NSE_FO|62329",
                "price": {
                    "current": 23867.0,
                    "close_price": 23996.7,
                    "change_abs": -129.70,
                    "change_pct": -0.54
                },
                "metric": {
                    "current": 132094775540,
                    "previous": 69295823909,
                    "change_abs": 62798951631.00,
                    "change_pct": 90.62
                }
            },
            {
                "instrument_key": "NSE_FO|62326",
                "price": {
                    "current": 54970.0,
                    "close_price": 55207.0,
                    "change_abs": -237.00,
                    "change_pct": -0.43
                },
                "metric": {
                    "current": 45591018600,
                    "previous": 43236361746,
                    "change_abs": 2354656854.00,
                    "change_pct": 5.45
                }
            },
            {
                "instrument_key": "NSE_FO|61093",
                "price": {
                    "current": 23977.8,
                    "close_price": 24089.6,
                    "change_abs": -111.80,
                    "change_pct": -0.46
                },
                "metric": {
                    "current": 5752633887,
                    "previous": 4917306790.5,
                    "change_abs": 835327096.50,
                    "change_pct": 16.99
                }
            }
        ],
        "page_number": 1,
        "page_size": 3,
        "total_pages": 9
    }
}

Name	Type	Description
status	string	Outcome of the request. Typically success for successful operations.
data	object	Response data object.
data.asset_type	string	Asset type from the request.
data.category	string	Category from the request.
data.time_stamp	integer	Unix timestamp in milliseconds when the data was generated.
data.metric_key	string	The metric used for ranking in this response.
data.smartlist	array	Ranked list of futures instruments.
data.smartlist[].instrument_key	string	Unique instrument identifier. See Instrument keys.
data.smartlist[].price.current	number	Last traded price (LTP).
data.smartlist[].price.close_price	number	Previous close price.
data.smartlist[].price.change_abs	number	Absolute price change (current - close_price).
data.smartlist[].price.change_pct	number	Percentage price change.
data.smartlist[].metric.current	number	Current value of the ranking metric.
data.smartlist[].metric.previous	number	Previous value of the ranking metric.
data.smartlist[].metric.change_abs	number	Absolute change in the metric.
data.smartlist[].metric.change_pct	number	Percentage change in the metric.
data.page_number	integer	Current page number.
data.page_size	integer	Number of records in the current page.
data.total_pages	integer	Total number of pages available.

Error codes

Error code	Description
UDAPI1212	Invalid asset_type — The asset_type value must be INDEX, STOCK, or COMMODITY.
UDAPI1213	Invalid category for the given asset_type — The category value is not supported for the provided asset_type.
UDAPI1214	Invalid page_size — The page_size value exceeds the maximum allowed value of 50.

Sample Code

Get futures smartlist

Curl

curl --location 'https://api.upstox.com/v2/market/smartlist/futures?asset_type=INDEX&category=TOP_TRADED&page_number=1&page_size=20' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {your_access_token}'

Python

import requests

url = 'https://api.upstox.com/v2/market/smartlist/futures'
params = {
    'asset_type': 'INDEX',
    'category': 'TOP_TRADED',
    'page_number': 1,
    'page_size': 20,
}
headers = {
    'Content-Type': 'application/json',
    'Accept': 'application/json',
    'Authorization': 'Bearer {your_access_token}'
}

response = requests.get(url, params=params, headers=headers)
print(response.text)

Node.js

const axios = require('axios');

const url = 'https://api.upstox.com/v2/market/smartlist/futures';
const params = {
  asset_type: 'INDEX',
  category: 'TOP_TRADED',
  page_number: 1,
  page_size: 20,
};
const headers = {
  'Content-Type': 'application/json',
  'Accept': 'application/json',
  'Authorization': 'Bearer {your_access_token}'
};

axios.get(url, { params, headers })
  .then(response => console.log(response.data))
  .catch(error => console.error(error));

Java

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 url = "https://api.upstox.com/v2/market/smartlist/futures"
            + "?asset_type=INDEX"
            + "&category=TOP_TRADED"
            + "&page_number=1"
            + "&page_size=20";

        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create(url))
            .header("Content-Type", "application/json")
            .header("Accept", "application/json")
            .header("Authorization", "Bearer {your_access_token}")
            .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        System.out.println(response.body());
    }
}

PHP

<?php

$query = http_build_query([
    'asset_type'  => 'INDEX',
    'category'    => 'TOP_TRADED',
    'page_number' => 1,
    'page_size'   => 20,
]);

$url = 'https://api.upstox.com/v2/market/smartlist/futures?' . $query;

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Content-Type: application/json',
    'Accept: application/json',
    'Authorization: Bearer {your_access_token}',
]);

$response = curl_exec($ch);
if (curl_errno($ch)) {
    echo 'Curl error: ' . curl_error($ch);
}
curl_close($ch);
echo $response;
?>

Loading...