ThetaPrime Request a license
Browse docs
Getting StartedInstallation GuideSetup GuideObtaining API Credentials
BrokersKite (Zerodha) SetupBreeze (ICICI Direct) SetupDhan Setup
Building StrategiesStrategy Composer GuideComposer Strategy Examples
OperationsStrategy Configuration & UsageOption ScannerData SourcesData ManagementMCP Setup (AI Assistant Tools)
Security & LicensingSecurityLicense & Activation
Docs / Setup Guide

Setup Guide

ThetaPrime opens as its own app window (Start Menu shortcut, or the tray icon once it's already running) — not a browser tab. The backend service starts the scheduler automatically on launch, so it's running even if the window itself is closed to the tray.

Dashboard Login

The dashboard is protected by a password on first run.

  1. Open ThetaPrime.
  2. You will be prompted to Set Dashboard Password — choose a password of at least 8 characters and click Set Password. This is stored securely in the OS keychain.
  3. On subsequent visits, enter your password at the login prompt.

After 3 wrong attempts, the source IP is locked out for 5 minutes.

To log out, click the ⏻ button in the top-right of the navigation bar.

First-Run Setup Wizard

On a fresh install (no broker credentials saved yet), logging in redirects you to /onboarding — a short welcome screen linking to license status and the Auth page. The Auth page shows a "Setup" banner with a Continue → button while onboarding is incomplete; it leads to a final step offering to run a paper simulation on yesterday's data. You can click Skip setup at any point to dismiss the wizard permanently and go straight to the dashboard — it will not reappear once dismissed or completed.

First-Time API Credentials

Before running any strategy you need credentials from the broker(s) you plan to use. Each broker has its own dedicated setup page with exact steps:

  • Kite (Zerodha) — the default broker.

  • Breeze (ICICI Direct) — recommended for multi-day historical simulations.

  • Dhan — automatic OAuth-style login via an API Key (like Kite/Breeze), or manual token paste as a fallback. Static IP whitelisting is mandatory, not just recommended.

Once you have credentials, enter them on the Auth page (top navigation bar). They are saved securely via the OS keychain — you will not need to re-enter them, only refresh the daily token as described on each broker's page.

SEBI's API trading rules require a fixed IP address for order placement on every broker this app supports. Ask your ISP for a static IP add-on before creating any broker API app, and register that IP with the broker alongside any redirect URL. A dynamic IP that later changes will stop matching what's registered and silently break live order placement until it's updated.

Enabling/Disabling a Broker

Each broker's card on the Auth page has a switch in its header. Turning it off dims that card (your saved credentials and token are untouched — this only hides the broker, it doesn't log it out) and removes its badge from the top-right navbar. Use this to declutter the navbar when you only trade through one or two of your configured brokers. All brokers are enabled by default.

Daily Login — Refreshing the Access Token

Every broker's access token expires and needs refreshing before the next trading day (exact expiry and refresh steps are on each broker's page — Kite, Breeze, Dhan). In general:

  1. Open the app and click Auth in the top navigation bar.
  2. Complete that broker's login/token-refresh step.
  3. The badge in the top-right navbar for that broker changes from ✕ (red) to ✓ (green).

All scheduled and manual strategy runs pick up the stored token automatically.

If a badge stays red after a login attempt, see API Contract Check below — the token may have been rejected rather than lost.

Verifying the Connection

On the Auth page, each broker's card has a Test Connection button (named per broker, e.g. Test Session for Kite). This calls a simple profile/ connection API with your stored credentials and confirms the token is valid before the market opens.

API Contract Check

Every time you log in to any broker, the app doesn't just save the new token — it first calls the same read-only endpoints your strategies rely on day-to-day (margins, positions, and order history) and checks they actually respond correctly. This catches a broken or changed broker API before the market opens, instead of a strategy discovering it mid-run.

  • If all checks pass: the token is saved as normal and the badge turns green.
  • If any check fails: the token is not saved — login effectively did not happen — and the Auth page shows an error naming exactly which check failed and which feature it would have broken (e.g. position sizing, reconciliation, order retry after a network drop).

This is expected behavior, not a bug: it means the broker API isn't answering correctly for your account right now, and the app is refusing to run on an untested connection rather than fail silently later. If you see this:

  1. Confirm the broker's site/app isn't reporting an outage.
  2. Re-check your credentials are still valid and try logging in again.
  3. Check the App Event Log (Reports page) for the specific error message behind the failed check.

Notification Setup (Optional)

ThetaPrime can send alerts for trade events (entries, exits, adjustments) via email, Telegram, and/or a custom webhook. All channels you configure fire together for every alert — they aren't exclusive, so e.g. email + Telegram both configured means both fire.

  1. Click Auth in the navigation bar.
  2. Scroll to the Notifications card.
  3. Toggle notifications On.
  4. Fill in the Email section:
