tossinvest-cli

Here is the translated document: <p align="center"> <a href="https://tossinvest-cli.vercel.app/"><img src="docs/assets/hero-banner-v5.png" alt="tossinvest-cli — connect your AI agents to Toss Securities" width="100%" /></a> </p> <p align="right"><strong>English</strong> · <a href="README.en.md">English</a></p> <div align="center"> <h1>tossinvest-cli</h1> <p><strong>The most flexible way to connect Toss Securities — via CLI, via MCP, from any AI agent.</strong></p> <p>Claude Code · Codex · Gemini · Cursor · GitHub Copilot — <code>tossctl</code> works with any AI agent. <strong>Connect to MCP server (<code>tossctl mcp</code>) or use in terminal</strong>, <strong>no official API key required, automatic routing.</strong></p> <p>_{21 features only available on the web app — <strong>100% of the official Open API supported.</strong> <a href="#supported-features">Full comparison table ↓</a>}</p> <p>_{<em>The most flexible way to connect Toss Securities — via CLI, via MCP, from any AI agent. 100% of the official Open API, plus 21 features only the web app had.</em>}</p> </div> <p align="center"> <a href="LICENSE"><img src="docs/assets/badges/license.svg" height="44" alt="License: MIT" /></a>&nbsp; <a href="https://go.dev/"><img src="docs/assets/badges/go.svg" height="44" alt="Built with Go 1.25+" /></a>&nbsp; <img src="docs/assets/badges/agents.svg" height="44" alt="Works with Claude · Codex · Cursor" /> </p> <p align="center"> <img src="docs/assets/badges/output.svg" height="44" alt="Output: JSON · CSV · SSE" />&nbsp; <a href="https://tossinvest-cli.vercel.app/docs/guide/hybrid-openapi"><img src="docs/assets/badges/hybrid.svg" height="44" alt="Routing: Official API + WTS" /></a> </p> <p align="center"> <a href="#quick-start"><strong>Quick Start</strong></a> · <a href="#supported-features"><strong>Supported Features</strong></a> · <a href="#command-list"><strong>Command List</strong></a> · <a href="#faq"><strong>FAQ</strong></a> · <a href="#documentation"><strong>Documentation</strong></a> · <a href="#sponsors"><strong>Sponsors</strong></a> </p> <p align="center"> <a href="https://github.com/JungHoonGhae/tossinvest-cli/stargazers"><img src="https://img.shields.io/github/stars/JungHoonGhae/tossinvest-cli" alt="GitHub stars" /></a> <a href="https://github.com/JungHoonGhae/tossinvest-cli"><img src="https://img.shields.io/badge/status-beta-orange.svg" alt="Status Beta" /></a> <a href="https://github.com/JungHoonGhae/tossinvest-cli/actions/workflows/ci.yml"><img src="https://github.com/JungHoonGhae/tossinvest-cli/actions/workflows/ci.yml/badge.svg" alt="CI" /></a> </p> > [!WARNING] > This project is not an official Toss Securities product. If you connect an official Open API key, the functionality works through the official Toss API, but other features use the unofficial Toss web internal API, which may violate the Toss Securities Terms of Service (TOS). The API may change without notice, and the developer assumes no responsibility for account restrictions, losses, or other disadvantages resulting from use. Use at your own risk. > [!IMPORTANT] > Trading features are disabled by default after installation. You must enable them individually in `config.json`. <div align="center"> _{<strong>WORKS WITH</strong>} <br /><br /> <img src="docs/assets/logos/claude.svg" height="30" alt="Claude Code" title="Claude Code" />&nbsp;&nbsp; <picture><source media="(prefers-color-scheme: dark)" srcset="docs/assets/logos/codex.svg" /><img src="docs/assets/logos/codex-light.svg" height="30" alt="Codex" title="Codex" /></picture>&nbsp;&nbsp; <img src="docs/assets/logos/googlegemini.svg" height="30" alt="Gemini CLI" title="Gemini CLI" />&nbsp;&nbsp; <picture><source media="(prefers-color-scheme: dark)" srcset="docs/assets/logos/cursor.svg" /><img src="docs/assets/logos/cursor-light.svg" height="30" alt="Cursor" title="Cursor" /></picture>&nbsp;&nbsp; <picture><source media="(prefers-color-scheme: dark)" srcset="docs/assets/logos/githubcopilot.svg" /><img src="docs/assets/logos/githubcopilot-light.svg" height="30" alt="GitHub Copilot" title="GitHub Copilot" /></picture>&nbsp;&nbsp; <img src="docs/assets/logos/opencode.svg" height="30" alt="OpenCode" title="OpenCode" />&nbsp;&nbsp; <img src="docs/assets/logos/qwen.svg" height="30" alt="Qwen Code" title="Qwen Code" />&nbsp;&nbsp; <img src="docs/assets/logos/deepseek.svg" height="30" alt="DeepSeek" title="DeepSeek" />&nbsp;&nbsp; <img src="docs/assets/logos/mistralai.svg" height="30" alt="Mistral" title="Mistral" />&nbsp;&nbsp; <picture><source media="(prefers-color-scheme: dark)" srcset="docs/assets/logos/moonshotai.svg" /><img src="docs/assets/logos/moonshotai-light.svg" height="30" alt="Kimi CLI" title="Kimi CLI" /></picture>&nbsp;&nbsp; <img src="docs/assets/logos/openclaw.svg" height="30" alt="OpenClaw" title="OpenClaw" /> </div> --- <p align="center"> <a href="https://www.star-history.com/#JungHoonGhae/tossinvest-cli&Date"> <picture> <source media="(prefers-color-scheme: dark)" srcset="docs/assets/star-history/star-history-dark.svg" /> <source media="(prefers-color-scheme: light)" srcset="docs/assets/star-history/star-history-light.svg" /> <img alt="Star History Chart" src="docs/assets/star-history/star-history-light.svg" width="600" /> </picture> </a> </p> <p align="center"> <a href="https://www.star-history.com/?repos=JungHoonGhae%2Ftossinvest-cli"> <picture> <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/badge?repo=JungHoonGhae/tossinvest-cli&theme=dark" /> <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/badge?repo=JungHoonGhae/tossinvest-cli" /> <img alt="Star History Rank" src="https://api.star-history.com/badge?repo=JungHoonGhae/tossinvest-cli" /> </picture> </a> </p> ## Sponsors <p align="center"> <a href="https://github.com/sponsors/JungHoonGhae"><img src="docs/assets/badges/sponsor.svg" height="46" alt="Become a sponsor" /></a> </p> <!-- sponsors:start --> <p align="center"> <a href="https://github.com/sponsors/JungHoonGhae" title="Private sponsor"><img src="docs/assets/sponsors/anonymous.svg" width="56" height="56" alt="private sponsor" /></a> </p> <p align="center">_{Currently <strong>1</strong> person is sponsoring my open-source work (including tossinvest-cli). Sponsorship is used for all my projects.}</p> <!-- sponsors:end --> ## Quick Start **Choose how to use it.** - **Use with AI agents (Claude·Codex·Cursor…)** → **MCP is the simplest.** Once registered (`claude mcp add tossctl tossctl mcp`), the agent handles everything naturally. → [MCP Quick Start](#mcp-quick-start--3-steps) - **Use in terminal·script·automation, or use all features (including favorites, real-time data)** → **CLI.** Start now. ↓ Both require a one-time login and use the same `tossctl`. For details, see [CLI vs. MCP — when to use each](#cli-vs-mcp--when-to-use-each). ### For Agents ```text Install tossinvest-cli: curl -fsSL https://raw.githubusercontent.com/JungHoonGhae/tossinvest-cli/main/install.sh | sh (macOS/Linux) or GitHub Releases (Windows). Run `tossctl doctor` to verify setup, then complete browser login with `tossctl auth login`. Use read-only commands first (account, portfolio, quote). Trading actions stay disabled until config.json explicitly allows them. Always run `tossctl order preview` before any trading mutation. ``` ### For Humans macOS / Linux: ```bash curl -fsSL https://raw.githubusercontent.com/JungHoonGhae/tossinvest-cli/main/install.sh | sh ``` Windows (PowerShell): ```powershell irm https://raw.githubusercontent.com/JungHoonGhae/tossinvest-cli/main/install.ps1 | iex ``` Verify installation: ```bash tossctl version tossctl doctor tossctl auth login tossctl account summary --output json ``` After installation, update with `tossctl update` (or `brew upgrade tossctl-cli` if installed with Homebrew). > `auth login` requires Google Chrome and Python, which are automatically set up by the installation script. > Windows, Homebrew, and source build installations are covered in the [Installation](#installation) section. > > After scanning the QR code, make sure to tap the **"Keep this device logged in"** confirmation prompt on your phone. > If you skip this step, the session will expire after about 1 hour of inactivity, requiring re-login. > You can verify successful capture with `tossctl auth status` and `Persistence: persistent cookie (expires ...)`. > **Headless environment (SSH server·CI):** `tossctl auth login --headless [--qr-output /tmp/toss-qr.png]`. > The QR URL and answer letter are output to stderr, allowing you to authenticate with the Toss app on your phone without a camera. The `--qr-output` file is saved with `0600` permissions. ### Session Extension The Toss server operates a 7-day active expiration clock, separate from the SESSION cookie (1-year `Max-Age`). 24 hours before expiration, all commands display a stderr warning: ``` ⚠ session expires in ~18h; run `tossctl auth extend` to renew ``` `tossctl auth extend` sends a push notification to your Toss app and waits for approval. ``` $ tossctl auth extend Waiting for approval in the Toss app on your phone... ✓ Extension complete. New expiry: 2026-05-13 07:03 KST (took 4s) ``` The default timeout is 120 seconds, which can be shortened with `--timeout 60s`. ## Support Scope > **tossctl covers 100% of the official Toss Open API's query and transaction range, and even more.** > It supports all endpoints in the [official Open API documentation](https://developers.tossinvest.com/docs), including account, balance, market price, order book, trades, candles, upper/lower limits, sellable quantity, fees, orders, and more. Additionally, it provides **21 unique features not available in the official Open API**, such as supply and demand, market indices, AI signals, conditional screening, and more. <p align="center"> <img src="docs/assets/api-comparison.svg" alt="tossctl vs official Open API (planned) coverage comparison — tossctl is the superset" width="840" /> </p> The official Toss Open API is currently in **staged rollout for pre-registered users**, with a limited scope (REST only). The `official API (planned)` column in the table below represents the expected coverage based on the official documentation, while the `tossctl` column represents the features provided by tossctl. **All ✅ rows in the official Open API column are also ✅ in tossctl**, meaning tossctl fully covers the official Open API range. - ✅ Supported · ❌ Not supported · 🔸 Partial support · 🆕 Newly added within the last month - **`official API (planned)` column = expected coverage based on public documentation** (may change due to staged rollout). - **`official API (planned)` column ❌ rows = tossctl unique features**. - **Verification criteria version**: The `official API` column in the table and diagram is verified based on the **official Open API version shown in the badge** (the version and last verification date are recorded in [.openapi-snapshot.json](docs/migration/.openapi-snapshot.json)). The full spec is mirrored daily at [`docs/migration/openapi.latest.json`](docs/migration/openapi.latest.json), and updated automatically when Toss updates the spec. ### Query (Read-only) · US·KR Common | Feature | Command | Official API (planned) | tossctl | |------|--------|:--:|:--:| | Account list / summary | `account list`, `account summary` | ✅ | ✅ | | Portfolio | `portfolio positions`, `portfolio allocation` (US: USD parallel) | ✅ | ✅ | | Trade history (ticks) | `quote trades <symbol> --count N` | ✅ | ✅ | | Order book (bid/ask 10 levels) | `quote orderbook <symbol>` (sell and buy quantity) | ✅ | ✅ | | Upper/lower limits | `quote limits <symbol>` (KR) | ✅ | ✅ | | Buy warnings | `quote warnings <symbol>` (margin trading, investment warning, VI, etc.) | ✅ | ✅ | | Market hours | `market hours` (today + next business day if closed) | ✅ | ✅ | | Exchange rate | `market fx` (USD exchange rate, USD index) | ✅ | ✅ | | Sellable quantity | `quote sellable <symbol>` (holdings sellable shares) | ✅ | ✅ | | Fees / tax rates | `quote commission <symbol>` (fee rate, tax rate) | ✅ | ✅ | | Uncompleted / completed / single orders | `orders list`, `orders completed`, `order show <id>` | ✅ | ✅ | | Market price | `quote get <symbol>` (OHLC, 52-week high/low, market cap, trading volume, trading intensity) | 🔸 *(trading intensity, 52-week, etc. excluded)* | ✅ | | Candlestick chart | `quote chart --interval 1m\|3m\|5m\|10m\|15m\|30m\|60m` | 🔸 *(1-minute, daily only)* | ✅ | | **Multi-market price / real-time update** | `quote batch <sym>[,sym,...]` (`--chart`·`--live`) | ❌ | ✅ | | **Supply and demand** | `quote flows <symbol>` (individual, foreign, institutional, KR) | ❌ | ✅ | | **Market indices** | `market index` (KOSPI, KOSDAQ, NASDAQ, S&P500, VIX), `market index <code\|name>` details (OHLC, 52-week) | ❌ | ✅ | | **Real-time popular rankings** | `market ranking --size N` | ❌ | ✅ | | **Official rankings (trading volume / price change)** | `market rankings --type ... --market KR --duration 1d` | ✅ | ✅ | | **Market indicator current price** | `market indicator KOSPI,KOSDAQ` | ✅ | ✅ | | **Market indicator candles** | `market indicator-candles KOSPI --interval 1d` | ✅ | ✅ | | **Market investor trading trends** | `market investor-trading KOSPI --interval 1d` | ✅ | ✅ | | **Conditional order query** | `order conditional list`, `order conditional get <id>` | ✅ | ✅ | | **Conditional order transactions** | `order conditional place\|cancel\|modify` (safety gate: config allowed + --execute + --confirm) | ✅ | ✅ | | **🆕 Investor net buy/sell** | `market investors` (foreign, institutional, individual net buy/sell) | ❌ | ✅ | | **🆕 Earnings schedule** | `market earnings` (`--major` major company curation) | ❌ | ✅ | | **🆕 Dividend history** | `portfolio dividends` (annual total, region, monthly, `--by-payment-date` tax) | ❌ | ✅ | | **Prime subscription status/benefits** | `account prime` (fee, interest 3-step comparison: general/Prime/applied) | ❌ | ✅ | | **🆕 Community rankings** | `community rankings --type influencer\|profit\|followers` | ❌ | ✅ | | **🆕 Sector performance** | `market sectors [id]` (large classification, sub-sector, 1-day, 1-month, 1-year) | ❌ | ✅ | | **🆕 Theme performance rankings** | `market themes` (today's top-gained theme, number of rising stocks) | ❌ | ✅ | | **🆕 Personalized news briefing** | `market briefing` (theme-based news bundle) | ❌ | ✅ | | **Toss AI signals** | `market signals` (stock-based AI signals, keywords, price change) | ❌ | ✅ | | **Conditional screening** | `market screener [id]` (preset) · `--filter '<json>'` (custom condition) `--nation kr\|us` | ❌ | ✅ | | **Watchlist query/management** | `watchlist list`·`groups`, `watchlist group create\|rename\|delete`, `watchlist add\|remove --group <id>` (folder CRUD + stock add/remove) | ❌ | ✅ | | **Transaction ledger** | `transactions list --market us\|kr` (buy/sell, deposit/withdrawal, dividend, stock transfer) | ❌ | ✅ | | **Cash overview** | `transactions overview --market us\|kr` (orderable, withdrawable, scheduled deposit) | ❌ | ✅ | | **CSV export** | `export positions\|orders --market`, `transactions list --output csv` | ❌ | ✅ | | **Real-time push** | `push listen` (SSE stream — order/price change notification) | ❌ *(official API REST only)* | ✅ | ### Transactions The official API also provides order creation, modification, cancellation, and fractional orders (`orderAmount` amount-based buy, 1.1.5+ US market sell). However, **KRW (Korean Won) settlement mode fractional orders, dry-run preview, and config-based safety gates** are unique to tossctl. | Feature | Command | Required config | Official API (planned) | tossctl | |------|--------|-------------|:--:|:--:| | Buy at specified price (US/KR) | `order place --side buy --price <value>` | `place` | ✅ | ✅ | | Sell at specified price (US/KR) | `order place --side sell --price <value>` | `place` + `sell` | ✅ | ✅ | | Domestic stock trading | `order place --market kr` (6-digit code auto-recognition) | `place` | ✅ | ✅ | | Order cancellation | `order cancel --order-id <id>` | `cancel` | ✅ | ✅ | | Order modification | `order amend --order-id <id>` | `amend` | ✅ | ✅ | | Fractional buy (US, amount-based) | `order place --fractional --amount <value>` (`--currency-mode USD`) | `place` + `fractional` | ✅ | ✅ | | **Fractional buy — KRW settlement** | `order place --fractional --amount <value>` (default KRW) | `place` + `fractional` | ❌ | ✅ | | **Order dry-run / preview** | `order preview` (verification without actual transmission) | — | ❌ | ✅ | All transactions also require `allow_live_order_actions=true`. Fractional orders are automatically converted to market orders and are amount-based (`--currency-mode KRW` default or `USD`). US specified price uses `--currency-mode` to select price interpretation: `KRW` (default, server exchange rate to USD conversion) or `USD` (input as USD price). Example: `order place --symbol MRVL --side buy --qty 1 --price 158.01 --currency-mode USD`. ### Why tossctl — Official API is only a part of Toss features The official Open API provides **only basic REST queries and orders** (about 20 endpoints). In contrast, the **meaningful query and transaction features used by Toss web app (WTS) are around 440** — excluding irrelevant endpoints like onboarding, KYC, terms, promotions, and telemetry. > **The official Open API covers only about 4% of them.** tossctl operates on top of the remaining range and provides features not available in the official API (supply and demand, market indices, AI signals, screening, investor net buy/sell, earnings schedule, dividend history, community rankings, sector performance, news briefing, real-time push, KRW fractional orders, dry-run preview, etc.). It will continue to implement the remaining meaningful range. #### Real-world scenarios — What official API can't do, tossctl can The abstract "broader range" actually makes a difference in real-world scenarios. **Official API only: ❌ → tossctl (or WTS): ✅**: | What you want to do | Official Open API | tossctl | |---|:---:|---| | **How much have you actually earned or lost (realized profit/loss) for a specific stock?** | ❌ No trading price | ✅ `completed_orders` aggregates buy/sell trading prices for all periods | | **Annual dividend and tax withholding history → Determine if subject to comprehensive taxation** | ❌ | ✅ `dividends` (before/after tax, monthly) | | **Foreign stock capital gains tax and loss carryover report** | ❌ | ✅ `transactions` + `completed_orders` to construct ledger | | **Monthly dividend cash flow (received and scheduled)** | ❌ | ✅ `dividends` monthly | | **Investor net buy/sell flow by stock** | ❌ Only trading volume | ✅ `trading_flows` | | **KOSPI, KOSDAQ, VIX, etc. indices** | ❌ Only individual stocks | ✅ `market_indices` / `index_detail` | | **Top stocks bought by foreigners/institutions today** | ❌ | ✅ `investor_rankings` | | **Sector/theme performance scan (what's moving)** | ❌ | ✅ `sectors` / `theme_rankings` | | **Conditional screening (high dividend, low PBR, growth)** | ❌ | ✅ `screener_presets` | | **Earnings call schedule** | ❌ | ✅ `earning_calls` / `earnings_major` | | **Total assets and evaluation profit/loss on one screen** | △ `holdings` + `buying_power` combination | ✅ `account_summary` at once | | **Query holdings and pending orders without official key** | ❌ Key required | ✅ `positions` / `pending_orders` (only web session) | | **Covered call ETF actual total return (dividend − NAV loss)** | ❌ | ✅ `completed_orders` + `dividends` combined | | **Post-analysis of supply and demand after buying a stock** | ❌ | ✅ `completed_orders` + `trading_flows` combined | In short, the official API is limited to *"precise query and order placement"* . tossctl extends this to **comprehensive analysis tools with tax, supply and demand, and research features**. For the full mapping, see [Automated Routing Guide ↗](https://tossinvest-cli.vercel.app/docs/guide/hybrid-openapi). Why tossctl is better in the long run: - **Flexibility — Most open way to connect to Toss Securities.** Terminal CLI, [MCP server](#mcp-server-tossctl-mcp), any AI agent (Claude Code, Codex, Gemini, Cursor, Copilot), scripts — all **one `tossctl`** handles. **Start without official key**, and automatically route to official API if connected. Not tied to specific apps, SDKs, languages, or agents. - **Range** — Official Open API has a narrow and slowly expanding scope. tossctl tracks the entire web app (catalog below) and implements features first, so it's always broader. - **Speed** — New features are integrated fastest on the web app (WTS) and external APIs follow with stable ranges only. tossctl monitors weekly and implements new endpoints **without waiting for official API release**. [Why official API is slow ↗](https://tossinvest-cli.vercel.app/docs/guide/hybrid-openapi) - **Superset** — Official Open API range is **already 100% supported** (tossctl leads even if official API catches up). - **Stability (resilience)** — Official Open API has endpoint group limits (1~10 requests per second). If repeated quickly, 8 out of 10 requests are blocked (measured at 3 points). tossctl bypasses to web session if blocked, ensuring user success — critical for automated trading and dashboards. [Rate limit table + measurement ↗](docs/migration/open-api.md#rate-limit-measurement) WTS Web API Catalog (Continuous Tracking) Extract all `/api/*` endpoints from the and categorize them into ** Next Addition Candidates / Intent**. Additions, changes, and deletions are monitored weekly represent the **meaningful range**, excluding insignificant endpoints, and updated in the catalog="center"> ="docs/reverse-engineering/wts-endpoints.json="https://img/badge/dynamic/json?urlA%2FFraw.githubusercontent.com%2FJungHoonGha2Ftossinvest-cli%2Fmain%2Fdocsverse-engineFwts-endpoints.json&query=%24.counts&label=WTSmeaningful%20API=%20endpoints&color=3182F6" altTS meaningful API" /></a> <a href="docs/reverse-engineering/wts-endpoints.json"><img src="img.shields.io/badge/dynamic/json?url=https%3A%2Fraw.githubusercontent.com%2FJungHoonGhae%2invest-cli%2F2Fdocs%2-engineering%2Fwpoints.json&query=%24.counts.implemented&implemented&color=success" alt="implemented" /></a> href="docs-engineering/wts-end"><img src="https.shields.io/badge/dynamic/json?url=https%3A%%2Fraw.githubusercontent2FJungHoonGhae%2Ftoss2Fmain%2Fdocs%2Freverse%2Fwts.json&query=%24andidate_next&label=next%20candidates&color= alt="next candidates"> <img src://img.shields.io%20Open%20API-~4%25%20of%20WTS" alt="official API coverage of WTS" /> > - **Classification** catalog: [`docs/reverse-enginets-endpointsdocs/reverse-engineering/wpoints.json)): `implemented` — already tossctl (corresponding toctl command) -` / `priority: next` — not yet implemented, with **high-value candidates for next additions** (e.g., virtual asset prices, real-time charts, rankings within industries, AI signal details) - `excluded` — intentionally excluded (out of scope, such as account creation, KYC, terms, promotions, telemetry, etc., with reasons recorded) - **Continuous Tracking-extract web bundles new/deleted/changed endpoints (`first_seen lifecycle), and automatically upon New candidates are selected and. ### Safety Model functions are disabled by default. A live order must pass the **persistent (config** and the **runtime) gate**. ```mermaid flowchart TD order place / cancel / amend"] --> P{"action/>place·cancelend"} P -->| X1["❌ DisabledActionError"] P| S{"<br/>sell·fractional<br/>(if applicable)"} S -->|violation| X❌ DisabledActionError"] S -->|ok| E{"--execute"} E -->|none| PV["📋 preview only output<br/>(confirm token E -->| M{"allow_live_order_actions"} M -->|false| X3["❌ ErrLiveActionsDisabled"] Mtrue| C{"<br/>== preview} C -->|mismatch| X4["ConfirmMismatch"] match| GO[" mutation to broker"] CFG["persistent gate ·"] P M end RT["runtime gate flag"] E C end- **Persistent Gate ():** `place``/`amend toggle + `sell`al` scope declarationallow_live_order_actions` switch. (US/KR markets are not considered gates orders are not riskier so they are treated- **Runtime Gate execution):** `--executeactual execution, not + `--confirm <tokenorder-specific token from preview). - The actual safety mechanism is the order-specific `--confirm < — only obtainable by, preventing unintended orders. v0.5 History:** Removed the redundant TTL grant layer (`internal`) and replaced itallow_live_order_actions` (providing the same protection). `--dangerously-smissions` flag (no semantically inverted been retired. Existing flags deprecated no-op aliases for one release to maintain script/agent## Official Open APIsince:20206-27--> toss entirely with a (WTS). Optionallyoss official Open API **automatic routing**, supported by the official Open the official API OAuth path, and the rest use WTS. > The differences between the official Open API and WTS web session (authentication, updates, coverage, stability), automatic IP registration, and routing behavior (diagram) are detailed in the [Automatic Routing Guide](https://tossinvest-cli.vercel.app/docs/guide/hybrid-openapi). ```bash # Obtain official key: https://corp.toss/ko/open-api tossctl init # onboarding wizard setup) tossapi login official key (environment variables also supported) tossctl status # diagnose key, token, allowed IP, tossctl open # connection verificationossctl account summary --backend openapi # enforce official API path (optional) ``` With the key connected, CI, and agents can automatically refresh tokens without human intervention. are strict — documentation, account limited to **1 per second**, and rapid repeated requests in 8 out of 10 rejections ([official measurements](docs/open-api.md#rate실측), subject to change). tossctl automatically falls WTS for uninter queries and monitoring. ### (`tossctl`) <!--since:-07-08--> The API and ** exclusive features** are exposed through the **MCP (Model Context Protocol) server**. #### Start — 3 Steps MCP is a mode of the `tossctl`tossctl`). **Install CLI first authentication (official key session), and register with the```bash 1) Install tossctl (macOS/Linux — Windows, Homebrew, and source builds are detailed in the "Installation) curl -fs://raw.githubusercontent.comHoonGhae-cli/main/install.sh # 2) Authentication — at least one to start (inactive be non-functional) tossctl openapi login Open API: official queries + orders ( issuance: https.tossinvest.com/ko/open-api) t auth login # W session: WTSpopular rankings, supply, AI signals, 3) MCP host and verifyClaude Code example) claude mcp add tossctl tossctl mcp cl list # → "tossctl: mcp - ✔``` For hosts with **JSON configuration** (Claude Codex, etc.), [configuration example](#-host-json-configuration). To use the terminal directly, registration is needed**; simply use `toss` (web for full functionality — Start](#quick-start). Both paths share the samectl` binary Why Catalog-based — Fixing 3 Constant Contexts MCP's inherent cost is that **tool schemas reside in the context permanently**. If one tool per API is registered, the tool's name, description, and parameter schema occupy context throughout the conversation. tossctl's API surface has **over 40 operations** (16 official queries + 3 orders + WTS exclusive queries + 1 system). as a separate tool **that many schemas constantly in context**, consuming tokens selection noise. tossctl uses a catalog mode inspired by KIS_MCP_Server, with **only ** exposed upfront and the rest of the operations only when needed**: - `list_operations` — operations (id, write access) and `query` -_operation` — fetch a's parameter schema **only at that moment** -_operation` — invoke the operation with id and parameters Result: **only 3 tool schemas are constantly in context agent finds the needed operation_operations`, schema with `describe calls it with ` ensuring unused operations not occupy context Exposed Scope WTS for Official Only for Writes MCP exposes **queries from API and WTS exclusive features** and uses API path for orders only**. - **Queries (read)**: Both official API (accounts, prices, quotes candles, etc.) and **WTS exclusive features** (popular rankings, supply and demand, AI signals, industries, earnings, dividends, WTS queries require a web session; without one, the operation will return an `tossctl auth login` guide. Queries are stale read, so the risk of exposing them to agents is low. - **Orders (write) cancellation, and **only the official** (not via WTS). Submitting orders through agents requires a **Toss-approved API** for safety and- **Authentication separation**: Official queries and orders use official keys (`openapi login`), while WTS queries use web sessions (`auth login`). **At least one authentication method is required for the MCP server to start**, and each operation checks its required authentication. This allows **WTS exclusive features to be used by agents via MCP**. > **Updates are automatic**. The host stores the `tossctl mcp` **command** and re-executes session, so updating the binary with `brew upgrade tossctl-cli` (ossctl update reflect new operations **registration** (catalog configuration is loaded from the binary at server start). ** is gated** likeossctl order config's `tr` and `allow_live_order_actions` toggles must be enabled, and default calls return a **dry-run preview** (with confirm token and warnings). Actual submission requires `execute: true` and `confirm: <token>`. Orders use **only the official API path** (not via WTS). #### MCP Host JSON Configuration For hosts with JSON configuration (Claude Desktop, Codex, etc.), add the the configuration fileossctl` must be in PATH): ```json { "mcpServers": { "tossinvest": { "command": "tossctl", "args": ["mcp"] } } } ``` CLI and MCP — When and What (Complementary) Two entrances of the same `tossctl` binary, **both work well with AI agents**. Not competing, just different approaches. | | **CLI** (`tossctl ...`) | **MCP** (`tossctl mcp`) | |---|---|---| | Execution Method | Shell command (`tossctl …`) | Structured MCP tool (JSON-RPC, no shell needed) | | Where | Anywhere with a shell — terminal, script, cron, **and shell-using AI agents** (Claude Code, Codex, Cursor, …) | **MCP native host** — agent calls operation as a tool (minimizing context with 3-tool catalog) | | How agent knows | Needs to be mentioned in prompt or registered with skills · `AGENTS.md`/`CLAUDE.md` | **Automatically exposed in tool list upon registration** → no separate notification needed | | Authentication | **Web session only** (automatic routing with official key connection) | Official inquiry/order needs official key (`openapi login`), WTS inquiry needs web session (`auth login`) — **at least one** | | Coverage | **Everything** — official + WTS (inquiry, order, real-time streaming, interest stock, etc.) | **Inquiry is official + WTS**, order is official path. No real-time streaming, WTS writing. | | Natural Language | Agent converts natural language → `tossctl` command | Agent converts natural language → MCP tool call | - **AI agents use both — the difference is 'how to know'.** MCP is automatically exposed as a tool upon registration and can be called without separate notification (inquiry for both official and WTS, order is official). CLI works well with shell-using agents (Claude Code, Codex, Cursor), but **needs to be mentioned in prompt or registered with skills** to be known — in return, **all features** (including real-time and WTS writing) are accessible with decisive and pipeable. - **Scripts, cron, pipes, and reproducible automation** are more natural with CLI (same command = same result). - Regardless of which one you use, **inquiry data and order safety gates are the same**: config opt-in + dry-run preview + `execute`/`confirm` token. > **Recommended to use read-only for autonomous agents.** If `trading.*` is turned off in config (default), MCP can only perform inquiries, and order operations will be blocked at the gate. To enable trading, a person needs to explicitly turn on the config, and actual submission requires `execute:true` + valid `confirm` token. ## Configuration ```bash tossctl config init tossctl config show ``` ```json { "$schema": "https://raw.githubusercontent.com/JungHoonGhae/tossinvest-cli/main/schemas/config.schema.json", "schema_version": 3, "trading": { "place": false, "sell": false, "fractional": false, "cancel": false, "amend": false, "allow_live_order_actions": false, "dangerous_automation": { "accept_fx_consent": false } }, "update_check": { "enabled": true } } ``` | Field | Description | |------|------| | `place` | Allow `order place` path (broker API branch: place) | | `cancel` | Allow `order cancel` path (broker API branch: cancel) | | `amend` | Allow `order amend` path (broker API branch: amend) | | `conditional` | Allow `order conditional place/cancel/modify` path (official Open API, also requires `allow_live_order_actions`) | | `sell` | Allow sell orders (`place` also required) — **scope declaration**: user self-declares scope limitation ("only buy" or "buy and sell") | | `fractional` | Allow fractional orders (`place` also required, only US market) — **scope declaration** | | `allow_live_order_actions` | Master kill switch — if any of `place/cancel/amend` is to reach actual broker, this value must be `true` | | `accept_fx_consent` | Automatically proceed with post-prepare FX confirmation | | `update_check.enabled` | New version notification (24h cache, GitHub Releases API, silent on failure). Default `true`. Skipped onCSV output, non-tty, and dev build. | > **Two types of toggles:** > - **Path gates** (`place`, `cancel`, `amend`) — broker API branches are actually turned on/off independently > - **Scope declarations** (`sell`, `fractional`) — user self-declares "I don't place orders in this category" to prevent mistakes/bugs/agent malfunctions > > `v0.4.3` removed `trading.grant`, `dangerous_automation.complete_trade_auth`, and `dangerous_automation.accept_product_ack`. `v0.5.2` removed `trading.kr` (asymmetric market gate — KR orders are not riskier than US, so removed). Remaining old settings are ignored; a one-line stderr warning (24h backoff) is shown on general command execution, and also displayed in `config status`/`doctor Order Examples ### Limit Buy (US) ```bash tossctl config init # config.json: place, allow_live_order_actions → true tossctl order preview \ --symbol TSLL --side buy --qty 1 --price 18000 --output json tossctl order place \ --symbol TSLL --side buy --qty 1 --price 18000 \ --execute --confirm <token> \ --output json ``` ### Fractional Buy (US, amount-based) ```bash # config.json: place, fractional, allow_live_order_actions → true tossctl order preview \ --symbol TSLL --side buy --fractional --amount 1000 --qty 0 --output json tossctl order place \ --symbol TSLL --side buy --fractional --amount 1000 --qty 0 \ --execute --confirm <token> \ --output json ``` ### Domestic Stock Buy ```bash # config.json: place, kr, allow_live_order_actions → true tossctl order place \ --symbol 005930 --market kr --side buy --qty 1 --price 200000 \ --execute --confirm <token> ``` ### Sell ```bash # config.json: sell → true (additional) tossctl order place \ --symbol TSLL --side sell --qty 1 --price 18000 \ --execute --confirm <token> ``` ### Multi-Stock Quote ```bash t quote batch TSLL930 GOOG Voutput table ``` ## What This Project Does Not Do | What it does not do | Description | |---|---| | Official API SDK | Not an official project providing Toss Securities API or official SDK. Migration plan after official Open API release is in [`docs/migration/open-api.md`](docs/migration/open-api.md). | | Universal Trading Client | Does not fully support all order types and markets. | | Unlimited Automated Trading | Not aimed at automated trading tools that execute directly without safety measures. | ## Installation <details> <summary>Homebrew, Windows, source build, and other installation methods</summary> ### Homebrew (macOS) ```bash brew tap JungHoonGhae/tossinvest-cli brew install tossctl ``` ### Windows (PowerShell) ```powershell irm https://raw.githubusercontent.com/JungHoonGhae/tossinvest-cli/main/install.ps1 | iex ``` The script installs to `%LOCALAPPDATA%\tossctl` and automatically adds it to your user PATH. After opening a new terminal, you can use the `tossctl` command immediately. For manual installation, download `tossctl-windows-amd64.zip` directly from [Releases](https://github.com/JungHoonGhae/tossinvest-cli/releases/latest). ### Source Build ```bash git clone https://github.com/JungHoonGhae/tossinvest-cli.git cd tossinvest-cli make build cd auth-helper python3 -m pip install -e . ``` </details> ## Command List ### Inquiry ```bashossctl account listossctl account summary tossctl portfolio positions tossctl portfolio allocation tossctl portfolio dividends [--year YYYY] [--by-payment-date] tossctl market investors|earnings|briefing|sectors|themes|index|ranking|signals tossctl community rankings --type influencer|profit|followers tossctl orders list tossctl orders completed --market us|kr|all tossctl order show <id> tossctl quote get <symbol> tossctl quote batch <symbol> [symbol...] tossctl quote orderbook|sellable|commission <symbol> tossctl watchlist list tossctl --market us|all toss orders --market us|all ``` ### Trading ```bash tossctl order preview --symbol <sym> --side <buy|sell> --qty <n> --price <krw> tossctl order preview --symbol <sym> --side buy --fractional --amount <krw> --qty 0 tossctl order place ...flags... --execute --confirm <token> tossctl order cancel-id <id> --symbol <sym> ... tossctl order amend --order-id <id> ... ``` `order cancel`, `order amend`, and `order show` can be executed without `--order-id` to select from pending/recent order lists directly. `watchlist group delete` and `rename` also work without folder names, selecting from lists. Pipes, non-TTY, and errors return without prompts, making it safe to integrate with scripts and agents. like portfolio and quotes have Korean-style profit/lossred for increase/profit, blue for decrease/loss), and work without colors, non-TTYNO_COLOR`, or `--output json|csv`. ### Real-time Push ```bash tossctl push listen # SSE subscription, JSONL stdout (exit with Ctrl+C) tossctl pushretry=false #nection ``` Sub to Toss web's SSE channels and streams `pending-order-refresh`, `purchase-price-refresh`, `share-holdings`, and `web-push` events as JSONL. Event classification and follow-up inquiry mapping are in [`docs/reverse-engineering/push-events.md`](docs/reverse-engineering/push-events.md). ### System ```bash tossctl version tossctl doctor tossctl doctor --report # JSON diagnostic bundle (for issue attachment, path redacted automatically) tossctl config init tossctl config show tossctl auth login tossctl auth status # session + Server Expiry (KST) tossctl auth extend # extend server-side ~7-day expiration with phone push approval tossctl auth doctor tossctl auth logout ``` ### Official Open API ```bash tossctl init # onboarding wizard (on first setup) tossctl openapi login # official key registration (env: TOSSCTL_OPENAPI_KEY / TOSSCTL_OPENAPI_SECRET) tossctl openapi status # key, token, and allowed IP diagnosis tossctl openapi test # connection verification tossctl openapi logout # delete credential file ``` ### API Regression Watch ```bash tossctl monitor api # 25 endpoint schema probe (parallel); exit 0 pass, 1 fail tossctl monitor api --quiet # for cron ``` Checks the response schema of 16 read-only endpoints in parallel on your machine with your session. Aims to detect [server-side body contract changes](https://github.com/JungHoonGhae/tossinvest-cli/issues/29). Returns only exit code, so users combine notification channels (Discord/Slack/ntfy/macos/email) with `|| <command>` in cron line. Recipe: [`AGENTS.md`](AGENTS.md). Setup guide: [`docs/operations.md`](docs/operations.md). ## Order Ref Rollover After `amend` or `cancel`, broker-side order ref may change. - `tossctl order show <old-id>` tracks new ref through local lineage cache. - Lineage cache: `<config dir>/trading-lineage.json` - If multiple canceled rows have the same condition, manual confirmation is required. ## Development ```bash make build make test make fmt make tidy ``` ## FAQ **Can I place orders right away?** US/KR limit buy/sell, US fractional buy, and same-day cancel are live verified. `amend` needs additional verification. All trades are executed only after enabling corresponding actions in `config.json`. **Is it an official API?** No, it's a non-official project reusing internal web APIs. **Why is Playwright needed?** Needed to secure login sessions through browser flow. Inquiry and trading logic are implemented in Go CLI. **Something seems broken. Where do I start checking?** Run `tossctl doctor -- ## Documents - [`docs/architecture.md`](docs/architecture.md) - [`docs/configuration.md`](docs/configuration.md) - [`docs/reverse-engineering/`](docs/reverse-engineering/) - [`docs/trading/`](docs/trading/) - [`auth-helper/README.md`](auth-helper/README.md) ## Local Storage Paths | Path | Description | |------|------| | `<config dir>/config.json` | Trading settings | | `<config dir>/session.json` | Browser session | | `<config dir>/trading-lineage.json` | Order ref tracking | | `<cache dir>/update-check.json` | Version, session expiry, config warning backoff cache | Paths can be overridden with `--config-dir`, `--session-file` flags. ## Contributing Feedback is welcome. Suggestions, bug reports: - Open an issue or PR on [GitHub](https://github.com/JungHoonGhae/tossinvest-cli/issues) - LinkedIn [@junghoonghae](https://www.linkedin.com/in/junghoonghae) - Email [lucas.ghae@remodule.dev](mailto:lucas.ghae@remodule.dev) ## License MIT