13. 시스템 환경 설정

프로그램의 디자인 테마, 화면 표시, 로그 기록, 계좌현황 자동 새로고침, 외부신호 수신, 조건반복 반복 상한, 상단 지수 표시, 조건검색 기준 시세와 관련한 환경 옵션을 설정합니다. 메뉴 [설정 → 시스템 환경 설정] 을 클릭하면 설정 화면이 열립니다.

아래 옵션을 원하는 대로 선택한 뒤 [저장] 하면 즉시 반영됩니다. (디자인 테마만 재시작이 필요합니다.)

13.1 디자인 테마

화면 전체의 색상 테마를 선택합니다.

⚠️ 주의: 테마를 바꾼 뒤 [저장] 하면 재시작 안내가 표시됩니다. 프로그램을 다시 시작해야 전체 화면에 적용됩니다.

13.2 표시 및 로그 옵션

💡 팁: 매매 성능을 최우선으로 두고 운용하실 때는 매매전략 조건 판단 상세 로그 기록을 해제하면 처리 부담을 조금 더 낮출 수 있습니다.

13.3 계좌현황 자동 새로고침

계좌현황 자동 새로고침 사용을 체크하면, 메인 화면의 계좌현황이 일정 주기마다 자동으로 갱신됩니다. 사용을 켜면 새로고침 주기를 조절할 수 있습니다.

⚠️ 주의: 새로고침 주기는 10초 이상을 권장합니다. 주기를 너무 짧게 설정하면 키움 서버에 부하가 커질 수 있으므로 주의하십시오.

13.4 외부신호 수신 (REST API)

외부 프로그램이 보내는 매매 신호를 REST API로 받아들이는 기능입니다. 직접 만든 프로그램이나 다른 분석 도구가 "이 종목의, 이 주문 전략을 지금 평가하라" 는 신호를 보내면, 부엉이 트레이더 프로가 그 주문 전략의 준비·실행조건을 평가한 뒤 주문을 냅니다.

⚠️ v2.3.0 — 매수 신호가 매도까지 발동시키던 문제를 고쳤습니다. 종전에는 신호에 담긴 매수·매도 구분이 실제로 쓰이지 않아, 매수 신호 하나를 보내면 그 전략·종목의 매도 주문 전략까지 함께 평가되었습니다. 매도 조건이 마침 맞으면 매수를 지시했는데 매도가 나갈 수 있었습니다. 이제 신호의 구분대로만 동작합니다. 그동안 이 동작에 기대어 매도가 나가고 있었다면, 업데이트 후에는 매도 신호를 명시적으로 보내셔야 합니다.

13.4.1 무엇을 외부가 정하고, 무엇을 프로그램이 정하나

외부는 시점과 대상만 지정하고, 얼마나 어떻게 사고팔지는 주문 전략 설정이 그대로 결정합니다.

13.4.2 수신 포트

프로그램이 신호를 기다릴 수신 포트를 지정합니다.

⚠️ 주의 (v2.4.1) — 기본 포트가 5050 → 15050 으로 바뀌었습니다. 외부신호를 쓰신다면 신호를 보내는 프로그램의 주소를 localhost:15050 으로 고치십시오. 프로그램 쪽 설정은 자동으로 바뀝니다. 설정 파일에 예전 기본값 5050 이 저장되어 있어도 새 기본값 15050 으로 읽습니다. 단, 5050 이 아닌 다른 포트를 직접 지정해 두셨다면 그 값이 그대로 유지됩니다.

📌 참고: 예전 기본값 5050 은 Windows가 동적으로 쓰는 포트 범위 안에 있어, Hyper-V 등이 재부팅 때마다 잡아 두는 예약 구간과 겹쳐 서버 시작에 실패하는 경우가 있었습니다. 15050 은 이 범위 바깥의 값입니다.

포트 입력란 아래에 현재 상태가 표시됩니다. 서버가 정상 동작 중이면 실행 상태가, 시작에 실패했으면 그 원인과 조치 안내가 함께 표시됩니다. [저장] 할 때 포트가 바뀌었거나 서버가 멈춰 있으면 자동으로 다시 시작하고 결과를 알려 줍니다.

💡 팁: 포트를 바꿔야 하는 대표적인 경우는 다음 두 가지입니다.