Field Example
SMTP Host smtp.gmail.com
Port 587
Username youraddress@gmail.com
Password (App Password — see below)
From address youraddress@gmail.com
Send alerts to youraddress@gmail.com
  1. Click Save Email Config, then Send Test to verify delivery.

Gmail users — App Password required

Google blocks SMTP access with your normal Google account password since 2022. You must use an App Password instead:

  1. Go to your Google Account → Security.
  2. Under "How you sign in to Google", click 2-Step Verification (must be enabled).
  3. Scroll to the bottom and click App passwords.
  4. Choose App: Mail / Device: Windows Computer. Click Generate.
  5. Copy the 16-character password shown and paste it into the Password field in ThetaPrime.

Telegram

ThetaPrime can send alerts directly to a Telegram chat — no bridge process required.

  1. Message @BotFather on Telegram, send /newbot, and follow the prompts to name your bot. BotFather replies with a bot token (looks like 123456789:AAF...) and your bot's link, t.me/YourBotName.
  2. Open t.me/YourBotName and send it any message (or press Start). This step is easy to miss but required — Telegram bots are not allowed to message a user first; the user has to message the bot at least once before it can reply. Skipping this causes the send to fail later with "chat not found" even though everything else is configured correctly.
  3. Message @userinfobot to get your numeric chat ID.
  4. In the Notifications card, toggle Notifications on, then fill in Bot Token and Chat ID under the Telegram section and click Save.
  5. Click Send Test. Check your chat with the bot for the test message.

Troubleshooting:

Symptom Cause
✗ No channel delivered (check config) The Notifications toggle at the top of the card is off — turn it on, no channel is even attempted while it's off.
Telegram's own Send Test fails with a 404 from api.telegram.org The Bot Token field has a literal bot pasted in front of the token (e.g. bot123456:AAF... instead of 123456:AAF...) — the app already adds that prefix when calling the API, so a token that includes it gets sent twice. Re-paste just the token BotFather gave you, nothing before the digits.
Telegram's own Send Test fails, no message arrives You haven't messaged your bot yet (step 2 above) — bots can't initiate a chat. Message the bot, then Send Test again.
Still nothing after messaging the bot Double-check the chat ID is your ID from @userinfobot, not the bot's own ID, and that the bot token was pasted in full.
Telegram fails but Send Test on it still shows ✓ Fixed 2026-08-12 — each channel's Send Test now checks only that channel, so a working webhook/email no longer masks a broken Telegram token.

Custom notification webhook (advanced)

If you use a different notification bot (WhatsApp, Slack, a custom integration), you can configure a webhook endpoint that ThetaPrime will call with each alert:

  1. Expand Advanced: custom notification webhook in the Notifications card.
  2. Enter the URL of your bot's HTTP endpoint (e.g. http://localhost:3001/send).
  3. ThetaPrime will POST { "message": "..." } to this URL for every alert.

What triggers a notification

Once the Notifications toggle is on, an alert fires automatically — no per-strategy setup needed — for:

  • Entry / short re-entry — strikes, prices, and capital deployed
  • Exit / short exit — P&L in points and ₹
  • Full-day sim complete — net P&L and entry/SL-hit counts
  • Skip — a strategy's filter blocked entry, with the reason
  • Adjustment / adjustment failed — leg roll details, or a warning if a roll failed and the position may be one-legged
  • Broker token not refreshed — checked once each trading morning at 08:45 IST; fires only if a broker with an enabled real-money strategy still has yesterday's (or no) session token, so you can re-login before it would have blocked an entry

An identical message repeated within 10 minutes is suppressed (this protects against a broker session issue re-firing the same alert on every poll) — distinct messages always go through.

Frequently Asked Questions

Does my computer need to stay on during the trading day? Yes. ThetaPrime runs as a Windows service on your own PC, not in any cloud — it can only enter, monitor, and exit positions while that machine is powered on and the service is running. A laptop that sleeps or shuts down stops managing your open trades until it's back.

What happens if my internet connection drops? ThetaPrime needs a live connection to your broker for as long as a position is open — entries, monitoring, and exits all depend on it. Brief blips are retried automatically: read-only broker calls (quotes, LTP, historical data, order status, etc.) get up to 2 retries with a 0.5s then 1.5s delay before giving up — 3 attempts total, roughly 2 seconds end to end. This applies only to idempotent (read-only) calls; order placement is never blind-retried, to avoid risking a duplicate leg. Five consecutive failures raise a "broker degraded" alert in the app event log. A sustained outage beyond that window means it can't act on your positions until connectivity returns, the same as if you were watching a terminal yourself. A stable, always-on connection is part of the setup, not optional.

Do I need a static IP address? Yes — see First-Time API Credentials above. SEBI's API trading rules require a fixed IP for order placement, registered with your broker. Ask your ISP for a static IP add-on before setting up any broker's API app. Dhan enforces this server-side — a stale IP silently blocks order placement while quotes/margins keep working, so it's the easiest one to miss.

Applies to ThetaPrime v0.35.4 · Page last updated 2026-08-23