Local Agent (Optional)

Most users don't need the agent. Browser Login now supports all three brokers (Kite, Upstox, Groww) directly — your API secret stays in your browser, no install required. The agent is for users who want one of the three specific features below.

The local agent is a Python program that runs on your machine. It's an optional power-user tool, not the default connection method.

When you need it

1. Trade data obfuscation. The agent multiplies all quantities by a secret factor before uploading tradebooks, so the cloud only sees scaled-down patterns. Without the agent, uploaded data is cleartext.
2. Headless / 24-7 operation. The agent runs as a daemon — no browser tab needed. Useful for VPS, Raspberry Pi, or always-on setups.
3. SEBI-compliant immediate orders. If you need to place immediate market orders (not GTTs) with your own static IP registered with the broker, the agent is the only path. Browser Login places orders via the cloud's IP, which won't match your SEBI registration.

If none of these apply, use Browser Login instead.

What it is

tradertape-agent is a small Flask backend + React/Vite frontend packaged as a Python wheel. It:

• Listens on 0.0.0.0:5679 (reachable from your phone on the LAN)
• Authenticates to your broker on your machine
• Polls the cloud every ~30 seconds for new signals to execute
• Reports holdings, positions, and margins to the cloud (optionally obfuscated)
• Reconciles cloud-side expectations against broker reality
• Exposes a mobile-friendly UI for portfolio viewing and settings

Installation

The agent is published on PyPI as tradertape-agent. Install it via pip with the appropriate broker extras:

# Bare install — Upstox + Groww only
pip install tradertape-agent

# With Kite support (adds the kiteconnect dependency)
pip install tradertape-agent[kite]

# Everything
pip install tradertape-agent[all]

The bare install is intentionally minimal — no kiteconnect dependency, smaller attack surface, faster install. Add [kite] if you want Kite support, [all] if you want flexibility.

The package targets Python 3.10+. On macOS, the system Python works; on Linux, install Python via your package manager (apt install python3-pip); on Windows, install from python.org.

After install, tradertape-agent is available as a CLI command:

$ tradertape-agent --help
Usage: tradertape-agent [COMMAND]

Commands:
  configure    Interactive setup wizard
  run          Run the agent (default if no command given)
  reset        Wipe local config and start over
  status       Print current status

First-run configuration

Before running the agent for the first time, you need:

1. A TraderTape account (with at least one model portfolio, otherwise the agent has nothing to do)
2. An agent API key from TraderTape Settings → Trading Agent → Generate Key
3. Your broker api_key and api_secret from the broker's developer console

Run the configure wizard:

tradertape-agent configure

You'll be prompted for:

