Quick Start

Choose your setup

tossctl reaches Toss Securities through two paths — the WTS web session (unofficial, full feature set) and the official Open API (official, stable but narrower). Pick what fits.

Setup	How	Best for
① Fast start · WTS only	one `tossctl auth login`	Fastest, full features. No application needed. Session needs phone approval ~every 7 days
② Official API only · openapi	`tossctl openapi login`	Officially-supported features only (narrow). Tokens auto-refresh → great for unattended runs (CI/servers). Needs application + IP registration
③ Both · auto-routing (recommended)	register both	Max stability + full scope. Officially-supported requests use the official path, the rest WTS

Most people just start with ① (step 1 below). The official key issuance steps, how auto-routing works, and the difference between the two paths are covered in the Official Open API Auto-routing guide. New here? The tossctl init wizard walks you through choosing a setup end to end.

1. Log in (WTS web session)

tossctl auth login

When the QR appears, scan it with the Toss app on your phone and be sure to tap the "keep this device signed in" confirmation. Skipping that second step expires the session after ~1h idle.

Check:

tossctl auth status
# "Persistence: persistent cookie (expires ...)" means you're good

Headless environments (SSH servers, CI)

tossctl auth login --headless --qr-output /tmp/toss-qr.png

The QR URL and answer letter are printed to stderr. Forward the URL to your phone and tap it to authenticate without a camera.

Extending the session

Toss enforces an ~7-day server-side activity expiry. From 24h before expiry a warning is shown, and you can extend without re-login via a push approval on your phone:

tossctl auth extend

2. Read

tossctl account summary             # account summary
tossctl portfolio positions         # holdings
tossctl quote get 005930            # KR quote (6-digit code auto-detected)
tossctl quote get TSLA              # US quote
tossctl market index                # major indices
tossctl market index nasdaq         # index detail (OHLC, 52w)

Every read command supports --output json|csv|table.

tossctl account summary --output json

3. Trade (optional, disabled by default)

Trading must be explicitly enabled in config.json, and you should always preview first.

# 1) dry-run preview (no order is sent)
tossctl order preview --symbol TSLA --side buy --qty 1 --price 250

# 2) live execution — two-step gate
tossctl order place --symbol TSLA --side buy --qty 1 --price 250 --execute --confirm <token>

See the Safety Model for all guardrails.