블루프린트 노드 상세 문서

위험 안내: 블루프린트 노드는 자동 거래 동작을 생성할 수 있지만, 노드 조합 자체가 수익을 보장하지 않습니다. 실거래 전에 반드시 백테스트를 먼저 진행하고, 그다음 Paper 모드나 소액으로 검증하세요. 거래소 API 키에는 출금 권한을 켜지 마세요.

1. 블루프린트의 기본 작동 방식

블루프린트는 “이벤트 기반 전략 흐름도”로 이해할 수 있습니다. 실행 가능한 블루프린트는 보통 다음 노드 그룹으로 구성됩니다.

이벤트 노드: 전략이 언제 실행될지 결정합니다. 예: 시작 시, 각 캔들, 각 Tick, 타이머, 주문 회신.
시장 노드: 현재 마운트된 거래쌍, 캔들, 최신가, 호가, 계정, 포지션을 읽습니다.
지표 노드: 캔들 또는 숫자 시리즈를 기반으로 기술 지표를 계산합니다.
신호/로직 노드: 지표와 가격을 boolean 조건으로 변환하여 진입, 청산, 차트 표시 여부를 결정합니다.
리스크 노드: 주문 빈도 제한, kill switch, 최소 수량 검증, 최대 포지션 제한, 쿨다운, 손절, 익절 규칙을 추가합니다.
주문/함수 노드: 진입, 청산, 취소, 종료 규칙 같은 거래 동작을 생성합니다.
상태 노드: 변수 저장, 카운터 유지, 상태 영속화, 신호 변화 감지를 처리합니다.
도구 노드: 표현식, 타입 변환, 사칙연산, 정규화, 정밀도 처리를 수행합니다.
차트 노드: 지표선, 수평선, 배경, 마커, 테이블, 주문 마커를 차트에 표시합니다.

가장 일반적인 전략 체인은 다음과 같습니다.

OnBar / OnBarClose
  -> Symbol Selector
  -> Get OHLCV
  -> 지표 노드
  -> 신호/로직 노드
  -> 리스크 노드
  -> strategy.entry / strategy.close / 주문 노드

실행 주기는 15m이고 시장 판단은 1h 데이터를 볼 때는 보통 다음처럼 설정합니다.

event.on_bar(timeframe=15m)
  -> market.symbol_selector
  -> market.get_ohlcv(timeframe=1h, limit=200)
  -> 1h 지표와 필터 조건
  -> 15m 실행 체인

2. 포트, 연결, 파라미터

각 노드는 입력 포트, 출력 포트, 파라미터로 구성됩니다.

개념	설명
입력 포트	이벤트나 데이터를 받습니다. 연결되지 않았을 때 일부 노드는 파라미터 기본값을 사용합니다.
출력 포트	이벤트, 숫자, boolean, 거래쌍, 주문 의도, 차트 참조 등을 출력합니다.
파라미터	오른쪽 속성 패널에서 설정합니다. “노출”된 파라미터는 전략 파라미터 패널에 표시되며 마운트 시 조정할 수 있습니다.
`multi` 입력	같은 입력 포트에 여러 연결을 허용합니다. 대표적으로 `riskInputs`, 주문 `plot`, `chart.plotchar.shape`가 있습니다.

플로우 타입

플로우 타입	용도	자주 쓰는 상황
`event`	실행 순서와 부수 효과 트리거를 제어	`eventIn` -> 주문, 상태 쓰기, 차트 그리기
`data`	데이터 값을 전달	가격, 지표, boolean 조건, 거래쌍, 리스크 의도
`ui`	차트/인터페이스 시각 체인의 과거 타입	현재 차트 노드는 대부분 말단 시각 노드로 사용됩니다

값 타입

타입	의미	자주 나오는 출처
`any`	임의 타입	표현식 입력, 동적 라벨, 호환 포트
`voidType`	데이터가 없는 이벤트	이벤트 노드의 트리거 출력
`number` / `integer` / `doubleType`	숫자, 정수, double	지표, 가격 계산, 카운터
`boolType`	boolean 조건	Compare, AND/OR, 신호 노드
`text`	텍스트	라벨, 주석, 상태 텍스트
`symbol`	거래쌍	Symbol Selector
`timeframe`	주기	주기 필터
`timestamp`	시간	날짜 필터, 차트 시간 구간
`seriesNumber`	숫자 시리즈	거래량, 시간 시리즈
`ohlcvSeries`	캔들 시리즈	Get OHLCV의 open/high/low/close
`chartVisualRef` / `chartPlotRef` / `chartHLineRef`	차트 객체 참조	Plot, HLine, Fill, 주문 마커 템플릿
`price`	가격	Last Price, Bid/Ask, Mark Price
`orderIntent`	리스크 또는 주문 의도	리스크 노드 출력, 주문 노드 입력
`orderUpdate`	주문 회신	주문 이벤트 노드
`position` / `balance` / `account`	포지션, 잔고, 계정 스냅샷	계정/포지션 시장 노드

컴파일과 연결 규칙