Cloud URL [https://tradertape.com]: 
Agent API key (zt_...): zt_abc123...
Primary broker (kite/upstox/groww) [kite]: kite
Kite API key: xxx
Kite API secret: yyy
Auto-execute signals (y/N): n
Stop loss percent [5]: 5
Poll interval seconds [30]: 30

Settings are written to ~/.tradertape-agent.json (chmod 600). The agent reads this file at startup.

You can run configure again at any time to update settings, or edit the JSON directly:

{
  "cloud_url": "https://tradertape.com",
  "api_key": "zt_abc123...",
  "primary_broker": "kite",
  "kite_api_key": "xxx",
  "kite_api_secret": "yyy",
  "upstox_api_key": "",
  "upstox_api_secret": "",
  "groww_api_key": "",
  "groww_api_secret": "",
  "auto_execute": false,
  "stop_loss_pct": 5,
  "poll_interval": 30
}

Running

tradertape-agent

Output:

[agent] Starting tradertape-agent v0.5.2
[agent] Cloud URL: https://tradertape.com
[agent] Primary broker: kite
[agent] Loaded brokers: kite, upstox
[agent] Listening on http://0.0.0.0:5679
[agent] Health: cloud=ok broker=ok poll=30s

The agent serves a UI at http://localhost:5679. Open it in a browser. You'll see:

• Dashboard — consolidated portfolio across all configured brokers
• Signals — pending signals from the cloud, with approve/reject buttons
• Holdings / Positions — broker-side data
• Mutual Funds — if you've uploaded CAS PDFs
• Brokers — login status for each configured broker
• Settings — agent config, including auto-execute toggle and broker credentials
• Uploads — upload tradebooks/ledgers locally; the agent obfuscates them and forwards to the cloud

The agent UI is mobile-responsive — open http://your-machine.local:5679 from your phone on the same WiFi. There's no authentication on the local UI by default (it's bound to your local network), so don't expose it to the public internet.

Auto-execute mode

By default the agent runs in manual approval mode: signals from the cloud appear in the agent UI's signal list, you tap Approve, and the order goes to the broker. This is the safest mode and the recommended starting point.

When you trust the strategy, switch to auto-execute in Settings. New signals are placed immediately without prompting. You'll get a Telegram notification (if configured) on every fill so you're not blind.

Auto-execute respects the strategy's risk rules: if a signal would breach a daily loss limit, sector cap, or position count, it's rejected with the reason logged.

Multi-broker setup

To run with multiple brokers, just configure all of them in ~/.tradertape-agent.json. The agent loads every broker that has both <broker>_api_key and <broker>_api_secret set.

The primary broker is the one that executes signals. The others are read-only — their holdings/positions show up in the consolidated view, but no orders go to them.

{
  "primary_broker": "kite",
  "kite_api_key": "...",
  "kite_api_secret": "...",
  "upstox_api_key": "...",
  "upstox_api_secret": "...",
  "groww_api_key": "...",
  "groww_api_secret": "..."
}

To switch primary brokers, edit the file and restart the agent. (No hot-reload — the broker connection is established at startup.)

How signals get to the agent

The agent polls GET /api/agent/pending-signals every poll_interval seconds. The cloud returns any signals belonging to portfolios owned by the agent's user that are in in_cart status with auto_place_signals = true (or signals you've manually approved through the agent UI).

For each signal, the agent:

1. Maps the symbol to the broker's instrument format (Kite: NSE:RELIANCE, Upstox: NSE_EQ|INE002A01018, Groww: same as Kite)
2. Computes the order price using the strategy's entry buffer
3. Places the GTT or order via the broker's API
4. Reports the result back to the cloud (POST /api/agent/signal-result)
5. The cloud updates the signal's gtt_status and the position's entry_order_id

For exits, the same flow runs in reverse: the cloud generates an exit signal, the agent places a SELL GTT, and on fill, the agent reports the close back to the cloud.

Reconciliation

Every poll cycle, the agent fetches your real holdings from the broker and compares them to the cloud's expectation:

For each holding:
    cloud_qty = sum of open ModelPositions for this symbol
    broker_qty = actual broker holding
    if cloud_qty != broker_qty:
        flag drift

Drift can come from:

• Manual orders placed outside TraderTape (you bought RELIANCE manually on Kite directly)
• Failed orders the cloud thought were filled
• Filled orders the cloud thought were rejected
• Stock splits / corporate actions not yet reflected in the cloud

Drift is not automatically corrected. The agent flags it and shows a warning in the UI. You manually decide what to do — usually either adjust the cloud's position record or place a corrective order.

See Reconciliation for the full story.

Privacy and obfuscation

If you have upload obfuscation enabled in your TraderTape account, the agent automatically scales numeric values in tradebook/ledger uploads before sending them to the cloud:

• A factor like 0.137 is generated once per user and stored on the agent only
• Quantity, price, and amount fields in tradebook XLSX files are multiplied by this factor
• The cloud sees scaled-down quantities (e.g. 137 instead of 1000), but the relative magnitudes are preserved
• Strategy logic and pattern analysis still work on the obfuscated data

When you view the dashboard from the cloud, the cloud shows the obfuscated numbers — that's all it has. When you view from the agent's local UI, the agent un-scales them on display so you see real values.

