{"id":52012740,"url":"https://github.com/tsui66/paper-trading-terminal","last_synced_at":"2026-07-31T20:30:43.450Z","repository":{"id":368971979,"uuid":"1287752372","full_name":"tsui66/paper-trading-terminal","owner":"tsui66","description":"Lightweight, local US stock paper trading terminal — CLI, built for AI agents.","archived":false,"fork":false,"pushed_at":"2026-07-03T02:37:44.000Z","size":135,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-07-03T03:24:22.049Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Rust","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/tsui66.png","metadata":{"files":{"readme":"README.md","changelog":null,"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-07-03T01:23:32.000Z","updated_at":"2026-07-03T02:37:48.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/tsui66/paper-trading-terminal","commit_stats":null,"previous_names":["tsui66/paper-trading-terminal"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/tsui66/paper-trading-terminal","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tsui66%2Fpaper-trading-terminal","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tsui66%2Fpaper-trading-terminal/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tsui66%2Fpaper-trading-terminal/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tsui66%2Fpaper-trading-terminal/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tsui66","download_url":"https://codeload.github.com/tsui66/paper-trading-terminal/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tsui66%2Fpaper-trading-terminal/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":36133223,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-07-20T02:08:10.276Z","status":"online","status_checked_at":"2026-07-31T02:00:06.731Z","response_time":112,"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-07-31T20:30:42.436Z","updated_at":"2026-07-31T20:30:43.412Z","avatar_url":"https://github.com/tsui66.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003ch1 align=\"center\"\u003epaper-trading-terminal\u003c/h1\u003e\n\n\u003cp align=\"center\"\u003e\u003cstrong\u003eAI-native CLI for US stock paper trading\u003c/strong\u003e — with real-time market data, portfolio, and trading.\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e English · \u003ca href=\"README.zh-CN.md\"\u003e简体中文\u003c/a\u003e · \u003ca href=\"README.zh-TW.md\"\u003e繁體中文\u003c/a\u003e · \u003ca href=\"README.ja.md\"\u003e日本語\u003c/a\u003e · \u003ca href=\"README.ko.md\"\u003e한국어\u003c/a\u003e\u003c/p\u003e\n\n## Features\n\n- **Paper account** — cash, positions, mark-to-market PnL, persisted in SQLite; TUI reset (`z`) restores `initial_cash` and clears positions/orders\n- **Orders** — market, limit, and stop buy/sell; stop orders trigger into slipped market fills, survive restarts, and remain cancellable while pending\n- **Realistic simulation** — session-aware execution (regular / pre / after-hours / closed), lot sizes, A-share price bands \u0026 T+1 sell lock, per-market regulatory fees + configurable broker commission\n- **Market data** — Yahoo first, Financial Context CLI fallback; fails loudly if both are down\n- **TUI** — adaptive layout (resizes panels \u0026 compact text on smaller terminals), watchlist, Braille candlestick chart with page scroll, in-app order entry, fill notifications\n- **AI-native** — structured JSON I/O, `paper schema` for tool discovery, `AgentSkill` for Rust embeds\n- **Rust library** — embed via `AgentSkill` and `TradingEngine`\n\n## Requirements\n\n- **paper** binary on `PATH` (see [Install \u0026 run](#install--run) below)\n- **Financial Context** CLI — *optional*; used as fallback when Yahoo is unavailable\n\nBuild from source additionally needs Rust stable ≥ 1.91 (Yahoo enabled by default).\n\n### AI agent install (Claude / Codex / OpenClaw)\n\nPrefer letting a coding agent install and verify for you. Copy a prompt from **[docs/agent-install.md](docs/agent-install.md)** into Claude Code, Codex, or OpenClaw — the agent should run the installer and confirm `paper quote AAPL` works.\n\n\u003cdetails\u003e\n\u003csummary\u003eQuick copy — universal install prompt\u003c/summary\u003e\n\n```text\nInstall the paper-trading-terminal CLI (`paper`) on this machine.\n\nProject: https://github.com/tsui66/paper-trading-terminal\n\nRules:\n- Detect OS yourself and run the official installer (do not only print commands).\n- macOS/Linux: curl -sSL https://github.com/tsui66/paper-trading-terminal/raw/main/install | sh\n- Windows PowerShell: iwr https://github.com/tsui66/paper-trading-terminal/raw/main/install.ps1 | iex\n\nVerify: paper -h → paper config provider-status → paper quote AAPL → paper account.\nRetry with Homebrew / Scoop / cargo build --release if the script fails.\nReport install path and verification output. fcontext is optional unless Yahoo fails.\n```\n\nMore prompts (per-agent wording, Financial Context CLI fallback, JSON tool wiring): [docs/agent-install.md](docs/agent-install.md).\n\n\u003c/details\u003e\n\n## Install \u0026 run\n\nFollow the steps in order. Each step prints hints — match them to confirm success.\n\n### Step 1 — Install `paper`\n\nPick your platform and run **one** command.\n\n**macOS / Linux (recommended)**\n\n```bash\ncurl -sSL https://github.com/tsui66/paper-trading-terminal/raw/main/install | sh\nexport PATH=\"$HOME/.local/bin:$PATH\"   # if `paper` not found\n```\n\nInstalls to `~/.local/bin` by default — **no sudo / password** (agent-friendly). System-wide: `PAPER_INSTALL_SYSTEM=1` before the curl pipe.\n\nYou should see:\n\n```text\nInstalling paper-trading-terminal@v…\nDownloading https://github.com/tsui66/paper-trading-terminal/releases/download/…\npaper CLI v… installed to /Users/you/.local/bin/paper\n\nNext steps:\n  paper -h                      # verify install\n  paper config provider-status  # check yahoo + fcontext (optional)\n  paper quote AAPL              # test live quote\n  paper tui                     # launch dashboard\n```\n\n**Windows (PowerShell)**\n\n```powershell\niwr https://github.com/tsui66/paper-trading-terminal/raw/main/install.ps1 | iex\n```\n\nYou should see `paper CLI v… installed` and (first time) `Added …\\Programs\\paper to your PATH`. **Restart the terminal** if `paper` is not found.\n\n\u003cdetails\u003e\n\u003csummary\u003eOther install methods\u003c/summary\u003e\n\n**Homebrew (macOS / Linux)**\n\n```bash\nbrew install --cask tsui66/tap/paper-trading-terminal\n```\n\n**Windows ([Scoop](https://scoop.sh))**\n\n```powershell\nscoop install https://github.com/tsui66/paper-trading-terminal/raw/refs/heads/main/.scoop/paper.json\n```\n\n**Build from source** (needs Rust ≥ 1.91)\n\n```bash\ngit clone https://github.com/tsui66/paper-trading-terminal\ncd paper-trading-terminal\ncargo build --release\n# binary: ./target/release/paper\nmake install-local   # optional: copy to ~/.local/bin (no sudo)\n```\n\nFork or self-hosted releases:\n\n```bash\nPAPER_INSTALL_REPO=your-org/paper-trading-terminal curl -sSL https://github.com/tsui66/paper-trading-terminal/raw/main/install | sh\n```\n\n\u003c/details\u003e\n\n### Upgrade\n\n```bash\npaper upgrade --check          # compare with latest GitHub release\npaper upgrade                  # download and replace current binary\npaper upgrade --version v0.0.3 # install a specific version\n```\n\nUses [GitHub Releases](https://github.com/tsui66/paper-trading-terminal/releases). Override repo with `PAPER_INSTALL_REPO=owner/name` or `--repo`.\n\n### Step 2 — Verify `paper`\n\n```bash\npaper -h\npaper config provider-status\n```\n\nExpected: help text prints; `yahoo` shows **ok** (primary). `fcontext` may show **missing** until Step 4 — that is fine for a first run.\n\n```bash\npaper quote AAPL\n```\n\nExpected: a line with price and change, e.g. `AAPL  $…  +….%  [yahoo]`.\n\n### Step 3 — Run\n\n```bash\npaper account          # cash \u0026 equity\npaper tui              # interactive dashboard\n```\n\nIn the TUI: `j`/`k` move the watchlist, `b`/`s` buy/sell, `Tab` switch chart period, `←`/`→` flip chart pages (older / newer), `z` reset account (double-confirm), `q` quit.\n\n**Paper trading (CLI)**\n\n```bash\npaper buy AAPL --qty 10\npaper buy MSFT --qty 5 --limit 500   # limit order — pending until price hits\npaper sell AAPL --qty 10 --stop 180  # stop-loss — triggers when price falls to 180\npaper orders\npaper cancel \u003corder-id-prefix\u003e\npaper portfolio --json\n```\n\n### Step 4 — (Optional) Install Financial Context CLI fallback\n\nSkip this if Yahoo quotes already work. Install fcontext when:\n\n- `paper config provider-status` shows `fcontext: missing` and you want a backup source\n- Yahoo is flaky and quotes fail intermittently\n- You need symbols or data Yahoo does not cover\n\n`paper` shells out to `fcontext` (or `fctx`) automatically — no extra config beyond `config.toml` defaults.\n\n**4a. Install the CLI**\n\nmacOS (Homebrew):\n\n```bash\nbrew install --cask aitaport/tap/fcontext-cli\n```\n\nLinux / macOS (script):\n\n```bash\ncurl -sSL https://github.com/aitaport/fcontext-cli/releases/latest/download/install.sh | sh\n```\n\nWindows (PowerShell):\n\n```powershell\niwr https://github.com/aitaport/fcontext-cli/releases/latest/download/install.ps1 | iex\n```\n\nWindows (Scoop):\n\n```powershell\nscoop install https://github.com/aitaport/fcontext-cli/releases/latest/download/fcontext.json\n```\n\nYou should have `fcontext` (and `fctx`) on `PATH`:\n\n```bash\nfcontext -h\n```\n\n**4b. Sign in (one time)**\n\n```bash\nfcontext auth login\n```\n\nOpen the URL in a browser, authorize, then:\n\n```bash\nfcontext auth login --auth-code YOUR_CODE\n```\n\nCheck:\n\n```bash\nfcontext auth status\nfcontext check\n```\n\n**4c. Verify with `paper`**\n\n```bash\nfcontext quote AAPL.US --format json\npaper config provider-status\npaper quote AAPL\n```\n\nExpected: `fcontext` shows **ok** in provider-status; quotes may show `[yahoo]` or `[fcontext]` depending on which provider answered.\n\n`paper` accepts `AAPL`; fcontext uses `AAPL.US` internally.\n\nMore: [Financial Context CLI docs](https://docs.fcontext.com).\n\n## Quick reference\n\nGlobal flags (all commands):\n\n| Flag | Description |\n|------|-------------|\n| `--json` | Machine-readable output |\n| `--config PATH` | Config file (default: `./config.toml`) |\n| `--db PATH` | SQLite path (default: `data/paper.db`) |\n\nEnvironment: `PAPER_CONFIG` overrides the config path (legacy: `PPT_CONFIG`).\n\n## Market data providers\n\nDefault chain in `config.toml`:\n\n```toml\n[provider]\ndefault = \"yahoo\"\nfallback = [\"fcontext\"]\n\n[provider.fcontext]\ncli = \"fcontext\"\ntimeout_secs = 30\n```\n\n| Priority | Provider | Notes |\n|----------|----------|-------|\n| 1 | **yahoo** | Default; free Yahoo Finance data (can be unstable) |\n| 2 | **fcontext** | Financial Context CLI fallback; install + `fcontext auth login` (see [Financial Context CLI](#step-4--optional-install-financial-context-cli-fallback)) |\n\n```\nyahoo ──fail──► fcontext ──fail──► error (operation aborted)\n```\n\nDiagnose the chain:\n\n```bash\npaper config provider-status\n```\n\n## TUI\n\n```bash\npaper tui\n```\n\n![Paper Trading Terminal TUI](docs/tui-screenshot.png)\n\nThe dashboard adapts to terminal size: panel widths, row heights, and table text scale automatically on smaller windows (recommended minimum ~80×24). Shortcut hints in the footer shrink in compact mode.\n\n| Key | Action |\n|-----|--------|\n| `j` / `k` or `↓` / `↑` | Move watchlist selection |\n| `Enter` | Select highlighted watchlist symbol (loads chart) |\n| `Tab` / `Shift-Tab` | Chart period (1m … Year); resets chart to latest page |\n| `←` / `→` | Chart pages — **one key press = one full screen** of bars (← older, → newer) |\n| `b` / `s` | Buy / sell selected symbol |\n| `m` | Cycle market / limit / stop in order bar |\n| `Enter` | Submit order (when order bar is active) |\n| `Esc` | Cancel order entry, or cancel account-reset confirm |\n| `n` | Cycle selected pending order |\n| `x` | Cancel selected pending order |\n| `z` | Reset account — press twice to confirm; restores `initial_cash`, clears positions \u0026 orders |\n| `r` | Refresh quotes and chart |\n| `q` | Quit |\n\n**Panels:** watchlist (left), candlestick chart (center), holdings + pending orders (right), log, order/shortcut bar (bottom). Orders table columns include symbol, side, type, qty, fill/trigger price, fee, and status; a detail line shows the selected order.\n\n**Chart navigation:** page 0 shows the most recent bars. `←` loads the previous (older) page; older history is fetched on demand. `→` returns toward the latest page. Arrow keys are ignored while the order entry bar is open (`Esc` to exit).\n\nLimit and stop fills ring the terminal bell and log `*** FILLED ***` with fee breakdown.\n\n## CLI reference\n\n| Command | Description |\n|---------|-------------|\n| `account` | Cash, equity, open position count |\n| `portfolio` | Mark-to-market breakdown |\n| `positions` | Open holdings |\n| `quote SYM [SYM…]` | Live quotes |\n| `historical SYM --range m6 --interval d1` | OHLCV candles |\n| `buy SYM --qty N [--limit P\\|--stop P]` | Market, limit, or buy-stop order |\n| `sell SYM --qty N [--limit P\\|--stop P]` | Market, limit, or sell-stop order |\n| `orders` | Pending limit and stop orders |\n| `cancel ID` | Cancel by UUID or unique prefix |\n| `history` | Filled / cancelled order log |\n| `pnl` | Realized + unrealized P\u0026L |\n| `config show` | Current settings |\n| `config set-provider NAME` | `yahoo` \\| `fcontext` |\n| `config set-fallback a,b` | Comma-separated fallback list |\n| `config provider-status` | Probe each provider + chain |\n| `schema` | Agent integration schema (JSON) |\n| `upgrade` | Download latest release and replace the `paper` binary |\n| `upgrade --check` | Check if a newer release is available |\n| `upgrade --version v0.0.3` | Install a specific release tag |\n| `tui` | Launch dashboard |\n\n**Ranges:** `d1` `d5` `m1` `m3` `m6` `y1` `y5`  \n**Intervals:** `m1` `m5` `m15` `m30` `h1` `d1` `w1` `mo1`\n\n## Trading simulation\n\nPaper fills respect market rules derived from the symbol suffix and live quote session status:\n\n| Rule | US | HK | A-share (`.SH` / `.SZ`) |\n|------|----|----|-------------------------|\n| Lot size | 1 share | 100 shares (default) | 100 shares |\n| T+1 sell lock | No | No | Yes — bought shares locked until next session |\n| Extended hours | Pre/after market orders allowed | Limit queue when closed | Follows CN session |\n| Price bands | — | — | ±10% (±5% for ST names) on limit orders |\n| Regulatory fees | SEC / FINRA on sells | Stamp duty, levies | Stamp duty, transfer fee |\n\nPlatform commission is configurable; regulatory fees are always modeled:\n\n```toml\n[trading]\ncommission_per_trade = 0.0   # flat per order\ncommission_bps = 0.0         # notional bps (1 bps = 0.01%)\nmin_commission = 0.0\nslippage_bps = 5.0\n```\n\nWhen the exchange is **closed**, market orders are rejected; limit and stop orders may queue. **Halted** or **suspended** symbols reject all orders.\n\n## Configuration\n\n`config.toml` at the project root (or path from `--config` / `PAPER_CONFIG`):\n\n```toml\n[account]\ninitial_cash = 100_000.0\ncurrency = \"USD\"\n\n[trading]\ncommission_per_trade = 0.0\ncommission_bps = 0.0\nmin_commission = 0.0\nslippage_bps = 5.0\n\n[cache]\nenabled = true\nttl_secs = 60\n\n[watchlist]\nsymbols = [\"AAPL\", \"MSFT\", \"NVDA\", \"GOOGL\", \"AMZN\", \"META\", \"TSLA\"]\n```\n\nCopy `.env.example` for optional env overrides and `RUST_LOG`. Financial Context auth is managed by the Financial Context CLI (`fcontext`), not `paper`.\n\nAccount reset is available in the TUI (`z`, double-confirm) only — there is no CLI `reset` command yet.\n\n## Agents \u0026 library\n\n**Install via agent:** [docs/agent-install.md](docs/agent-install.md) — copy-paste prompts for Claude Code, Codex, and OpenClaw.\n\nDiscover the CLI contract:\n\n```bash\npaper schema --json\n```\n\nExample subprocess integration:\n\n```bash\npaper portfolio --json\npaper buy AAPL --qty 10 --json\n```\n\nRust embedding:\n\n```rust\nuse paper_trading_terminal::cli::AppState;\nuse paper_trading_terminal::skill::{agent_schema, AgentSkill};\nuse paper_trading_terminal::{create_provider_stack, AppConfig, QuoteCache};\n\nlet config = AppConfig::load(None)?;\nlet provider = create_provider_stack(\u0026config, Some(QuoteCache::new(true, 60)))?;\nlet skill = AgentSkill::new(AppState::new(config, provider));\nlet _schema = agent_schema();\n```\n\n## Development\n\n```bash\nmake test          # cargo test + CLI integration\nmake lint          # fmt + clippy\n./scripts/test/test_fcontext.sh   # skips if Financial Context CLI missing\n```\n\nRelease packaging (local):\n\n```bash\n./scripts/package_release.sh                    # host tarball → dist/\n./scripts/package_release.sh 0.1.0 darwin-arm64 linux-amd64 windows-amd64\ncargo build --no-default-features   # slim binary without Yahoo\n```\n\nPush a `v*` tag to trigger [`.github/workflows/release.yml`](.github/workflows/release.yml) (multi-platform GitHub Release).\n\n### Project layout\n\n```\nsrc/\n  cli/          # Clap commands\n  engine/       # TradingEngine, orders, fills, market_rules, tradability\n  provider/     # yahoo, fcontext, fallback chain\n  tui/          # Ratatui dashboard (ui/layout adaptive sizing, kline pagination)\n  skill.rs      # AgentSkill + schema\ndata/           # SQLite DBs (gitignored), test configs\nscripts/\n  build_release.sh\n  test/         # Shell integration tests\n```\n\n### Architecture\n\n```\n┌─────────┐   ┌─────────┐\n│   CLI   │   │   TUI   │\n└────┬────┘   └────┬────┘\n     │             │\n     └──────┬──────┘\n            ▼\n     TradingEngine ──► SQLite (account, orders, positions)\n            │\n            ▼\n   FallbackProvider (yahoo → fcontext)\n```\n\n## Disclaimer\n\n**For research and learning only.** This project is a **simulated paper-trading** tool. It does not connect to a brokerage, execute real orders, or provide investment advice. Market data may be delayed or inaccurate. You are solely responsible for how you use this software.\n\n**免责声明：** 本工具仅供模拟盘**研究与学习**使用，不构成任何投资建议，不涉及真实股票交易。\n\n## License\n\nMIT — see [LICENSE](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftsui66%2Fpaper-trading-terminal","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftsui66%2Fpaper-trading-terminal","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftsui66%2Fpaper-trading-terminal/lists"}