블루프린트에는 이벤트 소스 노드가 최소 하나 있어야 합니다. 그렇지 않으면 실행되지 않습니다.
데이터 플로우는 순환이 없는 그래프여야 합니다. 데이터 노드가 서로 순환하면 컴파일이 실패합니다.
이벤트 플로우에 순환이 있으면 logic.gate로 제한해야 합니다. 그렇지 않으면 고빈도 반복 트리거가 발생할 수 있습니다.
데이터 포트 타입은 일치해야 합니다. 타입이 맞지 않으면 tool.cast_number, tool.cast_integer, tool.cast_bool을 넣어 명시적으로 변환하세요.
일반 입력 포트는 연결을 하나만 허용합니다. 여러 연결을 지원하는 입력 포트는 노드 정의에 표시됩니다.
주문 노드는 반드시 eventIn에 연결해야 합니다. 이벤트가 트리거되지 않으면 실행되지 않습니다.
주문 노드가 있는 경우 riskInputs에 최소 하나 이상의 리스크 노드를 연결하는 것이 좋습니다. 컴파일러는 주문 노드가 있지만 리스크 노드가 없거나, 주문 노드에 리스크 입력이 없다는 경고를 낼 수 있습니다.
market.symbol_selector는 현재 백테스트, 마운트, 디버그 컨텍스트의 거래쌍을 출력합니다. 재사용 가능한 블루프린트 템플릿에 적합하며, 템플릿에 거래쌍을 하드코딩하지 않아도 됩니다.
market.get_ohlcv의 timeframe=runtime은 실행 주기를 따릅니다. 상위 주기 필터를 쓰려면 1h, 15m 같은 주기를 명시적으로 선택하세요.

3. 고빈도 전략 구성 권장 사항

고빈도 또는 회전율이 높은 전략은 먼저 트리거 빈도와 주문 빈도를 제어해야 합니다.

기본 트리거는 event.on_bar 또는 event.on_bar_close를 우선 사용하세요. Tick 단위 반응이 명확히 필요할 때만 event.on_tick을 사용하세요.
event.on_tick 또는 짧은 event.on_timer를 사용한다면, 하위 체인에 logic.gate, risk.max_order_rate, logic.once_per_bar 중 하나 이상을 추가하세요.
같은 캔들에서 반복 진입을 원하지 않으면 logic.once_per_bar 또는 state.last_signal을 사용하세요.
Tick 레벨에서 큰 캔들 수를 반복 조회하지 마세요. market.get_ohlcv.limit은 지표 요구에 맞추고, 보통 100-300이면 충분합니다.
실행 주기와 판단 주기는 분리할 수 있습니다. 예를 들어 15m 실행, 1h 필터라면 이벤트 노드는 15m, 시장 노드는 1h로 설정합니다.
실거래 체인에서는 risk.kill_switch, risk.order_validation, risk.max_position_size, risk.max_order_rate를 기본으로 연결하는 것을 권장합니다.
손실 후 일시 정지가 필요한 전략은 risk.cooldown_after_loss 또는 risk.daily_consecutive_loss_cooldown을 추가하세요.

4. 이벤트 노드

이벤트 노드는 블루프린트 실행 진입점입니다. 이벤트 노드가 없으면 시장, 지표, 로직, 주문 노드가 런타임 프레임을 만들지 않습니다.

Node ID	이름	주요 입력	주요 출력	파라미터	용도와 주의 사항
`event.on_start`	OnStart	없음	`out` 트리거	없음	전략 시작 시 한 번 트리거됩니다. 변수 초기화나 초기 스냅샷 읽기에 적합합니다.
`event.on_stop`	OnStop	`enabled`	`out` 트리거	없음	전략 중지 시 한 번 트리거됩니다. 마무리 로직에 사용할 수 있습니다.`enabled`가 연결되지 않으면 기본적으로 활성으로 처리됩니다.
`event.on_bar`	OnBar	`timeframe`	`out` 트리거	`timeframe` 기본값 `1m`, 옵션 `1s/1m/5m/15m/1h`	지정한 주기마다 트리거되며 기본 전략 진입점으로 적합합니다.
`event.on_bar_open`	OnBarOpen	`timeframe`	`out` 트리거	OnBar와 동일	각 캔들 시작 시 트리거됩니다. 캔들 시작 실행에 적합합니다.
`event.on_bar_close`	OnBarClose	`timeframe`	`out` 트리거	OnBar와 동일	각 캔들 종료 시 트리거됩니다. 확정 캔들을 사용해 리페인트를 줄일 수 있습니다.
`event.on_tick`	OnTick	없음	`out` 트리거	없음	각 Tick마다 트리거되어 빈도가 가장 높습니다. 반드시 빈도 제한과 리스크 제어를 함께 사용하세요.
`event.on_timer`	OnTimer	`enabled`, `intervalSec`	`out` 트리거	`intervalSec=60`, 범위 1-86400초	고정 간격으로 트리거됩니다. 입력 포트로 파라미터를 덮어쓸 수 있습니다.
`event.on_order_update`	OnOrderUpdate	`symbol`, `side`, `status` 필터	`event`, `order`	없음	주문/체결 회신으로 트리거됩니다. 체결 후 상태 갱신이나 TP/SL 추가에 적합합니다.
`event.on_trade_transaction`	OnTradeTransaction	`symbol`, `side`, `status` 필터	`event`, `order`	없음	거래 트랜잭션 업데이트로 트리거됩니다. 더 세밀한 주문 상태 처리에 적합합니다.
`event.on_position_update`	OnPositionUpdate	`symbol`, `side` 필터	`event`, `position`	없음	포지션 변화 시 트리거됩니다. 포지션 동기화와 리스크 상태 갱신에 적합합니다.

5. 시장 노드

시장 노드는 현재 실행 컨텍스트에서 거래쌍, 캔들, 가격, 계정, 포지션 데이터를 읽습니다.

