① API 키 등록 가이드

v5 봇은 가입자 본인의 거래소 API 키를 사용하여 매매를 실행합니다. API 키는 DPAPI + HMAC 으로 로컬 PC 에서만 복호화되도록 암호화 저장됩니다 (서버 전송 X).

키움증권 (국내주식 + 미국주식 — 단일 API)

1. 키움 REST API 개발자 포털 (openapi.kiwoom.com) 접속 → 로그인 (키움 계좌 + 인증 필요)
2. API 사용 신청 → 사용할 계좌 지정 → 승인 시 앱키 (App Key) + 시크릿키 (Secret Key) 발급
3. v5 앱 → [설정] 탭 → 키움증권 카드 → 앱키 / 시크릿키 / 계좌번호 입력 → [저장]
4. 저장하면 v5 가 자동으로 REST 토큰을 발급받아 연결을 검증합니다 (별도 인증창 없음)

② 스캐너 사용법

v5 의 매매 흐름은 두 종류 — 종목 매매 와 조건식 매매.

1) 종목 매매 (시총 상위 화이트리스트)

코스피 + 코스닥 시총 상위 50+50 종목 (총 100) 을 1분봉 단위로 폴링하며 지표 신호 발생 시 매매.

1. [종목 매매] 탭 → [전략 인스턴스 생성] 클릭
2. 전략명 · 지표 (Cosmotec / Yoon V2 / YSW V3) · 매매 방향 (LONG / SHORT) 선택
3. 1회 매수 수량 + 최대 동시 보유 + TP/SL/TS 설정
4. [저장] → [활성화] → 봇이 자동으로 100 종목 폴링 시작

2) 조건식 매매 (키움 조건검색식 연동 · 국내 + 미국)

키움에 등록한 조건검색식 (예: "거래량 급증 + 상한가 근접") 을 실시간 감시하여, 편입 종목을 지표 평가 후 자동매수.

1. 키움 영웅문(국내) 또는 영웅문 글로벌(미국) → 조건검색 → 본인 조건식 생성 + 서버 저장
2. v5 [조건식 매매] 탭 → 전략 카드의 시장 (🇰🇷 국내 / 🇺🇸 미국) 선택 → 그 시장의 조건식 목록이 드롭다운에 로드
3. 조건식 선택 → 매매 방향 + 지표 + TP/SL/TS 설정 → [실시간 시작]
4. 조건식 편입 종목 즉시 (실시간) → 지표 ON 인 경우 평가 → 매수 트리거 → 모니터 자동 등록

지표 종류 (3종)

• Cosmotec (COTRADING2_V3) · LRC1 변화율(shift) 기반. 단기 추세 전환 포착.
• Yoon V2 (SuperTrend + VWMA) · 추세 추종 + 거래량 가중. 안정적 추세 진입.
• YSW V3 (True Reversal Slope) · LRC1 lowest/highest 반등률 기반. 바닥/천장 반전 포착.

※ 지표 파라미터 (LRC 기간 · 임계값 · cooldown 등) 는 각 카드에서 개별 설정 가능. 기본값 권장.

③ 차트 사용법

v5 차트는 TradingView Lightweight Charts 기반 — 캔들 + 지표 라인 + 매수/매도 마커를 시각화.

차트 진입 방법

1. 모니터 탭 → 포지션 행 클릭 → 해당 종목 차트 자동 표시
2. [종목 분석] 버튼 → 종목 코드 입력 → 4탭 모달 (차트/뉴스/공시/재무)
3. [조건식 매매] 탭 → 종목 행 클릭 → 차트 + 지표 평가 결과 표시

차트 컨트롤

• 타임프레임 · 1m / 3m / 5m / 15m / 30m / 1h / 4h / 1d (드롭다운)
• 지표 선택 · 차트 상단 드롭다운으로 Cosmotec / Yoon V2 / YSW V3 즉시 전환
• 마우스 드래그 · 좌우 = 시간 이동, 휠 = 확대/축소
• 크로스헤어 · 마우스 위치의 가격 + 시간 표시
• 자동 새로고침 · 1초 폴링 (실시간 캔들 업데이트)

