Skip to main content

Upstox Agent Skills

The Upstox Agent Skill lets AI coding agents like Claude Code and Codex interact directly with your Upstox account. Built on the official upstox-python-sdk and the Agent Skills open standard, it gives an agent the ability to place live orders, stream market data, and manage your portfolio across NSE, BSE, and MCX — equities, futures and options, and commodities.

Unlike a one-off script, the skill packages verified SDK patterns, pre-flight order validation, and built-in safety guardrails so an agent can execute trading workflows reliably and safely from natural language instructions.

What are Agent Skills?​

Agent Skills are self-contained capability packages that follow the SKILL.md open standard. A skill bundles documentation, reference material, helper scripts, and runnable examples that an agent loads on demand to perform a specific job — in this case, trading on Upstox.

The Upstox Agent Skill is compatible with:

  • Claude Code — Anthropic's CLI coding agent
  • Codex — OpenAI's coding agent
  • Any agent framework that supports the SKILL.md standard

How Agent Skills differ from MCP​

Both connect AI tools to your Upstox account, but they serve different workflows:

  • MCP integration provides read-only, conversational access to your account data inside assistants like Claude Desktop and ChatGPT. It is ideal for portfolio analysis and market research.
  • Agent Skills run inside coding agents and use the full upstox-python-sdk, so they can execute trades, run option strategies, and stream live feeds — not just read data.

Use MCP when you want to analyze and ask questions; use the Agent Skill when you want an agent to build and run trading workflows.

Key Capabilities​

Once installed, the skill enables an agent to handle the full trading workflow:

Order execution​

  • Place, modify, and cancel orders across segments using the v3 order APIs
  • GTT (good-till-triggered) orders — single-leg and multi-leg conditional orders
  • Multi-order placement and square-off / exit positions
  • Multi-leg option strategies — bull call spread, short strangle, and bear put butterfly examples included

Market feeds​

  • Live market data and order book depth via MarketDataStreamerV3
  • Quotes — last-traded price, OHLC, and full market quotes
  • Historical candles through the v3 history API
  • Option chains with Greeks, open interest, put-call ratio, and max pain

Portfolio access​

  • Holdings and open positions with live P&L
  • Available funds and margin requirements
  • Position conversion (for example, intraday to delivery)
  • Realised and unrealised P&L calculation

The skill covers NSE, BSE, and MCX across equities (NSE_EQ, BSE_EQ), futures and options (NSE_FO, BSE_FO, MCX_FO), indices, currencies, and commodities.

Prerequisites​

Before installing the skill, ensure you have:

Installing the Upstox Agent Skill​

Claude Code or Codex​

Add the skill directly with npx — no global install required:

npx skills add upstox/upstox-skills --skill upstox

The agent will pick up the skill on its next run and load it automatically when a request involves Upstox trading or market data.

Authentication and Configuration​

The skill needs only an access token to run. Provide it in one of two ways:

Environment variable (recommended)

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

Config file

Copy skills/upstox/config.json.example to skills/upstox/config.json and fill in your token:

{
  "access_token": "your-daily-token"
}

The environment variable takes precedence if both are set. config.json is git-ignored, so your token is never committed.

Daily token refresh

Upstox access tokens expire at the end of each trading day. Refresh your token daily from the Upstox developer portal. The skill never hardcodes credentials — they are always read from the environment or a git-ignored config file.

Safety Guardrails​

Because the skill can place live, irreversible financial orders, it enforces eight safety rules before any order is placed, modified, or cancelled:

Built-in safety rules
  • Confirmation required: Shows a full, human-readable order preview and waits for your explicit confirmation before placing, modifying, or cancelling.
  • Default order type is LIMIT: Never places a MARKET order unless you explicitly ask for one.
  • Default quantity is 1: Defaults to 1 share (equity) or 1 lot (F&O) when quantity is unspecified, so nothing is over-ordered.
  • Lot-size validation: Rejects F&O orders whose quantity is not a valid multiple of the contract's lot size.
  • Market Price Protection (MPP): Market orders are auto-bounded by Upstox MPP; you can tighten the band with the market_protection parameter.
  • Kill switch: Halt all trading in a segment via UserApi.update_kill_switch(...) — cancels pending orders and blocks new ones.
  • Sandbox first: Encourages rehearsing order workflows in the sandbox before going live.
  • No hardcoded secrets: Tokens are always read from the environment or a git-ignored config file.

Sandbox and Paper Trading​

Rehearse order-placement workflows without real money using the Upstox sandbox. The SDK exposes a single flag — no separate base URL is needed:

import os
import upstox_client

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

Always test order flows in the sandbox before placing live trades. For details, see the Upstox sandbox documentation.

Example Prompts​

Once the skill is installed, you can interact with your agent in natural language. Here are some examples:

Orders​

  • "Buy 10 SBIN at 820"
  • "Sell ITC at market, intraday"
  • "Place a GTT to buy Wipro when it falls to 440"
  • "Cancel order 240XXXXXX123"
  • "Square off all my F&O positions"

Portfolio​

  • "What am I holding right now?"
  • "Show my open positions"
  • "How much cash do I have free?"
  • "Move my ITC intraday position to delivery"

Market data​

  • "Last price of Bank Nifty"
  • "Daily candles for SBIN this month"
  • "Show the order book depth for Tata Motors"

Options​

  • "Pull the Nifty option chain for this week's expiry"
  • "Put-call ratio for Bank Nifty"
  • "Which Nifty strike is closest to spot?"
  • "Where's max pain on Nifty?"

Option strategies​

  • "Build a bull call spread on Nifty"
  • "Put on a short strangle on Bank Nifty"
  • "Set up a bear put butterfly on Nifty"

What's Included​

The skill follows a progressive-disclosure model — an agent loads only what each task needs:

  • SKILL.md: Entry point covering setup, the v2 vs v3 API split, safety rules, and core patterns.
  • references/: Deep-dive docs loaded on demand — orders, GTT orders, portfolio, market data, option chain, margins, instruments, kill switch, WebSocket, and errors.
  • scripts/: Shared utilities — a client factory (upstox_helpers.py), instrument resolution (instrument_search.py), and pre-flight order validation (validate_order.py).
  • examples/: Ten runnable Python scripts demonstrating order placement, portfolio summaries, historical candles, option-chain analysis, and multi-leg option strategies.

Responsible Usage​

Investment decision responsibility

AI-generated trading actions and analysis serve as research and execution support, not investment advice. Always:

  • Review every order preview carefully before confirming a trade
  • Rehearse new workflows in the sandbox before going live
  • Verify critical information directly through the Upstox platform
  • Consult qualified financial advisors for major investment decisions
  • Maintain proper risk management regardless of agent recommendations
Live orders are irreversible

The Agent Skill can place real orders that move real money. Confirm every order summary, start with small quantities, and keep the kill switch in mind for halting a segment when you need to step away.

Resources​

Frequently Asked Questions (FAQ)​

What is the Upstox Agent Skill?​

The Upstox Agent Skill is a capability package built on the SKILL.md open standard that lets AI agents like Claude Code and Codex place orders, stream market data, and manage your portfolio on NSE, BSE, and MCX using the official upstox-python-sdk.

How is the Agent Skill different from Upstox MCP?​

MCP integration provides read-only, conversational access to your account data inside assistants like Claude Desktop and ChatGPT. The Agent Skill runs inside coding agents and uses the full SDK, so it can execute trades and run strategies — not just read data.

Which AI agents support the Upstox Agent Skill?​

The skill works with Claude Code, Codex, and any agent framework that supports the SKILL.md standard.

How do I install the Upstox Agent Skill?​

For Claude Code or Codex, run npx skills add upstox/upstox-skills --skill upstox. For a global install, run npm install -g skills followed by skills add upstox/upstox-skills --skill upstox.

Can the Agent Skill place real trades?​

Yes. The skill can place live, irreversible orders using your access token. It enforces safety guardrails — confirmation prompts, LIMIT defaults, lot-size validation, and a sandbox mode — but you remain responsible for every confirmed order.

How does authentication work?​

The skill reads your Upstox access token from the UPSTOX_ACCESS_TOKEN environment variable or a git-ignored config.json file. Tokens expire daily and must be refreshed from the Upstox developer portal. Credentials are never hardcoded.

Can I test without using real money?​

Yes. The Upstox sandbox lets you place test orders with no real money. Initialize the client with Configuration(sandbox=True) and use a sandbox access token. Always rehearse order workflows in the sandbox before going live.