컨텍스트 변수 레퍼런스¶

컨텍스트 변수는 런타임이 스크립트 실행 시 자동 주입하는 읽기 전용 값입니다.

symbol¶

현재 종목 코드.

타입: str
예: "005930", "000660"

log("symbol:", symbol)

symbol_name¶

현재 종목명. 종목 코드 매핑 실패 시 코드 문자열이 그대로 들어옵니다.

타입: str

log("name:", symbol_name)

symbol_market¶

시장 구분.

타입: str
일반 값: "KOSPI", "KOSDAQ"

if symbol_market == "KOSDAQ":
    log("변동성 높은 시장")

event¶

실행 트리거 이벤트.

타입: str
값: "price_change" 또는 "candle_close"

라이브 런타임에서는 candle_close가 두 경우에 발생합니다.

실시간 틱이 봉 경계를 넘을 때 (체결 발생)
무체결 구간에서 봉 마감 타이머가 만료될 때

if event == "candle_close":
    log("봉 마감 기준 판단")

price¶

현재 가격.

타입: float

무체결 봉 마감 시에는 price가 직전 봉 종가와 동일할 수 있습니다.

log("price:", price)

volume¶

현재 거래량.

타입: float

무체결 봉 마감 이벤트에서는 거래량이 0일 수 있습니다.

log("volume:", volume)

position¶

현재 포지션 정보.

타입: PositionNamespace (읽기 전용)

속성	타입	설명
`qty`	`int`	보유 수량
`avg_price`	`float`	평균 매입가
`open_pnl`	`float`	평가 손익 (원)
`open_pnl_pct`	`float`	평가 손익률 (%)
`entry_price`	`float`	최초 진입가 (분할 매수해도 첫 진입 가격 유지, FLAT이면 0)
`minutes_since_entry`	`int`	최초 진입 후 경과 분 (FLAT이면 0)
`high_since_entry`	`float`	진입 후 최고가. `order_on` 스케일 봉의 high 기준 추적 (FLAT이면 0)
`low_since_entry`	`float`	진입 후 최저가. `order_on` 스케일 봉의 low 기준 추적 (FLAT이면 0)

if position.qty > 0:
    log("보유중:", position.qty, "주", "손익률:", position.open_pnl_pct)

# 트레일링 스탑: 고점 대비 3% 하락 시 청산
if price < position.high_since_entry * 0.97:
    exit(tag="trailing_stop")

# 진입 후 60분 경과 시 해제
if position.minutes_since_entry > 60:
    release(tag="timeout")

market¶

시장 시간 정보. 장마감 청산, 특정 시각 청산 등 시간 기반 전략에 활용합니다.

타입: MarketNamespace (읽기 전용)

속성	타입	설명
`time`	`str`	현재 캔들 시각 KST (`"HH:MM"` 포맷, 문자열 비교 가능)
`minutes_until_close`	`int`	장마감(15:30)까지 남은 분
`minutes_since_open`	`int`	개장(09:00) 후 경과 분

백테스트에서의 시장 시간

백테스트 실행 시 market.* 값은 현재 평가 중인 캔들의 타임스탬프를 기준으로 계산됩니다. 실시간 실행 시에는 현재 시각을 사용합니다.

# 장마감 10분 전 청산
if market.minutes_until_close < 10:
    exit(tag="market_close")

# 14:20 이후 신규 매수 차단
if market.time > "14:20":
    hold(tag="late_session")

barstate¶

특정 스케일의 봉 상태를 조회하는 함수. 멀티 타임프레임 스크립트에서 어떤 봉을 참조하는지 명확하게 지정합니다.

봉 상태를 확인할 때는 항상 barstate("5T").is_confirmed처럼 스케일을 명시하세요.

시그니처: barstate(scale: str) -> BarstateResult
반환 타입: BarstateResult (읽기 전용)

속성	타입	설명
`is_confirmed`	`bool`	해당 스케일의 봉이 확정(마감)됐는지
`is_new`	`bool`	해당 스케일의 새 봉이 시작됐는지

# 5분봉 확정 시에만 매매 판단
if barstate("5T").is_confirmed:
    if ta.cross_up(c.close, ta.sma(c.close, 20)):
        buy(qty=10)

# 멀티 타임프레임: 1시간봉 확정 + 5분봉 확정
if barstate("1H").is_confirmed and barstate("5T").is_confirmed:
    log("양쪽 봉 모두 확정")