Node ID	이름	주요 입력	주요 출력	파라미터	용도와 주의 사항
`market.symbol_selector`	Symbol Selector	`eventIn`	`eventOut`, `symbol`	없음	현재 마운트 또는 백테스트 중인 거래쌍을 출력합니다. 블루프린트 안에 symbol을 하드코딩하지 마세요.
`market.get_ohlcv`	Get OHLCV	`symbol`	`series/open/high/low/close/hlc3/ohlc4/volume/time`	`limit=200`, `timeframe=runtime/1m/5m/15m/1h`	최근 N개 캔들을 가져옵니다. 지표는 보통 `series` 또는 `close`에 연결하고, 변동성 지표는 high/low/close를 사용할 수 있습니다.
`market.last_price`	Get Last Price	`symbol`	`price`	없음	최신 체결가를 읽습니다. 실시간 조건이나 차트 가격 레벨에 적합합니다.
`market.bid_ask`	Get Bid/Ask	`symbol`	`bid`, `ask`	없음	최우선 매수/매도 호가를 읽습니다. 슬리피지 추정이나 능동/수동 실행 판단에 적합합니다.
`market.mark_price`	Get Mark Price	`symbol`	`price`	없음	무기한 선물의 마크 가격을 읽습니다. 선물 리스크 판단에 적합합니다.
`market.account_snapshot`	Get Balance/Position	`eventIn`	`eventOut`, `balance`, `position`	없음	계정 잔고와 포지션 스냅샷을 읽습니다. 이벤트 입력을 연결하면 읽는 시점을 제어할 수 있습니다.
`market.position_state`	Get Position State	`symbol`	`qty/absQty/side/entryPrice/openTimeMs/unrealizedPnl/isFlat`	없음	현재 거래쌍의 포지션 상태를 출력합니다. “무포지션일 때만 진입”, “보유 중일 때만 청산”에 자주 사용됩니다.

6. 지표 노드

대부분의 지표 노드는 ohlcvSeries를 받아 현재 bar 값을 출력합니다. 다중 주기 필터가 필요하면 Get OHLCV.timeframe을 목표 주기로 설정하세요.

Node ID	이름	주요 입력	주요 출력	핵심 파라미터	사용 상황
`indicator.sma`	SMA	`series`	`value`	`period=20`	단순 이동평균. 추세 방향과 평균 회귀 기준선에 사용합니다.
`indicator.ema`	EMA	`series`	`value`	`period=21`	지수 이동평균. SMA보다 반응이 빠릅니다.
`indicator.kama`	KAMA	`series`	`value/previous/slope/trend`	`erPeriod=10`, `fastPeriod=2`, `slowPeriod=30`, `slopeLookback=5`	적응형 이동평균. 횡보 구간 노이즈 필터링에 적합합니다.
`indicator.rsi`	RSI	`series` 또는 high/low/close	`value`	`period=14`	과매수/과매도, 모멘텀 다이버전스, 풀백 확인.
`indicator.atr`	ATR	`series` 또는 high/low/close	`value`	`period=14`	변동성, 손절 거리, 저변동성 필터.
`indicator.atr_median`	ATR Median	`high/low/close`	`atr/median`	`atrPeriod=14`, `medianPeriod=50`	현재 변동성이 평소보다 높은지 판단합니다.
`indicator.bb`	Bollinger Bands	`series`	`upper/middle/lower`	`period=20`	볼린저 돌파, 평균 회귀, 밴드 폭 필터.
`indicator.macd`	MACD	`series`	`macd/signal/hist`	`fastPeriod=12`, `slowPeriod=26`, `signalPeriod=9`	추세 모멘텀과 0선 필터.
`indicator.donchian`	Donchian	`series`	`upper/middle/lower`	`period=20`	구간 돌파와 터틀류 전략.
`indicator.candle_streak`	Candle Streak	`open/high/low/close`	`bullStreak/bearStreak/bullMoveAtr/bearMoveAtr/bodyAtr/direction`	`atrPeriod=14`, `minBodyPct=0.00005`	연속 양봉/음봉과 몸통 강도 필터. 과도한 추격 진입을 줄이는 데 사용합니다.
`indicator.adx`	ADX	`series` 또는 high/low/close	`value`	`period=14`	추세 강도 필터. 일반적인 기준값은 20/25입니다.
`indicator.chop`	CHOP	`series` 또는 high/low/close	`value`	`period=14`	추세/횡보 상태를 구분합니다. 값이 높으면 횡보, 낮으면 추세에 가깝습니다.
`indicator.vwap`	VWAP	`series`	`value`	`period=20`	거래량 가중 평균 가격. 장중 가격 괴리 판단에 적합합니다.
`indicator.stoch`	Stoch	`series`	`k/d`	`period=14`, `smoothK=3`, `smoothD=3`	스토캐스틱 지표. 횡보장에서 진입/청산에 사용합니다.
`indicator.stoch_rsi`	Stochastic RSI	`series`	`k/d`	`period=14`, `smoothK=3`, `smoothD=3`	RSI에 스토캐스틱을 적용해 더 민감한 신호를 만듭니다.
`indicator.highest`	Highest N	`series`	`value`	`period=20`	최근 N개 캔들의 최고값. 돌파 기준으로 사용합니다.
`indicator.lowest`	Lowest N	`series`	`value`	`period=20`	최근 N개 캔들의 최저값. 하향 돌파 기준으로 사용합니다.
`indicator.ichimoku`	Ichimoku	`series`	`conversion/base/spanA/spanB/lagging`	`conversionPeriod=9`, `basePeriod=26`, `spanBPeriod=52`, `displacement=26`	일목균형표. 여러 구성 요소로 추세 구조를 판단합니다.
`indicator.supertrend`	Supertrend	`series`	`value/trend`	`period=10`, `multiplier=3.0`	추세 추종과 손절 기준.
`indicator.fibonacci`	Fibonacci Retracement	`series`	`level0/236/382/500/618/786/100`	`period=100`	최근 구간의 피보나치 되돌림 레벨.
`indicator.cci`	CCI	`series`	`value`	`period=20`	CCI 순환 지표. 추세와 극단값 판단에 사용합니다.
`indicator.williams_r`	Williams %R	`series`	`value`	`period=14`	과매수/과매도 오실레이터.
`indicator.parabolic_sar`	Parabolic SAR	`series`	`value/trend`	`afStart=0.02`, `afStep=0.02`, `afMax=0.2`	추세 반전과 이동 손절 기준.
`indicator.obv`	OBV	`series`	`value`	없음	OBV. 가격과 거래량 방향 확인에 사용합니다.
`indicator.mfi`	MFI	`series`	`value`	`period=14`	거래량을 반영한 과매수/과매도 지표.
`indicator.volume`	Volume	`seriesNumber`	`value/average`	`period=20`	현재 거래량과 평균 거래량 비교. 가짜 돌파 필터에 사용합니다.
`indicator.keltner`	Keltner Channels	`series`	`upper/middle/lower`	`emaPeriod=20`, `atrPeriod=10`, `multiplier=2.0`	ATR 기반 채널 돌파와 풀백.
`indicator.roc`	ROC	`series`	`value`	`period=12`	가격 변화율. 가격 속도를 판단합니다.
`indicator.momentum`	Momentum	`series`	`value`	`period=10`	모멘텀 오실레이터.
`indicator.smoothed_momentum`	Smoothed Momentum	`series`	`momentum/value/bull/bear`	`period=10`, `smooth=3`	평활화된 모멘텀과 bullish/bearish boolean 출력을 제공합니다.
`indicator.wavetrend`	WaveTrend	`series`	`wt1/wt2/bull/bear/crossOver/crossUnder`	`channelLength=9`, `averageLength=12`, `maLength=3`, `overbought=60`, `oversold=-60`	오실레이터와 교차 신호. 풀백 확인에 적합합니다.
`indicator.aroon`	Aroon	`series`	`up/down/oscillator`	`period=25`	신고가/신저가 기반의 추세 강도를 식별합니다.
`indicator.cmf`	CMF	`series`	`value`	`period=20`	Chaikin Money Flow. 자금 유입/유출 필터.
`indicator.pivot_points`	Pivot Points	`series`	`pp/r1/r2/r3/s1/s2/s3`	`period=20`	지지/저항, 돌파, 풀백 목표.

