토스증권 웹에 로그인된 전용 Chrome 프로필을 브리지가 직접 소유하고, 브라우저 컨텍스트 안에서 read-only 조회를 수행하는 로컬 daemon/CLI 프로젝트다.
공식 토스증권 API 프로젝트가 아니다. browser-attached companion 성격의 비공식 read-only 도구다.
정식 지원 범위는 macOS desktop + 로컬 Google Chrome이다.
healthopen-loginaccount-summarypositionscompleted-ordersquoteorder-previewfx-previewplace-order(guarded preflight only, final submit blocked)verify-order(journal-backed recovery over current verify signals)reconnectshutdowndiagnostics
설치형 canonical path는 repo checkout 없이 toss-bridge ...만 호출하는 것이다.
예시:
uv tool install /path/to/toss-browser-bridge
toss-bridge health
toss-bridge open-login
toss-bridge account-summary
toss-bridge order-preview --market us --side buy --symbol AAPL --order-type market --quantity 1
toss-bridge fx-preview --side buy --amount-krw 100000
toss-bridge place-order --preview-receipt-file /tmp/order-preview.json --preview-fingerprint sha256:... --confirm --confirm-text "BUY 3 AAPL LIMIT 201.50 US"설치형 경로에서도 daemon bootstrap은 현재 설치된 Python 환경에서 직접 올라간다. canonical path에서 repo-local uv run --project . ... 재호출에 의존하지 않는다.
uv run --project . toss-bridge health
uv run --project . toss-bridge open-login
uv run --project . toss-bridge account-summary
uv run --project . toss-bridge order-preview --market us --side buy --symbol AAPL --order-type market --quantity 1
uv run --project . toss-bridge fx-preview --side buy --amount-krw 100000
uv run --project . toss-bridge place-order --preview-receipt-file /tmp/order-preview.json --preview-fingerprint sha256:... --confirm --confirm-text "BUY 3 AAPL LIMIT 201.50 US"
uv run --project . --extra dev pytest
TOSS_BRIDGE_LIVE_E2E=1 uv run --project . --extra dev pytest tests/test_live_e2e.py -q
sh scripts/scrub-check.sh개발 중에는 repo 안에서 uv run --project . ...를 써도 되지만, 소비 프로젝트와 실제 운영 경로는 설치형 toss-bridge를 기준으로 본다.
런타임 상태는 기본적으로 아래 경로를 사용한다.
~/Library/Application Support/toss-browser-bridge/chrome-profile~/Library/Application Support/toss-browser-bridge/token~/Library/Application Support/toss-browser-bridge/daemon.pid~/Library/Application Support/toss-browser-bridge/daemon.log~/Library/Application Support/toss-browser-bridge/mutation-journal.jsonl
TOSS_BRIDGE_HOME 환경변수로 override 가능하다.
기본 listen 포트는 42194이며, TOSS_BRIDGE_PORT로 override 가능하다.
기존 financier-v2 내장 bridge와 같은 머신에서 함께 돌릴 때는 포트를 분리해야 한다.
데이터는 페이지 안 fetch(credentials:include)로 가져오고 브라우저는 로그인 세션 + 요청 서명 호스트 역할만 한다. 따라서 렌더링(GPU·이미지)은 순수 오버헤드이며 다음 토글로 끌 수 있다. 둘 다 미설정이 기본이며 현행 동작(headed)과 동일하다.
| 환경변수 | 기본 | 동작 |
|---|---|---|
TOSS_BRIDGE_HEADLESS |
off | on이면 headless로 기동(창 없음). Chrome RSS 대폭 절감 |
TOSS_BRIDGE_LEAN |
off | on이면 GPU·이미지 디코드 비활성 등 경량 플래그 적용 |
값은 1/true/yes/on이 활성, 그 외(off/오타/미설정)는 전부 비활성으로 안전하게 처리된다.
headless는 화면이 없어 최초 로그인·세션 갱신(인증서/2FA) UI를 띄울 수 없다. 운용 모델은 headed로 한 번 로그인 → 세션이 chrome-profile에 잔존 → TOSS_BRIDGE_HEADLESS=on으로 재기동이다. 세션 만료 시 health가 attached_but_logged_out을 반환하므로, headed로 재기동해 재로그인한다. 토스 anti-automation 차단 가능성이 있어 조회 경로부터 검증 후 주문에 적용하기를 권장한다.
- logged out capability matrix: examples/health-attached-but-logged-out.json
- install guide: docs/installing.md
- runtime contract: docs/runtime-contract.md
- consumer integration: docs/consumer-integration.md
- preview layer guide: docs/preview-layer.md
- supervised submit guide: docs/guarded-submit-supervised-validation.md
- browser-attached read + preview
- zero-money guarded submit preflight
- browser-attached only
- Toss Securities web dependency
- daemon과 전용 Chrome 프로필은 세션 동안 한 번만 올려 두고 유지한다.
- discovery, preview, submit, verify는 이미 붙어 있는 daemon/browser 컨텍스트를 기준으로 진행한다.
- stale daemon을 정리해야 할 명확한 이유가 없는 한, 검증 중 daemon을 반복 재기동하지 않는다.
- final submit unlock은 기본값이 아니며, pytest 경로에서는 환경변수로 요청해도 차단된다.
- 실제 주문 create / verify / 정정 / 취소 / 환전
- 공식 API 안정성 보장
- 헤드리스 세션 재생
- 토스증권 웹 구조나 내부 endpoint가 바뀌면 깨질 수 있다.
- 전용 Chrome 프로필에 직접 로그인해야 한다.
health가attached_but_logged_out일 때는 브라우저 연결만 성공한 상태다.place-order는 fresh preview 재검증,preparepreflight, duplicate-prevention까지만 수행하고, 최종 submit은 아직 막아 둔다.verify-order는 mutation journal과 현재 read signal을 조합해verified_failed/verified_success/unknown을 판정한다. final create 이후 supervised submit만 아직 미구현이다.