• 다른 프로그램이 이미 그 포트를 쓰는 경우 — 사용 중이지 않은 다른 번호로 바꾸십시오.
• Windows가 예약한 포트 구간과 겹치는 경우 — Hyper-V 등을 사용하면 Windows가 일부 포트 구간을 미리 예약하며, 이 구간은 재부팅할 때마다 위치가 바뀝니다. 예약 구간은 명령 프롬프트에서 netsh interface ipv4 show excludedportrange protocol=tcp 로 확인할 수 있습니다.

📌 참고: 시작 실패는 로그 화면에도 기록되므로, 설정 창을 닫은 뒤에도 원인을 다시 확인할 수 있습니다. 수신 서버는 같은 PC(localhost) 의 요청만 받습니다.

13.4.3 신호를 받으려면 — 사전 준비

1. 주문 전략의 조건을 '외부 전략'으로 둡니다

발동할 주문 전략의 준비조건 또는 실행조건이 사용자 정의 → 외부 전략이어야 합니다(5.6.2).

2. 주문 전략 ID를 확인합니다

자동매매 만들기 화면(단일종목 / 키움 조건검색식 / 사용자 정의)의 주문 전략 목록 ID 컬럼에 표시되는 값입니다(5.7). 이 값을 신호의 orderStrategyId 로 보냅니다.

3. 신호 종류별 요구 사항을 확인합니다

📌 참고: 종목 선정 방법(단일종목 / 키움 조건검색식 / 사용자 정의)은 매도 신호에서는 제한이 없습니다. 다만 매수 신호로 새 매매작업을 만드는 경우에는 종목 선정 방법이 사용자 정의여야 합니다. 단일종목·조건검색식 전략은 종목을 스스로 고르는 방식이라, 외부가 임의 종목을 밀어 넣으면 전략의 종목 선정 체계와 충돌하기 때문입니다.

⚠️ 주의: 매도 신호는 매매작업을 새로 만들지 않습니다. 보유하지 않은 종목에 매도 신호를 보내면 주문 없이 종료됩니다. (종전에는 조건에 따라 매매작업이 통째로 새로 생성될 수 있었습니다.)

13.4.4 신호 규격

POST http://localhost:15050/api/external-signal/trade
Content-Type: application/json

⚠️ 주의: orderGubun 은 반드시 숫자로 보냅니다. "매도" 같은 문자열은 거부됩니다. 매도가 1, 매수가 2로 직관과 반대인데, 키움 주문체결 FID(907 매도수구분)를 그대로 따른 값입니다.

매도 신호 예시

{
  "stockCode": "005930",
  "tradeStrategyId": 42,
  "orderGubun": 1,
  "orderStrategyId": 137
}

매수 신호 예시

{
  "stockCode": "005930",
  "tradeStrategyId": 42,
  "orderGubun": 2
}

응답

⚠️ 주의: 200 은 주문이 나갔다는 뜻이 아닙니다. 신호를 처리 대기열에 넣었다는 뜻이며, 실제 주문 여부는 이후 조건 평가 결과에 달려 있습니다. 주문 결과는 로그 화면(11장)에서 확인하십시오.

400 이 반환되는 경우는 다음과 같습니다. (종전에는 이런 요청도 200 을 돌려준 뒤 아무 일도 일어나지 않았습니다.)

• stockCode 가 비어 있음
• tradeStrategyId 가 0 이하
• orderGubun 이 1 또는 2가 아님 (값 누락 포함)
• 매도 신호인데 orderStrategyId 가 없거나 0 이하

13.4.5 매도 수량은 어떻게 정해지나

수량은 매도 주문 전략의 주문금액식이 정합니다(5.9). 신호는 시점만 제공합니다.

여기서 보유수량 은 계좌 잔고가 아니라 매도가능수량입니다.

매도가능수량 = 전체 매수 체결 수량 − 당일 매도주문 수량 − 당일 이전 매도체결 수량

당일 매도주문은 체결 전이라도 전액 차감됩니다. 미체결 매도 주문이 걸려 있으면 그만큼 매도가능수량이 줄어듭니다.

📌 참고: 신호를 받았다고 곧바로 매도하는 것은 아닙니다. 신호는 준비·실행조건을 평가하게 만드는 방아쇠이며, 주문 전략에 부가 조건이 설정되어 있으면 그 조건까지 만족해야 주문이 나갑니다. 부가 조건이 없으면 신호만으로 통과합니다.

13.4.6 분할 매도 구성

방법 A — 주문 전략을 나눈다 (권장)

매도 주문 전략을 여러 개 만들고, 신호마다 orderStrategyId 를 바꿔 보냅니다.