7. 신호와 로직 노드

신호 노드는 보통 boolean 값을 출력합니다. 로직 노드는 조건을 조합하거나 이벤트 플로우를 제어합니다.

Node ID	이름	주요 입력	주요 출력	파라미터	용도와 주의 사항
`logic.compare`	Compare	`left/right`	`result`	`operator` 옵션 `> = true` 순간에만 이벤트를 통과시켜 조건이 계속 true일 때 반복 주문을 막습니다.
`logic.if_else`	If-Else	`eventIn/condition`	`trueOut/falseOut`	없음	조건에 따라 이벤트 플로우를 분기합니다.
`bool.expression`	Bool Expression	동적 변수 입력	`result`	`expression`, `variableCount`, 변수 별칭	다단계 Compare/AND/OR/NOT 조합을 표현식 하나로 대체합니다.`and/or/not`, `&&/
`logic.bool_expr`	Bool Expr	`a/b/c/d`	`result`	`expression`	기존 boolean 표현식 노드. 변수는 a-d로 고정됩니다.
`logic.ternary`	Select / Ternary	동적 변수 입력	`result`	`expression`, 변수 별칭	`a ? b : c` 같은 삼항 표현식. 색상, 숫자, 텍스트 선택에 적합합니다.
`logic.select_value`	Select Value	`condition/trueValue/falseValue`	`result`	없음	boolean 조건에 따라 두 값 중 하나를 선택합니다.
`logic.gate`	Gate	`eventIn`	`eventOut`	`cooldownSec=10`	이벤트 플로우 제한. 고빈도, Tick, 순환 이벤트에서 중요합니다.
`logic.once_per_bar`	Once Per Bar	`eventIn`	`eventOut`	없음	같은 캔들에서 한 번만 이벤트를 통과시킵니다.

표현식 노드 참고:

bool.expression, math.expression, tool.number_expr는 동적 변수 수를 지원합니다. variableCount 범위는 1-32입니다.
변수 기본 이름은 a/b/c...입니다. close, emaFast, atr 같은 별칭을 쓰면 표현식이 읽기 쉬워집니다.
boolean 표현식에는 `close > ema and rsi 주문 노드 riskInputs


## 9. 함수 노드와 주문 노드

함수 노드는 Pine Script 스타일의 거래 함수이며 `eventOut`, `triggered`, `label`을 출력하므로 전략 체인에서 계속 연결하기 좋습니다. 주문 노드는 말단 동작 노드에 가깝고 보통 거래 체인의 끝에 둡니다.

### 함수 노드

