toss-sync

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_SECRET are 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.