Privacy Model

TraderTape is a SaaS product that handles real money. Privacy is not optional. This document explains exactly what the cloud sees, what stays on your device, and the design choices that produce that split.

The high-order question

"Why would I trust a cloud service with my trading data?"

You shouldn't, if the answer requires unconditional trust. The TraderTape design makes trust selective: you decide which data goes where, and the architecture enforces those choices.

There are two user classes:

The Default class is what new users get. Your broker API secret never touches our servers.

How browser thin client login works (Default class)

The broker login modal has a checkbox: "Save secret to cloud for one-click login". For Default-class users, this is disabled — visible but greyed out, with a tooltip explaining that cloud storage requires admin/family approval.

So every login works like this:

1. You click the broker icon in the top-right toolbar and select Login
2. The singleton broker login modal opens (fast-path: if only one broker is configured, you skip the picker)
3. You paste your api_secret into the login form (your password manager autofills it)
4. A new tab opens to your broker's OAuth page; you complete MFA normally
5. When the broker redirects back, your browser computes SHA256(api_key + request_token + api_secret) locally using the Web Crypto API
6. Only the resulting one-way checksum is sent to our server
7. Our server forwards the checksum to your broker's token endpoint
8. The broker validates the checksum and returns an access_token
9. We store the access_token (~14 hours, revocable) so the scanner, dashboard, and /api/v1/* endpoints can read your account
10. Your api_secret is immediately wiped from React state

Your API secret never crosses the network. The SHA-256 checksum is useless without the single-use request_token (which expires in ~60 seconds). Even if our server were compromised, an attacker could not derive your secret from the checksum.

This works for Zerodha Kite and Groww (both use checksum-based auth). For Upstox, the API secret passes through our server once during the code exchange (Upstox's API requires it as a POST field), but is never stored. For ICICI Direct, the secret is always cloud-stored — their API requires a per-call checksum that can only be computed server-side — so ICICI users are always in the Admin/Family class for that broker.

Your password manager can save the API secret field so you don't have to paste it daily. In practice the daily ritual is: click broker icon → Login → password manager autofills → Enter → done. ~5 seconds.

The save-to-cloud toggle

For Admin/Family class users, the "Save secret to cloud" checkbox is enabled. When checked:

• After your next successful login, TraderTape POSTs the api_secret to /api/auth/kite-credentials (or the equivalent endpoint for non-Kite brokers)
• The secret is encrypted at rest using Fernet + a server-side key
• Future logins are one-click — the cloud re-uses the stored secret to do the OAuth exchange server-side

To switch back from "saved on cloud" to browser-only: uncheck the box and click Update in Settings, or uncheck the box during your next login. TraderTape sends clear_secret: true which removes the stored secret from the database.

This toggle is gated at the server via the allow_cloud_credentials permission. A non-admin user who tries to POST an api_secret will get a 403.

What's in the cloud database, always

These things are in the cloud no matter which class you pick:

• Email address (required for magic link login)
• Strategies (the DSL definitions you create or fork)
• Backtest results (computed from public market data)
• Signals (generated by the cloud scanner running your strategies)
• Audit log (every action you take in the system)
• Public market data (candles, instruments, NAVs -- shared across all users)

None of these reveal your identity beyond your email. None of them contain account-specific financial data unless you upload tradebook data.

What's in the cloud with your consent

• Broker api_key -- saved when you configure a broker in Settings. The api_key is not a secret -- it identifies your broker app but can't authenticate without the secret.

• Active broker session token -- present after a successful login. Lasts ~14 hours then expires. This lets the scanner, dashboard, and Telegram bot access your broker account without you having a browser tab open.

• Tradebook data -- uploaded via Settings. Stored as-is unless you use the local agent with obfuscation enabled.

• Broker snapshots -- holdings, positions, and margins fetched periodically (every 15 minutes during market hours) and stored for use when your session expires.

What never goes to the cloud (Default class)

• Your broker api_secret -- stays in your browser and password manager
• Your broker login password and OTP -- entered on the broker's own login page, never on ours

Multi-broker support

TraderTape supports three Indian brokers:

All three work via Browser Login. Your dashboard shows per-broker tabs so you can view holdings, positions, and orders from each broker separately.

Execution and SEBI compliance

All cloud-driven execution uses GTT (Good-Till-Triggered) orders only. GTT placement is exempt from SEBI's static-IP check because the actual order execution happens from the broker's infrastructure, not from the user's or our IP.

This means:

• You don't need a static IP to trade via TraderTape
• You can place GTTs from any device, any network
• Immediate market orders (/orders/regular) are not supported through the cloud -- they require a static IP per SEBI rules

Admin/Family accounts (Class 0) can place immediate market orders because SEBI permits IP sharing within family units and the admin's static IP is registered with the broker.

Admin/Family class (Class 0)

Admin users and family members explicitly approved by the admin can store their api_secret on the cloud (encrypted at rest with Fernet). This enables:

• Cloud-driven OAuth login (no need to paste the secret each time)
• Immediate market order placement from the cloud's IP
• Full automation without a browser tab open

This mode requires the admin to grant allow_cloud_credentials to the user.

The local agent (optional, advanced)

The local agent is a Python daemon that runs on your machine. It's not required for most users -- Browser Login handles everything. The agent is useful for:

• Trade data obfuscation -- the agent multiplies all numeric values by a secret factor before uploading tradebooks, so the cloud only sees scaled-down patterns
• Headless/24-7 operation -- runs without a browser tab open
• SEBI-compliant immediate orders -- orders leave from your machine's IP

If you don't need any of these, you don't need the agent.

What the admin can see

The cloud admin has direct database access. From the admin's perspective:

• Always visible: all users' emails, strategies, backtest results, signals, audit logs
• Visible only with consent: uploaded tradebook data, broker snapshots
• Never visible for Default users: the broker API secret (it never reaches the cloud)
• Visible for Admin/Family users: encrypted api_secret blobs (decryptable with the cloud's encryption key)

Authentication tokens

Your TraderTape session cookie:

• Name: tt_session
• Value: UUID, generated server-side
• TTL: 7 days (configurable)
• Flags: HttpOnly, Secure, SameSite=Lax

HttpOnly means JavaScript can't read the cookie (prevents XSS exfiltration). Secure means HTTPS-only. SameSite=Lax blocks most CSRF attacks.

Next

• Brokers -- connecting and managing broker accounts
• Local Agent -- the optional privacy/automation upgrade
• Architecture -- system components and data flow