| Node ID                 | 이름                | 주요 입력                               | 주요 출력                    | 핵심 파라미터                                                                                                 | 용도와 주의 사항                                                                                               |
| ----------------------- | ------------------- | --------------------------------------- | ---------------------------- | ------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
| `strategy.entry`      | strategy.entry      | `eventIn/when/symbol/riskInputs/plot` | `eventOut/triggered/label` | `enabled`, `entryId`, `direction`, `orderType`, `qtyMode`, `qty`, `limitOffsetPct`, `comment` | `when`이 true일 때 롱 또는 숏 진입 의도를 생성합니다. `entryId`는 전략 태그이며 거래소 주문 ID가 아닙니다. |
| `strategy.cancel`     | strategy.cancel     | `eventIn/when/riskInputs/plot`        | `eventOut/triggered/label` | `enabled`, `orderId`, `comment`                                                                         | 지정한 거래소 주문을 취소합니다. live 취소에는 보통 실제 `orderId`가 필요합니다.                             |
| `strategy.close`      | strategy.close      | `eventIn/when/symbol/riskInputs/plot` | `eventOut/triggered/label` | `enabled`, `entryId`, `orderType`, `qtyMode`, `qty`, `limitOffsetPct`, `comment`                | 현재 거래쌍 포지션을 전체, 수량, 퍼센트 방식으로 청산합니다.                                                   |
| `strategy.cancel_all` | strategy.cancel_all | `eventIn/when/riskInputs/plot`        | `eventOut/triggered/label` | `enabled`, `comment`                                                                                      | 조건이 true일 때 전체 취소 의도를 생성합니다.                                                                  |
| `strategy.close_all`  | strategy.close_all  | `eventIn/when/symbol/riskInputs/plot` | `eventOut/triggered/label` | `enabled`, `orderType`, `limitOffsetPct`, `comment`                                                   | 조건이 true일 때 현재 거래쌍의 전체 포지션을 청산합니다.                                                       |
| `strategy.exit`       | strategy.exit       | `eventIn/when/symbol/riskInputs/plot` | `eventOut/triggered/label` | `exitId`, `fromEntry`, `stop`, `limit`, `profit`, `loss`, `trailPoints`, `trailOffset`        | Pine 스타일 종료 규칙입니다. 손절, 익절, 트레일링 스톱을 설정할 수 있습니다.                                   |

### 주문 노드

| Node ID                  | 이름                 | 주요 입력                                                       | 출력 | 핵심 파라미터                                                                                     | 용도와 주의 사항                                                                                                         |
| ------------------------ | -------------------- | --------------------------------------------------------------- | ---- | ------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| `strategy.entry_block` | Strategy Entry Block | `eventIn/longCondition/shortCondition/symbol/riskInputs/plot` | 없음 | `orderType`, `qtyMode`, `qty`, `preferLongWhenBoth`, `longLabel`, `shortLabel`        | 전략 수준 진입 블록입니다. 롱/숏 조건을 동시에 받을 수 있으며, 양쪽이 동시에 트리거될 때 우선 방향을 설정할 수 있습니다. |
| `strategy.exit_block`  | Strategy Exit Block  | `eventIn/longCondition/shortCondition/symbol/riskInputs/plot` | 없음 | `orderType`, `qtyMode`, `qty`, `longLabel`, `shortLabel`                                | 전략 수준 청산 블록입니다. 롱/숏 종료 조건에서 바로 청산 의도를 생성합니다.                                              |
| `order.place_market`   | Place Market Order   | `eventIn/sideInput/riskInputs/plot`                           | 없음 | `side=buy/sell/auto`, `qtyMode=fixed/percent/quantity`, `qty`                               | 시장가 주문 의도를 생성합니다. 현재 `qty`는 USDT 금액으로 해석되며, `percent`는 사용 가능 자금 비율을 사용합니다.    |
| `order.place_limit`    | Place Limit Order    | `eventIn/sideInput/riskInputs/plot`                           | 없음 | `side`, `qtyMode`, `qty`, `priceOffsetPct`                                                | 지정가 주문 의도를 생성합니다. BUY는 아래로, SELL은 위로 오프셋됩니다.                                                   |
| `order.cancel_order`   | Cancel Order         | `eventIn/riskInputs/plot`                                     | 없음 | `orderId`                                                                                       | 지정한 거래소 주문을 취소합니다.                                                                                         |
| `order.close_position` | Close Position       | `eventIn/riskInputs/plot`                                     | 없음 | `qtyMode=all/quantity/percent`, `qty`, `orderType`, `priceOffsetPct`, `reduceOnly=true` | 현재 포지션을 청산합니다. 기본값은 reduce-only입니다.                                                                    |
| `order.set_tpsl`       | Set TP/SL            | `eventIn/riskInputs/plot`                                     | 없음 | `stopLossPct=1.0`, `takeProfitPct=2.0`                                                        | 포지션 또는 주문에 익절/손절 의도를 설정합니다.                                                                          |

주문 체인 예시:

OnBarClose(15m).out

-> Edge Trigger.eventIn

Compare.result

-> Edge Trigger.condition

Edge Trigger.eventOut

-> strategy.entry.eventIn

Symbol Selector.symbol

-> strategy.entry.symbol

risk.max_order_rate.intent

risk.max_position_size.intent

risk.stop_take_rule.intent

-> strategy.entry.riskInputs


## 10. 상태 노드

상태 노드는 런타임 중 변수와 신호를 기억합니다. 재시작 후에도 값을 유지해야 하면 `persistent_*`를 사용하세요.

