A single-user algorithmic trading platform for Indian equity options.
Signals are scraped from Telegram groups (MTProto userbot), executed via the Kotak Neo API, and monitored through a React dashboard.
┌─────────────────────────────────────────────────────────┐
│ Telegram Groups (3rd-party, no bot access) │
└──────────────────────────┬──────────────────────────────┘
│ MTProto (grammers-client)
▼
┌─────────────────────────────────────────────────────────┐
│ telegram_ingester regex signal parser │
│ → TradeSignal → broadcast channel │
└──────────────────────────┬──────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────┐
│ trading_engine stateful OMS (50ms tick) │
│ WaitingForEntry → Active → Target1Hit → Closed │
│ FeeCalculator (STT, SEBI, stamp, GST) │
│ → DbWriteMessage → mpsc channel │
└──────────────┬────────────────────────┬─────────────────┘
│ │
▼ ▼
┌──────────────────────┐ ┌────────────────────────────┐
│ kotak_client │ │ SQLite (WAL) │
│ REST: login + │ │ wallet / paper_trades / │
│ place_live_order │ │ system_logs / │
│ WebSocket: LTP feed │ │ trading_config │
│ (sfeed.*) │ └────────────────────────────┘
└──────────────────────┘ │
▼
┌───────────────────────┐
│ server (Axum :8080) │
│ GET /api/portfolio │
│ GET /api/settings │
│ POST /api/settings │
│ POST /api/webhook/.. │
│ GET /api/logs/stream│
└───────────┬───────────┘
│ SSE + REST
▼
┌───────────────────────┐
│ frontend (Vite/React)│
│ Settings bar │
│ P&L chart (recharts) │
│ Trade table │
│ Live log terminal │
└───────────────────────┘
| Tool | Minimum version | Install |
|---|---|---|
| Rust + Cargo | stable ≥ 1.80 | curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh |
| Node.js | ≥ 20 | nodejs.org |
| pnpm | ≥ 9 | npm i -g pnpm |
| SQLite | any | shipped with macOS/Linux |
git clone <repo-url> auto-trader
cd auto-trader
# type-check all 5 crates
cargo check
# run the server (SQLite auto-created at trades.db)
cargo run -p serverThe server listens on http://0.0.0.0:8080.
cd frontend
pnpm install
pnpm dev # http://localhost:5173 — proxies /api → :8080Open http://localhost:5173 in your browser.
cd frontend
pnpm build # outputs to frontend/dist/The Axum server already serves ../frontend/dist as a static fallback, so after building you can access the dashboard directly at http://localhost:8080.
This repo now supports a split deployment model:
- Backend on a VM or bare-metal host
- Frontend on Vercel
For the backend host:
cd auto-trader
cargo build --release -p server
cd kotak-bridge && npm installThen run the backend from the repo root so the SQLite database, Telegram session file, and kotak-bridge/ folder all stay in a stable relative layout:
cd auto-trader
./target/release/serverRecommended VM notes:
- Open TCP port
8080, or put Nginx/Caddy in front and expose HTTPS on443 - Keep
trades.dbandsession.jsonon persistent disk - Install Node.js on the VM because the Rust backend launches
kotak-bridge/index.js
For the Vercel frontend:
- Deploy the
frontend/directory - On first load, enter your backend URL or IP in the
Server URL or IP:PORTfield in the Kotak login panel - The frontend stores that server address in browser storage and a cookie, so you do not need to re-enter it every time
Examples:
http://34.93.xx.xx:8080https://api.example.com
The backend reads environment variables from the process environment. It also
auto-loads a .env file from the working directory at startup (via
dotenvy) if one is present — variables already exported in the shell or a
systemd EnvironmentFile= still take priority. So any of the following work:
- export the variables in your shell before starting the server,
- put them in a
.envfile next totrades.db(never commit this — it's gitignored), or - define them in a
systemdunit withEnvironment=orEnvironmentFile=
All backend date-sensitive logic is normalized to Indian Standard Time (IST, UTC+05:30).
That includes expiry-date interpretation, "today" checks, and persisted trade/log timestamps,
so behavior stays aligned with Indian markets even if the server is running in another timezone.
See .env.example for a ready-to-copy template (and
frontend/.env.example for the optional frontend
one). These are the supported variables:
# ── Sign-in (required) ────────────────────────────────────
# Gates the whole app — every /api/* route but /api/health, /api/version and
# the sign-in itself needs the bearer token a phone sign-in returns, signed
# with AUTH_SECRET. See "Signing In". Read at run time only, never built into
# the binary (release binaries are public).
AUTH_SECRET=change-me-too
ADMIN_PHONE=75xxxxxxxx # the owner's 10-digit number: the one admin
WA_SERVER_URL=https://wa.example.com # self-hosted WhatsApp server that sends the codes
WA_API_KEY=change-me
# ── SQLite ───────────────────────────────────────────────
DATABASE_URL=sqlite://trades.db # default
# ── Files kept between runs ──────────────────────────────
# The Kotak scrip-master CSVs are saved here after every download and
# streamed back by the admin's CSV download, so only the parsed store stays
# in memory; the instrument catalog (search) is built from them into
# data/instruments.db. Relative to the working directory, like trades.db.
DATA_DIR=data # default
# ── Memory alarm ─────────────────────────────────────────
# Server resident memory (MB) above which the log warns once (MEMORY_WARN in
# the dashboard log) and the pulse JSON (/api/telemetry/*, /api/health)
# reports memory_warn: true, until it falls 5% back under. Sized to the VM's
# real headroom: about 330 MB free with the server at 150 MB on 2026-11-04.
MEMORY_WARN_MB=450 # default
# Trading mode (PAPER/LIVE), max trade size, brokerage, and target/SL
# settings all live in the `trading_config` SQLite table, not env vars —
# edit them via the Settings bar in the UI or POST /api/settings.
# ── Telegram MTProto ingester (optional) ─────────────────
# Get these from https://my.telegram.org → API Development Tools
TELEGRAM_API_ID=12345678
TELEGRAM_API_HASH=abcdef1234567890abcdef1234567890
# Comma-separated chat IDs to listen to (use a negative number for groups)
TELEGRAM_CHAT_IDS=-1001234567890,-1009876543210
# ── Kotak Neo WebSocket ───────────────────────────────────
# Scrips to subscribe (pSymbol from scrip master, & separated)
KOTAK_SCRIPS=nse_cm|11536&nse_cm|1594
# ── Kotak Neo auto-login (optional) ───────────────────────
# Set all five to skip the manual Kotak login form. The server will:
# - log in at startup if no valid session is restored from the DB,
# - log in at 09:05 IST each trading day (pre-warm, so the Scrip Master is
# loaded before the 09:15 open), and retry at 09:15 if that failed.
# The 6-digit TOTP is generated from KOTAK_TOTP_SECRET (RFC 6238), so no
# human needs to read a code off an authenticator app each morning.
KOTAK_ACCESS_TOKEN=eyJhbGci... # API Dashboard access token
KOTAK_MOBILE_NUMBER=+91XXXXXXXXXX # registered mobile, with country code
KOTAK_UCC=Y4HAU # Unique Client Code
KOTAK_MPIN=123456 # 6-digit trading MPIN
KOTAK_TOTP_SECRET=JBSWY3DPEHPK3PXP # Base32 secret from TOTP registration (alias: KOTAK_TOTP_HASH)
# KOTAK_AUTO_LOGIN=false # set to disable unattended auto-login even if the above are setAny of access_token / mobile_number / ucc / mpin / totp left blank
in a manual POST /api/auth/kotak request also falls back to these same env
vars, and a blank totp is generated from KOTAK_TOTP_SECRET — so the
Kotak login form still works with only some fields filled in. A dedicated
POST /api/auth/kotak/auto-login (no body) logs in using only the env vars.
Example shell startup:
export AUTH_SECRET=change-me-too
export ADMIN_PHONE=75xxxxxxxx
export WA_SERVER_URL=https://wa.example.com
export WA_API_KEY=change-me
export DATABASE_URL=sqlite:///home/ubuntu/auto-trader/trades.db
export TELEGRAM_API_ID=12345678
export TELEGRAM_API_HASH=abcdef1234567890abcdef1234567890
export TELEGRAM_CHAT_IDS=-1001234567890,-1009876543210
cd ~/auto-trader
./target/release/serverThis section assumes:
- backend on a small Ubuntu/Debian VM (any cloud — GCP, Oracle Cloud, AWS, DigitalOcean, ...)
- frontend on Vercel
- repo uploaded with the same folder layout
Create a small VM (a free/burstable tier such as GCP e2-micro or Oracle Cloud's Always Free shapes is enough) and allow, in your cloud provider's console-level firewall (security list / network security group — this is separate from and in addition to the VM's own OS firewall):
- SSH from your admin IP
- TCP
8080if you want to expose the Rust server directly - TCP
80and443if you will use Nginx/Caddy as a reverse proxy
Gotcha — check the VM's own OS firewall too, and check rule order. Several stock cloud images (Oracle Cloud's Ubuntu images in particular) ship with
iptablespre-configured to accept SSH and reject everything else by default. If you (or a setup script) append newACCEPTrules for8080/443after that catch-allREJECTrule, they are silently dead —iptablesmatches top to bottom, so the reject fires first and the port stays closed to the outside world even thoughiptables -Lshows an "allow" rule for it further down. This is easy to miss because the backend still answers fine on127.0.0.1from inside the VM (loopback traffic skips the rule), so the API looks healthy over SSH while every external caller — including your Vercel frontend — silently times out.Check with
sudo iptables -L INPUT -n --line-numbersand make sure yourACCEPTrules for the ports you need come before any blanketREJECT/DROPrule. If you need to reorder, insert the correct rules withsudo iptables -I INPUT <line-number-before-the-reject> ..., remove the old dead ones, then runsudo netfilter-persistent save(ifiptables-persistentis installed) so the fix survives a reboot. After any change, verify from outside the VM —curl http://<public-ip>:8080/api/healthfrom your own machine, not just from inside an SSH session.
Recommended baseline packages:
sudo apt update
sudo apt install -y curl git nginx
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt install -y nodejs
node -v
npm -vRust itself is only needed on the VM if you plan to build there; the recommended flow (below) downloads a prebuilt release binary instead, so cargo/rustup are optional.
cd ~
git clone <repo-url> auto-trader
cd auto-trader/kotak-bridge
npm install
cd ..The backend binary itself does not need to be built on the VM — see step 4.
Important runtime note — PATH CONTRACT:
- the server binary must run with
auto-trader/backend/as its working directory, not the repo root — it resolvestrades.db,session.json,data/(the saved scrip-master CSVs),../frontend/dist, and../kotak-bridgerelative to the working directory it was started from. Starting it from anywhere else breaks those lookups. In production the binary itself also lives directly insidebackend/(see step 4), so in practice this means:cd ~/auto-trader/backend && ./the-binary. frontend/distis put in place by the deploy workflow: every release carries the frontend build (frontend-<version>.tar.gz, built by CI, never on the VM) and each deploy installs it, so the server's static-fallback route serves the same app as Vercel at the VM's own address. Until the first deploy it may be empty, which only means there is nothing to serve if you hit the VM directly.
If you are deploying from GitHub, point Vercel at the frontend/ directory.
Vercel settings:
- Framework preset:
Vite - Root directory:
frontend - Build command:
pnpm build - Output directory:
dist
No frontend environment variable is required for the backend URL because the UI now asks for it and stores it in browser storage and a cookie.
Download the latest release binary built by CI (.github/workflows/release-server.yml) rather than building on the VM — this is a small VM that also runs the live 50ms trading-tick loop once it's live, and a cargo build --release here would compete with it for CPU/memory:
cd ~/auto-trader/backend
LATEST_JSON=$(curl -s https://api.github.com/repos/MrImmortal09/auto-trader/releases/latest)
DOWNLOAD_URL=$(echo "$LATEST_JSON" | grep -o '"browser_download_url": *"[^"]*"' | grep 'x86_64-unknown-linux-gnu' | head -n1 | cut -d '"' -f4)
curl -fsSL "$DOWNLOAD_URL" -o "$(basename "$DOWNLOAD_URL")"
chmod +x server-*-x86_64-unknown-linux-gnuPut your env vars in ~/auto-trader/backend/.env (auto-loaded from the working directory at startup — see Environment Variables):
cat > ~/auto-trader/backend/.env <<'EOF'
AUTH_SECRET=change-me-too
ADMIN_PHONE=75xxxxxxxx
WA_SERVER_URL=https://wa.example.com
WA_API_KEY=change-me
TELEGRAM_API_ID=12345678
TELEGRAM_API_HASH=abcdef1234567890abcdef1234567890
TELEGRAM_CHAT_IDS=-1001234567890,-1009876543210
KOTAK_SCRIPS=nse_cm|11536&nse_cm|1594
EOFPATH CONTRACT, again: start it from inside backend/, not the repo root — trades.db, .env, session.json, and the ../frontend/dist / ../kotak-bridge lookups are all relative to the working directory:
cd ~/auto-trader/backend
./server-*-x86_64-unknown-linux-gnuExpected behavior:
- server binds to
0.0.0.0:8080 - Kotak bridge starts only after valid Kotak login tokens exist
- Telegram auth state is stored in
session.json
This project runs the backend in the foreground of a dedicated tmux pane rather than under systemd, so a live trading process is never silently backgrounded or auto-restarted mid-position without a human noticing:
tmux new-session -d -s 0
tmux send-keys -t 0:0 "cd ~/auto-trader/backend && ./server-*-x86_64-unknown-linux-gnu" C-m
tmux attach -t 0Session 0, window 0 (i.e. pane 0:0) is what the deploy workflow restarts — using the exact names above means it works with no edits. If you'd rather use a different session/window name, change PANE in .github/workflows/deploy.yml to match.
Updates are deployed by GitHub Actions. Every push to main builds a release (release-server.yml, version 0.1.<run number>: the server binary and the frontend build, frontend-<version>.tar.gz; a frontend that doesn't build stops the release) and then runs deploy.yml, at any time of day. Over SSH it starts the deploy detached on the VM (a dropped connection can't stop it halfway) and streams its log. Before anything stops, it downloads the release's binary and frontend build, checks the binary is a Linux binary and that both match GitHub's SHA-256, stages them, backs up the binary running and syncs ~/auto-trader to the release's tag (the Kotak bridge is plain JS read at spawn). Then it stops the server (Ctrl-C in its tmux pane, then SIGTERM, then SIGKILL, and waits for port 8080 to be free), swaps the binary in with an atomic rename and the frontend build in as frontend/dist (keeping the one it replaces as frontend/.dist_prev), starts it (making the tmux session again if a reboot lost it), and waits up to 180 s for /api/health to answer and /api/version to report the new version — rolling back the binary, the frontend and the source if it doesn't, or at once if the process dies. A release from before the frontend build was added leaves frontend/dist as it is. Only one deploy runs at a time. The engine is down from the stop until the new server answers: a few seconds, up to a minute or two when it restores the Kotak session and downloads the Scrip Master first — open positions included. Run Deploy server from the Actions tab to deploy again, or to go back to an older release by its tag. On the VM, each run's output is appended to /tmp/deploy.log.
The deploy needs four repository secrets: ORACLE_VM_HOST, ORACLE_VM_USER, ORACLE_VM_SSH_KEY (a key used only for deploys, its public half in the VM's ~/.ssh/authorized_keys) and ORACLE_VM_FINGERPRINT (the VM's host key, ssh-keyscan -t ed25519 <host> | ssh-keygen -lf -, the SHA256:… part). deploy-test.yml runs the deploy script against a simulated VM on every pull request that changes it.
If you'd rather run under systemd with auto-restart-on-crash instead of tmux, that's a reasonable alternative for a less hands-on setup — just be aware the deploy workflow as written assumes tmux, so you'd need to adapt its stop/start steps to systemctl restart first.
Directly exposing :8080 works, but a reverse proxy is cleaner and lets you add TLS.
Example Nginx site:
server {
listen 80;
server_name api.example.com;
location / {
proxy_pass http://127.0.0.1:8080;
proxy_http_version 1.1;
proxy_set_header Host $host;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_set_header Connection '';
proxy_buffering off;
}
}Then enable it:
sudo tee /etc/nginx/sites-available/auto-trader >/dev/null <<'EOF'
server {
listen 80;
server_name api.example.com;
location / {
proxy_pass http://127.0.0.1:8080;
proxy_http_version 1.1;
proxy_set_header Host $host;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_set_header Connection '';
proxy_buffering off;
}
}
EOF
sudo ln -s /etc/nginx/sites-available/auto-trader /etc/nginx/sites-enabled/auto-trader
sudo nginx -t
sudo systemctl reload nginxIf you have a domain, add HTTPS with Certbot afterward.
Client addresses behind the proxy. The backend keys its sign-in rate limits (the phone OTP's send and verify limits) on the last X-Forwarded-For hop, which $proxy_add_x_forwarded_for appends from nginx's own view of the client; earlier hops and any X-Real-IP are whatever the client sent and are ignored. Keep that proxy_set_header line. If the site sits behind Cloudflare, $remote_addr is a Cloudflare edge address unless nginx restores the visitor's, so add the real_ip directives to the http block (Cloudflare publishes its ranges at https://www.cloudflare.com/ips/):
set_real_ip_from 173.245.48.0/20; # one line per Cloudflare range, v4 and v6
real_ip_header CF-Connecting-IP;After the Vercel site is live:
- Open the frontend in the browser.
- On the sign-in page, click
Changeunder the form and enter your backend address. - Use either
http://PUBLIC_IP:8080or your reverse-proxied domain such ashttps://api.example.com. - Continue using the UI normally; all API calls, SSE logs, and downloads will use that stored backend URL.
Examples:
http://34.93.xx.xx:8080https://api.example.com
For Telegram:
- Open the frontend.
- Enter Telegram API ID, API hash, and phone number.
- Request the login code.
- Submit the OTP and 2FA password if prompted.
- Select the chats to monitor.
For Kotak:
- Enter the backend server URL once.
- Enter Kotak access token, mobile number, UCC, TOTP, and MPIN.
- Click
Connect. - On success, the backend fetches the scrip master and starts the Node bridge.
Before considering the deployment ready, verify:
curl http://127.0.0.1:8080/api/healthreturns JSON from inside the VM (over SSH)curl http://<public-ip>:8080/api/healthreturns JSON from your own machine, outside the VM — this is the check that would have caught the iptables-ordering gotcha from step 1; a pass over SSH alone does not prove the outside world can reach ittmux attach -t trader(or your session name) shows the server running and logging normally- the Vercel frontend can load settings and portfolio data
- live logs connect through
/api/logs/stream - Telegram chat selection works
- Kotak login succeeds and scrip master download works
These files should remain on persistent disk on the VM, inside backend/:
trades.db(+-shm/-walcompanion files)session.json.env- the current release binary,
backend/server-<version>-x86_64-unknown-linux-gnu kotak-bridge/node_modules/data/(DATA_DIR): the three Scrip Master CSVs the last download saved (data/scrip/<segment>.csv) and the instrument catalog built from them with its close snapshot (data/instruments.db+-wal/-shm). Gitignored, and rebuildable: the next Kotak login downloads the CSVs again and the catalog is rebuilt from them, so it is safe to delete (it costs one download, and search is empty until then) and need not be copied to a fresh VM. The engine never reads it: its Scrip Master comes from the login's download alone.
The deploy workflow keeps the previous binary (and a copy as backend/.server_prev) for rollback and prunes older ones — you don't need to manage binary versions by hand. If you ever move to a fresh VM, copy over trades.db*, session.json, and .env from backend/ before starting the server there.
The search slice (instruments/, quotes/, behind the search switch — PUT /api/v2/flags {"search": true}) was written against Kotak's documentation plus one day's real files, and ships with fallbacks that log what they find rather than refusing to start. On the first trading day with the switch on, read these:
Scrip Master CSV header(tracing, once per file per build) — the header line as the file has it andmissing=[...], the columns the catalog expected and did not find (their fields are left empty: nopDescmeans names are derived from the symbol, nopISINmeans no ISIN search). ThenInstrument catalog segment loadedwithkept,skipped,skip_reasons,unresolved_strikes(options whose symbol agreed with no strike scale) andduplicates; on 2026-11-04's files every segment loaded with nothing missing and nothing unresolved.Kotak quotes: first response shape(tracing, once per process) — the field names of the first REST quotes answer; the parser reads the documented ones (ltp,ohlc,change,per_change,last_volume,oi,year_high/year_low) and a renamed field shows up here as a missing figure.Kotak quotes call failed(warn, the first of a streak) with itsoutcome:Refusedhalves the batch (batch_sizeon the status page) and a key refused on its own is quarantined for ten minutes;RateLimited(a 429) andTransientback off.Close snapshot sweep ...at 15:35 IST:startedwith the key count, thensaved, orcut short/finished with keys unanswered(warn) when the day's close is partial.MEMORY_WARN/MEMORY_WARN_CLEAREDin the dashboard's log terminal — the server's resident memory crossedMEMORY_WARN_MB(default 450 MB), or fell 5% back under it. The pulse (memory_warn,memory_warn_mb) and/api/healthcarry the same.GET /api/v2/instruments/status(admin):catalog.dayshould be today after the 09:05 login,catalog.last_errornull,quotes.calls_per_secat or under 2 while screens are open,quotes.pausednull during hours with a session,quotes.close.partialfalse after 15:40.
The site (for example https://at.axiosiiitl.dev) opens on a sign-in page; nothing else loads, and the server answers nothing but /api/health, /api/version and the sign-in itself, until someone signs in. The redesign (v2) is at /v2/, one address per screen (/v2/desk, /v2/trade, /v2/market, /v2/settings, /v2/admin), and / opens it; the old dashboard (v1) is at /v1/ (/v1/execute, /v1/positions, …). The System screens have no button: open /v2/system or /v1/system (signed in as the admin).
- One way in: a phone number and a WhatsApp code. The server sends a 6-digit code through your WhatsApp server (
WA_SERVER_URL/WA_API_KEY), valid for 10 minutes and for one sign-in. Only numbers on the allow-list (the Admin page) get a code. There is no passkey. - Limits, per number: 3 codes every 10 minutes, 5 guesses a code, and 30 guesses a day across all its codes; past that the number gets no code until the day is up. Per address: 10 sends and 20 guesses every 10 minutes. Anyone who knows the admin's number can use those up — the way back in is
admin-token. - The admin is
ADMIN_PHONE, and nobody else. That number is put on the allow-list as the admin at every start, and any other admin row is made a paper user. The admin's sign-in does everything: LIVE orders, Paper↔LIVE, the kill switch, Kotak and Telegram, settings, the allow-list, clearing the database and updating the server. It lasts 7 days. - Everyone else is a paper trader: charts, the Market page and (once it ships) their own paper portfolio — never the owner's positions, trades, logs or settings, and never a real order.
- v1 at
/v1/opens with the admin's sign-in, made on the main page in the same browser. Without it, v1 shows a link there.
The server also stores the admin's code in a file, so you can still get in when WhatsApp is down:
-
Where:
admin-otp.login the server's working directory. On the VM that is~/auto-trader/backend/admin-otp.log, besidetrades.db. Read it over SSH:cat ~/auto-trader/backend/admin-otp.log # 2026-10-27 18:02:11 IST admin sign-in code 123456 for 75••••xxxx valid once, until 2026-10-27 18:12:11 IST
-
What: only the admin's latest code, in plain text. Users' codes are never written there. Every code, the admin's included, is also kept in
trades.db(tableotp_codes), but only as a keyed hash, so it can't be read back from the database. -
Who can read it: the file is created with mode
600, so only the VM user that runs the server can read it. It is replaced by each new admin code and deleted when the admin signs in. -
When WhatsApp fails or isn't set up, the admin's code still counts: the sign-in page says the code is on the server instead of refusing. A user's code is refused as before.
The admin's code shares its limits with anyone who types the admin's number, so a stranger can burn every code (and the day's 30 guesses) before you get to use one. The server binary can then mint an admin sign-in itself, from a shell on the VM:
cd ~/auto-trader/backend
./server-<version>-x86_64-unknown-linux-gnu admin-token
# eyJhbGciOiJIUzI1NiIs… ← the token (stdout); the line after it says what to doIt reads AUTH_SECRET and ADMIN_PHONE from .env and the admin's row from trades.db in that directory (read only — the running server keeps running), prints a 7-day admin token and exits. On the site, open the browser console and run localStorage.setItem('at_user_token', '<token>'), then reload. Anyone who can run this already has the VM, so it opens nothing new.
The server writes its log to its terminal: on the VM, the tmux pane 0:0 it runs in (see Deployment Guide § 5).
tmux attach -t 0 # watch the live log; detach with Ctrl-b then dDeploys append their output to /tmp/deploy.log on the VM (and show it in the Actions run). The engine's events also reach the dashboard's log terminal and the system_logs table in trades.db. The admin's code is not in any of these logs: they only say Admin sign-in code also written on the server, so the code doesn't travel wherever the log is shipped (Grafana Alloy, for example). Only admin-otp.log holds it.
Kotak session tokens expire daily. The server persists its session (auth
token, sid, base URL) in the kotak_session SQLite table and restores it
automatically at startup if it's still from today — otherwise it needs a
fresh login, which happens one of two ways:
- Manual — log in from the frontend's Kotak login panel (mobile, UCC,
TOTP, MPIN). This is the default if no
KOTAK_*auto-login env vars are set. - Automatic — set
KOTAK_ACCESS_TOKEN/KOTAK_MOBILE_NUMBER/KOTAK_UCC/KOTAK_MPIN/KOTAK_TOTP_SECRET(see Environment Variables) and the server logs in on its own — at startup, at 09:05 IST (pre-warm, so the Scrip Master is loaded before the bell), and again at 09:15 IST if still disconnected. No human action required, including in LIVE mode.
Either way, every step of the login is streamed to the dashboard's log
terminal (KOTAK_LOGIN_START → KOTAK_LOGIN_OK → KOTAK_WS_START →
KOTAK_CONNECTED → SCRIP_FETCH → SCRIP_FETCH_SUCCESS), so you can watch
an unattended login happen. Failures log KOTAK_LOGIN_FAILED in red. Secrets
are never logged — only a masked UCC and whether the TOTP was auto-generated.
Until a session exists, the WebSocket market-data feed will silently fail to connect (the position monitor still works in paper mode using entry_price as the assumed LTP).
On the first run with TELEGRAM_API_ID set, the ingester will prompt you interactively:
Telegram phone number (e.g. +91XXXXXXXXXX): +91XXXXXXXXXX
Login code (sent to your Telegram app): 12345
A session file session.db is created alongside the binary and reused automatically on subsequent runs.
If two-factor authentication is enabled you will also be asked for your 2FA password.
The current implementation stores the Telegram session in session.json in the working directory.
The Telegram parser recognises messages like:
BUY BHEL 425 CE ABOVE 8.25
TARGET :- 9.50 / 11.50
SL :- 5
JULY EXPIRY
| Field | Example | Notes |
|---|---|---|
| Action | BUY / SELL |
Required |
| Instrument | BHEL |
Underlying name |
| Strike | 425 |
Options only |
| Option type | CE / PE |
Options only |
| Entry condition | ABOVE / BELOW |
LTP trigger |
| Entry price | 8.25 |
Trigger price |
| Targets | 9.50 / 11.50 |
/-separated, ordered |
| Stop loss | SL :- 5 |
Initial SL |
| Expiry | JULY EXPIRY |
Optional |
Equity signals (no strike/type) are also supported:
BUY RELIANCE ABOVE 2500
TGT 2600 / 2700
SL 2420
Options calls with an entry range instead of a trigger (BUY only):
BUY NIFTY NEXT WEEK 23000 STRIKE PUTS 140-145 SL 120 TARGET 175
BUY NIFTY NEXT WEEK 23000 STRIKE PUTS @ 125-130 SL 105 TARGET 165
BUY NIFTY 22300 CALLS CMP 100-102 SL 90 TARGET 125
- The engine buys only while LTP is inside the range: below it the call waits for the price to climb in; above it, for a pullback. The entry-window % setting can only narrow the range.
CALL(S)/PUT(S)meanCE/PE;STRIKEand the@/CMP/ATprefix are optional.NEXT WEEK= the weekly expiry falling in next calendar week (Mon–Sun) — NIFTY's Tuesday, SENSEX's Thursday. Other instruments have no weekly series, soNEXT WEEKcalls on them are refused.- A range that is backwards, starts at/below the SL, or reaches target 1 is refused.
- A BUY call that names no instrument (
BUY AGAIN 22300 CALLS CMP 100-102) is ignored — never applied as an SL update to the message it replies to.
Index options only (index_options_only, off by default; PUT /api/v2/flags): when on, only CE/PE calls with a strike on NIFTY, BANKNIFTY, FINNIFTY, MIDCPNIFTY, SENSEX or BANKEX are traded, matched by exact name (NIFTY50 is not NIFTY). Stock options, equity calls and index calls with no strike (BUY NIFTY ABOVE 25000) are skipped and logged as SIGNAL_SKIPPED, from Telegram and from the webhook alike, including edits of such calls. Reply commands and positions already open are unaffected.
When replying directly to an original trade signal message in Telegram, the ingester recognises:
- SL Update: e.g.,
SL to 4.50,Move SL to 4,sl -> 2.5— updates the active stop-loss for the position. - Exit Command: e.g.,
exit at 610,exit @610,exit @ 610,exit 610,exit all at 610— immediately forces the position to exit all remaining quantities at the specified price.
WaitingForEntry ──LTP crosses entry──▶ Active
│
┌── SL hit ────────────┤
▼ ├── Target 1 (full exit) ──▶ Closed
Closed │
▲ └── Target 1 (partial) ──▶ Target1Hit
│ │
└──── SL (trailed) or Target 2 hit ───────────────────┘
On Target1Hit:
- Sells
target_1_exit_pct %of the position - Trails the SL to
(avg_buy_price + target_2) / 2
Both are configured under Settings → Telegram Call Rules and apply in PAPER and LIVE.
-
Call validity (
call_validity_minutes, default 120): a call that has not been bought within this many minutes of arriving is dropped (CALL_EXPIRED). Only unbought calls: an entry already sent to the broker and every open position are untouched. Cancelling a call from the dashboard still works any time.0= off (valid until the 15:39 no-entry cutoff). -
Indicator sizing (
indicator_sizing, off by default): when a call's entry triggers, the engine reads the last closed VWAP + PCR check of its index — the headline badge on the Market Data cards. BANKNIFTY and SENSEX use their own; NIFTY stands in for everything else (FINNIFTY, MIDCPNIFTY, BANKEX, stock options).Indicator vs call Lots bought Strongly agrees: PCR and VWAP both on the call's side (+2 reading + CE, −2 reading +PE)default lots × indicator_strong_agree_multiplier(1.5)Agrees: one of them on the call's side, the other neutral (+1 reading + CE, −1 reading +PE)default lots × indicator_agree_multiplier(1.0)NEUTRAL, or no fresh reading default lots × indicator_neutral_multiplier(0.5)Disagrees none — the call keeps waiting ( INDICATOR_WAIT) or is dropped (INDICATOR_SKIP), see belowLots round to the nearest whole lot with exact halves rounded down, never below 1 (1 lot × 1.5 stays 1 lot; 2 lots × 1.5 → 3). A manual qty override on a position is never scaled, but is still skipped on disagreement. A reading older than its interval + 2 minutes (Upstox down, server just restarted) counts as no fresh reading. The indicator's settings (interval, OI basis, strike range, PCR thresholds, VWAP band) are the same ones the Market Data page scores with. Logic and tests:
backend/shared_domain/src/entry_gate.rs.The multipliers in brackets are the defaults of a new database. A database from before the strong-agree tier keeps its saved
indicator_agree_multiplier(1.5 unless it was changed), so a plain agree keeps buying at that size until it is set to 1 under Settings.Three switches refine it; each can be turned on or off at any time and only matters while indicator sizing is on:
-
Opening checks (
indicator_early_checks, default on): the 09:16 check always counts as NEUTRAL. From 09:22 the latest closed 5-minute check (09:21, 09:26) is used until the first regular check closes (09:31 on 15 / 30 min, 10:01 on 60 min); after that the configured interval takes over. The Market Data cards still show the plain interval reading, so they can differ from the engine before the first regular check; the Settings preview shows what the engine uses. -
Wait on disagreement (
indicator_wait_on_disagree, default on): a call that triggers against the indicator is neither bought nor dropped. It is re-read every tick and bought once the indicator turns neutral or agrees while the price is still in the buy range. It still expires with call validity and the 15:39 cutoff. Off: the call is dropped on the spot. -
Aggressive top-up (
indicator_topup, off by default): a call bought at the reduced NEUTRAL size is topped up if the indicator later agrees while the price is back in the buy range. Which reading does it, and up to which size, is the Top-Up Rule (indicator_topup_mode); sizes are default lots × the multipliers above:Rule Tops up on Up to Top-ups per call strong_to_agree(default)strong agree only the agree size 1 strong_to_strongstrong agree only the strong-agree size 1 tierany agreement that reading's own size 1 stepany agreement that reading's own size, then once more to the strong-agree size when the reading turns strong; a call bought at the agree size steps up too up to 2 With 2 default lots (1 bought at neutral): the default rule adds 1 on a strong agree and holds 2;
strong_to_strongadds 2 and holds 3. Under every rule: only before target 1, while the stop is still at the signal level and the holding is exactly what the last buy left; never past call validity or 15:39; never on a manual qty override. A partly filled top-up ends it, and both steps ofstepshare the three-send cap. Added lots share the position's stop-loss and targets, and the average buy price is re-weighted. The indicator only ever adds: a reading that turns against an open position changes nothing. In LIVE only the broker's filled quantity is added to the holding; a top-up send with no broker verdict is not tracked and is flagged loudly instead, and a top-up that fills after the position was exited is sold straight back (TOPUP_AFTER_EXIT).
-
Whenever a new trade signal arrives for an instrument (e.g., SENSEX 80000 PE), any existing open position for the same underlying instrument in the opposite direction (e.g., an active SENSEX CE position or opposite side equity trade) is automatically exited with the reason Opposite Signal Exit.
Every completed trade records its explicit exit reason (exit_reason column in SQLite) which is displayed in the UI (Trade History & Daily Reports modal):
SL Hit: Initial Stop-Loss triggeredTrailed SL Hit: Trailing Stop-Loss triggered after Target 1Target 1 Hit/Target 2 Hit: Target profit levels reachedClosed via Frontend: Manually closed using the dashboard Close buttonExit via Telegram Msg: Exited via a direct Telegram reply command (e.g.,exit @ 610)Opposite Signal Exit: Automatically closed due to an opposite trade signal arrivingChart Stop Hit/Chart Target Hit: A scalp's stop or target set from the v2 charts was reached (the whole holding is sold)
| Section | URL | Description |
|---|---|---|
| Settings bar | top | Edit brokerage, max trade, targets, PAPER/LIVE toggle. Changes persist to SQLite immediately. |
| P&L chart | middle | Recharts line chart of cumulative realised P&L. |
| Trade table | middle | Full history with gross, charges breakdown, and per-trade P&L. |
| Log terminal | bottom | Live SSE stream of engine events (entry, SL hit, target hit, config changes). |
| Daily Reports | /reports |
Dedicated daily summary grouping trades by calendar date and Telegram signal ID. |
The Daily Reports page provides an aggregated view of trading performance by calendar day (in IST):
- Date-Level Summary: Shows the net realised P&L for each day.
- Signal Grouping: Trades are grouped by their originating Telegram
signal_id, making it easy to track net P&L per strategy or call. Trades without an ID appear under "Legacy Trades". - Trade Details Modal (Info
ibutton): Clicking theibutton next to any signal opens a modal showing:- Original Message: The raw Telegram message text that triggered the trade signal.
- Executions: Itemized BUY/SELL executions with timestamp, executed price, quantity, and net P&L after brokerage and taxes.
| Method | Path | Description |
|---|---|---|
GET |
/api/portfolio |
Wallet balance + last 100 trades |
GET |
/api/settings |
Current TradingConfig as JSON |
GET |
/api/market/indicator |
Last closed VWAP + PCR check per index and the CE / PE sizing verdict a call triggering now would get |
POST |
/api/settings |
Update TradingConfig (persisted to DB + in-memory) |
POST |
/api/webhook/telegram |
Inject a TradeSignal JSON manually (422 for a non-index call while index_options_only is on) |
GET |
/api/logs/stream |
SSE stream of engine log events |
GET |
/api/v2/flags |
v2 switches: {"index_options_only": false, "chart_stops": false, "search": false, "watchlists": false, "stock_charts": false, "stock_paper": false}. search opens the instrument search and quote routes below to anyone signed in; watchlists the watchlist routes; off (the default), they answer 404. stock_charts lets /api/v2/candles*, /api/v2/expiries, /api/v2/chain and /api/execute/stream name any NSE F&O underlying in the catalog, not only the six indices (a stock's ladder never places an order, and POST /api/execute/buy stays index-only). stock_paper lets POST /api/v2/me/buy take an NSE stock's CE/PE onto a user's paper book, beside the six indices' options (the owner's live buy is untouched; a stock option is a 409 while search is off or the catalog isn't built yet, since the catalog names the stock's cash row on the feed). stock_charts, watchlists and stock_paper need search on too: the instrument catalog is built, and the quote hub polled, only while search is on, so with it off a stock is not recognised and nothing polled is priced; a PUT that leaves them inconsistent is saved but logged as FLAGS_INCONSISTENT |
PUT |
/api/v2/flags |
Change only the switches named in the body; saved in their own table, so a v1 settings save never resets them |
PATCH |
/api/v2/positions/:id |
A scalp's chart stop and target: each {price, trigger} with trigger premium (the option's price) or index (its index — a CE's stop fires as the index falls, a PE's as it rises; targets the other way). Left out keeps a level, null clears it. Reaching either sells the whole holding; a level already crossed sells on the next tick (sells_now). New levels need chart_stops on; ones already set stay until the position closes |
GET |
/api/v2/history?range=&group=&mode= |
The v2 Desk's history: trades grouped into calls (one per Telegram call or scalp, with its legs and original message) closed in range (today, 7d default, 30d, all), with KPIs (net, calls, win rate, profit factor, average per call, max drawdown), the cumulative P&L curve, P&L grouped by channel (default), index or cepe, and trading days. A call counts once fully sold, on the day of its last sell. Rows from before channels were stored show as "Unknown channel" |
GET |
/api/execute/stream?index=&expiry=¢re= |
SSE, one frame every 250 ms: every index's spot, index's option ladder for expiry (YYYY-MM-DD, the nearest when left out; an unlisted one is a board error; the board lists expiries) with live prices for the strikes around centre (ATM when left out; the board says the window covered), and the open positions |
POST |
/api/execute/buy |
{trading_symbol, lots}: one tap, a market buy of any listed index option (any strike, any expiry from today) through the engine, or an add to the manual position already on that contract. Refused outside 09:15–15:30 IST, on a stale feed, without a price for the contract in the last 10 s, with the kill switch on, or over 10 lots |
GET |
/api/v2/expiries?index= |
Every expiry the index's options are listed for from today, earliest first, each with its lot size |
GET |
/api/v2/chain?index=&expiry= |
One expiry's strikes (the nearest by default), each side with its trading symbol and delta (Upstox's for the expiry it polls, else an assumed ±0.50) |
GET |
/api/v2/candles?symbol=&tf=&from=&to= |
Chart bars, oldest first. symbol: an index (NIFTY), its nearest future still trading (NIFTY:FUT), a future by its expiry (NIFTY:FUT:2026-11-24, the name the candle archive keeps it under) or an option (NIFTY:2026-10-27:22750:CE); with stock_charts on, also an NSE stock in the catalog and its contracts (RELIANCE, RELIANCE:FUT, RELIANCE:FUT:2026-12-29, RELIANCE:2026-11-24:1400:CE). An index's dated future is accepted whatever stock_charts says. The answer's symbol echoes the canonical name (a dated future keeps its date). A dated future is that contract on Kotak and Upstox, never another month's: a date no future expires on is a 404, like any contract neither broker lists, and one that has expired is a 400. tf: 1m, 5m (default) or 15m; from/to: IST days (default: the last five). Past days come from Upstox; today's are built from live ticks and replaced minute by minute with Upstox's official candles, which carry the volume. polled: true when no Kotak tick builds today's bars (a user's stock chart past the users' ten feed keys, a full ladder budget, or a feed that never ticked): they are Upstox's minutes alone |
GET |
/api/v2/candles/stream?symbols=&tf= |
SSE: every 250 ms, the bars that changed — the forming bar, and a closed bar again when Upstox's official minutes correct it. Up to 6 comma-separated symbols |
GET |
/api/v2/search?q=&limit= |
Behind the search flag, for anyone signed in. Everything q matches in the instrument catalog (every NSE equity and ETF, the six indices, every NSE F&O contract, SENSEX and BANKEX options), grouped indices / stocks / futures / options and ranked (exact symbol or ISIN, symbol prefix, name words, substring; F&O underlyings first), limit rows a group (1–8, default 8). A typed BANKNIFTY 52000 CE, RELIANCE NOV 1400 PE or TATA FUT resolves to the listed contracts; otherwise futures come nearest expiry first and options from the strikes around the spot. Each row carries id (<segment>:<token>), symbol, name, kind (INDEX/EQ/FUT/CE/PE), exchange, expiry, strike, lot_size, tick_size (rupees; the scrip master's paise divided by 100), ws_key and its quote when any source has one (source: live — Kotak's feed or REST quotes, never told apart; upstox while Kotak is down; after hours the 15:35 close, source: close with as_of), else null — every row's key is polled from then on, so asking again in 2 s fills the prices in; a contract is never priced before the poller's first read of it, however it is subscribed. Every figure of a quote is present, null when the source has none. catalog_day says which day's scrip master the catalog was built from |
GET |
/api/v2/quotes?keys= |
Behind the search flag. The quotes for up to 60 comma-separated price-map keys (nse_cm|2885, nse_fo|51386, idx|NIFTY 50; more is a 400), feed first; missing lists known keys no source has yet (polled from now, for 15 s; the hub keeps interest in at most 600 keys, oldest dropped), unknown the keys the catalog has no row for, which are never sent to Kotak |
GET |
/api/v2/instruments/:id |
Behind the search flag. One instrument by its id as the search lists it: symbol, name, exchange, segment and token, ISIN, lot and tick size, expiry and strike, underlying_key (a derivative's spot), nearest_expiry for an F&O underlying, and its quote (LTP, change, open/high/low, previous close, volume, 52-week range) plus the underlying's spot quote. 404 for an id the catalog has no row for; 500 (could not read the instrument catalog) when the catalog database failed |
GET |
/api/v2/watchlists |
Behind the watchlists flag, for anyone signed in — the admin too, with lists of its own: everything here is keyed by the sign-in's user id, and another person's list is a 404. {at, market_open, max_lists: 5, max_items: 50, max_name_chars: 40, watchlists: [{id, name, position, created_at, items: [{key, position, added_at, instrument, quote, age_secs}]}]}, lists and items in order. instrument is the catalog's row for the key, as /api/v2/search lists it (null once the catalog has dropped it — an expired contract); quote as /api/v2/quotes gives it (null until the poller's first read — every key is polled from this call on, so ask again in 2 s); age_secs how old that price is. A first call makes Watchlist 1 with NIFTY, BANKNIFTY and SENSEX (only then is trades.db written; every later call is a plain read). Keys are checked against the catalog, which is built only while search is on; 500 (could not read the instrument catalog) on this and every watchlist route when the catalog database failed, never unknown keys or rows shown as expired |
POST |
/api/v2/watchlists |
{name} (1–40 characters): a new, empty list at the end. 201 with {at, market_open, watchlist}; 409 at five lists |
PATCH |
/api/v2/watchlists/:id |
{name?, position?}: rename and/or move a list to position (0-based; the others shift). {at, market_open, watchlist} |
DELETE |
/api/v2/watchlists/:id |
A list and its items: {deleted: true, id}. 409 for the only list — everyone keeps at least one |
PUT |
/api/v2/watchlists/:id/items |
{keys: [...]}: the whole list, in order — what is left out goes, what is new is added. Keys are price-map keys (nse_cm|2885, nse_fo|51386, idx|NIFTY 50) or catalog ids (nse_cm:2885); either way the row's price-map key is what the list keeps. A key the list already holds (as its key or its id) is kept as it is without asking the catalog, so a list holding an expired contract can still be reordered. More than 50 is a 400; a new key the catalog has no row for is a 400 naming it ({error, unknown: [...]}), and nothing changes. {at, market_open, watchlist} |
POST |
/api/v2/watchlists/:id/items/:key |
One key added at the end (percent-encode the |): 201 when added, 200 when the list held it already, 409 at fifty, 400 for an unknown key. {at, market_open, watchlist} |
DELETE |
/api/v2/watchlists/:id/items/:key |
One key taken out, named by its key or its catalog id — an expired contract too (nse_fo:51386 removes nse_fo|51386); 404 when the list does not hold it. {at, market_open, watchlist} |
GET |
/api/v2/instruments/status |
Behind the search flag, admin only: the catalog's data day, rows per segment and per kind, loading and last_error, and the quote hub's wanted keys, calls_last_minute / calls_per_sec, batch_size, quarantined, refused / rate_limited / errors, paused (why nothing is polled: the switch off, no healthy session, a back-off), last_error, the running sweep and the close on file (day, rows, asked, partial). /api/v2/system carries the totals only |
GET |
/api/v2/me/desk |
A user's own paper Desk, in /api/v2/desk's shape: wallet (₹10,00,000 to start), today's figures, open positions and the calls closed today. /api/v2/me/* is for a user's phone sign-in only (the admin gets 403) |
GET |
/api/v2/me/history?range=&group= · /me/marks · /me/positions · /me/activity |
The user's closed calls (/api/v2/history's shape), today's fills for the charts, open positions, and the last 100 things that happened to them (in memory) |
POST |
/api/v2/me/buy |
{trading_symbol, lots}: a paper buy, filled at once at the live price — the same checks as /api/execute/buy but the kill switch, plus 10 open contracts per user, 40 feed subscriptions across all users (each held contract, plus one cash row per held stock), and no buy of a contract being squared off. The contract is an index option (NIFTY26NOV23000CE), or, with the stock_paper flag on, an NSE stock's CE/PE (RELIANCE26NOV1400CE) whose stock the instrument catalog lists; a future, a stock, an expired or a BSE stock contract, or an option on an index the app only charts (NIFTYNXT50: no feed name, no cash row, nothing for a level to trigger on), is a 400 saying so, and a stock option is a 409 while search is off or the catalog isn't built yet. The fill price is the contract's own feed tick from the last 10 s, never a REST quote. Charges are Kotak's (NSE rates for stocks, BSE for SENSEX/BANKEX) with ₹20 brokerage a leg; the wallet never goes below zero. Answers the fill: {trade_id, position_id, action, contract, index, qty, price, net_value, held, balance, reason}, index being the underlying (RELIANCE) |
POST |
/api/v2/me/positions/:id/sell · /close · /api/v2/me/exit-all |
{lots} / all of one / all of them, at the live price (from the last 10 s), 09:15–15:30 IST. Never more than is held |
PATCH |
/api/v2/me/positions/:id |
Chart stop and target, as /api/v2/positions/:id (not gated by chart_stops); the index trigger watches the underlying — an index option's index, a stock option's own stock price (its cash row joins the feed with the position). Checked every 500 ms; a crossed level sells everything at a fresh price. An expiring position is sold at 15:38 IST on its own expiry day — a stock's monthly, an index's weekly or monthly |
POST |
/api/v2/me/reset |
Start over with ₹10,00,000 and an empty history (only when nothing is open) |
auto-trader/
├── Cargo.toml workspace root
├── backend/
│ ├── shared_domain/ domain types (TradeSignal, TradingConfig, etc.)
│ ├── kotak_client/ Kotak Neo REST + WebSocket client
│ ├── telegram_ingester/ MTProto userbot + regex signal parser
│ ├── trading_engine/ stateful OMS + fee calculator
│ └── server/ Axum HTTP server + SQLite writer
├── frontend/ Vite + React 19 + Tailwind v4 dashboard
└── kotak-api-docs/ local copy of official Kotak API docs
All paper trades compute Kotak Neo charges automatically:
| Charge | Rule |
|---|---|
| Brokerage | Flat ₹20 per leg (configurable) |
| SEBI fee | 0.0001% of turnover |
| Exchange transaction charge | Options: 0.03503% of premium (NSE), 0.0325% (BSE: SENSEX, BANKEX) · Equity: 0.00297% (NSE), 0.00375% (BSE) |
| STT (options) | 0.15% of premium, SELL side only (since 1 April 2026) |
| STT (equity intraday) | 0.025% on SELL side only |
| Stamp duty | 0.003% on BUY side only |
| GST | 18% × (brokerage + SEBI + exchange charge) |