표시 요소

• 캔들 · 양봉 녹색 / 음봉 빨강
• LRC 라인 · LRC1 (단기) · LRC200 / LRC400 / LRC600 (장기 추세선)
• 매수 마커 · ▲ 녹색 (BUY 신호) · 실 매수 시점
• 매도 마커 · ▼ 빨강 (SELL 신호) · 익절 / 손절 / 청산
• 지표 시그널 · 캔들 위 ● 도트 (지표 조건 충족 봉)

차트 + 매매 연계

차트에서 본 신호가 실제 매매와 일치하는지 검증하려면:

1. 모니터 탭에서 매수 체결 발생
2. 해당 행 클릭 → 차트 자동 진입
3. 매수 시점에 ▲ 마커 + ● 지표 도트가 일치하는지 확인
4. 불일치 시 = 지표 파라미터 재조정 또는 cooldown 조정 신호

★ 전략 프리셋 만들기 ([전략 프리셋] 탭)

코딩 없이 지표와 파라미터를 조합해 나만의 전략 프리셋을 만들고, 차트에서 신호가 맞는지 눈으로 검증할 수 있습니다.

1. [전략 프리셋] 탭 → 새 인스턴스 → 지표 선택 (Cosmotec 3중 LRC / Yoon V2 / YSW V3 등)
2. 파라미터 조정 · len(주기) · threshold(민감도) · cooldown 등을 입력 → 이름 입력 → [저장]
3. 저장 즉시 [조건식 매매]/[종목 매매] 탭의 '전략 프리셋' 드롭다운에 나타납니다.
4. 차트 탭에서 종목 + 그 지표를 선택하면 ▲▼ 롱/숏 마커 + ● 지표 도트가 표시되어, 신호 타이밍이 만족스러운지 확인할 수 있습니다.
5. [조건식 매매]/[종목 매매]에서 그 프리셋 선택 + TP/SL/TS 설정 → 매매 시작.

④ 자동 매매 설정 (TP / SL / TS)

익절 (TP — Take Profit)

• TP % · 진입가 대비 % (예: 2.0 = +2% 도달 시 전량 청산)
• 부분 익절 · 1차 TP 50% / 2차 TP 50% (각각 % 별도 설정)
• TP 비활성 · 0 입력 시 TP 작동 안 함 (TS 또는 SL 만 사용)

손절 (SL — Stop Loss)

• SL % · 진입가 대비 % (예: -1.5 = -1.5% 도달 시 즉시 청산)
• SL 가드 · SL = 0 인 경우 안전장치로 자동 -3% 적용 (회원님 요청 사양)

트레일링 스탑 (TS — Trailing Stop)

• TS 활성화 · 최고가 대비 일정 % 하락 시 청산 (수익 극대화)
• TS Trigger % · 진입가 대비 +X% 도달 후 TS 활성화 (조기 손실 방지)
• TS Step % · 최고가 대비 -Y% 하락 시 청산

매매 파라미터 (UI 설정)

• 1회 매수 수량(비중 %) · 종목당 1회 진입 시 매수 비중 (예수금 대비 %)
• 최대 동시 보유 · 봇이 동시에 보유 가능한 종목 수 (자금 관리)
• 일일 매수 상한 · 하루 자동 매수 건수 상한 (과매수 방지)
• SHORT 청산 매도만 · 주식은 공매도 불가 → SHORT 신호 발생 시 보유 종목 청산만 (미보유면 skip)

⑤ 모니터 탭 (포지션 관리)

현재 보유 중인 포지션 + 미체결 주문 + 실시간 P&L 을 통합 모니터링.

포지션 그리드

• 종목 · 코드 + 종목명 (클릭 시 차트 자동 진입)
• 방향 · LONG / SHORT
• 진입가 · 현재가 · 수익률 · 실시간 갱신 (5초 폴링)
• TP / SL / TS · 현재 설정값 표시
• [수동 청산] · 즉시 시장가 청산 (확인 다이얼로그)