| Node ID                  | 이름              | 주요 입력               | 주요 출력                          | 파라미터                          | 용도와 주의 사항                                                          |
| ------------------------ | ----------------- | ----------------------- | ---------------------------------- | --------------------------------- | ------------------------------------------------------------------------- |
| `state.var_set`        | Var Set           | `value`               | `value`                          | `key=signal`                    | 현재 전략 변수를 설정합니다. 생명주기는 보통 런타임 인스턴스를 따릅니다.  |
| `state.var_get`        | Var Get           | 없음                    | `value`                          | `key=signal`                    | 현재 전략 변수를 읽습니다.                                                |
| `state.counter`        | Counter           | `eventIn`             | `value/eventOut`                 | `initialValue=0`, `step=1`    | 이벤트가 트리거될 때마다 카운트합니다. 트리거 횟수 통계에 적합합니다.     |
| `state.persistent_set` | Persistent KV Set | `eventIn/value`       | `value/eventOut`                 | `key=last_signal`               | 재시작 후에도 유지되는 변수를 씁니다.                                     |
| `state.persistent_get` | Persistent KV Get | 없음                    | `value`                          | `key=last_signal`, `fallback` | 영속 변수를 읽습니다. 키가 없으면 기본값을 반환합니다.                    |
| `state.rolling_window` | Rolling Window    | `eventIn/value`       | `values/latest/count/eventOut`   | `size=20`                       | 최근 N개 숫자 값의 롤링 윈도우를 유지합니다.                              |
| `state.last_signal`    | Last Signal       | `eventIn/signal`      | `signal/changed/eventOut`        | `key=signal`                    | 이전 신호를 저장하고 변화 여부를 출력합니다. 반복 주문 방지에 적합합니다. |
| `state.overbought`     | Overbought State  | `value/threshold`     | `result`                         | `threshold=70`                  | 지표 값이 임계값 이상인지 판단합니다.                                     |
| `state.oversold`       | Oversold State    | `value/threshold`     | `result`                         | `threshold=30`                  | 지표 값이 임계값 이하인지 판단합니다.                                     |
| `state.midline`        | Midline State     | `value/threshold`     | `result`                         | `threshold=50`                  | 지표 값이 중간선 임계값 이상인지 판단합니다.                              |
| `strategy.trend_state` | Trend State       | `changeUp/changeDown` | `state/stateCode/isLong/isShort` | `longCode=B`, `shortCode=S`   | 상태 노드이기도 하며, 전환 신호를 기반으로 추세 상태를 유지합니다.        |

## 11. 도구 노드

도구 노드는 중간 계산과 형식 처리를 담당합니다. 복잡한 계산에는 표현식 노드를 우선 사용하고, 단순 계산에는 사칙연산 노드를 사용하세요.

| Node ID               | 이름            | 주요 입력      | 주요 출력     | 파라미터                                     | 용도와 주의 사항                                                       |
| --------------------- | --------------- | -------------- | ------------- | -------------------------------------------- | ---------------------------------------------------------------------- |
| `math.expression`   | Math Expression | 동적 변수 입력 | `value`     | `expression`, `variableCount`, 변수 별칭 | `+ - * / %`와 괄호를 지원하는 숫자 표현식입니다.                     |
| `tool.number_expr`  | Number Expr     | 동적 변수 입력 | `value`     | `expression`, `variableCount`, 변수 별칭 | 기존 숫자 표현식 노드입니다. Add/Sub/Mul/Div 체인을 대체하기 좋습니다. |
| `tool.cast_number`  | Cast -> Number  | `value`      | `value`     | 없음                                         | 값을 명시적으로 숫자로 변환합니다.                                     |
| `tool.cast_integer` | Cast -> Int     | `value`      | `value`     | 없음                                         | 값을 명시적으로 정수로 변환합니다.                                     |
| `tool.cast_bool`    | Cast -> Bool    | `value`      | `value`     | 없음                                         | 값을 명시적으로 boolean으로 변환합니다.                                |
| `tool.clamp`        | Clamp           | `value`      | `value`     | `min=0`, `max=100`                       | 값을 지정 구간 안으로 제한합니다.                                      |
| `tool.normalize`    | Normalize       | `value`      | `value`     | `min=0`, `max=100`                       | 값을 0-1로 정규화합니다.                                               |
| `tool.add`          | Add             | `a/b`        | `value`     | 없음                                         | 덧셈.                                                                  |
| `tool.sub`          | Sub             | `a/b`        | `value`     | 없음                                         | 뺄셈.                                                                  |
| `tool.mul`          | Mul             | `a/b`        | `value`     | 없음                                         | 곱셈.                                                                  |
| `tool.div`          | Div             | `a/b`        | `value`     | 없음                                         | 나눗셈.                                                                |
| `tool.map_symbol`   | Map Symbol      | `symbol`     | `symbol`    | `exchange=binance/okx/bybit`               | 거래쌍을 대상 거래소 형식으로 매핑합니다.                              |
| `tool.tag`          | JSON/Tag        | `value`      | `value/tag` | `tag`                                      | 데이터에 텍스트 태그나 JSON 조각을 붙입니다.                           |
| `tool.round`        | Round/Precision | `value`      | `value`     | `precision=2`                              | 가격, 수량, 차트 표시용 숫자 정밀도를 처리합니다.                      |

## 12. 차트 노드

차트 노드는 전략을 시각화합니다. 일부 노드는 `eventIn`으로 현재 bar를 그릴지 제어하고, 일부는 순수 데이터 기반입니다. 차트 노드는 보통 주문 판단에 직접 참여하지 않으며 전략 체인의 보조 출력으로 사용하는 것이 좋습니다.

### 공통 차트 파라미터

| 파라미터        | 설명                                                                                                          |
| --------------- | ------------------------------------------------------------------------------------------------------------- |
| `pane`        | 표시 영역:`main` 메인 차트, `chart` 차트 레이어, `volume` 거래량, `indicator:0/1` 지표 패널.          |
| `visible`     | 표시 여부.                                                                                                    |
| `zIndex`      | 레이어 순서, 범위 -200부터 200까지. 값이 클수록 위에 표시됩니다.                                              |
| `layer`       | 렌더링 레이어:`background`, `underlay`, `overlay`, `annotation`.                                      |
| `style`       | Plot 스타일:`line`, `linebr`, `stepline`, `area`, `histogram`, `columns`, `circles`, `cross`. |
| `strokeStyle` | 선 스타일:`solid`, `dashed`, `dotted`.                                                                  |

### 차트 노드 인덱스

