arimanyus / warrenduffer

# Warren Duffer
Single Node process: broker REST client (Kotak Neo or Zerodha Kite), Jev (TypeSafe AI via Vercel AI Gateway) as a two-stage ranker over Nifty-50 names, live MIS orders, SQLite audit log, terminal-style dashboard on `127.0.0.1:8080`. Jev classifies, ranks, and decides take-profit. Code sizes, places the stop, and enforces the loss halt.
**Risk warning.** This software places real orders with real money through your broker account. There is no paper-trading mode. It is experimental, provided "as is" under the MIT license with no warranty, and is not investment advice. Automated intraday trading can lose money quickly. You are responsible for every order it sends, your broker's API terms, and the SEBI rules that apply to you. Start with `LIVE_QTY=1`. Not affiliated with Kotak Securities, Zerodha, Vercel or TypeSafe.
## Architecture
`src/kotak` and `src/zerodha` are the broker clients. `src/data` is quotes, bars, and the universe. `src/model` is Jev. `src/strategy` is rank, exits, and the governor. `src/executor` places and polls orders. `src/replay` is the virtual-clock sim. `src/{broker,config,costs,symbols,limiter,risk,db,server}.ts` is the shared core. `web/` is the dashboard. `scripts/` is probe, calibrate, replay, report, gates, smoke, and the Zerodha login step. `risk.json` holds model thresholds and exit tuning.
## Brokers
| | Kotak Neo | Zerodha Kite Connect |
|---|---|---|
| `BROKER` | `kotak` (default) | `zerodha` |
| Login | Automatic TOTP + MPIN at start, once more on expiry | Manual daily `pnpm zerodha:login` (Kite forbids automated login) |
| Session expiry | Re-logins once | ~06:00 IST daily; engine halts entries, alerts, needs new token + restart |
| Market data | Included | Needs Kite Connect market-data access |
| 1-min history (warm-up, calibrate, replay fetch) | Included | Needs historical-data add-on; minute data capped at 60 days → keep `WARMUP_DAYS` ≤ 60 |
| Order tags | As-is | Sanitised to ≤20 alphanumerics (`sl-12` → `SL12`) |
| Brokerage in PnL | Statutory only (matches a ₹0-brokerage plan) | Statutory only; Kite intraday brokerage is **not** deducted |
| Status | Verified live | Written against Kite v3 docs, not yet verified live: run `pnpm probe`, then `LIVE_QTY=1` |
Kotak: Trade API access token, mobile with `+91`, UCC, MPIN, base32 TOTP secret.
Zerodha:
1. Create an app on the Kite developer console; set redirect URL (e.g. `http://127.0.0.1/`).
2. Put `ZERODHA_API_KEY`, `ZERODHA_API_SECRET` in `.env`, `BROKER=zerodha`.
3. Each trading day: `pnpm zerodha:login` → open URL → log in → copy `request_token` from the redirect URL.
4. `pnpm zerodha:login `.
5. Paste `ZERODHA_ACCESS_TOKEN` into `.env`.
6. `pnpm start` (or restart the service).
`ZERODHA_REQUEST_TOKEN` is a one-shot alternative (single-use, minutes). `ZERODHA_ACCESS_TOKEN` wins if both are set. Zerodha auto-squares-off MIS near 15:20 for a fee — keep `FLATTEN_AT` earlier (default 15:10). Brokers may require API order traffic from a registered sta