upstox

Upstox Agent 技能

通过 AI Agent 在 Upstox 上进行交易——下达实盘订单、读取投资组合数据、接收实时行情，并通过 Upstox Developer API 和官方 upstox-python-sdk 访问 NSE、BSE 和 MCX 的完整印度市场。

此技能及其参考文档中的所有 SDK 签名均已对照 upstox-python SDK 源码验证。最常见的错误来源是混淆 v2 和 v3 API 类——编写订单或行情代码前，请阅读下面的 v2 与 v3 说明。

---

设置

安装

pip install upstox-python-sdk

凭据——仅使用环境变量，绝不硬编码

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

初始化客户端

import os
import upstox_client

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

建议使用共享助手，让每次调用都复用同一个已配置的客户端：

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

沙盒（模拟交易）

使用沙盒下达测试订单，无需动用真实资金。SDK 提供了一个标志——无需单独的基础 URL：

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

get_client(sandbox=True) 的作用相同。上线前务必在沙盒中演练订单下达工作流。

基础 URL

https://api.upstox.com/v2（较新的端点使用 /v3——SDK 会按类处理）。

---

v2 与 v3——编写订单／行情代码前请阅读

Upstox 的部分 API 有两个代际版本。它们使用不同的 SDK 类和不同的方法签名。选错版本是导致错误的首要原因。

事项	v3（首选）	v2（旧版）
订单	OrderApiV3 — place_order(body)、modify_order(body)、cancel_order(order_id) — 不需要 api_version 参数	OrderApi — place_order(body, api_version) 等 — 必须提供 api_version
GTT 订单	OrderApiV3.place_gtt_order(body)（仅 v3）	—
LTP／OHLC／希腊值	MarketQuoteV3Api — get_ltp(instrument_key=...) — 无需 api_version	MarketQuoteApi — ltp(symbol, api_version)
历史 K 线	HistoryV3Api.get_historical_candle_data(instrument_key, unit, interval, to_date, from_date=...)	HistoryApi（较旧的间隔方案）
资金与保证金	UserApi.get_user_fund_margin_v3() — 无参数	UserApi.get_user_fund_margin(api_version, segment=...)

订单、行情和历史数据默认使用 v3。多订单、订单簿、交易、经纪费、损益、期权、节假日和持仓转换仍使用各自的 v2 类（OrderApi、ChargeApi 等）。

---

安全防护——务必执行

此技能可以下达真实且不可撤销的金融订单。在执行任何 place_order、modify_order、cancel_order、place_gtt_order、exit_positions 或 cancel_multi_order 之前：

规则	行为
必须确认	显示完整、易于理解的订单预览，并在下单／修改／取消前取得用户明确确认。先运行 scripts/validate_order.py。
默认订单类型：LIMIT	除非用户明确要求使用“market”，否则绝不下达 MARKET 订单。
默认数量	未指定数量时，使用 1 股（股票）或 1 手（F&O）——绝不猜测更大的数量。
手数验证	如果 F&O 订单的数量不是该工具 lot_size 的倍数，则拒绝订单。
市场价格保护	MARKET 订单会由 Upstox MPP 自动设定价格上限；传入 market_protection（%）设置自己的价格缓冲，避免市场订单以离谱价格成交。参见 references/orders.md。
紧急停止开关	用户可通过 UserApi.update_kill_switch([{segment, action}]) 停止某个交易板块的所有交易——DISABLE 会取消待处理订单并阻止新订单。停用前请提醒用户：重新启用会锁定约 12 小时。参见 references/kill-switch.md。
先用沙盒	用户进行测试时，请在沙盒中（Configuration(sandbox=True)）演练。
不硬编码机密	始终从 os.environ 读取令牌。

---

速率限制

超出任何限制都会返回 HTTP 429 Too Many Requests——重试前请退避。

订单下单 API 的组合速率限制

适用于下单、修改、取消、多笔订单和 GTT 订单，所有操作合并计算。

常规算法 — 无需注册算法：

时间周期	请求限制
每秒	10 个请求
每分钟	500 个请求
每 30 分钟	2000 个请求

SEBI 注册算法 — 需要注册算法：

时间周期	请求限制
每秒	50 个请求
每分钟	500 个请求
每 30 分钟	2000 个请求

其他标准 API

持仓、仓位、资金、历史蜡烛图等。

时间周期	请求限制
每秒	50 个请求
每分钟	500 个请求
每 30 分钟	2000 个请求

---

关键常量

# 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"

• 交易所（exchange 字段）：NSE、NFO、CDS、BSE、BFO、BCD、MCX
• instrument_key 代码段前缀：NSE_EQ、NSE_FO、NSE_INDEX、BSE_EQ、BSE_FO、BSE_INDEX、NCD_FO、BCD_FO、MCX_FO

instrument_key 格式

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

使用 scripts/instrument_search.py 将人类可读名称解析为 instrument_key（服务端 Instrument Search API，无需下载主数据文件）。下单前务必始终通过此方式解析 instrument_key；不要猜测期权／期货代码，因为它们会随到期日变化。

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

---

核心模式

下限价买单（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)

获取持仓（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)

获取 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)

---

参考索引 — 按需加载

主题	加载时机	文件
订单（下单／修改／取消／多笔／退出）	任何订单操作	references/orders.md
GTT 订单（单腿和多腿）	条件单／触发后长期有效的订单	references/gtt-orders.md
投资组合（持仓、仓位、转换、盈亏）	查看／管理投资组合	references/portfolio.md
市场数据（LTP、OHLC、报价、蜡烛图、状态）	价格和历史数据	references/market-data.md
期权链（希腊值、OI、PCR、最大痛点）	期权分析	references/option-chain.md
保证金、资金和经纪费用	交易前检查保证金／费用	references/margins.md
熔断开关（暂停某个板块的交易）	风险控制／禁用某个板块	references/kill-switch.md
WebSocket（实时报价、订单更新）	实时数据流	references/websocket.md
交易品种（解析名称 → 代码、手数）	查询交易代码	references/instruments.md
错误（HTTP 和 UDAPI 代码）	调试、错误代码、429 错误	references/errors.md

---

此技能支持的提示词示例

• “以 820 的价格买入 10 股 SBIN”
• “设置 GTT 订单，在 Wipro 跌至 440 时买入”
• “我有多少可用现金？”
• “Bank Nifty 的最新价格”
• “获取本周的 Nifty 期权链”

---

SDK 参考

• PyPI：upstox-python-sdk · 导入：import upstox_client
• SDK 源代码：https://github.com/upstox/upstox-python
• API 文档：https://upstox.com/developer/api-documentation/
• 沙盒：upstox_client.Configuration(sandbox=True)
• 异常：from upstox_client.rest import ApiException