SuperAPI AI Directory
Partner中文AI newsFavorites
Skillsupstox

upstox

General & other

View repository

Updated 10-15 23:24

About this skill

Upstox Agent Skill

Trade on Upstox from an AI agent — place live orders, read portfolio data, stream market feeds, and access the full Indian market universe across NSE, BSE, and MCX through the Upstox Developer API and the official upstox-python-sdk.

All SDK signatures in this skill and its references are verified against the upstox-python SDK source. The single most common source of bugs is mixing up the v2 and v3 API classes — read the v2 vs v3 note below before writing order or quote code.

Setup

Install

pip install upstox-python-sdk

Credentials — environment variables only, never hardcode

export UPSTOX_ACCESS_TOKEN="your-daily-access-token"
export UPSTOX_SANDBOX_ACCESS_TOKEN="your-sandbox-access-token"

Initialize the client

import os
import upstox_client

configuration = upstox_client.Configuration()
configuration.access_token = os.environ["UPSTOX_ACCESS_TOKEN"]
api_client = upstox_client.ApiClient(configuration)

Prefer the shared helper so every call reuses one configured client:

from scripts.upstox_helpers import get_client
api_client = get_client()                 # reads UPSTOX_ACCESS_TOKEN (or sandbox)

Sandbox (paper trading)

Use the sandbox to place test orders without real money. The SDK exposes a flag — no separate base URL needed:

configuration = upstox_client.Configuration(sandbox=True)
configuration.access_token = os.environ["UPSTOX_SANDBOX_ACCESS_TOKEN"]

get_client(sandbox=True) does the same. Always rehearse order-placement workflows in the sandbox before going live.

Base URL

https://api.upstox.com/v2 (and /v3 for newer endpoints — the SDK handles this per class).

v2 vs v3 — read this before writing order/quote code

Upstox ships two generations of some APIs. They use different SDK classes and different method signatures. Picking the wrong one is the #1 cause of errors.

Concern v3 (preferred) v2 (legacy)
Orders OrderApiV3 — place_order(body), modify_order(body), cancel_order(order_id) — no api_version arg OrderApi — place_order(body, api_version), etc. — api_version required
GTT orders OrderApiV3.place_gtt_order(body) (only v3) —
LTP / OHLC / greeks MarketQuoteV3Api — get_ltp(instrument_key=...) — no api_version MarketQuoteApi — ltp(symbol, api_version)
Historical candles HistoryV3Api.get_historical_candle_data(instrument_key, unit, interval, to_date, from_date=...) HistoryApi (older interval scheme)
Funds & margin UserApi.get_user_fund_margin_v3() — no args UserApi.get_user_fund_margin(api_version, segment=...)

Default to v3 for orders, quotes, and historical data. Multi-order, order book, trades, brokerage, P&L, options, holidays, and convert-position remain on their v2 classes (OrderApi, ChargeApi, etc.).

Safety Guardrails — ALWAYS ENFORCE

This skill can place live, irreversible financial orders. Before any place_order, modify_order, cancel_order, place_gtt_order, exit_positions, or cancel_multi_order:

Rule Behaviour
Confirmation required Show a full, human-readable order preview and get explicit user confirmation before placing/modifying/cancelling. Run scripts/validate_order.py first.
Default order type: LIMIT Never place a MARKET order unless the user explicitly asks for "market".
Default quantity 1 share (equity) or 1 lot (F&O) when quantity is unspecified — never guess larger.
Lot-size validation Reject F&O orders whose quantity is not a multiple of the instrument's lot_size.
Market Price Protection MARKET orders are auto-bounded by Upstox MPP; pass market_protection (%) to set your own price buffer so a market order can't fill at a wild price. See references/orders.md.
Kill switch A user can halt all trading in a segment via UserApi.update_kill_switch([{segment, action}]) — DISABLE cancels pending orders and blocks new ones. Warn about the ~12-hour re-enable lock before disabling. See references/kill-switch.md.
Sandbox first Rehearse in sandbox (Configuration(sandbox=True)) when the user is testing.
No hardcoded secrets Always read tokens from os.environ.

Rate Limits

Breaching any limit returns HTTP 429 Too Many Requests — back off before retrying.

Combined rate limiting for Order Placement APIs

Applies across Place, Modify, Cancel, Multi Order, and GTT Order — combined.

Regular Algos — no algo registration needed:

Time duration Request limit
Per second 10 requests
Per minute 500 requests
Per 30 minutes 2000 requests

SEBI-Registered Algos — algo registration needed:

Time duration Request limit
Per second 50 requests
Per minute 500 requests
Per 30 minutes 2000 requests

Other Standard APIs

Holdings, positions, funds, historical candles, etc.

Time duration Request limit
Per second 50 requests
Per minute 500 requests
Per 30 minutes 2000 requests

Key Constants

# Transaction
BUY, SELL = "BUY", "SELL"

# Order types
MARKET, LIMIT, SL, SL_M = "MARKET", "LIMIT", "SL", "SL-M"

# Products
INTRADAY, DELIVERY, COVER, ONE_CANCELS_OTHER, MTF = "I", "D", "CO", "OCO", "MTF"

# Validity
DAY, IOC = "DAY", "IOC"
  • Exchanges (the exchange field): NSE, NFO, CDS, BSE, BFO, BCD, MCX
  • instrument_key segment prefixes: NSE_EQ, NSE_FO, NSE_INDEX, BSE_EQ, BSE_FO, BSE_INDEX, NCD_FO, BCD_FO, MCX_FO

instrument_key format

SEGMENT|IDENTIFIER
"NSE_EQ|INE002A01018"     # Reliance (equity → ISIN)
"NSE_INDEX|Nifty 50"      # index (→ name)
"NSE_FO|43919"            # F&O (→ numeric exchange token)

Resolve human names to instrument_key with scripts/instrument_search.py (the server-side Instrument Search API — no master-file downloads). Always resolve the instrument_key this way before placing an order; do not guess option/futures tokens — they change per expiry.

from scripts.instrument_search import resolve_instrument_key
inst = resolve_instrument_key("Reliance", exchanges="NSE", segments="EQ")
instrument_token = inst["instrument_key"]   # pass inst["lot_size"] to validate_order for F&O

Core Patterns

Place a limit buy (v3)

import os, upstox_client
from upstox_client.rest import ApiException

configuration = upstox_client.Configuration()
configuration.access_token = os.environ["UPSTOX_ACCESS_TOKEN"]
order_api = upstox_client.OrderApiV3(upstox_client.ApiClient(configuration))

body = upstox_client.PlaceOrderV3Request(
    quantity=1,
    product="D",                              # D = delivery/CNC
    validity="DAY",
    price=2500.0,
    tag="skill-order",
    instrument_token="NSE_EQ|INE002A01018",   # Reliance
    order_type="LIMIT",
    transaction_type="BUY",
    disclosed_quantity=0,
    trigger_price=0.0,
    is_amo=False,                             # required; True only for after-market orders
)

try:
    resp = order_api.place_order(body)        # NOTE: v3 has no api_version arg
    print("Order ID:", resp.data.order_ids)
except ApiException as e:
    print("Order failed:", e.body)

Get holdings (v2 PortfolioApi)

portfolio_api = upstox_client.PortfolioApi(upstox_client.ApiClient(configuration))
holdings = portfolio_api.get_holdings(api_version="2.0")
for h in holdings.data:
    print(h.trading_symbol, h.quantity, h.last_price, h.pnl)

Get LTP (v3 MarketQuoteV3Api)

mq = upstox_client.MarketQuoteV3Api(upstox_client.ApiClient(configuration))
resp = mq.get_ltp(instrument_key="NSE_EQ|INE002A01018")   # comma-separate for many
print(resp.data)

Reference Index — load on demand

Topic When to load File
Orders (place/modify/cancel/multi/exit) Any order operation references/orders.md
GTT orders (single & multi-leg) Conditional / good-till-triggered orders references/gtt-orders.md
Portfolio (holdings, positions, convert, P&L) View/manage portfolio references/portfolio.md
Market data (LTP, OHLC, quotes, candles, status) Prices & historical data references/market-data.md
Option chain (greeks, OI, PCR, max pain) Options analysis references/option-chain.md
Margins, funds & brokerage charges Pre-trade margin/charge checks references/margins.md
Kill switch (halt trading in a segment) Risk control / disable a segment references/kill-switch.md
WebSocket (live ticks, order updates) Streaming feeds references/websocket.md
Instruments (resolve names → tokens, lot size) Symbol lookup references/instruments.md
Errors (HTTP & UDAPI codes) Debugging, error codes, 429s references/errors.md

Example Prompts This Skill Handles

  • "Buy 10 SBIN at 820"
  • "Place a GTT to buy Wipro when it falls to 440"
  • "How much cash do I have free?"
  • "Last price of Bank Nifty"
  • "Pull the Nifty option chain for this week"

SDK Reference