rule¶

선언형 청산/주문 규칙을 등록하는 네임스페이스. 흔한 청산 패턴을 한 줄로 선언할 수 있습니다. 스크립트 실행 후 엔진이 등록된 규칙을 고정 우선순위로 자동 평가합니다.

타입: RuleNamespace
사용은 선택적 — rule.* 없이 직접 if/elif로 청산 로직을 작성해도 됩니다
사용자의 명시적 sell()/exit()/release()가 있으면 rule.*은 무시됩니다

메서드	설명
`rule.stop_loss(pct)`	고정 손절. 미실현 손익률 ≤ -pct% 시 EXIT
`rule.trailing_stop(pct)`	트레일링 스탑. 고점 대비 pct% 하락 시 EXIT
`rule.take_profit(pct, qty_ratio=1.0)`	익절. 미실현 손익률 ≥ +pct% 시 SELL (qty_ratio로 분할)
`rule.close_before(minutes)`	장마감 N분 전 청산
`rule.order_on(scale)`	주문 허용 봉 스케일 설정

우선순위: 손절 > 트레일링 > 익절 > 시간

# 청산 규칙 선언 (선택적)
rule.order_on("5T")
rule.stop_loss(pct=param("손절%", 3.0))
rule.take_profit(pct=param("익절%", 10.0), qty_ratio=0.5)
rule.trailing_stop(pct=param("트레일링%", 2.0))
rule.close_before(minutes=param("장마감전(분)", 10))

# 매매 로직
c = chart("5T")
if barstate("5T").is_confirmed:
    if ta.cross_up(c.close, ta.sma(c.close, 20)):
        buy(qty=10)

strategy¶

전략 실행 파라미터. 주문 기준 스케일과 최대 보유 수량을 설정합니다.

타입: StrategyNamespace
설정 가능 속성: order_on, max_holding

속성	타입	기본값	설명
`order_on`	`str`	`"5T"`	주문 판단 기준 타임스케일. `tick`, `1T`~`1H` 지원
`max_holding`	`int`	`10`	최대 보유 수량

# 15분봉 기준으로 주문, 최대 5주
strategy.order_on = "15T"
strategy.max_holding = 5

order_on에는 tick, 1T, 3T, 5T, 10T, 15T, 30T, 60T, 1H만 사용할 수 있습니다. 1D 이상 스케일은 지원하지 않습니다.

order_on은 손절(rule.stop_loss)을 포함한 모든 주문의 판단 주기를 결정합니다. 빠른 손절이 필요하면 order_on을 "1T" 또는 "tick"으로 설정하고, 매수 조건에서 상위 봉 마감을 직접 확인하세요:
rule.order_on("1T")  # 1분마다 판단 → 손절 즉시 발동
rule.stop_loss(pct=3)

c = chart("5T")
fast = ta.ema(c.close, 12)
slow = ta.ema(c.close, 26)

# 매수는 5분봉 확정 시에만
if barstate("5T").is_confirmed and position.qty == 0 and ta.crossover(fast, slow):
    buy(qty=1)

account¶

현재 연결된 브로커 계좌의 읽기 전용 정보.

타입: dict (읽기 전용)

log("계좌:", account)

script_params¶

실행 시 전달된 파라미터 딕셔너리.

타입: dict

length = script_params.get("length", 14)
rsi = ta.rsi(chart("1D").close, length)

요약표¶

변수	타입	설명
`symbol`	`str`	종목 코드
`symbol_name`	`str`	종목명
`symbol_market`	`str`	시장 구분
`event`	`str`	`price_change` / `candle_close`
`price`	`float`	현재 가격
`volume`	`float`	현재 거래량
`position`	`PositionNamespace`	포지션 (qty, avg_price, entry_price, open_pnl, open_pnl_pct, high/low_since_entry 등)
`market`	`MarketNamespace`	시장 시간 (time, minutes_until_close, minutes_since_open)
`barstate(scale)`	`BarstateResult`	스케일별 봉 상태 (is_confirmed, is_new)
`strategy`	`StrategyNamespace`	전략 설정 (order_on, max_holding)
`account`	`dict`	브로커 계좌 정보
`script_params`	`dict`	실행 파라미터

참고¶

상태 유지가 필요하면 var 네임스페이스를 사용하세요.