> For the complete documentation index, see [llms.txt](https://programgarden.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://programgarden.gitbook.io/docs/nodes/node_reference.md).
# 전체 노드 레퍼런스
ProgramGarden에서 사용할 수 있는 모든 노드의 상세 설명입니다. 각 노드는 워크플로우에서 하나의 **블록** 역할을 하며, 블록을 연결(엣지)하여 자동매매 전략을 만듭니다.
> **노드 수**: 12개 카테고리, 73개 노드
>
> **해외주식 / 해외선물 / 국내주식**: 대부분의 노드가 상품별로 분리되어 있습니다. 예를 들어 `OverseasStockBrokerNode`(해외주식), `OverseasFuturesBrokerNode`(해외선물), `KoreaStockBrokerNode`(국내주식)는 같은 기능이지만 상품이 다릅니다.
***
## 1. infra - 인프라/연결
워크플로우의 시작점, 증권사 연결, 데이터 흐름 제어를 담당하는 기반 노드들입니다.
### StartNode
워크플로우의 **진입점**입니다. 모든 워크플로우에 반드시 1개 있어야 합니다. StartNode 없이는 워크플로우가 실행되지 않습니다.
```json
{
"id": "start",
"type": "StartNode"
}
```
**출력**: `start` - 워크플로우 시작 신호
> **주의**: StartNode는 ScheduleNode와 함께 사용하면 스케줄에 따라 반복 실행됩니다. StartNode만 있으면 1회 실행 후 종료됩니다.
***
### BrokerNode (증권사 연결)
LS증권 API에 연결하는 노드입니다. **증권사 연결이 필요한 모든 노드**(계좌 조회, 시세 조회, 주문 등)는 이 노드가 먼저 있어야 합니다.
상품 유형에 따라 노드 타입이 다릅니다:
| 상품 | 노드 타입 | credential 타입 | 모의투자 |
| ---- | --------------------------- | ---------------------------- | ------------ |
| 해외주식 | `OverseasStockBrokerNode` | `broker_ls_overseas_stock` | 미지원 (실전만 가능) |
| 해외선물 | `OverseasFuturesBrokerNode` | `broker_ls_overseas_futures` | 지원 |
| 국내주식 | `KoreaStockBrokerNode` | `broker_ls_korea_stock` | 미지원 (실전만 가능) |
**해외주식 연결 (실전 전용):**
```json
{
"id": "broker",
"type": "OverseasStockBrokerNode",
"credential_id": "my-stock-cred",
"paper_trading": false
}
```
**해외선물 연결 (모의투자):**
```json
{
"id": "broker",
"type": "OverseasFuturesBrokerNode",
"credential_id": "my-futures-cred",
"paper_trading": true
}
```
**국내주식 연결:**
```json
{
"id": "broker",
"type": "KoreaStockBrokerNode",
"credential_id": "my-kr-cred"
}
```
| 필드 | 타입 | 필수 | 설명 |
| --------------- | ------- | :-: | ------------------------------------------------------------------------------------------------------------------ |
| `credential_id` | string | ✅ | credentials 섹션에서 정의한 인증 ID |
| `paper_trading` | boolean | ❌ | 모의투자 여부. **해외주식은 `false` 명시 필수** (기본값이 true여서 실전 연결이 실패). 해외선물은 `true`로 모의투자. 국내주식은 모의투자 미지원이므로 내부적으로 항상 false 강제. |
**출력**: `connection` - 증권사 연결 객체
> **자동 전달**: BrokerNode의 `connection`은 하위 노드(계좌, 시세, 주문 등)에 자동으로 전달됩니다. 엣지로 연결만 해주면 되고, `{{ nodes.broker.connection }}`처럼 직접 바인딩할 필요가 없습니다.
> **⚠️ OverseasStockBrokerNode는 `paper_trading: false` 필수**: Executor의 `paper_trading` 기본값은 `true`입니다. 해외주식 노드에서 이 필드를 생략하면 기본값(`true`)으로 처리되지만, LS증권은 해외주식 실거래만 제공하므로 연결이 즉시 거부되고 후속 노드(시세·계좌·주문 전부)가 전파 오류로 깨집니다. 따라서 **실거래 연결을 위해 반드시 `paper_trading: false`를 명시**해야 합니다.
| 노드 | `paper_trading` 값 | 의미 |
| --------------------------- | ----------------- | ---------------------------- |
| `OverseasStockBrokerNode` | `false` **필수 명시** | 실거래 연결 (모의투자 모드 없음) |
| `OverseasFuturesBrokerNode` | `true` / `false` | `true` → 모의투자, `false` → 실거래 |
| `KoreaStockBrokerNode` | (지정 불가) | 내부적으로 항상 `false` 강제 |
> **주의 - credential 설정**: `credential_id`가 credentials 섹션의 ID와 정확히 일치해야 합니다. 불일치하면 연결에 실패합니다.
***
### ThrottleNode
실시간 데이터의 흐름을 제어하는 **속도 조절기**입니다. 실시간 노드(RealMarketDataNode, RealAccountNode 등)는 초당 수십 번 데이터를 보내는데, 이를 받아서 하위 노드가 너무 자주 실행되지 않도록 막아줍니다.
```json
{
"id": "throttle",
"type": "ThrottleNode",
"mode": "latest",
"interval_sec": 5,
"pass_first": true
}
```
| 필드 | 타입 | 기본값 | 설명 |
| -------------- | ---------------------- | ---------- | ---------------------- |
| `mode` | `"skip"` \| `"latest"` | `"latest"` | 쿨다운 중 데이터 처리 방식 |
| `interval_sec` | number | `5` | 최소 실행 간격 (초), 0.1\~300 |
| `pass_first` | boolean | `true` | 첫 번째 데이터를 즉시 통과시킬지 여부 |
**모드 설명:**
| 모드 | 동작 | 언제 쓰나요? |
| -------- | -------------------------------------- | --------------------------- |
| `skip` | 쿨다운 중 들어오는 데이터를 전부 버림 | 단순히 실행 빈도만 줄이고 싶을 때 |
| `latest` | 쿨다운 중 최신 데이터만 기억해두고, 쿨다운 끝나면 그 데이터로 실행 | 항상 최신 상태를 반영해야 할 때 **(권장)** |
**latest 모드 동작 예시:**
```
시간 → 0초 1초 2초 3초 4초 5초 6초
데이터 A B C D - E F
결과 통과 대기 대기 대기 D실행 통과
(쿨다운 끝나면 가장 최신인 D 실행)
```
**필수 사용 패턴:**
{% @mermaid/diagram content="flowchart LR
A\[RealAccountNode] -->|빈번한 이벤트| B\[ThrottleNode] -->|5초마다| C\[ConditionNode] --> D\[OrderNode]" %}
> **중요**: 실시간 노드 → 주문 노드, 실시간 노드 → AI 에이전트를 **직접 연결하면 차단**됩니다. 반드시 ThrottleNode를 사이에 넣어야 합니다. 이는 초당 수십 번의 주문이 나가는 사고를 방지하기 위한 안전장치입니다.
> **팁**: `interval_sec`을 너무 짧게 설정하면 API 호출이 과도해져 증권사에서 제한당할 수 있습니다. 주문 관련 흐름에서는 최소 5초 이상을 권장합니다.
***
### SplitNode
리스트(배열) 데이터를 개별 항목으로 **분리**하여 하나씩 처리합니다. 예를 들어 관심종목 3개를 하나씩 분리해서 각각 차트 데이터를 조회할 때 사용합니다.
```json
{
"id": "split",
"type": "SplitNode",
"parallel": false,
"continue_on_error": true
}
```
| 필드 | 타입 | 기본값 | 설명 |
| ------------------- | ------- | ------- | -------------------------- |
| `parallel` | boolean | `false` | 병렬 실행 여부 (true면 동시에 실행) |
| `delay_ms` | number | `0` | 항목 간 대기 시간 (밀리초, 0\~60000) |
| `continue_on_error` | boolean | `true` | 하나가 에러 나도 나머지 계속 처리 |
**출력:**
* `item` - 현재 처리 중인 항목
* `index` - 현재 순번 (0부터 시작)
* `total` - 전체 항목 수
**사용 예시:**
{% @mermaid/diagram content="flowchart LR
A\["WatchlistNode
(AAPL, NVDA, TSM)"] -->|3개 종목| B\["SplitNode
(1개씩)"]
B -->|"1회차: AAPL"| C\[HistoricalDataNode]
B -->|"2회차: NVDA"| C
B -->|"3회차: TSM"| C" %}
하위 노드에서 현재 항목을 참조할 때는 `{{ item }}`을 사용합니다:
```json
{
"id": "history",
"type": "OverseasStockHistoricalDataNode",
"symbol": "{{ item }}"
}
```
> **주의 - API 호출 제한**: 종목이 많을 때 `parallel: true`로 설정하면 증권사 API를 동시에 많이 호출하게 되어 제한당할 수 있습니다. 10개 이상의 종목을 처리할 때는 `parallel: false`로 하고 `delay_ms: 500` 정도를 권장합니다.
> **팁**: SplitNode 없이도 이전 노드가 배열을 출력하면 다음 노드가 자동으로 반복 실행됩니다 (Auto-Iterate). SplitNode은 `parallel`, `delay_ms` 등 세밀한 제어가 필요할 때 사용하세요. 자세한 내용은 [자동 반복 처리 가이드](/docs/workflow/auto_iterate_guide.md)를 참고하세요.
***
### AggregateNode
SplitNode으로 분리된 결과를 다시 **하나로 모으는** 노드입니다. 예를 들어 3개 종목의 RSI 결과를 모아서 조건을 통과한 종목만 필터링할 때 사용합니다.
```json
{
"id": "aggregate",
"type": "AggregateNode",
"mode": "collect"
}
```
| 필드 | 타입 | 기본값 | 설명 |
| -------------- | ------ | ----------- | -------------------------------- |
| `mode` | string | `"collect"` | 집계 방식 |
| `filter_field` | string | `"passed"` | `filter` 모드에서 필터링할 필드명 |
| `value_field` | string | `"value"` | `sum`/`avg`/`min`/`max`에서 대상 필드명 |
**mode 옵션:**
| 모드 | 설명 | 사용 예시 |
| ---------------- | ------------------ | ---------------------- |
| `collect` | 모든 결과를 배열로 모음 | 3개 종목의 차트 데이터를 하나의 배열로 |
| `filter` | 특정 필드가 true인 것만 모음 | RSI 조건 통과한 종목만 |
| `sum` | 숫자 합계 | 전체 포지션 금액 합계 |
| `avg` | 숫자 평균 | 평균 수익률 |
| `min` / `max` | 최솟값 / 최댓값 | 가장 낮은 RSI 값 |
| `count` | 개수 | 조건 통과한 종목 수 |
| `first` / `last` | 첫 번째 / 마지막 항목 | - |
**출력:**
* `array` - 집계된 배열
* `value` - 집계된 단일 값 (sum, avg 등)
* `count` - 항목 수
**전형적인 패턴 (Split → 처리 → Aggregate):**
{% @mermaid/diagram content="flowchart LR
A\["WatchlistNode
(3종목)"] --> B\["SplitNode
(분리)"] --> C\["HistoricalDataNode
(각각 조회)"] --> D\["ConditionNode
(각각 평가)"] --> E\["AggregateNode
(결과 취합)"]" %}
***
### IfNode (조건 분기)
조건을 평가하여 **true/false 두 갈래로 실행 흐름을 분기**하는 노드입니다. 프로그래밍의 `if-else`와 같은 역할입니다.
```json
{
"nodes": [
{"id": "account", "type": "OverseasStockAccountNode"},
{"id": "if1", "type": "IfNode",
"left": "{{ nodes.account.balance }}",
"operator": ">=",
"right": 1000000},
{"id": "order", "type": "OverseasStockNewOrderNode"},
{"id": "notify", "type": "FieldMappingNode"}
],
"edges": [
{"from": "account", "to": "if1"},
{"from": "if1", "to": "order", "from_port": "true"},
{"from": "if1", "to": "notify", "from_port": "false"}
]
}
```
위 예시는 계좌 잔고가 100만원 이상이면 주문 실행, 미만이면 알림 노드로 분기합니다.
**입력 필드:**
| 필드 | 타입 | 설명 | 표현식 |
| ---------- | ------ | ------------------ | ----------------------------- |
| `left` | any | 왼쪽 피연산자 | `{{ nodes.account.balance }}` |
| `operator` | string | 비교 연산자 (기본값: `==`) | - |
| `right` | any | 오른쪽 피연산자 | `{{ 1000000 }}` |
**지원 연산자 (12종):**
| 연산자 | 설명 | 예시 |
| -------------- | ------------------- | --------------------------------------- |
| `==` | 같음 | `"AAPL" == "AAPL"` → true |
| `!=` | 다름 | `5 != 3` → true |
| `>` | 초과 | `100 > 50` → true |
| `>=` | 이상 | `100 >= 100` → true |
| `<` | 미만 | `50 < 100` → true |
| `<=` | 이하 | `100 <= 100` → true |
| `in` | 포함됨 | `"AAPL" in ["AAPL","TSLA"]` → true |
| `not_in` | 미포함 | `"MSFT" not_in ["AAPL","TSLA"]` → true |
| `contains` | 문자열 포함 | `"Hello World" contains "World"` → true |
| `not_contains` | 문자열 미포함 | `"Hello" not_contains "World"` → true |
| `is_empty` | 빈값 (right 불필요) | `[] is_empty` → true |
| `is_not_empty` | 비어있지 않음 (right 불필요) | `[1,2] is_not_empty` → true |
> **타입 자동 변환**: 숫자 비교(`>`, `>=`, `<`, `<=`)에서 문자열 `"100"`과 숫자 `50`을 비교하면 자동으로 숫자로 변환합니다. 변환 불가능한 경우 `false`를 반환합니다.
**출력:**
| 포트 | 타입 | 설명 |
| -------- | ------- | --------------------------------- |
| `true` | any | 조건 참 → upstream 데이터 pass-through |
| `false` | any | 조건 거짓 → upstream 데이터 pass-through |
| `result` | boolean | 조건 평가 결과 (`true` / `false`) |
**분기 연결 (from\_port):**
엣지에 `from_port`를 지정하여 어떤 브랜치의 후속 노드인지 명시합니다:
```json
{"from": "if1", "to": "buy_order", "from_port": "true"}
{"from": "if1", "to": "sell_order", "from_port": "false"}
```
`from_port`가 없는 엣지는 **항상 실행**됩니다 (합류 노드에 유용).
**활용 패턴:**
1. **잔고 확인 후 주문**: 잔고 >= 최소금액 → 매수 / 아니면 → 대기
2. **종목 필터링**: 종목코드 `in` 관심종목 리스트 → 분석 진행
3. **다단계 분기**: IfNode를 연속 배치하여 `if-elif-else` 구현
{% @mermaid/diagram content="flowchart LR
A\["AccountNode"] --> B\["IfNode
잔고 >= 100만?"]
B -->|true| C\["NewOrderNode
(매수)"]
B -->|false| D\["FieldMappingNode
(알림)"]" %}
> **캐스케이딩 스킵**: false 브랜치의 하위 노드들은 자동으로 실행이 스킵됩니다. 여러 노드가 연결되어 있어도 스킵이 전파됩니다.
***
## 2. account - 계좌 조회
계좌 잔고, 보유종목, 미체결 주문을 조회하는 노드들입니다.
### AccountNode (1회성 계좌 조회)
REST API로 현재 시점의 계좌 정보를 **한 번** 조회합니다. 스냅샷을 찍는 것과 같습니다.
| 상품 | 노드 타입 |
| ---- | ---------------------------- |
| 해외주식 | `OverseasStockAccountNode` |
| 해외선물 | `OverseasFuturesAccountNode` |
| 국내주식 | `KoreaStockAccountNode` |
```json
{
"id": "account",
"type": "OverseasStockAccountNode"
}
```
**출력:**
* `held_symbols` - 보유종목 코드 리스트 `["AAPL", "NVDA"]`
* `balance` - 예수금/매수가능금액
* `positions` - 보유종목 상세 정보
**positions 출력 예시:**
```json
[
{
"symbol": "AAPL",
"exchange": "NASDAQ",
"quantity": 10,
"buy_price": 185.50,
"current_price": 192.30,
"pnl_rate": 3.67
},
{
"symbol": "NVDA",
"exchange": "NASDAQ",
"quantity": 5,
"buy_price": 880.00,
"current_price": 920.50,
"pnl_rate": 4.60
}
]
```
> **주의**: AccountNode는 실행 시점의 데이터를 1회 조회합니다. 실시간으로 계속 업데이트되는 데이터가 필요하면 RealAccountNode을 사용하세요.
> **주의**: 보유종목이 없으면 `positions`는 빈 배열 `[]`을 반환합니다. 잔고가 0이면 `balance`는 0을 반환합니다. 에러가 아닙니다.
***
### OpenOrdersNode (미체결 주문 조회)
아직 체결되지 않은 주문 목록을 조회합니다. 지정가 주문을 넣었는데 아직 체결되지 않은 경우 등을 확인할 수 있습니다.
| 상품 | 노드 타입 |
| ---- | ------------------------------- |
| 해외주식 | `OverseasStockOpenOrdersNode` |
| 해외선물 | `OverseasFuturesOpenOrdersNode` |
| 국내주식 | `KoreaStockOpenOrdersNode` |
```json
{
"id": "openOrders",
"type": "OverseasStockOpenOrdersNode"
}
```
**출력:**
* `open_orders` - 미체결 주문 목록
* `count` - 미체결 주문 수
**open\_orders 출력 예시:**
```json
[
{
"order_no": "12345",
"symbol": "AAPL",
"side": "buy",
"order_type": "limit",
"price": 180.00,
"quantity": 10,
"filled_quantity": 0
}
]
```
> **팁**: CancelOrderNode와 `ScheduleNode` + `IfNode`를 조합하면 "30분 이내 미체결 시 자동 취소" 같은 로직을 직접 구현할 수 있습니다.
***
### RealAccountNode (실시간 계좌)
WebSocket으로 계좌 정보를 **실시간** 수신합니다. 주문이 체결되거나 시세가 변할 때마다 자동으로 업데이트됩니다.
| 상품 | 노드 타입 |
| ---- | -------------------------------- |
| 해외주식 | `OverseasStockRealAccountNode` |
| 해외선물 | `OverseasFuturesRealAccountNode` |
| 국내주식 | `KoreaStockRealAccountNode` |
```json
{
"id": "realAccount",
"type": "OverseasStockRealAccountNode",
"stay_connected": true,
"sync_interval_sec": 60,
"commission_rate": 0.25
}
```
| 필드 | 타입 | 기본값 | 설명 |
| ------------------- | ------- | ------ | ---------------------------------------- |
| `stay_connected` | boolean | `true` | 워크플로우 종료 후에도 WebSocket 연결 유지 |
| `sync_interval_sec` | number | `60` | REST API로 정확한 데이터 동기화하는 주기 (초, 10\~3600) |
| `commission_rate` | number | `0.25` | 수수료율 (%), 수익률 계산에 반영 |
| `tax_rate` | number | `0.0` | 세율 (%), 수익률 계산에 반영 |
**출력:**
* `held_symbols` - 보유종목 코드
* `balance` - 예수금
* `open_orders` - 미체결 주문
* `positions` - 보유종목 (실시간 수익률 포함)
**AccountNode vs RealAccountNode 비교:**
| 항목 | AccountNode | RealAccountNode |
| ------ | ---------------- | -------------------- |
| 연결 방식 | REST API (1회 조회) | WebSocket (실시간 스트리밍) |
| 데이터 갱신 | 호출 시점 1번 | 이벤트 발생 시 자동 갱신 |
| 사용 시점 | 매매 전 잔고 확인 | 실시간 모니터링, 리스크 관리 |
| 리소스 | 가벼움 | 연결 유지 필요 |
> **주의**: RealAccountNode의 데이터는 매우 빈번하게 업데이트됩니다. 하위에 주문 노드를 연결할 때는 반드시 **ThrottleNode**를 사이에 넣어주세요.
> **팁 - commission\_rate**: 해외주식 수수료는 증권사마다 다릅니다. LS증권의 경우 약 0.25%입니다. 정확한 수익률 계산을 위해 실제 수수료율을 입력하세요.
***
### RealOrderEventNode (실시간 주문 이벤트)
주문이 접수/체결/정정/취소/거부될 때마다 실시간으로 이벤트를 수신합니다. 주문 상태를 모니터링할 때 사용합니다.
| 상품 | 노드 타입 |
| ---- | ----------------------------------- |
| 해외주식 | `OverseasStockRealOrderEventNode` |
| 해외선물 | `OverseasFuturesRealOrderEventNode` |
| 국내주식 | `KoreaStockRealOrderEventNode` |
```json
{
"id": "orderEvents",
"type": "OverseasStockRealOrderEventNode",
"stay_connected": true
}
```
| 필드 | 타입 | 기본값 | 설명 |
| ---------------- | ------- | ------ | ------------------ |
| `stay_connected` | boolean | `true` | WebSocket 연결 유지 여부 |
**출력 (5개 포트):**
이벤트 종류별로 다른 출력 포트로 나갑니다:
| 포트 | 설명 | 언제 발생하나요? |
| ----------- | ------ | ----------------- |
| `accepted` | 주문 접수됨 | 주문이 거래소에 접수되었을 때 |
| `filled` | 체결됨 | 주문이 실제로 체결되었을 때 |
| `modified` | 정정 완료 | 주문 가격/수량이 정정되었을 때 |
| `cancelled` | 취소 완료 | 주문이 취소되었을 때 |
| `rejected` | 거부됨 | 주문이 거래소에서 거부되었을 때 |
**사용 예시 - 체결 알림:**
{% @mermaid/diagram content="flowchart LR
A\[RealOrderEventNode] -->|filled| B\[TableDisplayNode]
A -->|rejected| C\["TableDisplayNode
(에러 로그)"]" %}
> **팁**: `filled` 포트에 조건 로직을 연결하면 "체결되면 → 익절/손절 주문 자동 발생" 같은 흐름을 만들 수 있습니다.
***
## 3. market - 시세/종목
시세 조회, 종목 검색, 관심종목 관리를 담당하는 노드들입니다.
### MarketDataNode (현재가 조회)
REST API로 **당일 현재가**를 조회합니다. 단일 종목 기반으로 동작하며, 여러 종목을 조회하려면 SplitNode과 조합합니다.
| 상품 | 노드 타입 |
| ---- | ------------------------------- |
| 해외주식 | `OverseasStockMarketDataNode` |
| 해외선물 | `OverseasFuturesMarketDataNode` |
| 국내주식 | `KoreaStockMarketDataNode` |
```json
{
"id": "market",
"type": "OverseasStockMarketDataNode",
"symbol": "{{ item }}"
}
```
| 필드 | 타입 | 필수 | 설명 |
| -------- | ------ | :-: | ----- |
| `symbol` | object | ✅ | 종목 정보 |
`symbol` 지정 방법:
* SplitNode과 함께: `"{{ item }}"` (자동으로 현재 종목 사용)
* 직접 지정: `{"exchange": "NASDAQ", "symbol": "AAPL"}`
**출력**: `value` - 시세 데이터
```json
{
"symbol": "AAPL",
"exchange": "NASDAQ",
"price": 192.30,
"change": 1.50,
"change_pct": 0.79,
"volume": 45123456,
"open": 190.50,
"high": 193.20,
"low": 189.80,
"close": 192.30
}
```
> **MarketDataNode vs HistoricalDataNode**: MarketDataNode은 **오늘 현재가 1건**만 조회합니다. RSI나 MACD 같은 기술적 지표를 계산하려면 과거 N일 데이터가 필요하므로 **HistoricalDataNode**을 사용하세요.
***
### FundamentalNode (종목 펀더멘털 조회)
LS증권 g3104 API로 **PER, EPS, 시가총액, 52주 고/저가** 등 펀더멘털 데이터를 조회합니다. **해외주식 전용**입니다 (해외선물은 파생상품이므로 펀더멘털 개념 없음).
| 상품 | 노드 타입 |
| ---- | ------------------------------ |
| 해외주식 | `OverseasStockFundamentalNode` |
| 해외선물 | - (지원하지 않음) |
```json
{
"id": "fundamental",
"type": "OverseasStockFundamentalNode",
"symbols": [
{"exchange": "NASDAQ", "symbol": "AAPL"},
{"exchange": "NASDAQ", "symbol": "MSFT"}
]
}
```
| 필드 | 타입 | 필수 | 설명 |
| --------- | ------ | :-: | ---------------------------- |
| `symbol` | object | - | 단일 종목 (`{exchange, symbol}`) |
| `symbols` | array | - | 복수 종목 배열 |
`symbol` 또는 `symbols` 중 하나를 지정합니다. SplitNode과 함께 사용 시 `"symbol": "{{ item }}"`.
**출력**: `value` / `values` — 펀더멘털 데이터
```json
{
"exchange": "NASDAQ", "symbol": "AAPL", "name": "APPLE INC",
"industry": "Technology", "nation": "USA", "exchange_name": "NASDAQ",
"current_price": 264.35, "volume": 45123456, "change_percent": 1.25,
"per": 33.39, "eps": 7.9,
"market_cap": 3869057094000, "shares_outstanding": 14681100000,
"high_52w": 288.62, "low_52w": 169.21, "exchange_rate": 1443.1
}
```
| 출력 필드 | 설명 |
| ---------------------- | ------------- |
| `per` | PER (주가수익비율) |
| `eps` | EPS (주당순이익) |
| `market_cap` | 시가총액 |
| `shares_outstanding` | 발행주식수 |
| `high_52w` / `low_52w` | 52주 최고가 / 최저가 |
| `exchange_rate` | 환율 |
> **MarketDataNode vs FundamentalNode**: MarketDataNode은 시세(가격/변동) 위주이고 PER/EPS도 포함합니다. FundamentalNode은 **시가총액, 업종, 52주 고/저가, 발행주식수** 등 종목 기본정보를 추가로 제공합니다.
> **AI 에이전트 도구**: `is_tool_enabled = true`이므로 AIAgentNode에서 도구(tool)로 직접 호출할 수 있습니다.
***
### HistoricalDataNode (과거 차트 조회)
과거 N일치 **OHLCV**(시가/고가/저가/종가/거래량) 차트 데이터를 조회합니다. RSI, MACD 같은 기술적 지표 계산에 필수입니다.
| 상품 | 노드 타입 |
| ---- | ----------------------------------- |
| 해외주식 | `OverseasStockHistoricalDataNode` |
| 해외선물 | `OverseasFuturesHistoricalDataNode` |
```json
{
"id": "history",
"type": "OverseasStockHistoricalDataNode",
"symbol": "{{ item }}",
"interval": "1d",
"start_date": "{{ date.ago(90, format='yyyymmdd') }}",
"end_date": "{{ date.today(format='yyyymmdd') }}"
}
```
| 필드 | 타입 | 기본값 | 설명 |
| ------------ | ------- | ------- | ----------------- |
| `symbol` | object | - | 종목 정보 |
| `interval` | string | `"1d"` | 데이터 주기 |
| `start_date` | string | 3개월 전 | 조회 시작일 (YYYYMMDD) |
| `end_date` | string | 오늘 | 조회 종료일 (YYYYMMDD) |
| `adjust` | boolean | `false` | 수정주가 적용 여부 |
**interval 옵션:**
| 값 | 주기 | 용도 |
| ----- | ---- | ------------ |
| `1m` | 1분봉 | 단타/스캘핑 |
| `5m` | 5분봉 | 단기 매매 |
| `15m` | 15분봉 | 단기 매매 |
| `1h` | 1시간봉 | 스윙 트레이딩 |
| `1d` | 일봉 | **가장 많이 사용** |
| `1w` | 주봉 | 중장기 분석 |
| `1M` | 월봉 | 장기 분석 |
**출력**: `value` - OHLCV 배열
```json
[
{"date": "2025-01-10", "open": 190.0, "high": 193.5, "low": 189.2, "close": 192.3, "volume": 45000000},
{"date": "2025-01-09", "open": 188.5, "high": 191.0, "low": 187.8, "close": 190.0, "volume": 38000000}
]
```
> **주의 - RSI 기간 설정**: RSI 14일을 계산하려면 최소 14일 이상의 데이터가 필요합니다. `start_date`를 넉넉하게 잡아주세요. 보통 RSI 14일 기준으로 최소 30일, 권장 90일 이상입니다.
> **주의 - 분봉 데이터**: 1분봉/5분봉은 조회 가능한 기간이 제한적입니다 (최근 수일). 일봉은 수년치 조회 가능합니다.
> **팁**: `adjust: true`로 설정하면 액면분할 등이 반영된 수정주가를 조회합니다. 장기 백테스트에 유용합니다.
***
### RealMarketDataNode (실시간 시세)
WebSocket으로 **실시간 시세**를 수신합니다. 체결이 발생할 때마다 데이터가 업데이트됩니다.
| 상품 | 노드 타입 |
| ---- | ----------------------------------- |
| 해외주식 | `OverseasStockRealMarketDataNode` |
| 해외선물 | `OverseasFuturesRealMarketDataNode` |
```json
{
"id": "realMarket",
"type": "OverseasStockRealMarketDataNode",
"symbol": "{{ item }}",
"stay_connected": true
}
```
| 필드 | 타입 | 기본값 | 설명 |
| ---------------- | ------- | ------ | ------------------------------- |
| `symbol` | object | - | 종목 (SplitNode의 `{{ item }}` 사용) |
| `stay_connected` | boolean | `true` | 워크플로우 종료 후에도 연결 유지 |
**출력:**
* `ohlcv_data` - OHLCV 실시간 데이터
* `data` - 전체 시세 (현재가, 호가, 거래량 등)
> **LS증권 미국 주식 거래 시간 (한국시간 기준)**:
| 구간 | 겨울 (서머타임 미적용) | 여름 (서머타임 적용, 3\~11월) | 비고 |
| ----- | ------------------- | -------------------- | -------- |
| 주간거래 | 10:00 \~ 17:30 | 09:00 \~ 16:30 | 지정가만 가능 |
| 프리마켓 | 18:00 \~ 23:30 | 17:00 \~ 22:30 | 장전 시간외 |
| 정규장 | 23:30 \~ 06:00 (익일) | 22:30 \~ 05:00 (익일) | 메인 거래 시간 |
| 애프터마켓 | 06:00 \~ 09:30 | 05:00 \~ 08:30 | 장후 시간외 |
> 실시간 시세는 위 거래 시간 중에 수신됩니다.
> **주의**: 실시간 노드 하위에 주문이나 AI 노드를 연결할 때는 반드시 ThrottleNode를 거쳐야 합니다.
***
### SymbolQueryNode (종목 검색)
종목 코드나 이름으로 종목을 검색합니다. "애플의 종목코드가 뭐지?" 할 때 사용합니다.
| 상품 | 노드 타입 |
| ---- | -------------------------------- |
| 해외주식 | `OverseasStockSymbolQueryNode` |
| 해외선물 | `OverseasFuturesSymbolQueryNode` |
```json
{
"id": "query",
"type": "OverseasStockSymbolQueryNode",
"keyword": "AAPL"
}
```
**출력**: `symbols` - 검색 결과 종목 리스트
***
### WatchlistNode (관심종목)
사용자가 직접 지정하는 **관심종목 목록**입니다. 워크플로우에서 처리할 종목을 정의하는 가장 기본적인 방법입니다.
```json
{
"id": "watchlist",
"type": "WatchlistNode",
"symbols": [
{"exchange": "NASDAQ", "symbol": "AAPL"},
{"exchange": "NASDAQ", "symbol": "NVDA"},
{"exchange": "NYSE", "symbol": "TSM"}
]
}
```
| 필드 | 타입 | 필수 | 설명 |
| --------- | ----- | :-: | ------------------------------- |
| `symbols` | array | ✅ | 종목 목록 (`{exchange, symbol}` 배열) |
**출력**: `symbols` - 종목 리스트
> **주의 - exchange 필수**: 종목 코드만 넣으면 안 됩니다. `exchange`(거래소)와 `symbol`(종목코드)을 함께 지정해야 합니다.
| 거래소 | 코드 | 예시 종목 |
| ------- | -------- | ---------------------- |
| 나스닥 | `NASDAQ` | AAPL, NVDA, TSLA, MSFT |
| 뉴욕증권거래소 | `NYSE` | TSM, JPM, V, WMT |
| 아멕스 | `AMEX` | SPY, QQQ, GLD |
***
### MarketUniverseNode (지수 구성종목)
나스닥100, S\&P500 같은 **대표 지수의 구성종목**을 자동으로 가져옵니다.
> 해외주식 전용입니다. Broker 연결이 필요하지 않습니다 (독립 실행).
```json
{
"id": "universe",
"type": "MarketUniverseNode",
"universe": "NASDAQ100"
}
```
| 필드 | 타입 | 기본값 | 설명 |
| ---------- | ------ | ------------- | ----- |
| `universe` | string | `"NASDAQ100"` | 지수 이름 |
**지원 인덱스:**
| 인덱스 | 종목 수 | 설명 |
| ----------- | ------ | -------------- |
| `NASDAQ100` | \~101개 | 나스닥 대형주 100선 |
| `SP500` | \~503개 | S\&P 500 |
| `SP100` | \~100개 | S\&P 100 (대형주) |
| `DOW30` | 30개 | 다우존스 산업평균 |
**출력**: `symbols` (종목 리스트), `count` (종목 수)
> **팁**: MarketUniverseNode + ScreenerNode을 조합하면 "나스닥100 중 시총 1000억 이상 + 거래량 100만주 이상" 같은 스크리닝이 가능합니다.
***
### ScreenerNode (종목 스크리닝)
시가총액, 거래량, 섹터 등의 **조건으로 종목을 필터링**합니다.
> 해외주식 전용입니다. Broker 연결이 필요하지 않습니다.
```json
{
"id": "screener",
"type": "ScreenerNode",
"market_cap_min": 100000000000,
"volume_min": 1000000,
"sector": "Technology",
"exchange": "NASDAQ",
"max_results": 10
}
```
| 필드 | 타입 | 기본값 | 설명 |
| ---------------- | ------ | ----- | ---------------------------------------- |
| `symbols` | array | - | 입력 종목 리스트 (미지정 시 전체 대상) |
| `market_cap_min` | number | - | 최소 시가총액 (USD) |
| `market_cap_max` | number | - | 최대 시가총액 (USD) |
| `volume_min` | number | - | 최소 일 거래량 |
| `sector` | string | - | 섹터 (Technology, Healthcare, Financial 등) |
| `exchange` | string | - | 거래소 (NASDAQ, NYSE, AMEX) |
| `max_results` | number | `100` | 최대 결과 수 (1\~500) |
**출력**: `symbols` (조건 충족 종목), `count` (결과 수)
> **팁 - 시가총액 단위**: 미국 달러 기준입니다. 1000억 달러 = `100000000000`, 10억 달러 = `1000000000`.
***
### SymbolFilterNode (종목 집합 연산)
두 종목 리스트를 **비교/필터링**합니다. 집합 연산(차집합, 교집합, 합집합)을 수행합니다.
```json
{
"id": "filter",
"type": "SymbolFilterNode",
"operation": "difference",
"input_a": "{{ nodes.universe.symbols }}",
"input_b": "{{ nodes.account.held_symbols }}"
}
```
| 필드 | 타입 | 기본값 | 설명 |
| ----------- | ---------- | -------------- | ----------- |
| `operation` | string | `"difference"` | 연산 방식 |
| `input_a` | expression | - | 첫 번째 종목 리스트 |
| `input_b` | expression | - | 두 번째 종목 리스트 |
**operation 옵션:**
| 연산 | 의미 | 실전 예시 |
| -------------- | ---------------- | -------------------------- |
| `difference` | A에만 있는 것 (A - B) | 나스닥100 중 **아직 보유하지 않은** 종목 |
| `intersection` | A, B 모두에 있는 것 | 관심종목 중 **현재 보유 중인** 종목 |
| `union` | A + B 합치기 | 두 리스트 합치기 (중복 제거) |
**출력**: `symbols` (결과 리스트), `count` (개수)
**사용 예시 - 미보유 종목만 매수:**
{% @mermaid/diagram content="flowchart LR
A\[MarketUniverseNode] --> C\["SymbolFilterNode
(difference)"] --> D\[...매수 로직]
B\[AccountNode] --> C" %}
### ExclusionListNode (거래 제외 종목)
거래에서 **제외할 종목**을 관리합니다. 수동 입력과 동적 바인딩을 결합할 수 있고, 입력 종목 리스트에서 자동 필터링도 가능합니다.
```json
{
"id": "exclusion",
"type": "ExclusionListNode",
"symbols": [
{"exchange": "NASDAQ", "symbol": "NVDA", "reason": "변동성 과다"},
{"exchange": "NYSE", "symbol": "BA", "reason": "사고 리스크"}
],
"default_reason": "리스크 관리",
"input_symbols": "{{ nodes.watchlist.symbols }}"
}
```
| 필드 | 타입 | 기본값 | 설명 |
| ----------------- | ---------- | ---- | --------------------------------------- |
| `symbols` | array | `[]` | 수동 제외 종목 `[{exchange, symbol, reason}]` |
| `dynamic_symbols` | expression | - | 동적 제외 종목 바인딩 |
| `input_symbols` | expression | - | 필터링할 원본 종목 리스트 |
| `default_reason` | string | `""` | 사유 미지정 시 기본 사유 |
**출력**: `excluded` (제외 종목), `filtered` (필터링 결과), `count` (제외 수), `reasons` (종목별 사유)
**3가지 활용 패턴:**
| 패턴 | 설명 | 설정 |
| --------------- | -------------------- | ------------------------------------------ |
| 선언만 | 제외 목록 정의, 다른 노드에서 참조 | `symbols`만 설정 |
| 직접 필터링 | 입력 리스트에서 제외 종목 제거 | `symbols` + `input_symbols` |
| SymbolFilter 연동 | 차집합 연산으로 제외 적용 | SymbolFilterNode의 `input_b`에 `excluded` 연결 |
**주문 안전장치**: ExclusionListNode가 워크플로우에 있으면, NewOrderNode에서 제외 종목 주문을 **자동 차단**합니다 (`ignore_exclusion: true`로 비활성화 가능).
### CurrencyRateNode (환율 조회)
**credential 없이** 실시간 환율을 조회합니다. ECB 데이터 기반의 frankfurter.app API를 사용합니다.
```json
{
"id": "currency",
"type": "CurrencyRateNode",
"base_currency": "USD",
"target_currencies": ["KRW", "JPY", "EUR"]
}
```
| 출력 | 타입 | 설명 |
| ---------- | ------ | -------------------------------------- |
| `rates` | array | `[{base, target, rate, timestamp}]` 배열 |
| `krw_rate` | number | USD/KRW 환율 (KRW가 target에 포함된 경우) |
### FearGreedIndexNode (공포/탐욕 지수)
CNN의 Fear & Greed Index를 조회합니다. **credential 불필요**.
```json
{
"id": "fg",
"type": "FearGreedIndexNode"
}
```
| 출력 | 타입 | 설명 |
| ---------------- | ------ | ----------------------------------------------------- |
| `value` | number | 0\~100 (0=극도 공포, 100=극도 탐욕) |
| `label` | string | Extreme Fear / Fear / Neutral / Greed / Extreme Greed |
| `previous_close` | number | 전일 종가 지수 |
> **팁**: IfNode와 연결하여 `value <= 25`이면 매수, `value >= 75`이면 매도하는 역발상 전략을 구성할 수 있습니다.
> **공통**: 외부 시장 데이터 노드는 retry 기본 활성화, rate limit, 실시간 노드 직접 연결 차단 (ThrottleNode 경유 필수) 설정을 가집니다.
### MarketStatusNode (실시간 장운영정보)
LS증권 JIF TR 기반 **실시간 장운영정보** 노드. 12개 시장(KOSPI/KOSDAQ/KRX\_FUTURES/NXT/KRX\_NIGHT/US/CN\_AM/CN\_PM/HK\_AM/HK\_PM/JP\_AM/JP\_PM)의 개장·종가·서킷브레이커·사이드카 상태를 WebSocket 으로 수신. 브로커 상품 종류(해외주식/해외선물/국내주식) 무관하게 사용 가능 (BrokerNode 세션 공유, broker 없이는 불가).
**⚠️ 해외선물 미지원**: CME, HKEX Futures, SGX 등은 JIF 범위 밖입니다. `markets` Literal 에서 명시적으로 제외되어 ValidationError 를 발생시킵니다.
```json
{
"id": "market_status",
"type": "MarketStatusNode",
"markets": ["US"],
"stay_connected": true,
"include_extended_hours": false
}
```
| 필드 | 타입 | 기본값 | 설명 |
| ------------------------ | ----------------- | ------- | ------------------------------------------------------------------------------------------------------------------------- |
| `markets` | `List[MarketKey]` | `[]` | 구독할 시장 필터. 빈 리스트는 12개 전체. `['US']`, `['KOSPI','KOSDAQ']` 등 부분 선택 가능. 해외선물 키(`CME`, `SGX` 등) 주입 시 Pydantic ValidationError |
| `stay_connected` | bool | `true` | `true` 면 워크플로우 실행 내내 JIF 구독 유지 (실시간 전이 감지), `false` 면 첫 스냅샷 수신 후 해제 — AI Agent Tool 일회성 질의용 |
| `include_extended_hours` | bool | `false` | `true` 면 프리마켓/시간외단일가/에프터마켓 등 시간외 세션도 `*_is_open` 편의 포트에서 `True` 로 반환 |
| 출력 포트 | 타입 | 설명 |
| --------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------- |
| `statuses` | array | 각 시장 스냅샷 배열 `[{market, jangubun, jstatus, jstatus_label, is_open, is_regular_open, is_extended_open, updated_at}, ...]` |
| `event` | object | 최근 전이 이벤트 `{market, prev_jstatus, jstatus, transition, label, timestamp}` |
| `us_is_open` | boolean | 미국장(NASDAQ/NYSE/AMEX 통합) 개장 여부 |
| `kospi_is_open` | boolean | 코스피 개장 여부 |
| `kosdaq_is_open` | boolean | 코스닥 개장 여부 |
| `krx_futures_is_open` | boolean | 코스피 파생 개장 여부 |
| `hk_is_open` | boolean | 홍콩 개장 여부 (오전/오후 중 하나라도 열려있으면 True) |
| `cn_is_open` | boolean | 중국 개장 여부 (오전/오후 OR) |
| `jp_is_open` | boolean | 일본 개장 여부 (오전/오후 OR) |
**주말/이벤트 미수신 시 초기값**: `stay_connected=true` 에서 bool 포트는 `False` 로 초기화 (보수적 기본값 — 주말 오주문 방지).
**사용 예제 — 위험관리 매도 게이트**
```json
{
"nodes": [
{"id": "broker", "type": "OverseasStockBrokerNode", "credential_id": "broker_cred"},
{"id": "market_status", "type": "MarketStatusNode", "markets": ["US"], "stay_connected": true},
{"id": "if_us_open", "type": "IfNode",
"left": "{{ nodes.market_status.us_is_open }}", "operator": "==", "right": true}
],
"edges": [
{"from": "broker", "to": "market_status"},
{"from": "broker", "to": "if_us_open"},
{"from": "if_us_open", "to": "sell_order", "from_port": "true"},
{"from": "if_us_open", "to": "telegram_market_closed", "from_port": "false"}
]
}
```
**AI Agent Tool 등록**: `is_tool_enabled=True`. LLM 이 "미국장 지금 열려있어?" 같은 자연어 질의에서 `markets=['US']` 로 호출 후 `us_is_open` 포트 반환. 자세한 내용은 `ai_agent_guide.md` 참조.
> **거래소 매핑 참고**: `US` 는 JIF 단일 코드로 NASDAQ, NYSE, AMEX, Dow Jones, S\&P 500 등 모든 미국 거래소를 포함합니다. 거래소별 세분화(NASDAQ 만 / NYSE 만)는 JIF 레벨에서 제공되지 않습니다.
***
## 4. condition - 조건 평가
매수/매도 조건을 판단하는 핵심 노드들입니다.
### ConditionNode
**플러그인 기반**으로 매수/매도 조건을 판단합니다. RSI, MACD, 볼린저밴드 등 다양한 기술적 지표를 플러그인으로 선택하여 사용합니다.
```json
{
"id": "rsi",
"type": "ConditionNode",
"plugin": "RSI",
"fields": {
"period": 14,
"threshold": 30,
"direction": "below"
}
}
```
| 필드 | 타입 | 필수 | 설명 |
| ----------- | ---------- | :-: | ------------------------- |
| `plugin` | string | ✅ | 사용할 플러그인 ID (RSI, MACD 등) |
| `fields` | object | ❌ | 플러그인별 파라미터 |
| `positions` | expression | 조건부 | 포지션 데이터 (익절/손절 플러그인에서 필수) |
**플러그인별로 필요한 데이터가 다릅니다:**
| 플러그인 유형 | 필요 데이터 | 연결할 노드 | 예시 플러그인 |
| ------- | ------------ | ---------------------- | -------------------------------------- |
| 시계열 기반 | 과거 OHLCV 데이터 | HistoricalDataNode | RSI, MACD, BollingerBands, VolumeSpike |
| 포지션 기반 | 보유종목 정보 | AccountNode의 positions | ProfitTarget, StopLoss |
**출력:**
* `result` - 조건 평가 결과
```json
{
"passed": true,
"passed_symbols": [
{"symbol": "AAPL", "exchange": "NASDAQ", "rsi": 28.5}
],
"analysis": [
{"symbol": "AAPL", "rsi": 28.5, "signal": "oversold"},
{"symbol": "NVDA", "rsi": 55.2, "signal": "neutral"}
]
}
```
* `passed`: 조건을 통과한 종목이 **하나라도** 있으면 `true`
* `passed_symbols`: 조건을 통과한 종목만
* `analysis`: 모든 종목의 분석 결과
**전형적인 사용 패턴:**
{% @mermaid/diagram content="flowchart LR
A\[BrokerNode] --> B\[WatchlistNode] --> C\[SplitNode] --> D\[HistoricalDataNode] --> E\["ConditionNode
(RSI)"]
E --> F\["LogicNode
(AND)"]
F --> G\[NewOrderNode]" %}
> **팁**: 하나의 워크플로우에 ConditionNode을 여러 개 넣고, LogicNode으로 조합할 수 있습니다. 예: "RSI 과매도 **AND** MACD 골든크로스일 때만 매수".
> 전체 플러그인 목록과 파라미터: [종목조건 플러그인](/docs/strategies/stock_condition.md)
***
### LogicNode
여러 조건을 **논리적으로 조합**합니다. "RSI **그리고** MACD", "RSI **또는** 볼린저밴드" 같은 복합 조건을 만듭니다.
```json
{
"id": "logic",
"type": "LogicNode",
"operator": "all",
"conditions": [
{
"is_condition_met": "{{ nodes.rsi.result }}",
"passed_symbols": "{{ nodes.rsi.passed_symbols }}"
},
{
"is_condition_met": "{{ nodes.macd.result }}",
"passed_symbols": "{{ nodes.macd.passed_symbols }}"
}
]
}
```
| 필드 | 타입 | 필수 | 설명 |
| ------------ | ------ | :-: | ----------------------------------- |
| `operator` | string | ✅ | 논리 연산자 |
| `threshold` | number | 조건부 | 임계값 (`at_least`, `weighted` 등에서 사용) |
| `conditions` | array | ✅ | 조건 목록 |
**conditions 배열 항목:**
| 필드 | 설명 |
| ------------------ | ---------------------------------- |
| `is_condition_met` | ConditionNode의 result 바인딩 |
| `passed_symbols` | ConditionNode의 passed\_symbols 바인딩 |
| `weight` | 가중치 (`weighted` 연산자에서만 사용, 0\~1) |
**연산자 설명:**
| 연산자 | 의미 | 실전 예시 |
| ---------- | ------------------- | ----------------------------------- |
| `all` | 모든 조건 만족 (AND) | RSI 과매도 **그리고** MACD 골든크로스 |
| `any` | 하나 이상 만족 (OR) | RSI 과매도 **또는** 볼린저밴드 하단 이탈 |
| `not` | 모든 조건 불만족 | RSI 과매수 **아닌** 종목 |
| `xor` | 정확히 하나만 만족 | 두 신호 중 하나만 |
| `at_least` | N개 이상 만족 | 3개 조건 중 **2개 이상** (threshold: 2) |
| `at_most` | N개 이하 만족 | 최대 1개만 충족 |
| `exactly` | 정확히 N개 만족 | 정확히 2개 충족 |
| `weighted` | 가중치 합이 threshold 이상 | RSI 40% + MACD 35% + BB 25% = 가중 점수 |
**weighted 예시 (스코어링):**
```json
{
"id": "logic",
"type": "LogicNode",
"operator": "weighted",
"threshold": 0.6,
"conditions": [
{
"is_condition_met": "{{ nodes.rsi.result }}",
"passed_symbols": "{{ nodes.rsi.passed_symbols }}",
"weight": 0.4
},
{
"is_condition_met": "{{ nodes.macd.result }}",
"passed_symbols": "{{ nodes.macd.passed_symbols }}",
"weight": 0.35
},
{
"is_condition_met": "{{ nodes.bb.result }}",
"passed_symbols": "{{ nodes.bb.result.passed_symbols }}",
"weight": 0.25
}
]
}
```
이 예시에서 RSI(40%) + MACD(35%) = 75% ≥ 60%(threshold)이면 매수 신호가 됩니다.
> 상세 가이드: [조건 조합 (LogicNode)](/docs/nodes/logic_guide.md)
***
## 5. order - 주문 실행
실제 매수/매도 주문을 실행하는 노드들입니다.
### NewOrderNode (신규 주문)
신규 매수/매도 주문을 실행합니다. **플러그인을 사용하지 않으며**, 고정 필드(`side`/`order_type`/`order`)를 직접 설정합니다. `order`는 `PositionSizingNode.order`를 바인딩하는 것이 표준 패턴입니다.
| 상품 | 노드 타입 |
| ---- | ----------------------------- |
| 해외주식 | `OverseasStockNewOrderNode` |
| 해외선물 | `OverseasFuturesNewOrderNode` |
| 국내주식 | `KoreaStockNewOrderNode` |
```json
{
"id": "order",
"type": "OverseasStockNewOrderNode",
"side": "buy",
"order_type": "market",
"order": "{{ nodes.sizing.order }}"
}
```
| 필드 | 타입 | 필수 | 설명 |
| ------------ | -------------------------------------- | :-: | ---------------------------------------------------------- |
| `side` | `"buy"` \| `"sell"` | ✅ | 매수/매도 |
| `order_type` | `"market"` \| `"limit"` | ✅ | 시장가/지정가 |
| `price_type` | enum | ❌ | LS증권 호가 유형 (`limit`, `market`, `LOO`, `LOC`, `MOO`, `MOC`) |
| `order` | `{symbol, exchange, quantity, price?}` | ✅ | `PositionSizingNode.order` 바인딩 권장 (expression-only) |
**출력**: `result` - 주문 결과 (배열)
```json
[
{
"order_id": "12345",
"exchange": "NASDAQ",
"symbol": "AAPL",
"side": "buy",
"quantity": 10,
"price": 192.30,
"status": "submitted"
}
]
```
> **⚠️ `plugin: "MarketOrder"` / `"LimitOrder"` 은 존재하지 않는 예제였습니다**: 구 버전 가이드의 `plugin` + `fields: {side, amount_type, amount}` 패턴은 실제로 구현되지 않았으며 사용 시 `[log/error] 주문할 종목이 없습니다` 경고 후 조용히 no-op 됩니다. 반드시 위의 고정 필드 + `PositionSizingNode.order` 바인딩 패턴을 사용하세요.
> **중요 - 실시간 연결 차단**: 실시간 노드(RealMarketDataNode 등)에서 NewOrderNode으로 **직접 연결할 수 없습니다**. 초당 수십 번 주문이 나가는 사고를 방지하기 위해, 반드시 ThrottleNode를 사이에 넣어야 합니다.
> **주의 - 실전 주문**: 해외주식 BrokerNode은 모의투자를 지원하지 않으므로, 주문 노드를 연결하면 **실제 돈으로 거래**됩니다. 처음에는 소량으로 테스트하세요.
> **주의 - 재시도 비활성화**: 주문 노드는 네트워크 에러를 제외하고 자동 재시도가 **비활성화**되어 있습니다. 중복 주문을 방지하기 위한 안전장치입니다.
> 전체 주문 파이프라인 예시: [주문 노드 사용법](/docs/strategies/order_condition.md)
***
### ModifyOrderNode (주문 정정)
미체결 주문의 가격이나 수량을 정정합니다. **플러그인을 사용하지 않으며**, `order_id` + `new_price` / `new_quantity` 를 직접 설정합니다.
| 상품 | 노드 타입 |
| ---- | -------------------------------- |
| 해외주식 | `OverseasStockModifyOrderNode` |
| 해외선물 | `OverseasFuturesModifyOrderNode` |
```json
{
"id": "modify",
"type": "OverseasStockModifyOrderNode",
"order_id": "{{ item.order_id }}",
"new_price": "{{ finance.markup(item.price, 1.0) }}"
}
```
| 필드 | 타입 | 필수 | 설명 |
| -------------- | ------- | :-: | ----------- |
| `order_id` | string | ✅ | 정정 대상 주문 ID |
| `new_price` | number | ❌ | 변경할 가격 |
| `new_quantity` | integer | ❌ | 변경할 수량 |
> **⚠️ `TrailingStop` 플러그인은 존재하지 않습니다**: 가격 추적 정정은 실시간 시세(`OverseasStockRealMarketDataNode` + `ThrottleNode`)와 `OverseasStockOpenOrdersNode`를 조합한 워크플로우에서 `new_price`를 표현식으로 직접 계산하여 구현하세요.
***
### CancelOrderNode (주문 취소)
미체결 주문을 취소합니다. **플러그인을 사용하지 않으며**, `order_id` 를 직접 설정합니다.
| 상품 | 노드 타입 |
| ---- | -------------------------------- |
| 해외주식 | `OverseasStockCancelOrderNode` |
| 해외선물 | `OverseasFuturesCancelOrderNode` |
```json
{
"id": "cancel",
"type": "OverseasStockCancelOrderNode",
"order_id": "{{ item.order_id }}"
}
```
| 필드 | 타입 | 필수 | 설명 |
| ---------- | ------ | :-: | --------- |
| `order_id` | string | ✅ | 취소할 주문 ID |
> **⚠️ `TimeStop` 플러그인은 존재하지 않습니다**: "N분 이내 미체결 시 자동 취소"는 `ScheduleNode`로 주기적으로 `OverseasStockOpenOrdersNode`를 조회하고, 미체결 시간을 `IfNode`로 판정한 뒤 `OverseasStockCancelOrderNode`를 호출하여 직접 구현하세요.
***
### PositionSizingNode (포지션 크기 계산)
**주문 수량을 자동으로 계산**합니다. "잔고의 10%만 투자" 같은 자금 관리 규칙을 적용합니다.
```json
{
"id": "sizing",
"type": "PositionSizingNode",
"symbol": "{{ item }}",
"balance": "{{ nodes.account.balance }}",
"method": "fixed_percent",
"max_percent": 10
}
```
| 필드 | 타입 | 기본값 | 설명 |
| ---------------- | ---------- | ----------------- | ---------------------------- |
| `symbol` | expression | - | 대상 종목 |
| `balance` | expression | - | 가용 잔고 |
| `market_data` | expression | - | 현재가 정보 (선택) |
| `method` | string | `"fixed_percent"` | 포지션 사이징 방법 |
| `max_percent` | number | `10` | 잔고 대비 비율 (%) |
| `fixed_amount` | number | - | 고정 금액 (fixed\_amount 방법 시) |
| `fixed_quantity` | number | `1` | 고정 수량 (fixed\_quantity 방법 시) |
**method 옵션:**
| 방법 | 설명 | 사용 예시 |
| ---------------- | ------ | ---------------------- |
| `fixed_percent` | 잔고의 N% | "잔고의 10%씩 투자" (가장 일반적) |
| `fixed_amount` | 고정 금액 | "종목당 $1000씩 투자" |
| `fixed_quantity` | 고정 수량 | "종목당 10주씩 매수" |
| `kelly` | 켈리 공식 | 승률 기반 최적 비율 (고급) |
| `atr_based` | ATR 기반 | 변동성 기반 사이징 (고급) |
**출력**: `order` - 주문 정보
```json
{
"symbol": "AAPL",
"exchange": "NASDAQ",
"quantity": 5,
"price": 192.30
}
```
**전형적인 사용 패턴:**
{% @mermaid/diagram content="flowchart LR
A\[AccountNode] -->|balance| C\["PositionSizingNode
(잔고의 10%로 계산)"]
B\[ConditionNode] -->|종목| C
C -->|order| D\["NewOrderNode
(계산된 수량으로 주문)"]" %}
> **팁**: PositionSizingNode의 출력(`order`)을 NewOrderNode의 `order` 필드에 바인딩하면 자동으로 계산된 수량으로 주문됩니다. 과도한 집중 투자를 방지하는 핵심 노드입니다.
***
## 6. risk - 리스크 관리
### PortfolioNode
멀티 전략 포트폴리오의 **자본 배분과 리밸런싱**을 관리합니다. 여러 전략에 자금을 어떻게 나눌지 결정합니다.
```json
{
"id": "portfolio",
"type": "PortfolioNode",
"total_capital": 100000,
"allocation_method": "equal",
"rebalance_rule": "drift",
"drift_threshold": 5.0,
"reserve_percent": 10
}
```
| 필드 | 타입 | 기본값 | 설명 |
| ------------------- | ------ | --------- | ----------------- |
| `total_capital` | number | `100000` | 총 투자 자본 (USD) |
| `allocation_method` | string | `"equal"` | 자금 배분 방법 |
| `rebalance_rule` | string | `"none"` | 리밸런싱 규칙 |
| `drift_threshold` | number | `5.0` | 배분 비율 이탈 허용치 (%) |
| `reserve_percent` | number | `0` | 현금 보유 비율 (%, 비상금) |
**배분 방법:**
| 방법 | 설명 | 예시 (3개 전략, $100,000) |
| ------------- | ------------------------- | -------------------------- |
| `equal` | 균등 배분 | 각각 $33,333 |
| `custom` | 사용자 지정 | RSI 50%, MACD 30%, BB 20% |
| `risk_parity` | 변동성 역비례 (변동성 낮은 전략에 더 많이) | 안정형 $45,000, 공격형 $25,000 등 |
| `momentum` | 최근 수익률 비례 (잘 되는 전략에 더 많이) | 수익률 높은 전략에 자금 집중 |
**리밸런싱 규칙:**
| 규칙 | 설명 |
| ---------- | ------------------------------------------- |
| `none` | 리밸런싱 안 함 (초기 배분 유지) |
| `periodic` | 주기적으로 리밸런싱 (daily/weekly/monthly/quarterly) |
| `drift` | 배분 비율이 `drift_threshold`% 이상 벗어나면 리밸런싱 |
| `both` | 주기 + 드리프트 둘 다 적용 |
**출력**: `combined_equity` (통합 자산곡선), `allocation_weights` (배분 비율), `rebalance_signal` (리밸런싱 신호), `allocated_capital` (전략별 배분 금액)
> **팁 - reserve\_percent**: 항상 일정 비율은 현금으로 보유하는 것이 안전합니다. `reserve_percent: 10`이면 총 자본의 10%를 현금으로 유지합니다.
***
## 7. schedule - 스케줄/시간
### ScheduleNode
크론(cron) 스케줄에 따라 워크플로우를 **반복 실행**합니다. "평일 9시에 자동 실행", "15분마다 체크" 같은 스케줄을 설정합니다.
```json
{
"id": "schedule",
"type": "ScheduleNode",
"cron": "0 */15 9-16 * * mon-fri",
"timezone": "America/New_York"
}
```
| 필드 | 타입 | 기본값 | 설명 |
| ---------- | ------- | -------------------- | ------------------- |
| `cron` | string | `"0 */5 * * * *"` | 크론 표현식 (6-field 권장) |
| `timezone` | string | `"America/New_York"` | 타임존 |
| `enabled` | boolean | `true` | 활성화 여부 |
> **cron 포맷**: 예제는 **6-field (`초 분 시 일 월 요일`)** 로 통일합니다. 5-field(`분 시 일 월 요일`)도 지원되지만 혼동 방지를 위해 초 필드를 명시하세요.
**자주 쓰는 크론 예시 (6-field):**
| 표현식 | 설명 |
| ------------------------- | ------------------------- |
| `0 30 9 * * *` | 매일 오전 9:30 (뉴욕 시간) |
| `0 */15 9-16 * * mon-fri` | 평일 9\~16시, 15분마다 |
| `0 0 9 * * mon` | 매주 월요일 오전 9:00 |
| `0 0 23 * * *` | 한국시간 기준 매일 08:00 (뉴욕 23시) |
**출력**: `trigger` - 스케줄 트리거 신호
> **주의 - timezone**: 미국 주식은 뉴욕 시간(`America/New_York`)으로 설정하세요. 한국 시간으로 설정하면 거래시간이 맞지 않습니다.
> **팁 - LS증권 미국 주식 거래 시간 (한국시간 기준)**:
| 구간 | 겨울 (서머타임 미적용) | 여름 (서머타임 적용, 3\~11월) | 비고 |
| ----- | ------------------- | -------------------- | -------- |
| 주간거래 | 10:00 \~ 17:30 | 09:00 \~ 16:30 | 지정가만 가능 |
| 프리마켓 | 18:00 \~ 23:30 | 17:00 \~ 22:30 | 장전 시간외 |
| 정규장 | 23:30 \~ 06:00 (익일) | 22:30 \~ 05:00 (익일) | 메인 거래 시간 |
| 애프터마켓 | 06:00 \~ 09:30 | 05:00 \~ 08:30 | 장후 시간외 |
> 한국시간 오전에도 주간거래로 미국 주식 매매가 가능합니다. 정규장 외 시간에는 지정가 주문만 가능하므로 `OverseasStockNewOrderNode`에서 `order_type: "limit"` + `order.price`를 명시하여 지정가 주문을 사용하세요.
> 상세 가이드: [스케줄 설정](/docs/nodes/schedule_guide.md)
***
### TradingHoursFilterNode
**거래시간 필터**입니다. 거래시간이 아니면 대기하다가, 거래시간이 시작되면 통과시킵니다.
```json
{
"id": "tradingHours",
"type": "TradingHoursFilterNode",
"start": "09:30",
"end": "16:00",
"timezone": "America/New_York",
"days": ["mon", "tue", "wed", "thu", "fri"]
}
```
| 필드 | 타입 | 필수 | 설명 |
| ---------- | ------ | :-: | ----------------------------------------- |
| `start` | string | ✅ | 시작 시간 (HH:MM) |
| `end` | string | ✅ | 종료 시간 (HH:MM) |
| `timezone` | string | ✅ | 타임존 |
| `days` | array | ✅ | 활성 요일 (mon, tue, wed, thu, fri, sat, sun) |
**동작 방식:**
| 상황 | 동작 |
| ----------- | --------------------------- |
| 거래시간 내 | 즉시 통과 |
| 거래시간 외 | 거래시간 시작까지 **대기** (blocking) |
| shutdown 요청 | 종료 |
**출력**: `passed` (통과 여부), `blocked` (차단 여부)
> **주의**: 거래시간 외에 워크플로우를 시작하면 이 노드에서 **멈춰서 대기**합니다. ScheduleNode과 조합하여 거래시간 내에만 실행되도록 설정하는 것을 권장합니다.
***
## 8. data - 데이터 조회/저장
### SQLiteNode
로컬 SQLite 데이터베이스에 데이터를 **저장하고 조회**합니다. 매매 이력 저장, 최고가 추적 등에 활용합니다.
두 가지 모드를 지원합니다:
#### 모드 1: execute\_query (SQL 직접 작성)
SQL을 알고 있다면 직접 쿼리를 작성할 수 있습니다.
```json
{
"id": "sqlite",
"type": "SQLiteNode",
"db_name": "trading.db",
"operation": "execute_query",
"query": "SELECT * FROM trade_history WHERE symbol = :symbol",
"parameters": {"symbol": "AAPL"}
}
```
#### 모드 2: simple (SQL 없이 CRUD)
SQL 없이 테이블/액션/컬럼을 선택하여 사용합니다.
```json
{
"id": "sqlite",
"type": "SQLiteNode",
"db_name": "trading.db",
"operation": "simple",
"table": "peak_tracker",
"action": "upsert",
"columns": ["symbol", "peak_price"],
"values": {"symbol": "AAPL", "peak_price": 195.50},
"on_conflict": "symbol"
}
```
| 필드 | 타입 | 필수 | 설명 |
| ------------- | ------ | :-: | ---------------------------------------------------- |
| `db_name` | string | ✅ | DB 파일명 (자동 생성됨) |
| `operation` | string | ✅ | `execute_query` 또는 `simple` |
| `query` | string | 조건부 | SQL 쿼리 (execute\_query 모드) |
| `parameters` | object | ❌ | 쿼리 파라미터 (`:name` 형식) |
| `table` | string | 조건부 | 테이블명 (simple 모드) |
| `action` | string | 조건부 | `select` / `insert` / `update` / `delete` / `upsert` |
| `values` | object | 조건부 | 저장할 값 |
| `on_conflict` | string | 조건부 | upsert 시 충돌 키 (예: `"symbol"`) |
**출력**: `rows` (조회 결과), `affected_count` (영향 행 수)
> **팁 - upsert**: "있으면 업데이트, 없으면 삽입"입니다. 최고가 추적처럼 한 종목당 하나의 레코드를 유지할 때 유용합니다.
***
### HTTPRequestNode
외부 HTTP API를 호출합니다. 뉴스 API, 경제 지표 API 등 외부 데이터를 가져올 때 사용합니다.
```json
{
"id": "http",
"type": "HTTPRequestNode",
"method": "GET",
"url": "https://api.example.com/news",
"query_params": {"symbol": "AAPL", "limit": "5"},
"timeout_seconds": 30
}
```
| 필드 | 타입 | 기본값 | 설명 |
| ----------------- | ------ | ------- | ---------------------------------------- |
| `method` | string | `"GET"` | HTTP 메서드 (GET, POST, PUT, PATCH, DELETE) |
| `url` | string | - | 요청 URL |
| `query_params` | object | - | URL 쿼리 파라미터 |
| `body` | object | - | 요청 본문 (POST/PUT/PATCH) |
| `headers` | object | - | 추가 헤더 |
| `credential_id` | string | - | API 인증 정보 |
| `timeout_seconds` | number | `30` | 타임아웃 (초, 1\~300) |
**출력**: `response` (응답 데이터), `status_code` (HTTP 상태 코드), `success` (성공 여부), `error` (에러 메시지)
> **주의**: 실시간 노드에서 HTTPRequestNode으로 직접 연결하면 **경고**가 표시됩니다. ThrottleNode를 사용하세요.
> **팁**: 인증이 필요한 API는 `credential_id`로 credentials 섹션의 HTTP 인증 정보를 참조합니다. Bearer 토큰, 헤더 키, Basic 인증 등을 지원합니다.
***
### FieldMappingNode
데이터의 **필드명을 변환**합니다. 외부 API 응답의 필드명이 ProgramGarden 형식과 다를 때 매핑해줍니다.
```json
{
"id": "mapping",
"type": "FieldMappingNode",
"data": "{{ nodes.http.response }}",
"mappings": [
{"from": "ticker", "to": "symbol"},
{"from": "last_price", "to": "price"},
{"from": "vol", "to": "volume"}
],
"preserve_unmapped": true
}
```
| 필드 | 타입 | 기본값 | 설명 |
| ------------------- | ---------- | ------ | ----------------------------------- |
| `data` | expression | - | 변환할 데이터 |
| `mappings` | array | - | 매핑 규칙 `[{from: "원래이름", to: "새이름"}]` |
| `preserve_unmapped` | boolean | `true` | 매핑 규칙에 없는 필드도 유지할지 여부 |
**출력**: `mapped_data` (변환된 데이터)
**변환 전**: `{"ticker": "AAPL", "last_price": 192.30, "vol": 45000000}` **변환 후**: `{"symbol": "AAPL", "price": 192.30, "volume": 45000000}`
> **팁**: ConditionNode의 플러그인은 `symbol`, `open`, `high`, `low`, `close`, `volume` 같은 표준 필드명을 기대합니다. 외부 API 데이터를 ConditionNode에 넣기 전에 FieldMappingNode으로 필드명을 맞춰주세요.
***
### FileReaderNode (파일 리더)
파일을 읽어 텍스트/데이터로 변환합니다. PDF, TXT, CSV, JSON, MD, DOCX, XLSX 포맷을 지원합니다. AIAgentNode의 도구로도 사용 가능합니다.
```json
{
"id": "reader",
"type": "FileReaderNode",
"file_paths": ["/app/data/report.pdf", "/app/data/prices.csv"],
"format": "auto"
}
```
| 필드 | 설명 | 기본값 |
| ------------------ | -------------------------------------------------------------- | ------- |
| `file_paths` | 파일 경로 배열 | - |
| `file_data_list` | Base64 인코딩 파일 데이터 배열 | - |
| `format` | 포맷 (`auto`, `pdf`, `txt`, `csv`, `json`, `md`, `docx`, `xlsx`) | `auto` |
| `pages` | PDF 페이지 범위 (예: `"1-5"`, `"1,3,5"`) | 전체 |
| `encoding` | 텍스트 인코딩 | `utf-8` |
| `extract_tables` | PDF 테이블 추출 (pdfplumber) | `false` |
| `sheet_name` | XLSX 시트명 | 첫 번째 시트 |
| `max_file_size_mb` | 파일당 최대 크기(MB) | `10` |
**출력 포트**: `texts` (텍스트 배열), `data_list` (파싱된 데이터 배열), `metadata` (파일 메타데이터 배열)
> **보안**: 파일 경로는 `/app/data/` 하위로 제한됩니다. 경로 탈출 공격이 자동 차단됩니다.
> **팁**: 복수 파일을 한 번에 처리하면 출력이 배열이 되어 auto-iterate로 파일별 AI 분석이 가능합니다.
***
## 9. display - 시각화
차트와 테이블을 생성합니다. 실시간 노드와 연결하면 데이터가 **자동으로 갱신**됩니다.
### TableDisplayNode (테이블)
데이터를 테이블(표) 형태로 표시합니다.
```json
{
"id": "table",
"type": "TableDisplayNode",
"title": "보유 종목 현황",
"data": "{{ nodes.account.positions }}",
"columns": ["symbol", "quantity", "buy_price", "current_price", "pnl_rate"],
"limit": 20,
"sort_by": "pnl_rate",
"sort_order": "desc"
}
```
| 필드 | 타입 | 기본값 | 설명 |
| ------------ | ---------- | -------- | --------------------------------- |
| `title` | string | - | 테이블 제목 |
| `data` | expression | - | 표시할 데이터 (배열) |
| `columns` | array | 전체 | 표시할 컬럼 목록 (미지정 시 모든 컬럼) |
| `limit` | number | `10` | 최대 행 수 (1\~100) |
| `sort_by` | string | - | 정렬 기준 컬럼 |
| `sort_order` | string | `"desc"` | `"asc"` (오름차순) 또는 `"desc"` (내림차순) |
***
### LineChartNode (라인 차트)
시계열 데이터를 라인 차트로 표시합니다. RSI 추이, 가격 변동 등을 시각화할 때 사용합니다.
```json
{
"id": "chart",
"type": "LineChartNode",
"title": "RSI 추이",
"data": "{{ nodes.rsi.result.analysis }}",
"x_field": "date",
"y_field": "rsi"
}
```
| 필드 | 타입 | 필수 | 설명 |
| --------- | ---------- | :-: | -------------------- |
| `title` | string | ❌ | 차트 제목 |
| `data` | expression | ✅ | 차트 데이터 (배열) |
| `x_field` | string | ✅ | X축 필드명 (보통 `"date"`) |
| `y_field` | string | ✅ | Y축 필드명 (보통 값 필드) |
> **주의**: `x_field`와 `y_field`를 반드시 명시해야 합니다. 자동 추론은 지원하지 않습니다.
***
### MultiLineChartNode (다중 라인 차트)
여러 시리즈(종목)를 **한 차트에** 표시합니다. 종목별 가격 비교에 유용합니다.
```json
{
"id": "multiChart",
"type": "MultiLineChartNode",
"title": "종목별 가격 추이",
"data": "{{ nodes.history.value }}",
"x_field": "date",
"y_field": "close",
"series_key": "symbol"
}
```
> **주의**: `HistoricalDataNode`의 출력은 `.value`(단수, 배열) 또는 `.value.time_series`(단일 종목의 시계열)입니다. 구 버전에서 쓰던 `.values`(복수)는 존재하지 않습니다.
| 필드 | 타입 | 필수 | 설명 |
| ------------ | ------ | :-: | ------------------------------------- |
| `series_key` | string | ✅ | 시리즈 구분 키 (예: `"symbol"`이면 종목별로 라인 분리) |
***
### CandlestickChartNode (캔들스틱 차트)
OHLCV 데이터를 **캔들스틱(봉) 차트**로 표시합니다. 주식 차트의 기본 형태입니다.
```json
{
"id": "candle",
"type": "CandlestickChartNode",
"title": "AAPL 일봉",
"data": "{{ nodes.history.value }}",
"date_field": "date",
"open_field": "open",
"high_field": "high",
"low_field": "low",
"close_field": "close",
"volume_field": "volume"
}
```
| 필드 | 타입 | 필수 | 설명 |
| -------------- | ------ | :-: | ------ |
| `date_field` | string | ✅ | 날짜 필드 |
| `open_field` | string | ✅ | 시가 필드 |
| `high_field` | string | ✅ | 고가 필드 |
| `low_field` | string | ✅ | 저가 필드 |
| `close_field` | string | ✅ | 종가 필드 |
| `volume_field` | string | ❌ | 거래량 필드 |
***
### BarChartNode (바 차트)
범주형 데이터를 바(막대) 차트로 표시합니다.
```json
{
"id": "bar",
"type": "BarChartNode",
"title": "종목별 수익률",
"data": "{{ nodes.account.positions }}",
"x_field": "symbol",
"y_field": "pnl_rate"
}
```
***
### SummaryDisplayNode (요약 카드)
핵심 지표를 **요약 카드** 형태로 표시합니다. 대시보드의 KPI 카드처럼 한눈에 보이는 요약 정보입니다.
```json
{
"id": "summary",
"type": "SummaryDisplayNode",
"title": "계좌 요약",
"data": "{{ nodes.account }}"
}
```
***
## 10. analysis - 백테스트/분석
### BacktestEngineNode
과거 데이터로 전략을 **검증**합니다. 실제 돈을 투자하기 전에 "이 전략이 과거에 얼마나 수익이 났을까?"를 시뮬레이션합니다.
```json
{
"id": "backtest",
"type": "BacktestEngineNode",
"initial_capital": 10000,
"commission_rate": 0.001,
"position_sizing": "kelly",
"exit_rules": {
"stop_loss_percent": 5,
"take_profit_percent": 15
}
}
```
| 필드 | 타입 | 설명 |
| ----------------- | ------ | ------------------------------------------- |
| `initial_capital` | number | 초기 투자 자본 (USD) |
| `commission_rate` | number | 수수료율 (0.001 = 0.1%) |
| `position_sizing` | string | 포지션 사이징: `fixed`, `percent`, `kelly`, `atr` |
| `exit_rules` | object | 자동 청산 규칙 |
**exit\_rules 옵션:**
| 필드 | 설명 |
| --------------------- | --------------------------- |
| `stop_loss_percent` | 손절 비율 (%) - 이 이상 손실나면 자동 매도 |
| `take_profit_percent` | 익절 비율 (%) - 이 이상 이익나면 자동 매도 |
**출력:**
* `equity_curve` - 자산 변동 곡선 (날짜별 자산 추이)
* `summary` - 성과 요약
```json
{
"total_return": 25.3,
"mdd": -8.2,
"win_rate": 62.5,
"sharpe_ratio": 1.85,
"total_trades": 48
}
```
> **팁**: `summary`의 `sharpe_ratio`가 1.0 이상이면 괜찮은 전략, 2.0 이상이면 우수한 전략으로 평가됩니다. `mdd`(최대 낙폭)가 -20% 이하면 위험할 수 있습니다.
***
### BenchmarkCompareNode
여러 백테스트 결과를 **나란히 비교**합니다. "RSI 전략 vs Buy & Hold, 어떤 게 더 나았을까?"를 분석합니다.
```json
{
"id": "compare",
"type": "BenchmarkCompareNode",
"strategies": [
"{{ nodes.backtestRSI }}",
"{{ nodes.backtestSPY }}"
],
"ranking_metric": "sharpe"
}
```
| 필드 | 타입 | 필수 | 설명 |
| ---------------- | ------ | :-: | ---------------------- |
| `strategies` | array | ✅ | BacktestEngineNode 출력들 |
| `ranking_metric` | string | ❌ | 순위 기준 (기본: `sharpe`) |
**ranking\_metric 옵션:**
| 지표 | 설명 | 좋은 값 |
| -------- | ---------------- | ----------------- |
| `sharpe` | 위험 대비 수익 (샤프 비율) | 높을수록 좋음 (>1.0) |
| `return` | 총 수익률 | 높을수록 좋음 |
| `mdd` | 최대 낙폭 | 낮을수록(0에 가까울수록) 좋음 |
| `calmar` | 수익률 / MDD | 높을수록 좋음 |
**출력:**
* `combined_curve` - 통합 자산 곡선 (비교 차트용)
* `comparison_metrics` - 전략별 비교 지표
* `ranking` - 순위
**사용 패턴:**
{% @mermaid/diagram content="flowchart LR
A\["BacktestEngineNode
(내 RSI 전략)"] --> C\[BenchmarkCompareNode] --> D\[LineChartNode]
B\["BacktestEngineNode
(SPY Buy\&Hold)"] --> C" %}
> **팁 - Buy & Hold 벤치마크**: BacktestEngineNode에 조건 신호 없이 데이터만 넣으면 **Buy & Hold** (사서 보유) 전략으로 자동 적용됩니다. 내 전략이 단순 보유보다 나은지 비교하세요.
***
## 11. ai - AI 에이전트
### LLMModelNode
LLM(대규모 언어 모델) API에 연결합니다. BrokerNode이 증권사에 연결하듯, LLMModelNode은 **AI 서비스에 연결**합니다.
```json
{
"id": "llm",
"type": "LLMModelNode",
"credential_id": "my-openai-cred",
"model": "gpt-4o",
"temperature": 0.3,
"max_tokens": 2000
}
```
| 필드 | 타입 | 기본값 | 설명 |
| --------------- | ------- | ---------- | ---------------------------- |
| `credential_id` | string | - | LLM API 인증 ID |
| `model` | string | `"gpt-4o"` | 사용할 모델명 |
| `temperature` | number | `0.7` | 응답의 창의성 (0.0=정확, 2.0=창의적) |
| `max_tokens` | number | `1000` | 최대 응답 길이 (토큰 수, 100\~128000) |
| `streaming` | boolean | `false` | 응답을 실시간으로 받을지 여부 |
**지원 LLM 제공자:**
| 제공자 | credential 타입 | 대표 모델 |
| ------------ | ------------------ | --------------------------- |
| OpenAI | `llm_openai` | gpt-4o, gpt-4o-mini |
| Anthropic | `llm_anthropic` | claude-sonnet-4-5-20250929 |
| Google | `llm_google` | gemini-2.0-flash |
| Azure OpenAI | `llm_azure_openai` | (배포 이름 사용) |
| Ollama | `llm_ollama` | llama3, mistral (로컬 실행, 무료) |
**출력**: `connection` - LLM 연결 (`ai_model` 엣지로 AIAgentNode에 전달)
> **팁 - temperature**: 투자 분석처럼 정확성이 중요한 작업은 `temperature: 0.1~0.3`을 권장합니다. 창의적인 전략 아이디어가 필요하면 `0.7~1.0`으로 올리세요.
> **팁 - Ollama**: 무료로 AI를 사용하고 싶다면 Ollama를 로컬에 설치하여 사용할 수 있습니다. 단, 성능은 OpenAI/Anthropic보다 낮을 수 있습니다.
***
### AIAgentNode
AI 에이전트가 워크플로우의 다른 노드를 \*\*도구(Tool)\*\*로 활용하여 시장을 분석하고 의사결정합니다.
```json
{
"id": "agent",
"type": "AIAgentNode",
"preset": "technical_analyst",
"user_prompt": "AAPL, NVDA의 최근 차트를 분석하고 매수 적절성을 판단해주세요.",
"output_format": "json",
"max_tool_calls": 10,
"cooldown_sec": 60
}
```
| 필드 | 타입 | 기본값 | 설명 |
| ----------------- | ------ | ---------- | ----------------------------------- |
| `preset` | string | `"custom"` | 에이전트 역할 프리셋 |
| `system_prompt` | string | - | AI에게 주는 역할 지시 (custom 모드에서 필수) |
| `user_prompt` | string | - | AI에게 질문/지시 (표현식 사용 가능) |
| `output_format` | string | `"text"` | 응답 형식: `text`, `json`, `structured` |
| `output_schema` | object | - | `structured` 모드에서 응답 구조 정의 |
| `max_tool_calls` | number | `10` | AI가 도구를 최대 몇 번 호출할 수 있는지 (1\~50) |
| `timeout_seconds` | number | `60` | 최대 실행 시간 (초) |
| `cooldown_sec` | number | `60` | 연속 실행 간 최소 대기 시간 (초, 1\~3600) |
**프리셋 역할:**
| 프리셋 | 역할 | 적합한 상황 |
| ------------------- | ------- | ------------------------- |
| `technical_analyst` | 기술적 분석가 | RSI, MACD 등 차트 분석 |
| `risk_manager` | 리스크 관리자 | 포지션 위험도 평가 |
| `news_analyst` | 뉴스 분석가 | 뉴스/이벤트의 주가 영향 분석 |
| `strategist` | 종합 전략가 | 전체 포트폴리오 전략 수립 |
| `custom` | 사용자 정의 | `system_prompt`로 직접 역할 지정 |
**연결 방법 (3가지 엣지 타입):**
```json
{
"edges": [
{"from": "llm", "to": "agent", "type": "ai_model"},
{"from": "history", "to": "agent", "type": "tool"},
{"from": "market", "to": "agent", "type": "tool"},
{"from": "broker", "to": "agent"}
]
}
```
| 엣지 타입 | 용도 | 필수 |
| ----------- | ---------------------------------- | :---------: |
| `ai_model` | LLMModelNode → AIAgentNode (AI 연결) | ✅ (1개) |
| `tool` | 기존 노드 → AIAgentNode (도구로 등록) | ❌ (여러 개 가능) |
| `main` (기본) | 실행 순서 | - |
**출력**: `response` - AI 응답
> **중요**: `tool` 엣지로 연결된 노드는 AI가 **필요할 때만 호출**합니다. 항상 실행되는 것이 아니라, AI가 "이 데이터가 필요하다"고 판단했을 때만 호출됩니다.
> **중요 - 실시간 연결 차단**: 실시간 노드에서 AIAgentNode으로 직접 연결할 수 없습니다. ThrottleNode를 사이에 넣어야 합니다.
> **주의 - Stateless**: AI 에이전트는 매 실행마다 **이전 대화를 기억하지 않습니다**. 필요한 정보는 `user_prompt`에 표현식으로 전달하세요.
> **주의 - API 비용**: LLM API는 사용량에 따라 비용이 발생합니다. `cooldown_sec`을 적절히 설정하여 과도한 호출을 방지하세요.
> 상세 가이드: [AI 에이전트 가이드](/docs/nodes/ai_agent_guide.md)
***
## 부록: 노드 카테고리 요약
| 카테고리 | 노드 수 | 용도 | 주요 노드 |
| ----------- | ---- | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `infra` | 8 | 시작/연결/흐름/분기 | StartNode, BrokerNode, ThrottleNode, SplitNode, AggregateNode, IfNode |
| `account` | 12 | 계좌 조회 | AccountNode, OpenOrdersNode, RealAccountNode, RealOrderEventNode (해외주식/선물 + 국내주식) |
| `market` | 23 | 시세/종목/펀더멘털/환율/심리/제외종목/장운영정보 | MarketDataNode, FundamentalNode, HistoricalDataNode, RealMarketDataNode, WatchlistNode, ScreenerNode, SymbolFilterNode, ExclusionListNode, CurrencyRateNode, FearGreedIndexNode, FundamentalDataNode, MarketStatusNode, KoreaStock\* |
| `condition` | 2 | 조건 평가 | ConditionNode, LogicNode |
| `order` | 10 | 주문 실행 | NewOrderNode, ModifyOrderNode, CancelOrderNode, PositionSizingNode (해외주식/선물 + 국내주식) |
| `risk` | 1 | 리스크 관리 | PortfolioNode |
| `schedule` | 2 | 스케줄/시간 | ScheduleNode, TradingHoursFilterNode |
| `data` | 4 | 데이터 조회/저장 | SQLiteNode, HTTPRequestNode, FieldMappingNode, FileReaderNode |
| `display` | 6 | 시각화 | TableDisplayNode, LineChartNode, MultiLineChartNode, CandlestickChartNode, BarChartNode, SummaryDisplayNode |
| `analysis` | 2 | 백테스트 | BacktestEngineNode, BenchmarkCompareNode |
| `ai` | 2 | AI 에이전트 | LLMModelNode, AIAgentNode |
| `messaging` | 1 | 알림/메시징 | TelegramNode |
***
## 다음 단계
* [워크플로우 구조 이해](/docs/workflow/structure.md) - 노드, 엣지, 인증의 개념부터
* [자동 반복 처리](/docs/workflow/auto_iterate_guide.md) - 여러 종목을 자동으로 처리하는 방법
* [표현식 문법](/docs/workflow/expression_guide.md) - `{{ }}` 표현식 작성법
* [조건 조합](/docs/nodes/logic_guide.md) - 여러 조건을 논리 연산으로 조합
* [종목조건 플러그인](/docs/strategies/stock_condition.md) - RSI, MACD 등 77개 전략 플러그인
* [AI 에이전트](/docs/nodes/ai_agent_guide.md) - LLM으로 시장 분석