주문 히스토리

• 당일 체결 내역 (시간 · 종목 · 방향 · 수량 · 가격 · P&L)
• CSV 다운로드 → 외부 저널 또는 세무 자료로 활용

봇 상태 표시

• 상단 도트 · 거래소별 연결 상태 (🟢 정상 / 🔴 오프라인)
• 잔고 칩 · KRW + USD 통합 잔고 + DAILY PNL
• 업데이트 칩 · 신버전 출시 시 자동 표시 → 클릭 시 1-click 업데이트

⑥ 자동 업데이트

v5 봇은 서버에서 manifest.json 을 폴링하여 신버전 출시를 자동 감지합니다.

1. 봇 시작 시 manifest.json 폴링 (24h 마다)
2. 신버전 발견 → 상단 [● 업데이트 사용 가능] 칩 표시
3. 칩 클릭 → 업데이트 다이얼로그 → [지금 업데이트]
4. Setup.exe 다운로드 → 자동 실행 (RestartReplace) → 봇 자동 재시작

⑦ 트러블슈팅

"로그인 실패" 메시지

• cosmotec.xyz 가입 이메일/비밀번호 정확히 입력 (대소문자 구분)
• 구독 만료 시 → [구독 갱신] 후 재로그인
• 기기 한도 초과 시 → 웹 → [내 기기 관리] 에서 기존 기기 해지

키움 REST API 연결 안 됨 (국내·미국 공통)

• 앱키 / 시크릿키 / 계좌번호를 정확히 입력했는지 확인 (앞뒤 공백 X)
• 키움 REST API 사용 신청 승인 완료 여부 확인 (개발자 포털)
• 발급 키가 실전 투자용인지 확인 (v5 는 실전 도메인 연결)
• [설정] 탭에서 [연결] 재시도 → REST 토큰 자동 재발급 (약 24시간 유효)

미국주식 매매/조회 안 됨

• 키움 계좌에 미국주식 거래 권한이 있는지 확인 (없으면 조건검색은 되어도 주문 거부)
• 미국 예수금(외화 또는 원화주문 가능액) 확인 — 0 이면 주문가능수량 0 으로 매수 skip
• "시장가매매는 정규장만 가능" 메시지 → 프리/애프터장에서는 자동으로 지정가(±6호가)로 재주문됩니다 (정상 동작)
• 국내 조건검색과 동시 가동 시 연결 끊김 → 한쪽만 켜세요 (같은 앱키 1세션 제한)

차트 안 나옴 / 데이터 0개

• 인터넷 연결 확인
• 해당 종목 거래정지 여부 확인
• 봇 재시작 (캐시 초기화)

봇이 매매 안 함

• 전략 인스턴스가 활성화 상태인지 확인 ([전략] 탭)
• 지표 ON / 매매 방향 / 1회 매수 수량 정상 설정 확인
• 잔고 부족 / API 키 만료 확인 ([설정] 탭)
• 로그 파일 확인 — %LOCALAPPDATA%\COSMOTEC v5\logs\

⑧ 자주 묻는 질문 (FAQ)

① API Key Registration Guide

The v5 bot executes trades using your own exchange API keys. Keys are stored encrypted with DPAPI + HMAC so they can only be decrypted on your local PC (never sent to the server).

Kiwoom Securities (Korean + US stocks — single API)

1. Go to the Kiwoom REST API developer portal (openapi.kiwoom.com) → log in (needs a Kiwoom account + auth)
2. Apply for API usage → specify the account → on approval you receive an App Key + Secret Key
3. v5 app → [Settings] tab → Kiwoom card → enter App Key / Secret Key / account number → [Save]
4. On save, v5 auto-issues the REST token and validates the connection (no separate login popup)

② Using the Scanner

v5 has two trading flows — Symbol Trading and Condition Trading.

1) Symbol Trading (top-market-cap whitelist)

