Official Open API Auto-routing

tossctl works fully with just a web session (WTS). Registering an official Toss Open API key turns on auto-routing: features the official API supports go through the official OAuth path, and everything else goes through WTS. Everything works without a key too, and you can add one whenever you like.

Official Open API vs WTS web session

These are the two paths tossctl uses to reach Toss Securities. They behave differently, so understanding the difference tells you which combination you need.

In short — the official API is stable but narrow; WTS covers everything but is unofficial and its session expires more often. tossctl combines them: officially-covered requests go through the official path (stability), the rest through WTS (coverage), routed automatically.

The official API lags by structure, not neglect

On any platform, the first-party app is where the core experience lives. It is also the best place to ship and integrate new features fast, so new capabilities naturally land in the app (WTS) first. A public API carries real versioning, compatibility, and support costs, so it opens a carefully chosen, stable subset afterwards. The official API being conservative is reasonable, not stingy.

As a result, the most Toss-flavored capabilities (investor flows, indices, AI signals, screener, real-time push) arrive in the app first and fastest. That is not anyone's fault, it is the shape of the platform. tossctl works with that shape rather than against it: it uses the path the app itself uses (WTS as the primary path) so you can use those features now, while auto-routing officially-supported features through the official path to keep stability.

How auto-routing works

For each request, the router checks "is it officially supported → is a key present → preference".

• Reads and trades the official API supports are routed via OAuth token, which is more stable
• Features outside the official scope (flows, indices, AI signals, etc.) always go through WTS
• If the official route is temporarily unavailable, tossctl auto-falls back to WTS (one-line stderr notice)
• Orders never cross-fallback (a failed official route errors out rather than risk a duplicate order)

Which auth do you need?

Getting your official Open API key

1. Pre-registration — Apply at corp.tossinvest.com/ko/open-api.
2. Official docs — Full spec at developers.tossinvest.com/docs.
3. Issue the key — After approval, go to Toss app → Settings → Open API to generate your API Key and Secret.
4. Allowed IPs — The IP of the machine you use the key from is usually registered automatically. If you need other IPs (e.g., a server), add them via WTS (Toss web). Requests from unlisted IPs are blocked (diagnose with tossctl openapi status; the IP list lookup needs a web session).

Secret handling

Recommended (in order of preference)

① Environment variables (CI, agents, automation)

export TOSSCTL_OPENAPI_KEY=tsck_live_xxxxxxxxxxxxxxxxxxxx
export TOSSCTL_OPENAPI_SECRET=tssk_live_xxxxxxxxxxxxxxxxxxxx
tossctl openapi status   # auto-reads env vars

② Credentials file written by tossctl openapi login (personal dev machine)

tossctl openapi login \
  --key tsck_live_xxxxxxxxxxxxxxxxxxxx \
  --secret tssk_live_xxxxxxxxxxxxxxxxxxxx
# → <config dir>/openapi-credentials.json (mode 0600)

Never do this

• Paste plaintext keys or secrets into chat, issues, PRs, commits, screenshots, or logs
• Hardcode them in config.json, source code, or documentation
• Pass --key/--secret flags directly on the command line (shell history exposure) — use env vars instead
• Set allowed IPs to 0.0.0.0/0 or an unrestricted range
• If you suspect a compromise, re-issue immediately from the Toss app

Onboarding wizard

First time? Run tossctl init for a guided setup.

tossctl init
# Checks web session → prompts for official key (optional) → configures trading settings

Official key management commands

Register / update

# Pass via env or enter interactively
tossctl openapi login
tossctl openapi login --key tsck_live_xxxx --secret tssk_live_xxxx

Status and diagnostics

tossctl openapi status
# Example output:
#   Official key : ✓ (set via file)
#   Token        : valid (expires in 23m 41s)
#   Allowed IPs  : 203.0.113.42 ✓ (current IP matches)   # needs a web session
#   Routing      : auto (official + wts)

status explains common failure causes:

• IP not allowed — your egress IP is not in the key's allowlist
• IP lookup failed (web session required) — the allowed-IP lookup needs a WTS session first (tossctl auth login)
• token expired — auto-renewed; force manual refresh: tossctl openapi login
• key not set — set env vars or run openapi login

Connection test

tossctl openapi test
# Makes a real API call to validate key + IP + token

Log out (delete credentials file)

tossctl openapi logout

Backend routing control

Global flag --backend

tossctl account summary --backend openapi   # force the official path
tossctl account summary --backend wts        # force the WTS path
tossctl account summary --backend auto       # default: auto-routing

official keeps working as a deprecated alias for openapi (--backend official, openapi.prefer: "official"). Use openapi for new setups.

Config keys openapi.*

{
  "openapi": {
    "enabled": true,
    "prefer": "openapi",
    "fallback": true
  }
}

Fallback and source display

When the official route is temporarily unavailable, tossctl switches to WTS and prints one line to stderr:

[tossctl] official route unavailable, falling back to wts (account summary)

If fallbacks are frequent, run tossctl openapi status and tossctl doctor to diagnose.

For the full list of officially-supported features, see Support Scope.