| Node ID                      | 이름            | 주요 입력                                               | 주요 출력    | 핵심 파라미터                                                                                 | 용도와 주의 사항                                                                               |
| ---------------------------- | --------------- | ------------------------------------------------------- | ------------ | --------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
| `chart.color`              | Color           | 없음                                                    | `color`    | `color=#FF38BDF8`                                                                           | 색상 텍스트를 출력해 여러 차트 노드에서 재사용할 수 있습니다.                                  |
| `chart.background`         | Background      | `eventIn/color/startValue/endValue/startTime/endTime` | 없음         | `color`, `rangeMode=bars/time`, `startBarsAgo/endBarsAgo`                               | 캔들 구간 또는 시간 구간에 배경 영역을 그립니다.                                               |
| `chart.bar_color`          | Bar Color       | `eventIn`                                             | 없음         | `colorMode=single/trend/theme`, body/wick/border/up/down 색상                               | 캔들 색상을 변경합니다. 추세 상태 시각화에 적합합니다.                                         |
| `chart.plots`              | Plot            | `color/value`                                         | `plotRef`  | `style`, `color`, `lineWidth`, `histBase`, `offset`, `showLast`, `trackPrice`   | 지표선, 막대, 영역 등을 그리고 Plot 참조를 출력합니다.                                         |
| `strategy.plot_trend_line` | Plot Trend Line | `value/trend`                                         | `plotRef`  | `style`, `upColor`, `downColor`, `neutralColor`, `lineWidth`                        | 추세 상태에 따라 색상이 자동 전환되는 지표선입니다.                                            |
| `chart.fill`               | Fill            | `color/plot1/plot2`                                   | 없음         | `color`, `showLast`, `fillGaps`                                                         | 두 Plot/HLine 참조 사이 영역을 채웁니다. 두 참조는 같은 패널에 있어야 합니다.                  |
| `chart.hline`              | HLine           | `price/color/startValue/endValue/startTime/endTime`   | `hlineRef` | `price`, `title`, `color`, `linestyle`, `linewidth`, `rangeMode`                  | 수평선을 그리고 Fill 참조로도 사용할 수 있습니다.                                              |
| `chart.levels`             | Levels          | `value/color`                                         | 없음         | `value`, `color`, `lineWidth`, `strokeStyle`, `label`, 구간 파라미터                | 지지/저항, 익절/손절 참고용 가격선을 그립니다.                                                 |
| `chart.line`               | Line            | `startValue/endValue`                                 | 없음         | `lineColor`, `lineWidth`, `strokeStyle`, `leftBarsAgo/rightBarsAgo`                   | 과거 bar에서 현재 또는 미래 오프셋까지 선분을 그립니다.                                        |
| `chart.box`                | Box             | `top/bottom/text`                                     | 없음         | `fillColor`, `borderColor`, `textColor`, `borderWidth`, `leftBarsAgo/rightBarsAgo`  | 가격 구간 박스를 그립니다. 횡보 구간이나 공급/수요 구역에 적합합니다.                          |
| `chart.tables`             | Tables          | `eventIn` 및 동적 `value1...valueN`                 | 없음         | `title`, `placement`, `itemCount=1-12`, `labelPosition`, `columnCount`, 색상과 정렬 | 차트 대시보드를 표시합니다.`itemCount`에 따라 값 입력과 라벨 파라미터가 동적으로 확장됩니다. |
| `chart.text`               | Text            | `value`                                               | `text`     | `color`, `textFallback`, `size`, `barsAgo`                                            | 텍스트를 출력합니다. 값이 연결되면 “텍스트 + 값” 형태로 이어 붙입니다.                       |
| `chart.shapes`             | Shapes          | `value/series/text`                                   | `shape`    | `shape`, `location=abovebar/belowbar/absolute`, 색상, 크기, offset                        | 형태 마커를 그립니다.`series`가 false이면 보통 그리지 않습니다.                              |
| `chart.plotchar`           | PlotChar        | `series/value/text/shape`                             | 없음         | `location`, `value`, `color`, `offset`, `yOffset`                                   | 조건에 따라 텍스트 또는 형태 마커를 그립니다.`shape`는 다중 연결을 지원합니다.               |
| `chart.entry_plot`         | Entry Plot      | 없음                                                    | `plotRef`  | `shape=arrow_right_sharp`, `size`, `textSize`                                           | 진입 차트 템플릿을 출력합니다. 실제 그리기는 주문 체결 시 발생합니다.                          |
| `chart.exit_plot`          | Exit Plot       | 없음                                                    | `plotRef`  | `shape=arrow_left_sharp`, `size`, `textSize`                                            | 청산 차트 템플릿을 출력합니다. 실제 그리기는 주문 체결 시 발생합니다.                          |

자주 쓰는 차트 연결:

EMA.value -> chart.plots.value

RSI.value -> chart.tables.value1

Entry Plot.plotRef -> strategy.entry.plot

Exit Plot.plotRef -> strategy.close.plot


## 13. 자주 쓰는 전략 템플릿

### 15m 실행, 1h 추세 필터

event.on_bar_close(timeframe=15m)

-> market.symbol_selector.eventIn

market.symbol_selector.symbol

-> market.get_ohlcv.symbol

market.get_ohlcv(timeframe=1h).close

-> indicator.ema(period=50)

market.get_ohlcv(timeframe=1h).close

-> indicator.ema(period=200)

EMA50.value > EMA200.value

-> logic.compare.result

logic.compare.result

-> strategy.entry.when

event.on_bar_close.out

-> logic.edge_trigger.eventIn

logic.compare.result

-> logic.edge_trigger.condition

logic.edge_trigger.eventOut

-> strategy.entry.eventIn


### 돌파 진입과 ATR 리스크

Get OHLCV.close -> indicator.donchian.series

Last Price.price -> signal.breakout.value

Donchian.upper -> signal.breakout.level

Get OHLCV -> indicator.atr

ATR.value -> strategy.atr_stop_block.atr

risk.max_order_rate.intent

risk.order_validation.intent

strategy.atr_stop_block.intent