Polls the top 50+50 stocks by market cap on KOSPI + KOSDAQ (100 total) on 1-minute candles and trades when an indicator signal fires.

1. [Symbol Trading] tab → click [Create Strategy Instance]
2. Select strategy name · indicator (Cosmotec / Yoon V2 / YSW V3) · direction (LONG / SHORT)
3. Set quantity per buy + max concurrent holdings + TP/SL/TS
4. [Save] → [Activate] → the bot starts polling the 100 symbols automatically

2) Condition Trading (Kiwoom condition-search · Korean + US)

Monitors your Kiwoom condition-search formula (e.g. "volume surge + near upper limit") in real time and auto-buys entering symbols after an indicator check.

1. Kiwoom HeroMoon (Korean) or HeroMoon Global (US) → Condition Search → create your formula + save it to the server
2. v5 [Condition Trading] tab → on the strategy card select the market (🇰🇷 KR / 🇺🇸 US) → that market's condition list loads into the dropdown
3. Select the formula → set direction + indicator + TP/SL/TS → [Start Real-time]
4. As soon as a symbol enters the condition (real time) → if the indicator is ON it is evaluated → buy trigger → monitor auto-registered

Indicator Types (3)

• Cosmotec (COTRADING2_V3) · Based on LRC1 rate-of-change (shift). Captures short-term trend reversals.
• Yoon V2 (SuperTrend + VWMA) · Trend-following + volume-weighted. Stable trend entries.
• YSW V3 (True Reversal Slope) · Based on LRC1 lowest/highest rebound rate. Captures bottom/top reversals.

※ Indicator parameters (LRC period · threshold · cooldown, etc.) can be set individually on each card. Defaults are recommended.

③ Using the Chart

The v5 chart is built on TradingView Lightweight Charts — visualizing candles + indicator lines + buy/sell markers.

How to Open the Chart

1. Monitor tab → click a position row → the chart for that symbol appears automatically
2. [Analyze Symbol] button → enter a symbol code → 4-tab modal (Chart / News / Disclosures / Financials)
3. [Condition Trading] tab → click a symbol row → shows the chart + indicator evaluation result

Chart Controls

• Timeframe · 1m / 3m / 5m / 15m / 30m / 1h / 4h / 1d (dropdown)
• Indicator selection · Switch instantly between Cosmotec / Yoon V2 / YSW V3 via the dropdown at the top of the chart
• Mouse drag · left/right = pan time, wheel = zoom in/out
• Crosshair · shows the price + time at the mouse position
• Auto-refresh · 1-second polling (real-time candle updates)

Display Elements

• Candles · bullish green / bearish red
• LRC lines · LRC1 (short term) · LRC200 / LRC400 / LRC600 (long-term trend lines)
• Buy marker · ▲ green (BUY signal) · actual buy point
• Sell marker · ▼ red (SELL signal) · take-profit / stop-loss / liquidation
• Indicator signal · ● dot above the candle (candle that met the indicator condition)

Chart + Trading Linkage

To verify that the signals you see on the chart match the actual trades:

1. A buy fill occurs in the Monitor tab
2. Click that row → jump straight to the chart
3. Check that the ▲ marker + ● indicator dot align at the buy point
4. A mismatch = a sign to retune the indicator parameters or adjust the cooldown

★ Building a Strategy Preset ([Strategy Preset] tab)

Without coding, combine indicators and parameters into your own preset, then verify the signals on the chart.

1. [Strategy Preset] tab → new instance → select an indicator (Cosmotec triple LRC / Yoon V2 / YSW V3, etc.)
2. Adjust parameters · len (period) · threshold (sensitivity) · cooldown, etc. → enter a name → [Save]
3. Once saved it appears immediately in the "Strategy Preset" dropdown of the [Condition Trading] / [Symbol Trading] tab.
4. On the Chart tab, select the symbol + that indicator to see ▲▼ long/short markers + ● indicator dots, and check whether the signal timing is satisfactory.
5. In [Condition Trading] / [Symbol Trading], select that preset + set TP/SL/TS → start trading.

