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.
Read first. account, portfolio, quote, market, transactions are side-effect free.
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.
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. only after approval: tossctl order place ... --execute --confirm <token>

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. Everything still works without a 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 <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.
Quote/summary types have stable keys. Server-side changes are caught early by tossctl monitor api.

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.