각 주문 전략이 독립적이라 실행주기를 1회 로 두어도 되고, 어느 단계를 건너뛸지도 외부가 자유롭게 정할 수 있습니다.

방법 B — 하나의 주문 전략을 반복한다

매도 주문 전략의 실행주기를 조건반복 으로 두고 같은 orderStrategyId 로 신호를 반복 전송합니다.

⚠️ 주의: 직전 매도가 체결된 뒤에 다음 신호를 보내야 합니다. 명세는 주문이 전량 체결된 시점에 다시 무장되므로, 당일 미체결 매도 주문이 남아 있으면 다음 신호는 건너뜁니다. 신호를 연속으로 쏘면 두 번째부터 무시됩니다.

하루 반복 횟수에는 상한이 있습니다(13.5, 기본 3회). 4분할 이상으로 나눠 매도할 계획이라면 이 값을 먼저 올려 주십시오. 또한 주문금액식으로 계산한 수량이 1주 미만이 되면 자동으로 멈춥니다.

실행주기별 지원 여부

13.4.7 접수는 됐는데 주문이 나가지 않을 때

아래 상황은 모두 사용자 로그에 사유가 기록되므로 로그 화면(11장)에서 원인을 확인하십시오.

13.5 조건반복 반복 상한

실행주기가 조건반복인 주문 전략이 하루에 다시 실행되는 횟수의 상한입니다(5.7.2).

종전에는 3회로 고정되어 있었고 프로그램 안에 값이 박혀 있어 바꿀 수 없었습니다. v2.3.0부터 이 화면에서 조정할 수 있습니다. 기본값이 종전과 같은 3회라, 따로 바꾸지 않으면 동작은 그대로입니다.

💡 팁: 하나의 매도 주문 전략을 반복해 4분할 이상으로 나눠 매도할 계획이라면 이 값을 먼저 올려 주십시오. 이 횟수를 넘으면 명세가 완료 처리되어 그날은 더 이상 반복되지 않습니다.

13.6 상단 지수 · 해외 참고 지표 표시

화면 맨 위 업종지수 틱커(3.7)에 띄울 항목을 고릅니다. 저장 즉시 반영됩니다.

상단 지수 표시 — 키움이 실시간으로 내려주는 국내 업종지수 중에서 고릅니다. 기본은 KOSPI · KOSDAQ 이고 개수 제한은 없습니다.

• 3개 이상 고르면 등락 표기가 퍼센트만으로 짧아지고(등락폭은 마우스를 올리면 표시), 창 폭이 모자라면 다음 줄로 접힙니다.
• 여기서 끄는 것은 화면 표시뿐입니다. 코스피·코스닥은 꺼도 시세를 계속 받습니다. 조건식의 코스피지수·코스닥지수(5.8)와 휴장일 판단이 이 값을 쓰므로, 표시를 꺼도 매매 동작은 달라지지 않습니다.

상단 해외 지표 표시 (참고용) — NASDAQ(나스닥 종합) · S&P500 · USD/KRW(원·달러 환율) · WTI(원유 선물)를 띄울 수 있습니다. 기본은 모두 표시이며, 모두 끄면 외부 조회 자체가 멈춥니다.

⚠️ 주의: 해외 지표는 키움이 아니라 외부 공개 데이터(야후 파이낸스)에서 1분마다 가져오는 참고용 지연 시세입니다. 예고 없이 조회가 막히거나 늦어질 수 있어 자동매매 판단에는 전혀 쓰이지 않습니다. 값이 5분 넘게 갱신되지 않으면 해당 표시가 흐려집니다. 하나라도 켜 두면 이 PC에서 해당 서비스로 주기적인 조회가 나갑니다(보내는 정보는 없습니다).

13.7 조건검색 기준 시세 (v2.3.7)

키움 조건검색식을 조회할 때 어느 시세를 기준으로 종목을 검출할지 정합니다.

바꾼 값은 다음 조건검색 요청부터 적용됩니다.

⚠️ 주의:

• 모의투자 계좌는 통합시세를 지원하지 않아 이 설정과 무관하게 항상 KRX 시세로 조회됩니다. 모의투자에서 검증한 조건검색식이라도 실서버에서는 검출 종목·시점이 달라질 수 있습니다.
• 이미 실행 중인 실시간 조건검색에는 소급 적용되지 않습니다. 해당 매매전략을 중지한 뒤 다시 시작해야 새 기준으로 조회됩니다.