④ Auto-Trading Settings (TP / SL / TS)

Take Profit (TP)

• TP % · % relative to entry price (e.g. 2.0 = liquidate the full position when +2% is reached)
• Partial take-profit · 1st TP 50% / 2nd TP 50% (each % set separately)
• Disable TP · enter 0 and TP won't trigger (use only TS or SL)

Stop Loss (SL)

• SL % · % relative to entry price (e.g. -1.5 = liquidate immediately when -1.5% is reached)
• SL guard · if SL = 0, a safety -3% is auto-applied (spec requested by the owner)

Trailing Stop (TS)

• Enable TS · liquidate when price drops a set % from the high (maximize profit)
• TS Trigger % · activate TS after reaching +X% from entry (prevents early loss)
• TS Step % · liquidate when price drops -Y% from the high

Trading Parameters (UI Settings)

• Quantity per buy (weight %) · buy weight per entry into a symbol (% of deposit)
• Max concurrent holdings · the number of symbols the bot can hold at once (money management)
• Daily buy limit · cap on the number of auto-buys per day (over-buying guard)
• SHORT = liquidation sell only · stocks cannot be short-sold, so a SHORT signal only liquidates held symbols (skips if none held)

⑤ Monitor Tab (Position Management)

Unified monitoring of currently held positions + open orders + real-time P&L.

Position Grid

• Symbol · code + name (clicking jumps to the chart)
• Direction · LONG / SHORT
• Entry · Current · Return · updated in real time (5-second polling)
• TP / SL / TS · shows the current settings
• [Manual Liquidation] · immediate market-order liquidation (confirmation dialog)

Order History

• Today's fills (time · symbol · direction · quantity · price · P&L)
• CSV download → use for an external journal or tax records

Bot Status Indicators

• Top dots · per-exchange connection status (🟢 normal / 🔴 offline)
• Balance chip · combined KRW + USD balance + DAILY PNL
• Update chip · shown automatically when a new version is released → click for a 1-click update

⑥ Auto-Update

The v5 bot polls manifest.json from the server to automatically detect new releases.

1. On bot start it polls manifest.json (every 24h)
2. New version found → shows the [● Update Available] chip at the top
3. Click the chip → update dialog → [Update Now]
4. Setup.exe downloads → runs automatically (RestartReplace) → the bot restarts automatically

⑦ Troubleshooting

"Login failed" message

• Enter your cosmotec.xyz registration email/password exactly (case-sensitive)
• If your subscription expired → [Renew Subscription] then log in again
• If the device limit is exceeded → web → [Manage My Devices] to deregister an existing device

Kiwoom REST API won't connect (Korean & US)

• Confirm the App Key / Secret Key / account number are entered exactly (no leading/trailing spaces)
• Confirm your Kiwoom REST API usage application is approved (developer portal)
• Confirm the keys are for real trading (v5 connects to the real domain)
• Press [Connect] again in the [Settings] tab → the REST token auto-reissues (~24h validity)

US stocks won't trade / query

• Confirm your Kiwoom account has US trading permission (without it, condition search works but orders are rejected)
• Check your US deposit (foreign-currency or KRW-order available balance) — if 0, orderable quantity is 0 and buys are skipped
• "Market orders are allowed only during regular session" message → in pre/after-hours the bot auto-reorders as a limit (±6 ticks). This is normal.
• Disconnects when run together with Korean condition search → run only one side (same App Key single-session limit)

Chart doesn't show / 0 data points

• Check your internet connection
• Check whether the symbol is suspended from trading
• Restart the bot (clears the cache)

The bot isn't trading

• Confirm the strategy instance is Active (the [Strategy] tab)
• Confirm the indicator is ON / direction / quantity per buy are set correctly
• Check for insufficient balance / expired API keys (the [Settings] tab)
• Check the log files — %LOCALAPPDATA%\COSMOTEC v5\logs\

⑧ Frequently Asked Questions (FAQ)