{"id":50459887,"url":"https://github.com/jpramirez/trade-kit","last_synced_at":"2026-06-01T04:04:03.869Z","repository":{"id":360189095,"uuid":"1239223732","full_name":"jpramirez/trade-kit","owner":"jpramirez","description":"Open-source CLI trading toolkit for Tiger Brokers and Moomoo. Go binaries, paper mode, JSON config, no dependencies.","archived":false,"fork":false,"pushed_at":"2026-05-25T10:42:54.000Z","size":5022,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-25T12:27:03.814Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jpramirez.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-14T22:11:59.000Z","updated_at":"2026-05-25T10:42:55.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/jpramirez/trade-kit","commit_stats":null,"previous_names":["jpramirez/trade-kit"],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/jpramirez/trade-kit","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jpramirez%2Ftrade-kit","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jpramirez%2Ftrade-kit/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jpramirez%2Ftrade-kit/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jpramirez%2Ftrade-kit/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jpramirez","download_url":"https://codeload.github.com/jpramirez/trade-kit/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jpramirez%2Ftrade-kit/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33759204,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-01T02:00:06.963Z","response_time":115,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-06-01T04:03:57.021Z","updated_at":"2026-06-01T04:04:03.857Z","avatar_url":"https://github.com/jpramirez.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# trade-kit\n\n**The open-source CLI trading toolkit for Tiger Brokers and Moomoo.**\n\nZero dependencies. Paper mode by default. Go binaries — download and run.\n\nBuilt for retail traders in Singapore, Hong Kong, and the US who want to automate their workflow without writing code.\n\n\u003e ⚠️ See [DISCLAIMER.md](DISCLAIMER.md) — this is not financial advice.\n\n---\n\n## Tools\n\n| Tool | Binary | What it does |\n|---|---|---|\n| [tiger](#1-tiger-cli) | `tiger-cli` | Tiger Brokers — positions, quotes, orders, analysis |\n| [moomoo](#2-moomoo-cli) | `moomoo-cli` | Moomoo/Futu — same interface, pure Go TCP client |\n| [scheduler](#3-scheduler) | `scheduler` | Order queue daemon — fire orders at market windows |\n| [daytrader](#4-daytrader-bot) | `daytrader-bot` | Gap-up scanner — finds gap plays at pre-market open |\n| [earnings](#5-earnings-bot) | `earnings-bot` | Earnings scanner — buys pre-announcement run-up |\n| [bounce](#6-bounce-bot) | `bounce-bot` | RSI oversold bounce — buys dips with volume confirmation |\n| [index](#7-index-trader) | `index-trader` | Index momentum — QQQ/VIX signals for TQQQ/SQQQ |\n| [controller](#8-controller) | `controller` | Portfolio risk manager — circuit breaker, NAV, signal gate |\n\nJump to: [Setup](#setup) · [Workflows](#workflow-playbooks) · [Signal bus](#the-signal-bus) · [Troubleshooting](#troubleshooting)\n\n---\n\n## Setup\n\n### Build from source\n\nRequires Go 1.21+.\n\n```bash\ngit clone https://github.com/jpramirez/trade-kit\ncd trade-kit\n\n# Build a single tool\ncd tiger \u0026\u0026 go build -o tiger-cli ./cmd/\n\n# Or build everything at once\nfor d in tiger moomoo scheduler daytrader earnings bounce controller index; do\n  (cd $d \u0026\u0026 go build -o ../${d} ./cmd/)\ndone\n```\n\n### Tiger credentials\n\n1. Apply for Tiger Open API access at [openapi.tigersecurities.com](https://openapi.tigersecurities.com)\n2. Download your RSA key pair from the developer portal\n3. Create `~/.trade-kit/tiger/.env`:\n\n```env\nTIGER_ID=\u003cyour tiger developer ID\u003e\nPRIVATE_KEY=\u003cbase64-encoded PKCS8 RSA private key\u003e\nTRADE_PASSWORD=\u003cyour 6-digit trade PIN\u003e\n```\n\n4. Test connection:\n\n```bash\n./tiger-cli positions       # paper mode — safe, reads only\n./tiger-cli --live positions  # your real account\n```\n\n### Moomoo credentials\n\n1. Download and start [Futu OpenD](https://www.futunn.com/download/OpenD) — it runs as a local daemon on port 11111\n2. Create `~/.trade-kit/moomoo/.env`:\n\n```env\nMOOMOO_HOST=127.0.0.1\nMOOMOO_PORT=11111\nTRADE_PASSWORD=\u003cyour 6-digit trade PIN\u003e\nACC_ID=\u003cyour account ID\u003e\n```\n\n3. Start OpenD, then test:\n\n```bash\nfutu-opend \u0026              # start OpenD in background\n./moomoo-cli positions    # paper mode\n```\n\n---\n\n## Paper · Semi · Live\n\nEvery write command has three modes. Paper is always the default.\n\n| Mode | Flag | What happens |\n|---|---|---|\n| Paper | (default) | Prints what would happen — nothing sent to broker |\n| Live | `--live` | Sends to broker after you type `Y` to confirm |\n| Semi (bots only) | `--semi` | Bot prompts you before each trade signal |\n\n```bash\n./tiger-cli buy AAPL 10              # paper — safe, no order sent\n./tiger-cli --live buy AAPL 10       # live — prompts: Execute? [y/N]\n./daytrader-bot --semi run           # bot asks before each trade\n./daytrader-bot --live run           # bot auto-executes every signal\n```\n\n---\n\n## 1. tiger-cli\n\nThe Tiger Brokers command-line client. Reads positions, quotes, and orders. Places buy/sell/stop/modify orders. Runs technical analysis.\n\n### Quick start\n\n```bash\n./tiger-cli positions                 # see open positions\n./tiger-cli quote AAPL                # live price\n./tiger-cli orders                    # open orders\n./tiger-cli analyze AAPL              # multi-timeframe TA\n```\n\n### Read commands\n\nThese are always safe — no orders placed.\n\n#### `positions`\nList open stock positions.\n\n```bash\n./tiger-cli positions\n./tiger-cli --json positions          # JSON output for scripting\n```\n\nOutput: symbol, shares, avg cost, market price, market value, unrealised P\u0026L, realised P\u0026L.\n\n#### `account`\nCash, buying power, and net liquidation value.\n\n```bash\n./tiger-cli account\n```\n\n#### `quote \u003cSYMBOL\u003e`\nReal-time price snapshot.\n\n```bash\n./tiger-cli quote AAPL\n./tiger-cli quote ES3.SI              # Singapore-listed stock\n./tiger-cli --json quote NVDA\n```\n\nOutput: price, change%, open, high, low, volume, previous close.\n\n#### `orders`\nAll open and pending orders.\n\n```bash\n./tiger-cli orders\n./tiger-cli --json orders\n```\n\nOutput: order ID, symbol, action, type, qty, filled, limit, stop, TIF, status.\n\n#### `analyze \u003cSYMBOL\u003e [--futures]`\nMulti-timeframe technical analysis: RSI, MACD, Bollinger Bands, EMA across 1D / 1H / 15m.\n\n```bash\n./tiger-cli analyze AAPL              # US stock\n./tiger-cli analyze ES3.SI            # Singapore stock\n./tiger-cli analyze MNQ --futures     # Micro E-mini Nasdaq futures\n./tiger-cli --json analyze AAPL       # machine-readable output\n```\n\nOutput per timeframe:\n- RSI(14) — overbought \u003e 70, oversold \u003c 30\n- MACD line, signal, histogram\n- Bollinger %B (position within the bands)\n- EMA 20 / 50 / 200 and price relationship\n- Bias score: **BULLISH** / **NEUTRAL** / **BEARISH**\n\nOverall: bull count, bear count, alignment (**BULLISH** / **MIXED** / **BEARISH**).\n\n\u003e **Note:** RSI \u003e 70 and %B \u003e 1.0 are scored as overextension, not strength. This reflects mean-reversion risk at extremes.\n\n#### `markov \u003cSYMBOL\u003e`\nMarkov regime model — tomorrow's state probabilities based on two years of daily returns.\n\n```bash\n./tiger-cli markov NVDA\n./tiger-cli markov ES3.SI\n./tiger-cli --json markov AAPL\n```\n\nOutput:\n- Current state: **BULL** / **SIDE** / **BEAR** (based on trailing 20-day return, ±5% thresholds)\n- Historical distribution of days in each state\n- 3×3 transition matrix (sticky states highlighted where P(self) \u003e 50%)\n- Forecasts at 1d / 5d / 10d via matrix exponentiation\n- Signal: direction + confidence (HIGH / MEDIUM / LOW), P(bull) − P(bear)\n\n### Write commands\n\nThese require `--live` for real execution. Paper mode logs the action only.\n\n#### `buy \u003cSYMBOL\u003e \u003cSHARES\u003e [--limit \u003cprice\u003e] [--stop \u003cprice\u003e] [--target \u003cprice\u003e]`\n\n```bash\n./tiger-cli --live buy AAPL 10                            # market buy\n./tiger-cli --live buy AAPL 10 --limit 180.00             # limit buy\n./tiger-cli --live buy AAPL 10 --limit 180 --stop 174     # buy + stop-loss\n./tiger-cli --live buy AAPL 10 --limit 180 --stop 174 --target 198\n```\n\n- Market buy: DAY order, fills at best available price\n- Limit buy: fills at your price or better (DAY)\n- `--stop`: places a separate GTC stop-loss order after the entry fills\n- `--target`: places a separate GTC take-profit limit order after entry fills\n\n#### `sell \u003cSYMBOL\u003e \u003cSHARES\u003e [--limit \u003cprice\u003e]`\n\n```bash\n./tiger-cli --live sell AAPL 10                           # market sell\n./tiger-cli --live sell AAPL 10 --limit 195.00            # limit sell (GTC)\n```\n\nLimit sell stays open until filled or you cancel it.\n\n#### `stop \u003cSYMBOL\u003e \u003cSHARES\u003e --price \u003cprice\u003e`\nPlace a GTC stop-loss on an existing position.\n\n```bash\n./tiger-cli --live stop AAPL 100 --price 174.00\n```\n\n#### `target \u003cSYMBOL\u003e \u003cSHARES\u003e --price \u003cprice\u003e`\nPlace a GTC take-profit limit on an existing position.\n\n```bash\n./tiger-cli --live target AAPL 100 --price 198.00\n```\n\n#### `cancel \u003cORDER_ID\u003e`\n\n```bash\n./tiger-cli --live cancel 43116645746347008\n```\n\n#### `modify \u003cORDER_ID\u003e [--limit \u003cp\u003e] [--stop \u003cp\u003e] [--qty \u003cn\u003e] [--tif DAY|GTC]`\nModify an open order in-place (no cancel + re-enter).\n\n```bash\n./tiger-cli --live modify 43116645746347008 --limit 182.00\n./tiger-cli --live modify 43116645746347008 --stop 176.00 --qty 8\n```\n\nRequires at least one of: `--limit`, `--stop`, `--qty`, `--tif`.\n\n### Futures commands\n\nFor micro futures: MES (Micro E-mini S\u0026P 500), MNQ (Micro E-mini Nasdaq), M2K (Micro Russell 2000).\n\n```bash\n# Enter long MES at 5100, protective stop at 5090\n./tiger-cli --live futures entry MES long 1 --entry 5100 --stop 5090\n\n# Enter short MNQ at 16500, stop at 16600\n./tiger-cli --live futures entry MNQ short 2 --entry 16500 --stop 16600\n\n# Market-close an open position\n./tiger-cli --live futures close MES long 1\n\n# Trail the stop — cancel old, place new\n./tiger-cli --live futures update-stop MES long 1 --stop 5095 --old-id 789012\n```\n\n`futures entry` always places the protective stop immediately after the entry. If the stop order fails, an emergency market close fires automatically.\n\n### Playbook: Morning check ritual\n\nRun this every morning before the open to see where you stand:\n\n```bash\n./tiger-cli account            # buying power available\n./tiger-cli positions          # what you're holding\n./tiger-cli orders             # any open limits/stops\n./tiger-cli analyze AAPL       # quick TA on a position\n```\n\n---\n\n## 2. moomoo-cli\n\nSame command interface as tiger-cli. Uses the Futu OpenD TCP protocol — no Python, no bridge.\n\nFutu OpenD must be running before any order commands.\n\n### Symbol format\n\nAuto-detected from the ticker pattern:\n\n| Input | Interpreted as |\n|---|---|\n| `AAPL` | `US.AAPL` |\n| `Z74`, `D05` | `SG.Z74`, `SG.D05` (alpha + 2 digits) |\n| `558`, `1810` | `SG.558`, `HK.1810` |\n| `HK.00700` | `HK.00700` (explicit prefix) |\n\n### Commands (identical to tiger-cli)\n\n```bash\n./moomoo-cli positions\n./moomoo-cli account\n./moomoo-cli quote Z74\n./moomoo-cli orders\n\n./moomoo-cli --live buy Z74 100 --limit 4.50 --stop 4.20\n./moomoo-cli --live sell Z74 100 --limit 4.80\n./moomoo-cli --live stop Z74 100 --price 4.20\n./moomoo-cli --live cancel FS1C71DE6D05BA1000\n./moomoo-cli --live modify FS1C71DE6D05BA1000 --limit 4.60\n```\n\n### Playbook: SGX dividend stock management\n\n```bash\n# Check your Singapore blue-chip positions\n./moomoo-cli positions\n./moomoo-cli quote Z74         # Singtel\n./moomoo-cli quote D05         # DBS Bank\n\n# Add a trailing stop after a 5% gain\n./moomoo-cli --live stop Z74 1000 --price 4.30\n\n# Take partial profit\n./moomoo-cli --live sell Z74 500 --limit 4.90\n```\n\n---\n\n## 3. scheduler\n\nA persistent order queue. You add orders at any time (even when the market is closed), and the daemon fires them automatically when the target market window opens.\n\nMarket windows:\n\n| Window | Time | Use case |\n|---|---|---|\n| `next_open` | 9:30 AM ET / 21:30 SGT | Default — regular open |\n| `pre_market` | 4:00 AM ET / 16:00 SGT | Pre-market executions |\n| `pre_open` | 9:20 AM ET / 21:20 SGT | 10 min before open |\n| `morning` | 7:00 AM SGT / 23:00 UTC | SGT morning scan trigger |\n| `now` | Immediate | Next daemon tick |\n\n### Add orders to the queue\n\n```bash\n# Basic buy/sell (defaults to next_open)\nscheduler add buy AAPL 10\nscheduler add sell AAPL 5\nscheduler add buy SCHD 4 --limit 31.65\n\n# Specify window\nscheduler add --at pre_market sell QUBT 15\nscheduler add --at next_open buy SCHD 4 --limit 31.65 --note \"dividend reinvestment\"\n\n# Stop-loss and take-profit\nscheduler add stop EXTR 9 --price 23.50\nscheduler add target NVDA 5 --price 160.00\n\n# Modify or cancel an existing Tiger order\nscheduler add modify 43116645746347008 --stop 23.50\nscheduler add modify 43116645746347008 --limit 155.00 --qty 50\nscheduler add cancel 43116645746347008\n\n# Run a shell command at market open\nscheduler add exec \"./daytrader-bot scan\"\nscheduler add --at pre_open exec \"./daytrader-bot scan\"\n\n# Re-queue the same command every day (--daily)\nscheduler add --at pre_open exec \"./daytrader-bot --live scan\" --daily\n```\n\n### Manage the queue\n\n```bash\nscheduler list             # show all pending and completed orders\nscheduler ls               # alias for list\n\nscheduler cancel a3f2b1    # remove a pending order by its 8-character ID\nscheduler clear            # cancel all pending orders at once\n```\n\n### Start the daemon\n\nThe daemon checks every 30 seconds and fires any due orders.\n\n```bash\nscheduler daemon \u0026                         # background\nscheduler daemon --log ~/scheduler.log \u0026   # with log file\n\n# Check it's running\ntail -f ~/scheduler.log\n```\n\nThe daemon re-reads the queue file on every tick, so orders added after it starts are picked up automatically. You don't need to restart it.\n\n### Time header\n\nEvery `scheduler` command (except `daemon`) prints a time header:\n\n```\n  Mon 25 May 21:32:14 SGT  |  09:32:14 ET  |  🟢 market open  →  market close in 6h 27m\n```\n\n### Playbook: Night-before queue\n\nYou're in Singapore and want to set up orders before you go to sleep:\n\n```bash\n# Queue tonight's orders (it's 11 PM SGT, US market opens in 10 hours)\nscheduler add buy SCHD 4 --limit 31.65 --note \"weekly buy\"\nscheduler add sell QUBT 15 --note \"take profit\"\nscheduler add modify 43116645746347008 --stop 23.50 --note \"trail stop\"\n\n# Start the daemon (if not already running)\nscheduler daemon --log ~/scheduler.log \u0026\n\n# Confirm what's queued\nscheduler list\n\n# Go to sleep — daemon fires at 9:30 AM ET / 9:30 PM SGT\n```\n\n### Playbook: Automate daily scans\n\nRun the gap scanner every day at pre-open (9:20 AM ET) automatically:\n\n```bash\n# Queue a daily exec order — re-queues itself after each run\nscheduler add --at pre_open exec \"./daytrader-bot scan\" --daily\n\n# Start the daemon\nscheduler daemon --log ~/scheduler.log \u0026\n```\n\n---\n\n## 4. daytrader-bot\n\nGap-up day trade scanner. Scans your watchlist for stocks gapping 3–20% at the open with above-normal volume (RVOL \u003e 1.5). Enters on the first pullback, exits hard by 11:00 AM ET.\n\n### Config — `daytrader.json`\n\n```json\n{\n  \"gap_min_pct\": 3.0,\n  \"gap_max_pct\": 20.0,\n  \"stop_pct\": 2.0,\n  \"rr_min\": 3.0,\n  \"budget\": 200.0,\n  \"min_adv\": 500000,\n  \"scan_interval_sec\": 60,\n  \"watchlist\": [\"LUNR\", \"RKLB\", \"ASTS\", \"KTOS\", \"IONQ\", \"RDW\", \"QQQ\"]\n}\n```\n\n| Field | What it controls |\n|---|---|\n| `gap_min_pct` | Minimum gap% to qualify (3% default) |\n| `gap_max_pct` | Maximum gap% — filters runaway movers (20% default) |\n| `stop_pct` | Stop-loss placed this % below entry (2% default) |\n| `rr_min` | Skip if risk/reward ratio is below this (3.0 = 3:1) |\n| `budget` | Max capital per trade in USD |\n| `min_adv` | Minimum average daily volume to avoid illiquid stocks |\n| `scan_interval_sec` | How often to re-scan during `run` mode (60s) |\n| `watchlist` | Symbols to watch — add anything you follow |\n\n### Commands\n\n#### `scan`\nOne-time scan — prints signals, no action.\n\n```bash\n./daytrader-bot scan\n./daytrader-bot --paper scan     # explicit paper (same as default)\n./daytrader-bot --earnings scan  # use earnings watchlist + tighter params\n```\n\nOutput for each symbol:\n- `▶ LONG` — setup found: gap%, qty, entry price, stop, target\n- `◎ WATCH` — interesting but criteria not fully met (shows reason)\n- `—` — no setup, skipped\n\n#### `run`\nContinuous scan + execute loop. Runs until you stop it.\n\n```bash\n./daytrader-bot run              # paper (safe)\n./daytrader-bot --semi run       # prompts before each trade\n./daytrader-bot --live run       # auto-executes\n```\n\nWhat it does every tick:\n1. Fetches price, gap%, and RVOL for each symbol in watchlist\n2. Generates entry signals for qualifying setups\n3. Checks pending signals: skips if price has drifted \u003e2% from signal\n4. Places buy limit + immediate stop-loss (live/semi only)\n5. At `exit_by_min` (11:00 AM ET): market-sells all open positions\n\n#### `monitor`\nPrint current signal bus state — useful in a second terminal while `run` is looping.\n\n```bash\n./daytrader-bot monitor\n```\n\n#### `status`\nPrint open trades and closed P\u0026L.\n\n```bash\n./daytrader-bot status\n```\n\n#### `close \u003cSYMBOL\u003e`\nManually exit a position at market.\n\n```bash\n./daytrader-bot close LUNR\n```\n\n### Earnings mode\n\nAdds today's earnings stocks to the watchlist (from `earnings.json`), tightens the RVOL filter, and allows shorts on gap-down:\n\n```bash\n./daytrader-bot --earnings scan\n./daytrader-bot --earnings --live run\n```\n\nEarnings mode params:\n- `gap_min_pct`: 5% (bigger gap required)\n- `stop_pct`: 3% (tighter stop)\n- `rvol_min`: 2.0x (higher volume bar)\n- Exit by: 10:30 AM ET instead of 11:00 AM ET\n- Shorts allowed on gap-down earnings misses\n\n### Playbook: Pre-market gap trade\n\n```bash\n# 9:15 AM ET — pre-market, run a scan to see what's gapping\n./daytrader-bot scan\n\n# Found LUNR gapping +8.3% with RVOL 3.2x — looks good\n# 9:30 AM ET — market opens, run in semi mode to approve each trade\n./daytrader-bot --semi run\n\n# Bot prompts: \"LUNR: BUY 5 @ limit $35.50, stop $34.79? [y/N]\"\n# Type y — order placed\n# Position closes automatically by 11:00 AM ET\n```\n\n---\n\n## 5. earnings-bot\n\nEarnings momentum scanner. Buys N days before an earnings announcement to capture the pre-announcement run-up. Sells on the day of earnings (before the report) to avoid event risk.\n\n### Config — `earnings.json`\n\n```json\n{\n  \"days_before\": 3,\n  \"stop_pct\": 5.0,\n  \"budget\": 200.0,\n  \"min_adv\": 500000,\n  \"min_price\": 3.0,\n  \"max_run_pct\": 20.0,\n  \"scan_interval_sec\": 300,\n  \"watchlist\": [\"NVDA\", \"LUNR\", \"RKLB\", \"OKLO\"],\n  \"earnings_dates\": {\n    \"LUNR\": \"2026-05-14\",\n    \"NVDA\": \"2026-05-20\"\n  }\n}\n```\n\n| Field | What it controls |\n|---|---|\n| `days_before` | Buy this many days before earnings date (3 default) |\n| `stop_pct` | Stop-loss % below entry (5% default) |\n| `max_run_pct` | Skip if stock already ran \u003e20% into earnings |\n| `budget` | Max capital per trade |\n| `earnings_dates` | Override or add earnings dates (format: YYYY-MM-DD) |\n\nKeep `earnings_dates` updated — the bot will not enter a trade for a symbol without a date.\n\n### Commands\n\n#### `scan`\nEvaluate watchlist and print signals.\n\n```bash\n./earnings-bot scan\n```\n\nOutput per symbol:\n- `▶ ENTER` — N days before earnings, setup met: qty, entry, stop\n- `◀ EXIT` — earnings day, sell now: position summary\n- `◎ WATCH` — upcoming but criteria not met (too early, already ran)\n- `—` — no earnings date, or not applicable\n\n#### `run`\nContinuous scan + execute loop.\n\n```bash\n./earnings-bot run\n./earnings-bot --semi run\n./earnings-bot --live run\n```\n\nLogic per tick:\n1. Scan every `scan_interval_sec` (5 min default)\n2. Generate ENTER signals when `N days_before` an earnings date\n3. Generate EXIT signals on the earnings date itself\n4. Execute fresh ENTER signals (checks drift \u003c3% and no existing position)\n5. Execute EXIT signals (sells at market)\n\n#### `monitor` / `status` / `close`\nSame as daytrader-bot:\n\n```bash\n./earnings-bot monitor        # signal bus\n./earnings-bot status         # trade store + P\u0026L\n./earnings-bot close NVDA     # manual exit\n```\n\n### Playbook: Pre-earnings momentum trade\n\n```bash\n# Check what's coming up\n./earnings-bot scan\n\n# NVDA reports in 3 days — ENTER signal generated\n# Run in semi mode (you confirm each entry)\n./earnings-bot --semi run\n\n# Bot: \"NVDA: BUY 2 @ limit $882.50, stop $838.38? [y/N]\"\n# Type y\n\n# Three days later — earnings day, EXIT signal fires automatically\n# Bot sells before the report to avoid event risk\n```\n\n---\n\n## 6. bounce-bot\n\nRSI oversold bounce scanner. Buys when a stock's RSI drops below 20 with above-normal volume — a setup that historically reverts to the mean. Exits when RSI recovers to 50, or after 5 trading days, or at the stop-loss.\n\n### Config — `bounce.json`\n\n```json\n{\n  \"rsi_entry\": 20.0,\n  \"rsi_exit\": 50.0,\n  \"stop_pct\": 5.0,\n  \"max_hold_days\": 5,\n  \"budget\": 150.0,\n  \"min_adv\": 500000,\n  \"min_price\": 3.0,\n  \"scan_interval_sec\": 300,\n  \"watchlist\": [\"RKLB\", \"LUNR\", \"ASTS\", \"IONQ\", \"KTOS\", \"RDW\"]\n}\n```\n\n| Field | What it controls |\n|---|---|\n| `rsi_entry` | Enter when RSI drops below this (20 default — deep oversold) |\n| `rsi_exit` | Exit when RSI recovers above this (50 default — neutral) |\n| `stop_pct` | Hard stop-loss below entry |\n| `max_hold_days` | Force-close after this many trading days |\n| `budget` | Max capital per trade |\n\n### Commands\n\n#### `scan`\nOne-time RSI scan.\n\n```bash\n./bounce-bot scan\n```\n\nOutput: `▶ ENTER` with RSI value, qty, entry, stop — or `—` (not oversold enough).\n\n#### `run`\nContinuous scan, execute, and monitor exits.\n\n```bash\n./bounce-bot run\n./bounce-bot --semi run\n./bounce-bot --live run\n```\n\nExit logic (checked every tick):\n- RSI \u003e 50: take profit, close position\n- Stop hit: loss limited\n- 5 trading days elapsed: time exit\n\n#### `monitor` / `status` / `close`\n\n```bash\n./bounce-bot monitor\n./bounce-bot status\n./bounce-bot close LUNR\n```\n\n### Playbook: Catching a dip\n\n```bash\n# Scan for oversold setups in your watchlist\n./bounce-bot scan\n\n# RKLB RSI = 17.3, RVOL 2.1x — ENTER signal\n# ASTS RSI = 22.1 — not oversold enough (above threshold of 20)\n\n# Run in semi mode and approve the RKLB entry\n./bounce-bot --semi run\n\n# Bot will auto-exit when RSI recovers to 50 (usually 1–3 days)\n# Or stops you out at -5% if the dip continues\n```\n\n---\n\n## 7. index-trader\n\nQQQ/VIX momentum signal generator. Monitors QQQ direction and VIX level every 30 seconds. Generates **LONG TQQQ** or **SHORT SQQQ** signals based on index momentum. Exits automatically at target (+6%), stop (-5%), or hard EOD (12:30 PM ET default).\n\nThis is a scalp tool — it trades 3x leveraged ETFs intraday and closes the same session.\n\n### Config — `index.json`\n\n```json\n{\n  \"qqq_long_threshold\": 0.3,\n  \"qqq_short_threshold\": -0.3,\n  \"vix_max\": 25.0,\n  \"vix_spike_min\": 20.0,\n  \"budget\": 200.0,\n  \"tqqq_shares\": 2,\n  \"sqqq_shares\": 4,\n  \"stop_pct\": 5.0,\n  \"target_pct\": 6.0,\n  \"grace_period_min\": 10,\n  \"exit_by_min\": 750,\n  \"scan_interval_sec\": 30\n}\n```\n\n| Field | What it controls |\n|---|---|\n| `qqq_long_threshold` | QQQ must be up \u003e0.3% to signal LONG TQQQ |\n| `qqq_short_threshold` | QQQ must be down \u003e0.3% to signal SHORT SQQQ |\n| `vix_max` | Skip all trades if VIX is above this (too volatile) |\n| `tqqq_shares` | Shares to buy when going long |\n| `sqqq_shares` | Shares to buy when going short (inverse, so more shares) |\n| `stop_pct` | Hard stop: 5% below entry |\n| `target_pct` | Take profit: 6% above entry |\n| `grace_period_min` | No trades in first N minutes (default: first 10 min after open) |\n| `exit_by_min` | Hard EOD exit time in minutes since midnight (750 = 12:30 PM ET) |\n\n### Modes\n\n```bash\n./index-trader -mode watch      # observe signals, no action (default)\n./index-trader -mode semi       # confirm before trade (10s timeout)\n./index-trader -mode live       # auto-execute via tiger-cli\n```\n\n### Signal logic (every 30 seconds)\n\n1. Fetch QQQ and VIX prices via Yahoo Finance\n2. Skip if: pre-market, after 12:30 PM ET, VIX ≥ 25, in grace period (first 10 min)\n3. If QQQ \u003e +0.3% → signal: **BUY TQQQ**\n4. If QQQ \u003c -0.3% → signal: **BUY SQQQ**\n5. If in position: check stop/target on every tick, print live P\u0026L\n6. Exit: when stop/target hit, or hard exit at 12:30 PM ET\n\n### Playbook: Index scalp session\n\n```bash\n# 9:15 AM ET — fire up the watcher\n./index-trader -mode watch\n\n# 9:30 AM ET — market opens, grace period starts (no trades for 10 min)\n# Output: [09:30:14] QQQ +0.21% | VIX 18.3 | 🟡 grace period (8m left)\n\n# 9:40 AM ET — grace period ends\n# Output: [09:40:14] QQQ +0.44% | VIX 17.8 | → LONG signal: BUY 2 TQQQ @ $82.50\n\n# Switch to semi when you've watched enough patterns\n./index-trader -mode semi\n\n# Auto-exits at target +6% or stop -5%, latest 12:30 PM ET\n```\n\n### Tips\n\n- Watch in `watch` mode for several sessions before going semi or live\n- Raise `vix_max` threshold if you want to trade in choppier markets\n- Lower `grace_period_min` to 5 on trend days, raise to 20 on gap-and-crap days\n- `tqqq_shares` and `sqqq_shares` control position size — start small\n\n---\n\n## 8. controller\n\nThe portfolio risk manager. Does not place orders — it monitors your positions and signals, enforces risk limits, and gives you a single dashboard view before you make any decision.\n\nRun `controller status` before every session.\n\n### Config — `controller.json`\n\n```json\n{\n  \"t1_symbols\": [\"Z74\", \"ES3\", \"D05\", \"O39\", \"SGOV\"],\n  \"position_max_pct\": 30.0,\n  \"cash_reserve_pct\": 15.0,\n  \"max_positions\": 6,\n  \"circuit_breaker_alert_pct\": 10.0,\n  \"circuit_breaker_estop_pct\": 15.0,\n  \"rr_min_swing\": 3.0,\n  \"rr_min_scalp\": 2.0\n}\n```\n\n| Field | What it controls |\n|---|---|\n| `t1_symbols` | Your \"Track 1\" stable/dividend stocks (blue-chips, ETFs) |\n| `position_max_pct` | No single position can exceed this % of NAV (30%) |\n| `cash_reserve_pct` | Always keep at least this % in cash (15%) |\n| `max_positions` | Max concurrent open positions (6) |\n| `circuit_breaker_alert_pct` | Alert when session drawdown exceeds this (10%) |\n| `circuit_breaker_estop_pct` | Emergency stop threshold (15%) |\n| `rr_min_swing` | Minimum R:R for swing signals (earnings, bounce) |\n| `rr_min_scalp` | Minimum R:R for scalp signals (daytrader, index) |\n\n### Commands\n\n#### `status`\nFull portfolio dashboard. Run this every morning.\n\n```bash\n./controller status\n```\n\nThe dashboard shows ten panels:\n\n1. **NAV TRAJECTORY** — Today's drawdown vs circuit breaker thresholds  \n   `✅ OK` / `🔴 ALERT –10%` / `🚨 ESTOP –15%`\n\n2. **PLAYBOOK GATE** — Can you open a new trade right now?  \n   Shows: position count vs max, cash reserve %, max position size, max next-trade capital\n\n3. **SIGNAL EXPIRY** — Pending signals with countdown bars  \n   `💀 expired` / `🔴 \u003c 2 hours` / `🟡 \u003c 24 hours`\n\n4. **PATTERN** — Market activity classification  \n   `A ⚡` 3+ strategies firing (capital-constrained, prioritise by R:R)  \n   `B 💤` No signals (cash is a position)  \n   `C 🎯` Single signal (cleanest case, full focus)\n\n5. **POSITIONS** — T1 (stable/dividend) and T2 (tactical) split\n\n6. **TRACK 2 CAPITAL** — Deployment view: estimated T2 cash vs deployed\n\n7. **OPEN ORDERS** — All pending stops and limit orders\n\n8. **SIGNAL BUS** — All bot signals: pending, active, filled, expired  \n   Each shows R:R check (`⚠️` if below minimum, `✅` if OK)\n\n9. **BOOTSTRAP FILLED** — Recent profits with the 40/60 reinvestment split\n\n10. **DAILY LOG** — Written to `logs/daily-YYYY-MM-DD.json`\n\n#### `gate [cost]`\nQuick pre-flight check before opening a trade.\n\n```bash\n./controller gate         # just show limits\n./controller gate 200     # check if a $200 trade is allowed right now\n```\n\nBlocks if any of these are true:\n- Already at max positions (6)\n- Trade would exceed 30% of NAV\n- Cash reserve would drop below 15%\n\n#### `monitor`\nSignal bus detail — sorted by status, newest first.\n\n```bash\n./controller monitor\n```\n\nUseful while bots are running — shows every pending/active/filled signal with R:R, expiry countdown, and notes.\n\n#### `bootstrap \u003cprofit\u003e`\nCalculate how to split a closed profit (40% to savings, 60% reinvested).\n\n```bash\n./controller bootstrap 500\n```\n\nOutput:\n```\nNet profit:        $500.00\n40% → savings:     $200.00\n60% → reinvest:    $300.00\n   T1 (dividend):  $150.00\n   T2 (tactical):  $150.00\n```\n\n#### `estop`\n**Emergency stop.** Cancels all open orders and market-sells all positions.\n\n```bash\n./controller estop\n```\n\nYou must type `CONFIRM` to proceed. Use this only in a crisis (flash crash, rogue daemon, unexpected news).\n\n### Playbook: Morning risk review\n\n```bash\n# 9:00 AM ET — before anything else\n./controller status\n\n# Check the gate before entering any trade\n./controller gate 200\n\n# If gate is GREEN and pattern is C (single signal), proceed\n# If gate is RED (at max positions), don't open anything\n\n# End of day — log the session\n./controller status    # writes to logs/daily-YYYY-MM-DD.json\n```\n\n### Playbook: Circuit breaker protocol\n\n```bash\n./controller status\n# Panel 1 shows: 🔴 ALERT — NAV drawdown –10.5%\n\n# Alert level: stop opening new positions\n# Review all pending signals\n./controller monitor\n\n# If it hits –15%\n./controller status\n# Panel 1 shows: 🚨 ESTOP — NAV drawdown –15.2%\n\n# Emergency stop\n./controller estop\n# Type CONFIRM\n```\n\n---\n\n## Workflow playbooks\n\n### Playbook: Full morning routine (SGT)\n\nThis is the complete morning-before-open routine. Takes about 5 minutes.\n\n```bash\n# 9:00 PM SGT (9:00 AM ET, 30 min before open)\n\n# 1. Check your P\u0026L and account\n./tiger-cli account\n./tiger-cli positions\n./tiger-cli orders\n\n# 2. Run portfolio risk check\n./controller status\n\n# 3. Scan for setups\n./daytrader-bot scan        # gap plays (reads Yahoo Finance)\n./bounce-bot scan           # RSI oversold setups\n./earnings-bot scan         # pre-earnings entries (if any due)\n\n# 4. Check the gate before acting on any signal\n./controller gate 200\n\n# 5. Open your chosen mode in a dedicated terminal\n./daytrader-bot --semi run  # opens at 9:30 ET, prompts before each trade\n```\n\n### Playbook: Set it and sleep (automated)\n\nQueue tonight's orders and let the daemon handle everything.\n\n```bash\n# 10:00 PM SGT (night before)\n\n# Queue orders\nscheduler add buy SCHD 4 --limit 31.65\nscheduler add sell QUBT 10\n\n# Set up daily pre-market scan (runs every day until you cancel it)\nscheduler add --at pre_open exec \"./daytrader-bot scan\" --daily\nscheduler add --at next_open exec \"./daytrader-bot --live run\" --daily\n\n# Start daemon (if not already running)\nscheduler daemon --log ~/scheduler.log \u0026\n\n# Confirm everything is queued correctly\nscheduler list\n\n# Go to sleep — daemon fires at 9:30 PM SGT (9:30 AM ET)\n```\n\n### Playbook: Multi-bot session\n\nRunning multiple strategies simultaneously with the controller watching over all of them.\n\n```bash\n# Terminal 1 — controller dashboard (refresh manually)\nwatch -n 30 ./controller status\n\n# Terminal 2 — gap plays\n./daytrader-bot --live run\n\n# Terminal 3 — RSI bounces\n./bounce-bot --live run\n\n# Terminal 4 — index scalp (watch mode first, go semi after 30 min)\n./index-trader -mode watch\n\n# Terminal 5 — scheduler daemon (fires any queued orders)\nscheduler daemon --log ~/scheduler.log\n```\n\n### Playbook: Earnings week\n\nSet up for a week with heavy earnings reports:\n\n```bash\n# 1. Update earnings dates\n# Edit earnings/earnings.json → add this week's reporters\n{\n  \"earnings_dates\": {\n    \"NVDA\": \"2026-05-20\",\n    \"RKLB\": \"2026-05-19\",\n    \"OKLO\": \"2026-05-18\"\n  }\n}\n\n# 2. Run earnings scan + daytrader scan together (earnings adds to daytrader watchlist)\n./earnings-bot scan\n./daytrader-bot --earnings scan\n\n# 3. Run both bots in semi mode during the session\n./earnings-bot --semi run \u0026\n./daytrader-bot --earnings --semi run \u0026\n\n# 4. Monitor signals\n./controller monitor\n```\n\n---\n\n## The signal bus\n\nAll scanner bots share a single `signals.json` file in the working directory. This is how the bots and controller communicate.\n\n```\ndaytrader-bot  ─┐\nearnings-bot   ─┼──→  signals.json  ←── controller monitors\nbounce-bot     ─┘\n```\n\n**A signal** is a trade candidate written by a bot. It contains:\n\n```json\n{\n  \"id\": \"c08af385\",\n  \"symbol\": \"LUNR\",\n  \"strategy\": \"earnings\",\n  \"action\": \"enter\",\n  \"entry_limit\": 34.20,\n  \"stop\": 32.49,\n  \"qty\": 6,\n  \"reason\": \"3 days before earnings, RVOL 1.9x\",\n  \"expires_at\": \"2026-05-20T20:00:00Z\",\n  \"status\": \"pending\"\n}\n```\n\nStatus lifecycle: `pending` → `active` (entry order placed) → `filled` / `expired` / `rejected` / `declined`\n\nYou can manually add signals to `signals.json` with any text editor — the bots and controller will pick them up on the next scan.\n\n---\n\n## File reference\n\n```\nWorking directory:\n  signals.json          ← shared signal bus (auto-created)\n  order-queue.json      ← scheduler queue (auto-created, gitignored)\n  nav-history.json      ← controller session baseline (auto-created)\n  logs/                 ← daily P\u0026L logs (auto-created by controller)\n  daytrader.json        ← daytrader config\n  earnings.json         ← earnings config + dates\n  bounce.json           ← bounce config\n  controller.json       ← risk limits config\n  index.json            ← index trader config\n\nCredentials:\n  ~/.trade-kit/tiger/.env\n  ~/.trade-kit/moomoo/.env\n```\n\n---\n\n## Troubleshooting\n\n| Symptom | Likely cause | Fix |\n|---|---|---|\n| `Tiger credentials not found` | `.env` file missing or wrong path | Check `~/.trade-kit/tiger/.env` exists with correct keys |\n| `connection refused` (moomoo) | Futu OpenD not running | `futu-opend \u0026` |\n| `Order ID 0` | Tiger API rejected the order | Check symbol is valid US stock, account has buying power |\n| `SKIPPED: no position held` | Scheduler sell guard triggered | You already sold, or symbol spelling mismatch |\n| `signal expired` | Signal older than expiry window | Re-run the scan to generate a fresh signal |\n| `Gate blocked — max positions` | 6+ open positions | Close something before opening new trades |\n| `drift \u003e2%` | Price moved away from signal before execution | Signal is stale — rescan |\n| `yahoo_kline: no data` | Yahoo Finance rate limit or bad symbol | Wait 60s, retry, or check ticker spelling |\n| `build failed` | Go version \u003c 1.21 | `go version`, upgrade if needed |\n\n### Debug mode (tiger-cli)\n\nSet `TIGER_LOG_LEVEL=debug` to see raw API request/response payloads:\n\n```bash\nTIGER_LOG_LEVEL=debug ./tiger-cli quote AAPL\n```\n\n---\n\n## Versioning\n\nSemantic versioning. See [CHANGELOG.md](CHANGELOG.md).\n\nCurrent version: **v0.3.1**\n\n---\n\n## Broker sign-up\n\nIf trade-kit is useful, consider signing up through these links:\n\n- **Tiger Brokers** — [Sign up](https://www.itiger.com/sg/invite) (up to S$1,000 welcome rewards for new accounts)\n- **Moomoo** — [Sign up](https://www.moomoo.com/sg) (free stocks for new accounts)\n\n---\n\n## Roadmap\n\n- [ ] `notifier` — Telegram/Discord signal delivery\n- [ ] `alert` — price alert daemon (monitors watchlist for threshold triggers)\n- [ ] `journal` — trade journal + P\u0026L stats (SQLite, auto-populated from brokers)\n- [ ] `backtest` — historical strategy validation via Yahoo Finance OHLCV\n- [ ] `options` — options chain viewer (calls/puts, IV, OI)\n- [ ] GoReleaser CI — pre-built binaries for macOS, Linux, Windows\n\n---\n\n## License\n\nMIT — see [LICENSE](LICENSE).\n\nNot financial advice — see [DISCLAIMER.md](DISCLAIMER.md).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjpramirez%2Ftrade-kit","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjpramirez%2Ftrade-kit","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjpramirez%2Ftrade-kit/lists"}