Official Open API Auto-routing

A web session (WTS) supports implemented WTS features and most hybrid reads and regular CLI orders. An official key adds official routing and official-only commands such as account buying-power, market business-days|stocks, quote metadata, conditional orders, and stream. A web session alone does not cover the entire CLI.

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 adds Securities features 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.

Real scenarios — what the official API can't, and tossctl can

What "broader scope" actually means. Official-only ❌ → tossctl (incl. WTS) ✅:

Taxes & P&L (your account ledger)

Market flows & indices

Research & account dashboard

Combine data in external analysis

These examples combine source data; they do not provide automatic tax filing or total-return calculations. Check date ranges and pagination limits.

Securities WTS and the general Toss app are separate

The current WTS extension covers Toss Securities: implemented features such as investor flows, indices, AI signals, and screeners. General Toss card payments, monthly spending, and bank transaction histories are not supported.

Screens in the same app do not imply shared credentials, consent, or permissions. Banking requires separate API and authorization verification; a WTS cookie is not assumed to grant access.

How auto-routing works

Each command declares a source=official|wts|both|local policy. A both read normally checks the official key and preference before choosing its starting route.

Eligible read fallback errors are transport errors, auth/IP errors, 429, and 5xx. Other domain 4xx errors pass through. Orders and settings writes never cross-fallback. --backend openapi preserves the read fallback setting; set openapi.fallback=false as well to restrict supported reads to the official path.

An exception is market fx: it starts with WTS to preserve the broader FX feed and attempts official USD/KRW on failure. Check command help, the catalog, and Support Scope for each route.

Which auth do you need?

Getting your official Open API key

1. Check eligibility — Consult the official overview for current application and access requirements.
2. Official docs — Full spec at developers.tossinvest.com/docs.
3. Issue the key — Follow the official Open API settings available to your account to generate an API Key and Secret.
4. Allowed IPs — Check that your machine's egress IP is registered. 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
# → <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

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   # prefer official (keeps fallback setting)
tossctl account summary --backend wts        # pin WTS (disables official)
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
  }
}

Response scope and ordering

• quote chart and ops/MCP candles return oldest first, consistently across table, JSON and CSV. Official newest-first responses are normalized to the WTS chart convention; the last candle is the latest.
• market indicator-candles preserves the official newest-first page. next_before addresses an older page.
• Official ops/MCP orders and order only expose supported order types, including limit, market and limit-on-close. Unsupported types such as pre/post-market closing-price orders are excluded from both lists and detail. Reading every page or receiving an empty list does not establish the full order history. WTS queries have a different scope; these omissions are not HTTP errors and do not trigger automatic fallback.
• stream infers numeric-leading six-character alphanumeric codes (005930, 0101N0) as KR. This is client classification, not a guarantee that the server supports subscriptions for each symbol.

For market business-days KR, after_market spans the KRX/NXT after-market union. The server's earliest start and latest end are preserved. The session is omitted only when both exchanges close their after-market; its presence does not establish NXT availability. single_price_auction_end is NXT-based and omitted from JSON when NXT closes. holiday: true means the day has no sessions. Pre/post-market closing-price sessions are excluded.

For official ops/MCP stock_supply with type=short, rates are server-provided decimal ratios (for example, 0.0318 = 3.18%). Their denominators are daily cumulative volume and amount, including pre/post-market closing-price sessions and the after-market. null means the baseline data is unavailable; 0 is returned when the baseline is zero. In tossctl JSON, a rate field is omitted for an upstream null, while numeric 0 is retained.

Fallback and source display

For an eligible read error with an equivalent WTS implementation and fallback enabled, tossctl reports the switch on stderr:

tossctl: official path unavailable, falling back to web session (…)

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

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