FAQ

Common questions. If yours isn't here, open an issue on GitHub.

General

Is this legal? Is it official?

This is not an official Toss Securities product. Its WTS features reuse the internal web API unofficially, which may violate their Terms of Service. The API can change without notice, and you bear the risk of account restrictions, losses, or other consequences.

How does it relate to the official Open API?

tossctl adds WTS-only investor flows, AI signals, dividends, and watchlists to official accounts, quotes, and orders. Features, endpoints, and operations are different units, so we do not compare them as a percentage. See Support Scope.

What happens as the official API grows?

We track official API changes and update supported routes. WTS-session features and official-key-only features differ; supported reads prefer the official API by default.

Install

What do I need?

General reads need the binary and the feature's credentials. WTS login needs Chrome, Python 3.11+, Playwright, and auth-helper. Installers do not install Chrome or Python themselves; check with tossctl doctor.

Does it work on Windows?

Yes. Install via PowerShell (irm https://raw.githubusercontent.com/JungHoonGhae/tossinvest-cli/main/install.ps1 | iex) or a GitHub Releases binary.

Auth & sessions

Login succeeds but auth status is invalid / rejected (400·401·403)

Session expiry, missing persistence approval, or mismatched authentication environments can cause failures. Diagnose with tossctl doctor --report and tossctl auth status, then log in again if needed. Versions before v0.10.1 also had an OS User-Agent mismatch bug, but not every auth failure has that cause.

tossctl auth logout
tossctl auth login
tossctl auth status   # expect 'Live Check: valid'

My session drops after ~1 hour

After scanning the QR, you must tap the "keep this device signed in" confirmation on your phone to get a persistent session. Verify tossctl auth status shows Persistence: persistent cookie (expires ...).

My session expires every ~7 days

Toss enforces a ~7-day server-side activity expiry separate from the SESSION cookie. From 24h before expiry a warning appears; run tossctl auth extend to renew via a push approval in the Toss app — no re-login needed.

Headless environments (SSH servers, CI)?

tossctl auth login --headless [--qr-output /tmp/toss-qr.png]. The QR URL and answer letter print to stderr; forward the URL to your phone to authenticate without a camera.

Trading

Can an order fire by accident?

Live trading is blocked by default. Trading is fully off out of the box and must be enabled per-action in config.json. Live orders require a two-step --execute + --confirm <token>, and tossctl order preview lets you check first. See Safety Model.

Which orders are supported?

KR/US regular orders, cancels, amends, official conditional orders, and US market fractional buys (amount) and sells (quantity). Fractional sells are contract-tested but not live-verified. Check Support Scope and command help for constraints.

Agents & output

How do agents integrate?

General read commands emit structured results via --output json, and the rules for safe, correct agent use are in the AI Agent Guide. For direct LLM ingestion there's also /llms.txt and /llms-full.txt.

Output formats?

table · JSON · CSV · SSE — drop straight into scripts and pipelines.

Getting help

Open an issue on GitHub. Including tossctl doctor --report output speeds up diagnosis (home paths and some identifiers are masked; review the output before sharing).