{"_id":"@2oolkit/toss-cli","_rev":"3-86206a5bfab93747449c016186423686","name":"@2oolkit/toss-cli","dist-tags":{"latest":"0.1.2"},"versions":{"0.1.0":{"name":"@2oolkit/toss-cli","version":"0.1.0","keywords":["toss","tossinvest","toss-securities","토스증권","korea","krx","kospi","kosdaq","stock","stocks","equities","trading","brokerage","cli","mcp","model-context-protocol","ai-agent","claude","cursor","windsurf","openapi","rest"],"author":{"name":"haeminmoon"},"license":"MIT","_id":"@2oolkit/toss-cli@0.1.0","maintainers":[{"name":"haeminmoon","email":"mym0846@gmail.com"}],"homepage":"https://github.com/haeminmoon/toss-cli#readme","bugs":{"url":"https://github.com/haeminmoon/toss-cli/issues"},"bin":{"toss-cli":"dist/index.js","toss-mcp":"dist/mcp.js"},"dist":{"shasum":"d1f778591ea2f5993264e8d4705bfa716a92f1d0","tarball":"https://registry.npmjs.org/@2oolkit/toss-cli/-/toss-cli-0.1.0.tgz","fileCount":11,"integrity":"sha512-jRQ+I6xNAoHvogSW7yeh8R+E1REKmhwA03wtqHSD4osEeEdLG2wMTD9Dfxkbss2TvCAkVeAab/C1eJKloFQodA==","signatures":[{"sig":"MEQCIE85jMxY08UVAACg7rhCpZnBbJm4wlrb5+xXPmfzzJVyAiBzY1Uu9eaqaxRKUULEkL9YrxJDdpUnIgS43+n1XvtYoA==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":281288},"type":"commonjs","engines":{"node":">=20"},"gitHead":"0ccb31222c6bee49c64c5b1fb2ed87989a6efc93","scripts":{"dev":"ts-node src/index.ts","lint":"tsc --noEmit","test":"jest","build":"tsup","test:watch":"jest --watch","test:coverage":"jest --coverage","prepublishOnly":"npm run build"},"_npmUser":{"name":"haeminmoon","email":"mym0846@gmail.com"},"repository":{"url":"git+https://github.com/haeminmoon/toss-cli.git","type":"git"},"_npmVersion":"11.4.2","description":"CLI & MCP server for the Toss Securities (토스증권) Open API — query KR/US stock prices, manage your account, and place orders","directories":{},"_nodeVersion":"24.4.1","dependencies":{"zod":"3.24.4","commander":"^13.1.0","@modelcontextprotocol/sdk":"1.27.1"},"_hasShrinkwrap":false,"devDependencies":{"jest":"^29.7.0","tsup":"^8.3.0","ts-jest":"^29.2.5","ts-node":"^10.9.2","typescript":"^5.7.0","@types/jest":"^30.0.0","@types/node":"^22.10.0"},"_npmOperationalInternal":{"tmp":"tmp/toss-cli_0.1.0_1782118721694_0.41535008609857615","host":"s3://npm-registry-packages-npm-production"}},"0.1.1":{"name":"@2oolkit/toss-cli","version":"0.1.1","keywords":["toss","tossinvest","toss-securities","토스증권","korea","krx","kospi","kosdaq","stock","stocks","equities","trading","brokerage","cli","mcp","model-context-protocol","ai-agent","claude","cursor","windsurf","openapi","rest"],"author":{"name":"haeminmoon"},"license":"MIT","_id":"@2oolkit/toss-cli@0.1.1","maintainers":[{"name":"haeminmoon","email":"mym0846@gmail.com"}],"homepage":"https://github.com/haeminmoon/toss-cli#readme","bugs":{"url":"https://github.com/haeminmoon/toss-cli/issues"},"bin":{"toss-cli":"dist/index.js","toss-mcp":"dist/mcp.js"},"dist":{"shasum":"66762cbaa357cc7b1a8ddf3e19f3788eb6e169bb","tarball":"https://registry.npmjs.org/@2oolkit/toss-cli/-/toss-cli-0.1.1.tgz","fileCount":11,"integrity":"sha512-+3R3hc4RRg2vSjhC+y2HEeSMikb02YyzIauoS/ldMsZ+d67inCtDflplIc32Gjd4DS1if9osNW0LbiJFnS6k7Q==","signatures":[{"sig":"MEUCIQDkzsU/NYYYMVFj+j4cl6EtfNRLymjwwYuKd3l56fD07gIgQQ7QmO12Y/W44faaNhDd4Uitj58M47VDO9IKVLzQqac=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":281962},"type":"commonjs","engines":{"node":">=20"},"gitHead":"36cf92382ad6385c9ad2d1dd53070b6f09389522","scripts":{"dev":"ts-node src/index.ts","lint":"tsc --noEmit","test":"jest","build":"tsup","test:watch":"jest --watch","test:coverage":"jest --coverage","prepublishOnly":"npm run build"},"_npmUser":{"name":"haeminmoon","email":"mym0846@gmail.com"},"repository":{"url":"git+https://github.com/haeminmoon/toss-cli.git","type":"git"},"_npmVersion":"11.4.2","description":"CLI & MCP server for the Toss Securities (토스증권) Open API — query KR/US stock prices, manage your account, and place orders","directories":{},"_nodeVersion":"24.4.1","dependencies":{"zod":"3.24.4","commander":"^13.1.0","@modelcontextprotocol/sdk":"1.27.1"},"_hasShrinkwrap":false,"devDependencies":{"jest":"^29.7.0","tsup":"^8.3.0","ts-jest":"^29.2.5","ts-node":"^10.9.2","typescript":"^5.7.0","@types/jest":"^30.0.0","@types/node":"^22.10.0"},"_npmOperationalInternal":{"tmp":"tmp/toss-cli_0.1.1_1782119534935_0.7608984359471229","host":"s3://npm-registry-packages-npm-production"}},"0.1.2":{"name":"@2oolkit/toss-cli","version":"0.1.2","description":"CLI & MCP server for the Toss Securities (토스증권) Open API — query KR/US stock prices, manage your account, and place orders","author":{"name":"haeminmoon"},"license":"MIT","homepage":"https://github.com/haeminmoon/toss-cli#readme","bugs":{"url":"https://github.com/haeminmoon/toss-cli/issues"},"repository":{"type":"git","url":"git+https://github.com/haeminmoon/toss-cli.git"},"keywords":["toss","tossinvest","toss-securities","토스증권","korea","krx","kospi","kosdaq","stock","stocks","equities","trading","brokerage","cli","mcp","model-context-protocol","ai-agent","claude","cursor","windsurf","openapi","rest"],"type":"commonjs","bin":{"toss-cli":"dist/index.js","toss-mcp":"dist/mcp.js"},"scripts":{"build":"tsup","dev":"ts-node src/index.ts","lint":"tsc --noEmit","test":"jest","test:watch":"jest --watch","test:coverage":"jest --coverage","prepublishOnly":"npm run build"},"dependencies":{"@modelcontextprotocol/sdk":"1.27.1","commander":"^13.1.0","zod":"3.24.4"},"devDependencies":{"@types/jest":"^30.0.0","@types/node":"^22.10.0","jest":"^29.7.0","ts-jest":"^29.2.5","ts-node":"^10.9.2","tsup":"^8.3.0","typescript":"^5.7.0"},"engines":{"node":">=20"},"_id":"@2oolkit/toss-cli@0.1.2","_nodeVersion":"24.4.1","_npmVersion":"11.4.2","dist":{"integrity":"sha512-nx+EwLUvCovxmmvG/1j15SXySVs9PWIr9EKlqjX3BqA634LtE4UWF9JBfzJkTLeQa4MkqgtWnyqY5aGaQhrV+Q==","shasum":"39da4ef1fa1c0368d9437a56d8c3d6ff457b1cde","tarball":"https://registry.npmjs.org/@2oolkit/toss-cli/-/toss-cli-0.1.2.tgz","fileCount":11,"unpackedSize":297538,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIHvW6HcPn1gpj6tx8GdkWRknJ/7/pgQ9p3Z8qRo8NfC5AiEA0hECl01pVvZftcK1iZi1ACl0XZRT2YTsnHtTJT2u4Og="}]},"_npmUser":{"name":"haeminmoon","email":"mym0846@gmail.com"},"directories":{},"maintainers":[{"name":"haeminmoon","email":"mym0846@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/toss-cli_0.1.2_1782175004539_0.45632132059501873"},"_hasShrinkwrap":false}},"time":{"created":"2026-06-22T08:58:41.574Z","modified":"2026-06-23T00:36:44.792Z","0.1.0":"2026-06-22T08:58:41.863Z","0.1.1":"2026-06-22T09:12:15.077Z","0.1.2":"2026-06-23T00:36:44.681Z"},"bugs":{"url":"https://github.com/haeminmoon/toss-cli/issues"},"author":{"name":"haeminmoon"},"license":"MIT","homepage":"https://github.com/haeminmoon/toss-cli#readme","keywords":["toss","tossinvest","toss-securities","토스증권","korea","krx","kospi","kosdaq","stock","stocks","equities","trading","brokerage","cli","mcp","model-context-protocol","ai-agent","claude","cursor","windsurf","openapi","rest"],"repository":{"type":"git","url":"git+https://github.com/haeminmoon/toss-cli.git"},"description":"CLI & MCP server for the Toss Securities (토스증권) Open API — query KR/US stock prices, manage your account, and place orders","maintainers":[{"name":"haeminmoon","email":"mym0846@gmail.com"}],"readme":"# toss-cli\n\n[토스증권 Open API](https://developers.tossinvest.com/docs)를 위한 **CLI 겸 MCP 서버**입니다. 국내(KRX)·미국 주식의 시세·호가·캔들·시장정보를 조회하고, 계좌와 보유 주식을 확인하며, 주문 생성·정정·취소까지 터미널이나 AI 에이전트에서 바로 할 수 있습니다.\n\n> ⚠️ **실거래 계좌에 연결됩니다.** 주문 명령은 실제 돈으로 진짜 주문을 넣습니다. 매매 전 [안전](#안전)을 꼭 읽어보세요.\n\n## 기능\n\n- 📈 **시세** — 현재가(다건), 호가, 최근 체결, 상/하한가, OHLCV 캔들\n- 🏷️ **종목 정보** — 종목 마스터(종목명·시장·통화·상장상태)와 매수 유의사항/VI\n- 🌐 **시장 정보** — KRW↔USD 환율, 국내·미국 장 운영 시간\n- 💼 **계좌** — 계좌 목록, 보유 주식, 매수 가능 금액, 판매 가능 수량, 수수료\n- 🧾 **주문** — 생성 / 정정 / 취소 / 목록 / 상세 (국내·미국, 지정가·시장가, 수량·금액 기반)\n- 🤖 **MCP 서버** — 모든 조회·매매 기능을 Claude, Cursor, Windsurf 등에서 쓸 수 있는 툴로 제공\n- 🔐 **OAuth2** — 액세스 토큰 자동 발급·캐싱 (클라이언트당 토큰 1개, 만료 직전까지 재사용)\n- 🧰 모든 명령에서 JSON 또는 table 출력 지원\n\n## 설치\n\n```bash\nnpm install -g @2oolkit/toss-cli\n```\n\n설치 없이 바로 실행:\n\n```bash\nnpx @2oolkit/toss-cli market price 005930\n```\n\nNode.js 20 이상이 필요합니다.\n\n## 빠른 시작\n\n1. 토스증권 WTS에서 **설정 → Open API** 메뉴로 들어가 **client_id**와 **client_secret**을 발급받습니다.\n2. CLI를 설정합니다:\n\n   ```bash\n   toss-cli config init\n   ```\n\n   크리덴셜을 `~/.toss-cli/config.json`(권한 `0600`)에 저장하고 계좌를 자동 선택합니다.\n\n3. 바로 조회:\n\n   ```bash\n   toss-cli market price 005930,AAPL\n   toss-cli account holdings\n   toss-cli order list --status OPEN\n   ```\n\n## 설정\n\n설정값은 `~/.toss-cli/config.json`을 먼저 읽고, 없으면 환경변수로 폴백합니다:\n\n| 설정 키        | 환경변수              | 설명                                   |\n| ------------- | --------------------- | -------------------------------------- |\n| `clientId`    | `TOSS_CLIENT_ID`      | OAuth2 client_id                       |\n| `clientSecret`| `TOSS_CLIENT_SECRET`  | OAuth2 client_secret                   |\n| `accountSeq`  | `TOSS_ACCOUNT_SEQ`    | 계좌/주문 명령의 기본 계좌             |\n| `baseUrl`     | `TOSS_API_BASE_URL`   | API base URL 오버라이드(기본: 운영)    |\n\n```bash\ntoss-cli config set --client-id tsck_live_xxx --client-secret tssk_live_yyy\ntoss-cli config set --account 1\ntoss-cli config list      # 시크릿은 마스킹되어 표시됩니다\ntoss-cli config path\ntoss-cli config logout    # 저장된 크리덴셜 + 캐시 토큰 삭제\ntoss-cli config logout --keep-credentials   # 캐시 토큰만 비우기(강제 재인증)\n```\n\n> **권장:** 시크릿을 CLI 인자로 넘기는 `config set --client-secret <값>`보다 `config init`(에코 없는 숨김 프롬프트)이나 환경변수를 쓰세요. 인자로 넘긴 시크릿은 셸 히스토리와 프로세스 목록(`ps`)에 노출될 수 있습니다.\n\nOAuth2 액세스 토큰은 `~/.toss-cli/token.json`에 캐시되어 만료 직전까지 재사용됩니다. 토스는 **클라이언트당 유효한 토큰이 1개**(재발급 시 이전 토큰 즉시 무효화)이므로, 이 캐싱이 동시 세션이 서로의 토큰을 무효화하는 것을 막아줍니다.\n\n## 명령어\n\n모든 명령은 `-o, --output <json|table>`(기본 `table`)을 지원합니다. 계좌/주문 명령은 `-a, --account <accountSeq>`로 기본 계좌를 덮어쓸 수 있습니다.\n\n### 시세 (`market`)\n\n```bash\ntoss-cli market price 005930,AAPL              # 현재가 (최대 200종목)\ntoss-cli market orderbook 005930               # 호가\ntoss-cli market trades 005930 -n 20            # 최근 체결 (최대 50)\ntoss-cli market price-limits 005930            # 상/하한가 (미국은 null)\ntoss-cli market candles 005930 -i 1d -n 200    # OHLCV (간격 1m 또는 1d, 요청당 최대 200)\ntoss-cli market candles 005930 -i 1d -n 1000 --paginate   # 200개 초과는 자동 페이지네이션 (nextBefore 커서)\ntoss-cli market candles 005930 -i 1d --adjusted --before 2026-06-01T00:00:00+09:00\n```\n\n> **캔들 개수:** API는 **요청당 최대 200개**를 반환합니다(201개 이상은 서버가 거부). `-n`을 생략하면 200개를 가져옵니다. 200개를 초과해 가져오려면 `--paginate`를 붙이세요 — 응답의 `nextBefore` 커서를 따라 200개씩 페이지를 반복 조회하고(요청 간 ~200ms 대기, 5 req/s 이하), 시간 오름차순으로 중복 제거·정렬한 뒤 `-n`개로 잘라 반환합니다. `--paginate` 없이 `-n`이 200을 넘으면 로컬에서 명확한 에러로 막습니다.\n\n### 종목 정보 (`stock`)\n\n```bash\ntoss-cli stock info 005930,AAPL                # 종목 마스터\ntoss-cli stock warnings 005930                 # 매수 유의사항 & VI\n```\n\n### 시장 정보 (`info`)\n\n```bash\ntoss-cli info exchange-rate --base USD --quote KRW\ntoss-cli info calendar --market KR             # 국내 장 운영 시간\ntoss-cli info calendar --market US --date 2026-06-22\n```\n\n### 계좌 (`account`)\n\n```bash\ntoss-cli account list                          # 계좌 목록 (accountSeq 확인)\ntoss-cli account holdings                      # 보유 주식 + 합산 평가\ntoss-cli account holdings -s 005930            # 종목 필터\ntoss-cli account buying-power -c KRW           # 매수 가능 금액\ntoss-cli account sellable 005930               # 판매 가능 수량\ntoss-cli account commissions                   # 시장별 수수료율\n```\n\n### 주문 (`order`)\n\n```bash\n# 수량 기반 (국내 & 미국)\ntoss-cli order create 005930 --side BUY  --type LIMIT  --quantity 10 --price 70000\ntoss-cli order create 005930 --side SELL --type MARKET --quantity 5\n\n# 금액 기반 (미국 MARKET 전용 — 정규장에서만)\ntoss-cli order create AAPL --side BUY --type MARKET --amount 100.5\n\n# 선택 옵션: --tif DAY|CLS, --client-order-id <키>, --confirm-high-value\ntoss-cli order modify <orderId> --type LIMIT --quantity 10 --price 71000\ntoss-cli order cancel <orderId>\ntoss-cli order list --status OPEN\ntoss-cli order list --status CLOSED --limit 50\ntoss-cli order get <orderId>\n```\n\n요청 전송 전에 클라이언트에서 검증하는 규칙:\n\n- `--quantity` / `--amount` 중 **정확히 하나**만.\n- `--price`는 `LIMIT`에서 **필수**, `MARKET`에서는 **금지**.\n- `--amount`는 `--type MARKET`(미국 전용)을 요구하고 `--price`를 금지합니다.\n- 1억원 이상 주문은 `--confirm-high-value`가 필요합니다.\n\n## MCP 서버\n\n`toss-cli`는 모든 기능을 툴로 제공하는 MCP 서버(`toss-mcp`)를 함께 배포합니다.\n\n### Claude Desktop / Cursor / Windsurf (JSON)\n\nMCP 클라이언트 설정에 추가:\n\n```json\n{\n  \"mcpServers\": {\n    \"toss\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"-p\", \"@2oolkit/toss-cli\", \"toss-mcp\"],\n      \"env\": {\n        \"TOSS_CLIENT_ID\": \"tsck_live_xxx\",\n        \"TOSS_CLIENT_SECRET\": \"tssk_live_yyy\",\n        \"TOSS_ACCOUNT_SEQ\": \"1\"\n      }\n    }\n  }\n}\n```\n\n### Codex CLI (TOML)\n\n`~/.codex/config.toml`에 추가:\n\n```toml\n[mcp_servers.toss]\ncommand = \"npx\"\nargs = [\"-y\", \"-p\", \"@2oolkit/toss-cli\", \"toss-mcp\"]\n\n[mcp_servers.toss.env]\nTOSS_CLIENT_ID = \"tsck_live_xxx\"\nTOSS_CLIENT_SECRET = \"tssk_live_yyy\"\nTOSS_ACCOUNT_SEQ = \"1\"\n```\n\n> **참고:** 패키지에 bin이 2개(`toss-cli`, `toss-mcp`)라, npx로 MCP 서버를 띄울 땐 반드시 `-p`로 패키지를 지정해야 합니다 (`npx -y -p @2oolkit/toss-cli toss-mcp`). `-p` 없이 `npx @2oolkit/toss-cli toss-mcp`로 쓰면 CLI가 실행되며 `unknown command 'toss-mcp'` 에러가 납니다.\n\n이미 `toss-cli config init`을 실행했다면(또는 `~/.toss-cli/config.json`이 있으면) 위의 `env` 블록은 생략 가능합니다 — 서버가 해당 파일에서 크리덴셜을 읽습니다.\n\n**툴 목록:** `get_prices`, `get_orderbook`, `get_trades`, `get_price_limits`, `get_candles`, `get_stocks`, `get_stock_warnings`, `get_exchange_rate`, `get_market_calendar`, `get_accounts`, `get_holdings`, `get_buying_power`, `get_sellable_quantity`, `get_commissions`, `list_orders`, `get_order`, `create_order`, `modify_order`, `cancel_order`.\n\n## 에러 & Rate Limit\n\n에러에는 API의 `code`, 메시지, `requestId`(CS 문의 시 첨부 권장)가 담깁니다. 자주 보는 코드: `invalid-token` / `expired-token`(재인증), `account-header-required`(계좌 설정), `insufficient-buying-power`, `order-hours-closed`, `price-out-of-range`, `confirm-high-value-required`.\n\nAPI는 클라이언트 × API 그룹 단위로 초당 요청 수(TPS)를 제한합니다. `429`를 받으면 `Retry-After` 헤더만큼 대기 후 백오프하세요. 남은 허용량은 `X-RateLimit-*` 응답 헤더로 확인할 수 있습니다.\n\n## 안전\n\n- 크리덴셜과 캐시 토큰은 `0600` 권한으로 저장되며 `config list` 출력에서 마스킹됩니다.\n- `order create` / `modify` / `cancel`(CLI)과 `create_order` / `modify_order` / `cancel_order`(MCP)는 **실거래** 계좌에 작동합니다. 종목·방향·수량·가격을 꼭 재확인하세요.\n- `--confirm-high-value` 가드는 1억원 이상 주문에 대한 API 보호 장치를 그대로 반영합니다.\n- 더 이상 쓰지 않을 때는 `toss-cli config logout`으로 저장된 크리덴셜과 토큰을 삭제할 수 있습니다.\n\n## 개발\n\n```bash\nnpm install\nnpm run build        # tsup → dist/index.js (CLI), dist/mcp.js (MCP)\nnpm run lint         # tsc --noEmit\nnpm test             # jest\nnpm run test:coverage\n```\n\n## 라이선스\n\nMIT\n","readmeFilename":"README.md"}