-> strategy.entry.riskInputs


### 같은 신호의 반복 주문 방지

Compare.result -> state.last_signal.signal

OnBar.out -> state.last_signal.eventIn

state.last_signal.changed -> strategy.entry.when

state.last_signal.eventOut -> strategy.entry.eventIn


## 14. 문제 해결

| 문제                         | 먼저 확인할 것                                                                                                                         |
| ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| 블루프린트가 컴파일되지 않음 | 이벤트 소스가 있는지, 포트 타입이 맞는지, 데이터 플로우가 순환하는지, 입력 포트에 중복 연결이 있는지 확인하세요.                       |
| 전략이 트리거되지 않음       | 이벤트 주기가 맞는지,`when`이 true인지, `Edge Trigger`가 이미 트리거됐는지, 날짜 필터가 만료됐는지 확인하세요.                     |
| 주문 노드가 실행되지 않음    | `eventIn`이 연결됐는지, `riskInputs`가 연결됐는지, 리스크가 거부했는지, 런타임 모드가 거래를 허용하는지 확인하세요.                |
| 고빈도 반복 주문             | `logic.gate`, `logic.once_per_bar`, `state.last_signal`, `risk.max_order_rate`를 추가하세요.                                   |
| 1h 필터가 적용되지 않음      | `market.get_ohlcv.timeframe`이 명시적으로 `1h`인지 확인하세요. 실수로 `runtime`을 쓰지 마세요.                                   |
| 지표가 비어 있거나 비정상    | `limit`이 지표 기간을 충분히 포함하는지, 입력이 올바른 시리즈에 연결됐는지, 백테스트 구간에 충분한 과거 캔들이 있는지 확인하세요.    |
| 차트가 표시되지 않음         | 필요한 차트 입력이 있는지,`visible`이 켜져 있는지, `pane/layer/zIndex`가 적절한지, Fill의 두 참조가 같은 패널에 있는지 확인하세요. |
| 타입 불일치                  | `tool.cast_number`, `tool.cast_integer`, `tool.cast_bool`을 삽입하세요.                                                          |

## 15. 전체 Node ID 인덱스

다음 인덱스는 블루프린트 파일의 `schemaId`를 빠르게 확인할 때 사용합니다.

| 분류   | Node ID                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| 이벤트 | `event.on_start`, `event.on_stop`, `event.on_bar`, `event.on_bar_open`, `event.on_bar_close`, `event.on_tick`, `event.on_timer`, `event.on_order_update`, `event.on_trade_transaction`, `event.on_position_update`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| 시장   | `market.symbol_selector`, `market.get_ohlcv`, `market.last_price`, `market.bid_ask`, `market.mark_price`, `market.account_snapshot`, `market.position_state`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| 지표   | `indicator.sma`, `indicator.ema`, `indicator.kama`, `indicator.rsi`, `indicator.atr`, `indicator.atr_median`, `indicator.bb`, `indicator.macd`, `indicator.donchian`, `indicator.candle_streak`, `indicator.adx`, `indicator.chop`, `indicator.vwap`, `indicator.stoch`, `indicator.stoch_rsi`, `indicator.highest`, `indicator.lowest`, `indicator.ichimoku`, `indicator.supertrend`, `indicator.fibonacci`, `indicator.cci`, `indicator.williams_r`, `indicator.parabolic_sar`, `indicator.obv`, `indicator.mfi`, `indicator.volume`, `indicator.keltner`, `indicator.roc`, `indicator.momentum`, `indicator.smoothed_momentum`, `indicator.wavetrend`, `indicator.aroon`, `indicator.cmf`, `indicator.pivot_points` |
| 신호   | `logic.cross_over`, `logic.cross_under`, `signal.enter_range`, `signal.leave_range`, `signal.breakout`, `signal.breakdown`, `strategy.date_range_filter`, `strategy.cross_signal`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| 로직   | `logic.compare`, `logic.boolean_and`, `logic.boolean_or`, `logic.boolean_not`, `logic.edge_trigger`, `logic.if_else`, `bool.expression`, `logic.bool_expr`, `logic.ternary`, `logic.select_value`, `logic.gate`, `logic.once_per_bar`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| 리스크 | `risk.max_order_rate`, `risk.kill_switch`, `risk.order_validation`, `risk.max_position_size`, `risk.cooldown_after_loss`, `risk.daily_consecutive_loss_cooldown`, `risk.stop_take_rule`, `strategy.atr_stop_block`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| 함수   | `strategy.entry`, `strategy.cancel`, `strategy.close`, `strategy.cancel_all`, `strategy.close_all`, `strategy.exit`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| 주문   | `strategy.entry_block`, `strategy.exit_block`, `order.place_market`, `order.place_limit`, `order.cancel_order`, `order.close_position`, `order.set_tpsl`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| 상태   | `strategy.trend_state`, `state.var_set`, `state.var_get`, `state.counter`, `state.persistent_set`, `state.persistent_get`, `state.rolling_window`, `state.last_signal`, `state.overbought`, `state.oversold`, `state.midline`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| 도구   | `math.expression`, `tool.number_expr`, `tool.cast_number`, `tool.cast_integer`, `tool.cast_bool`, `tool.clamp`, `tool.normalize`, `tool.add`, `tool.sub`, `tool.mul`, `tool.div`, `tool.map_symbol`, `tool.tag`, `tool.round`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| 차트   | `chart.color`, `chart.background`, `chart.bar_color`, `chart.plots`, `strategy.plot_trend_line`, `chart.fill`, `chart.hline`, `chart.levels`, `chart.line`, `chart.box`, `chart.tables`, `chart.text`, `chart.shapes`, `chart.plotchar`, `chart.entry_plot`, `chart.exit_plot`                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |