📚

Setup & Daily Workflow

Everything you need to get TraderX running and use it every trading morning.

⚠
Paper Trading Only — TraderX never places real orders. It only reads live market data from Upstox and simulates trades in a local SQLite database. No order-placement endpoint is ever called.

1 Prerequisites

  • ✓ Python 3.10+ — check with python3 --version
  • ✓ An Upstox Developer App — create one at developer.upstox.com ↗
  • ✓ Your app's Redirect URI set to exactly: http://127.0.0.1:8000/callback
  • ✓ An active Upstox trading account with market data subscription

2 Installation

Clone or download the project, then install dependencies:

Terminal
cd /path/to/TraderX
pip install -r requirements.txt
💡 Using a virtual environment is recommended: 
python3 -m venv .venv
source .venv/bin/activate   # macOS / Linux
.venv\Scripts\activate      # Windows
pip install -r requirements.txt

3 Configuration

Open config.yaml and fill in your Upstox credentials:

config.yaml
upstox:
  api_key: "YOUR_API_KEY"       # client_id from Upstox dev portal
  api_secret: "YOUR_API_SECRET" # client_secret from Upstox dev portal
  redirect_uri: "http://127.0.0.1:8000/callback"

strategy:
  target_pct: 20.0        # Exit at +20% from entry
  stoploss_pct: 20.0      # Exit at -20% from entry
  hard_exit_time: "09:32" # HH:MM IST — force-close all positions
  max_positions: 3

server:
  host: "127.0.0.1"
  port: 8000
🔒 Security: config.yaml contains your API secret — keep it local. It is listed in .gitignore along with .upstox_token and traderx.db.

Alternatively, use environment variables (take priority over YAML):

Terminal
export UPSTOX_API_KEY="your_api_key"
export UPSTOX_API_SECRET="your_api_secret"

4 Running the App

Terminal
cd /path/to/TraderX
python3 -m uvicorn app:app --host 127.0.0.1 --port 8000

Then open your browser at:

▶  http://127.0.0.1:8000

On startup you should see in the terminal:

  TraderX — Paper Trading Dashboard
  PAPER TRADING MODE — NO LIVE ORDERS WILL BE PLACED
============================================================

5 Upstox Authentication

Upstox uses OAuth 2.0. You need to log in once each trading day (tokens expire daily at midnight).

1
Click "Login to Upstox" in the top-right of the dashboard.
↓
2
You'll be redirected to Upstox's login page. Enter your credentials and complete 2FA.
↓
3
Upstox redirects back to /callback. The token is exchanged and saved to .upstox_token automatically.
↓
4
The auth dot turns green and shows "Connected to Upstox". You're ready.
🔄 Token reuse: Once authenticated, the token is cached. If you restart the app during the same day, it loads automatically — no re-login needed until the next day.

6 Daily Workflow

~9:00 AM
Start the server & authenticate

Run the app and click "Login to Upstox" if not already authenticated. The green dot confirms you're live.

~9:15 AM
Market opens

Watch price action for the first 2 minutes to identify your candidates.

9:17 AM
Submit candidates

Type up to 3 stock names (e.g. RELIANCE, TCS, INFY) in the input boxes and click ▶ Start Tracking. The app will:

  • Look up each stock's current spot price
  • Find the ATM Put option for the current weekly expiry
  • Fetch the live LTP as entry price
  • Calculate Target (+20%) and SL (−20%)
  • Start streaming live LTP via Upstox WebSocket
9:17–9:32 AM
Monitor

Watch the 3 cards. Each one independently tracks whether it hits target, SL, or neither. A flash and badge update happens the moment any position exits.

9:32 AM
Hard Exit

Any positions still open are automatically closed at the current LTP with reason TIME_EXIT. The feed stops. No action needed from you.

After 9:32 AM
Mark your actual pick

Toggle "My actual pick" on whichever of the 3 you would have (or did) trade. This is used to filter the Stats panel to show your personal track record.

7 Dashboard Guide

◯
Countdown Ring
SVG ring at the top counts down from 9:15 to 9:32 AM. Turns red with pulsing digits in the last 2 minutes.
📊
Position Cards
One card per candidate. Shows symbol, LTP, P&L % in large text (green/red), and a gauge bar between SL and Target.
🔴
Status Badges
● OPEN → ✓ TARGET HIT or ✕ SL HIT or ⏰ TIME EXIT. Card border glows the matching color.
⚡
Exit Flash
When any position exits, the card flashes + a full-screen color overlay fires — impossible to miss even at a glance.
🔌
Disconnect Banner
Red pulsing banner appears at the top if the Upstox WebSocket feed drops. Auto-reconnect is attempted in the background.
📈
Stats Panel
Win rate, avg win/loss %, and expectancy computed from all historical trades. Toggle between "All Candidates" and "My Picks Only".

8 Strategy Parameters

All parameters are in config.yaml. Change them without touching any Python code:

Parameter Default Description
target_pct 20.0 Exit position when LTP rises +N% above entry price
stoploss_pct 20.0 Exit position when LTP falls −N% below entry price
hard_exit_time 09:32 Force-close all open positions at this time IST (HH:MM)
max_positions 3 Maximum simultaneous candidate positions
entry_window_start 09:15 Earliest allowed entry time (informational)
🔄 Restart the server after changing config.yaml for changes to take effect.

9 CLI Tools

You can run upstox_client.py directly to test the connection without starting the full dashboard:

Smoke-test WebSocket feed (prints 5 ticks, then exits)
python3 upstox_client.py --test "NSE_INDEX|Nifty 50"
Resolve ATM PE for a stock and print its LTP
python3 upstox_client.py --atm-pe RELIANCE
Manually exchange an OAuth code (if the browser callback fails)
python3 upstox_client.py --code <AUTH_CODE_FROM_URL>

10 Troubleshooting

▸ "Not authenticated" — login button doesn't work

Make sure api_key and api_secret are filled in config.yaml. Also confirm the Redirect URI in your Upstox app settings is exactly http://127.0.0.1:8000/callback (no trailing slash).

▸ "Empty option chain" error when submitting stocks

This happens if the stock name doesn't match Upstox's instrument search, or there's no active option chain (e.g. entered outside trading hours). Try using the exact Upstox instrument key format: NSE_FO|<token>. You can find instrument keys in Upstox's instrument dump CSV.

▸ The red "data feed disconnected" banner keeps appearing

The WebSocket auto-reconnects with exponential backoff (up to 30s). Check your internet connection. If it persists, your Upstox token may have expired — re-login via the dashboard button.

▸ LTP shows 0.00 or doesn't update

The option may have zero liquidity or market is closed. Confirm you're within market hours (9:15 AM – 3:30 PM IST). The WebSocket feed only carries active ticks — illiquid options may be slow.

▸ Port 8000 is already in use

Change the port in config.yaml under server.port, and update the Redirect URI in both config.yaml and your Upstox app settings to match.

python3 -m uvicorn app:app --host 127.0.0.1 --port 8080
▸ "protobuf" import error on startup

Install the package manually: pip install protobuf. The app will fall back to JSON decoding if the compiled MarketDataFeed_pb2.py module fails — but having protobuf installed is required.

▲ Back to Dashboard