콘텐츠로 이동

실행 모델

전략이 "언제" 실행되고 "어떻게" 주문이 나가는지 이해하면, 전략이 예상과 다르게 동작하는 상황을 방지할 수 있습니다. 예를 들어 "봉이 아직 마감되지 않았는데 매수가 나갔다"거나 "아무 신호가 없는데 매도가 실행됐다"는 문제의 원인이 대부분 실행 모델을 모르기 때문입니다.

처음에는 개념만 파악하면 충분합니다. 나중에 전략이 예상과 다르게 동작할 때 다시 찾아보세요.

이벤트 기반 실행

스크립트는 이벤트가 발생할 때마다 처음부터 끝까지 다시 실행됩니다.

이벤트 종류

대부분의 전략은 event 변수를 직접 체크할 필요가 없습니다. 스크립트는 이벤트마다 실행되므로, 조건을 그냥 작성하면 됩니다. event는 특정 이벤트에서만 동작을 다르게 하고 싶을 때 사용합니다.

price_change — 실시간 가격 변동

예시 (특정 이벤트에서만 처리하고 싶을 때):

if event == "price_change":
    # 가격이 바뀔 때마다 실행
    if price < position.avg_price * 0.97:
        sell(tag="3% 손절")

candle_close — 봉 마감

if event == "candle_close":
    # 봉이 확정될 때 실행 (권장)
    if barstate("1D").is_confirmed:
        # 일봉 마감 기준 판단

일봉 전략에서는 event 체크가 필요 없습니다

일봉(1D) 전략은 event == "candle_close" 체크 없이도 봉 마감 시점에만 실행됩니다. barstate("1D").is_confirmed만으로 충분합니다. 두 조건을 함께 쓰면 봉 마감 이외 이벤트에서도 스크립트가 실행될 때 조건 평가 순서가 달라져 예상치 못한 타이밍에 신호가 생길 수 있습니다.

봉 마감 기준 전략을 권장합니다

price_change 이벤트는 장중에 수백~수천 번 발생합니다. 특별한 이유가 없다면 봉 마감(candle_close) 또는 barstate().is_confirmed를 사용하는 것이 더 안정적입니다.

실행 순서

매 이벤트마다 아래 순서로 처리됩니다.

flowchart TD
    A["이벤트 수신\nprice_change / candle_close"] --> B["스크립트 전체 실행\n(처음부터 끝까지)"]
    B --> C{"마지막 결정 함수"}
    C -->|"hold() / buy() / sell() / exit()"| D["리스크 검사\n손절 · 익절 · 계좌 한도"]
    C -->|"release()"| F["즉시 해제 처리\n(게이트 무시)"]
    D -->|"rule.* / 리스크 강제청산"| G["시장가 주문 전송\n(order_on 우회)"]
    D -->|"미발동 + hold()"| H["주문 없음"]
    D -->|"일반 BUY/SELL 통과"| E{"order_on 게이트"}
    E -->|"게이트 열림\n(봉 마감 일치)"| I["주문 전송\n내 PC → 증권사"]
    E -->|"게이트 닫힘"| H
    D -->|"차단"| H

의사결정 규칙

한 번의 실행에서 buy, sell, hold 중 하나만 최종 결정이 됩니다. 여러 번 호출하면 마지막 호출만 유효합니다.

buy(tag="첫 번째 시도")
sell(tag="두 번째 시도")
# 최종 결정: SELL (마지막 호출)

모든 분기에서 반드시 하나의 결정이 내려지도록 if/elif/else를 완성하세요.

# 올바른 패턴
if 조건_A:
    buy(tag="A 조건")
elif 조건_B:
    sell(tag="B 조건")
else:
    hold()      # 나머지 경우에도 반드시 결정

상태 유지 (var)

일반 변수는 이벤트마다 초기화됩니다. 이전 실행의 값을 기억하려면 var를 사용하세요.

# 잘못된 방법 — 항상 1
count = 0
count += 1

# 올바른 방법 — 실행 간 누적
var.init(count=0)
var.count += 1
log("총 실행 횟수:", var.count)

자세한 내용: var 네임스페이스

주문 타이밍 (order_on)

rule.order_on()으로 주문이 실행될 봉 마감 조건을 선언합니다.

rule.order_on("5T")   # 5분봉 마감 시에만 주문

order_on 게이트가 열리지 않은 이벤트에서는 일반 buy(), sell() 주문이 전송되지 않습니다.
다만 아래 두 경우는 order_on을 우회해 즉시 처리됩니다.

  • rule.* 태그로 생성된 주문 (예: rule.stop_loss, rule.take_profit)
  • 리스크 엔진 강제청산 (risk_liquidate)

release()는 게이트 상태와 무관하게 즉시 해제 처리됩니다. hold()는 주문을 전송하지 않으므로 게이트의 영향을 받지 않습니다.

지원 값: "tick", "1T", "3T", "5T", "10T", "15T", "30T", "60T", "1H" — 일봉(1D) 초과는 지원하지 않습니다.

백테스트

스튜디오에서 백테스트를 실행하면 과거 데이터로 전략의 동작을 검증할 수 있습니다.

  • 실거래와 동일한 주문 판단 로직을 사용합니다
  • 봉 마감 타이밍이 실거래와 동일하게 적용됩니다
  • 거래량이 0인 봉(무체결 구간)에서는 시장가 주문이 체결되지 않습니다
  • 리스크 트리거는 종가만이 아니라 시가→고가→저가→종가 경로에서 평가됩니다
  • 리스크 트리거 가격(expected_price)과 실제 체결가(fill_price)는 다를 수 있습니다 (예: next_open 체결 모델)
  • 마지막 캔들에서 리스크가 트리거되면 다음 봉이 없으므로 next_open 설정과 무관하게 트리거 가격으로 체결됩니다 (체결 모델이 close로 자동 전환)

백테스트 결과는 미래를 보장하지 않습니다

백테스트는 전략의 논리적 타당성을 확인하는 도구입니다. 과거 성과가 미래 수익을 보장하지 않으며, 실제 시장 상황은 백테스트와 다를 수 있습니다.

조건검색 연동

조건검색 연동을 사용하면 HTS(증권사 홈트레이딩 시스템)에서 미리 만들어 둔 종목 필터를 Quantiq 전략에 연결할 수 있습니다. 예를 들어 'RSI 30 이하 종목' 조건검색식을 연결하면, 해당 조건을 만족하는 종목이 자동으로 전략 감시 목록에 추가됩니다.

거래 탭에서 HTS 조건검색식을 전략에 연결하면, 조건을 만족하는 종목이 자동으로 전략의 감시 대상에 추가됩니다.

  • 전략 활성화 시 즉시 조건 결과를 조회하여 종목을 바인딩합니다
  • 이후 주기적으로 조건 결과를 갱신합니다
  • 조건에서 제외된 종목은 포지션이 없으면 다음 갱신 시 감시 목록에서 제거됩니다
조건검색 → 후보 종목 수집 → 전략 스크립트 판단 → 진입/청산

자세한 내용: 거래 탭 사용법

실행 흐름 전체 요약

전략 하나의 실행 흐름을 한 줄로 요약하면:

이벤트 수신 → 전략 코드 실행 → buy/sell/hold 결정 → 리스크 검사 → 주문 전송

각 단계의 상세 내용이 궁금하다면 아래 다음 단계 문서를 참고하세요.

다음 단계