AI Agent Guide

tossctl is designed for AI agents (Claude Code · Codex · Cursor · OpenClaw, etc.) to drive Toss Securities. This page lists the rules for using it safely and correctly.

LLM-ready formats: /llms.txt (curated index) · /llms-full.txt (all docs in one file).

Core rules

Always call with --output json. Table output is for humans — do not parse it.
Check the leaf command's policy. quote alert, portfolio hidden, and watchlist include writes. Inspect mutating, writes_state, environment, and the operation's mutation policy instead of inferring safety from the parent command.
Trading is disabled by default. It fails unless allowed in config.json. Do not enable it on your own — ask the user.
Always run order preview before placing to confirm quantity, price, and amount (no order is sent).
Live trades are two-step: --execute + --confirm <token>. The token comes from the preview/confirm flow — never guess or bypass it.
Settings and paper writes also need approval in the current request. Settings use a preview and state-bound confirmation; irreversible actions need an extra acknowledgement. Paper writes use separate opt-in and --execute, never reusable as live approval.
Mind PII. Responses include account numbers, balances, and holdings. Do not forward or log them externally.

Recommended workflow

1. tossctl doctor --output json        # check env & session
2. (if no session) ask the user to run `tossctl auth login`
3. tossctl account summary --output json
4. tossctl portfolio positions --output json
5. (on a trade request) tossctl order preview ... --output json  → user confirmation
6. a human performs the final live-order confirmation (no automatic agent submission)

Session & auth

A session is created once by a human via tossctl auth login (QR + phone approval). Agents cannot log in — if there's no session, ask the user to.
Near expiry, a stderr warning appears. Extend via phone push with tossctl auth extend.
Use tossctl auth status --output json to check validity/expiry programmatically.

Official Open API (optional) — better for unattended runs

Registering an official Toss Open API key routes officially-supported reads/trades through OAuth with tokens that auto-refresh. The web session (WTS) has a ~7-day activity expiry that needs periodic phone approval; the official path has no such limit, which suits CI, servers, and long-running agents. WTS features work with a web session, but official-only reads, conditional orders, and stream require an official key.

Non-interactive setup: set TOSSCTL_OPENAPI_KEY / TOSSCTL_OPENAPI_SECRET env vars, then tossctl openapi login (flags also work). The credential file is saved 0600.
tossctl openapi status --output json — diagnose key / token / allowed IPs / routing. The key needs an allowed-IP entry; the IP list lookup itself requires a WTS session.
tossctl openapi ip replace-current --output json — preview replacement of the existing list with the current public IP. Apply only after user approval with --execute --confirm <token> using the preview's confirm_token; every mutation is verified and failures reconcile the previous allowlist from server state.
tossctl <command> --backend auto|wts|openapi — pick the routing backend per request.
First-time setup is also available via the tossctl init wizard.
Details: Official Open API Auto-routing.

Output contract

On success, JSON on stdout; on failure, a non-zero exit code + stderr message.
tossctl monitor api checks 86 read endpoints by default, plus four paper probes after opt-in. It does not guarantee detection of every outage or data error.

Don't

Leave real account data in public output, commits, or logs.
Place orders without preview, guess --confirm tokens, or bypass the trade gate.
Parse table output (human-formatted, fragile) — always JSON.
Automatically run tossctl update. Use read-only tossctl update --check for version checks.

Local history and smaller responses

Use --fields to select JSON paths and --compact to remove indentation: tossctl portfolio positions --fields symbol,quantity --compact. Missing fields are omitted; inspect full JSON first. Preserve snapshot freshness, range, complete, and warnings when reading history, and partial/sections for briefings. history sync is a local write: execute only when the current request authorizes saving, using its preview confirmation token. See the history guide.