By name: toss-sync description: Sync portfolio from Toss Securities. Use when user mentions "토스", "Toss", "토스에서", "토스 동기화", "sync from toss", "toss 조회", or wants to update their portfolio from their brokerage account.
Toss Securities Portfolio Sync
Sync holdings from Toss Securities into the local portfolio tracker. The
official Toss Open API (OAuth2) is the default source; the legacy tossctl
CLI is used as a fallback when API credentials are not configured.
Prerequisites
Official Open API (preferred)
Set both credentials in .env (issued in the Toss Securities app:
더보기 → Open API → 신청):
TOSS_CLIENT_ID=...
TOSS_CLIENT_SECRET=...
# TOSS_OPENAPI_BASE_URL=https://openapi.tossinvest.com # optional override
No browser, QR scan, or session re-login is needed — the OAuth token is issued and refreshed automatically.
tossctl fallback (only if no API credentials)
- Install:
curl -fsSL https://raw.githubusercontent.com/JungHoonGhae/tossinvest-cli/main/install.sh | sudo sh - Log in:
tossctl auth login(requires Chrome + QR code scan from Toss app) - Check status:
tossctl doctor
Sync Workflow
Step 1: Sync from Toss
Preview changes first:
./bin/stock-cli portfolio sync --dry-run
Apply sync:
./bin/stock-cli portfolio sync
This will:
- Fetch current positions from Toss (Open API by default, tossctl fallback)
- Auto-create KR and US portfolios if they don't exist
- Compare Toss holdings with local portfolio.db
- Record synthetic BUY/SELL transactions for any differences
- Subsequent syncs are idempotent (no changes if already in sync)
- The output JSON includes
"source": "toss-api"or"tossctl"so you can confirm which path ran
Force a specific source if needed:
./bin/stock-cli portfolio sync --source toss-api --dry-run
./bin/stock-cli portfolio sync --source tossctl --dry-run
Step 2: Evaluate (optional)
After sync, evaluate the portfolio:
./bin/stock-cli portfolio report --market KR
./bin/stock-cli portfolio report --market US
./bin/stock-cli portfolio risk --market US
Sync one market only
./bin/stock-cli portfolio sync --market KR
./bin/stock-cli portfolio sync --market US
Auth troubleshooting
- Open API: the OAuth token is refreshed automatically, so there is no
session to expire. An auth error means
TOSS_CLIENT_ID/TOSS_CLIENT_SECRETare missing or invalid — verify them in.env. - tossctl fallback: sessions expire after inactivity. Re-login with
tossctl auth login, then retry the sync.
Common User Triggers
When the user says any of these, run the sync:
- "토스에서 가져와줘"
- "토스 동기화해줘"
- "토스 조회해줘"
- "Toss에서 내 포트폴리오 가져와"
- "sync from toss"
- "update from brokerage"
Always run --dry-run first and show the user what will change before applying.