This is the two-persona model: SaaS users keep real numbers private even from the cloud's database admin. See Privacy Model for the details.

Running the agent as a service

For production use, you want the agent to start at boot and respawn on crash.

macOS (launchd)

~/Library/LaunchAgents/com.tradertape.agent.plist:

<?xml version="1.0" encoding="UTF-8"?>
<plist version="1.0">
<dict>
    <key>Label</key><string>com.tradertape.agent</string>
    <key>ProgramArguments</key>
    <array>
        <string>/usr/local/bin/tradertape-agent</string>
    </array>
    <key>RunAtLoad</key><true/>
    <key>KeepAlive</key><true/>
    <key>StandardOutPath</key><string>/Users/you/Library/Logs/tradertape-agent.log</string>
    <key>StandardErrorPath</key><string>/Users/you/Library/Logs/tradertape-agent.err</string>
</dict>
</plist>

launchctl load ~/Library/LaunchAgents/com.tradertape.agent.plist
launchctl list | grep tradertape

Linux (systemd)

/etc/systemd/system/tradertape-agent.service:

[Unit]
Description=TraderTape Agent
After=network.target

[Service]
Type=simple
User=you
ExecStart=/usr/local/bin/tradertape-agent
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target

sudo systemctl enable --now tradertape-agent
sudo systemctl status tradertape-agent

Windows

Use NSSM or the built-in Task Scheduler to run tradertape-agent at boot. Windows isn't a primary target — Linux/macOS are recommended.

Troubleshooting

"Cloud authentication failed"

Your agent API key is wrong, expired, or revoked. Regenerate from TraderTape Settings → Trading Agent → Regenerate Key, then run tradertape-agent configure again.

"Broker not connected"

The agent successfully started but can't talk to the broker. Common causes:

• Kite token expired — open the agent UI, go to Brokers → Kite → Login. The agent opens a browser tab for OAuth.
• Upstox refresh token expired — same flow as Kite
• Groww credentials changed — re-run configure to update them

"Signals not appearing in the agent"

Check the cloud side first:

• The portfolio is active, not paused
• The portfolio has auto_place_signals = true OR you've manually moved signals to in-cart
• The portfolio's user_id matches the agent's user (i.e. you're using the right agent API key)

Then check the agent:

• Is it polling? Look for [agent] poll: 0 new signals lines in the log
• Is the cloud URL correct? tradertape-agent status prints it
• Is the network reachable? curl https://tradertape.com/api/auth/me from the agent host

"Agent UI is slow / unresponsive"

The agent serves data from the broker on every page load. If your broker is rate-limiting (Kite has 3 req/s), the UI feels slow. The agent caches results for 5–10 seconds to mitigate this, but during heavy use you'll see it.

"Reconciliation always shows drift"

If you have any positions on the broker that aren't in TraderTape (e.g. you bought stocks manually before installing TraderTape), they'll always show as drift. Either:

• Import them: upload your tradebook files via the agent's Uploads page
• Suppress them: there's a per-symbol "ignore for reconciliation" toggle in the agent settings

"Auto-execute placed an order I didn't want"

Check the strategy's entry conditions. Auto-execute only fires when the strategy generates a signal — it never places trades on its own. Common cause: a strategy with very loose conditions firing on noisy data.

The fix is on the strategy, not the agent. Disable auto-execute, tighten the strategy, re-enable when confident.

Updates

pip install --upgrade tradertape-agent[all]

The agent doesn't auto-update. Check the version in TraderTape Settings → Trading Agent → Latest version banner periodically. Major releases are announced via the in-app changelog.

Source code

The agent lives at tools/agent-desktop/ in the main TraderTape repo. It's MIT-licensed and contributions are welcome. The README in that folder has dev setup instructions.

Next

• Brokers — broker comparison and connection paths
• Connect a Broker quickstart — short-form setup
• Reconciliation — full drift detection story
• Privacy Model — what stays where