Tài liệu chi tiết về node blueprint

Cảnh báo rủi ro: Node blueprint có thể tạo hành động giao dịch tự động, nhưng việc kết hợp node không bảo đảm lợi nhuận. Trước khi giao dịch thật, hãy backtest, sau đó kiểm chứng bằng paper trading hoặc vốn nhỏ. Không bật quyền rút tiền cho API key của sàn.

1. Cách blueprint hoạt động

Blueprint có thể hiểu là “sơ đồ luồng chiến lược theo sự kiện”. Một blueprint có thể chạy thường gồm các nhóm node sau:

Node sự kiện: Quyết định khi nào chiến lược chạy, ví dụ khi khởi động, mỗi nến, từng Tick, timer hoặc biên nhận lệnh.
Node thị trường: Đọc cặp giao dịch đang gắn, nến, giá mới nhất, sổ lệnh, tài khoản và vị thế.
Node chỉ báo: Tính chỉ báo kỹ thuật từ nến hoặc chuỗi số.
Node tín hiệu/logic: Chuyển chỉ báo và giá thành điều kiện boolean để quyết định vào lệnh, thoát lệnh hoặc vẽ biểu đồ.
Node quản trị rủi ro: Thêm giới hạn tần suất, kill switch, kiểm tra khối lượng tối thiểu, giới hạn vị thế, cooldown, stop loss và take profit.
Node đặt lệnh/hàm: Tạo hành động mở vị thế, đóng vị thế, hủy lệnh, quy tắc thoát.
Node trạng thái: Lưu biến, duy trì bộ đếm, lưu trạng thái bền vững và phát hiện thay đổi tín hiệu.
Node công cụ: Chạy biểu thức, ép kiểu, tính cộng trừ nhân chia, chuẩn hóa và xử lý độ chính xác.
Node biểu đồ: Hiển thị đường chỉ báo, đường ngang, nền, marker, bảng và marker lệnh trên biểu đồ.

Một chuỗi chiến lược phổ biến:

OnBar / OnBarClose
  -> Symbol Selector
  -> Get OHLCV
  -> Node chỉ báo
  -> Node tín hiệu/logic
  -> Node quản trị rủi ro
  -> strategy.entry / strategy.close / node đặt lệnh

Nếu khung thực thi là 15m nhưng bộ lọc thị trường dùng dữ liệu 1h, thường cấu hình như sau:

event.on_bar(timeframe=15m)
  -> market.symbol_selector
  -> market.get_ohlcv(timeframe=1h, limit=200)
  -> Chỉ báo và bộ lọc 1h
  -> Chuỗi thực thi 15m

2. Port, kết nối và tham số

Mỗi node gồm input port, output port và tham số.

Khái niệm	Mô tả
Input port	Nhận sự kiện hoặc dữ liệu. Khi không kết nối, một số node dùng giá trị mặc định của tham số.
Output port	Xuất sự kiện, số, boolean, cặp giao dịch, ý định đặt lệnh, tham chiếu biểu đồ và các giá trị khác.
Tham số	Được cấu hình ở bảng thuộc tính bên phải. Tham số được “exposed” sẽ xuất hiện trong bảng tham số chiến lược và có thể chỉnh khi gắn blueprint.
Input `multi`	Cho phép nhiều kết nối vào cùng một input port. Thường gặp ở `riskInputs`, `plot` của lệnh và `chart.plotchar.shape`.

Loại luồng

Loại luồng	Mục đích	Trường hợp thường gặp
`event`	Điều khiển thứ tự thực thi và kích hoạt hành động phụ	`eventIn` -> đặt lệnh, ghi trạng thái, vẽ biểu đồ
`data`	Truyền giá trị dữ liệu	Giá, chỉ báo, điều kiện boolean, cặp giao dịch, ý định rủi ro
`ui`	Loại luồng hình ảnh cũ cho node biểu đồ/giao diện	Node biểu đồ hiện tại phần lớn là node hình ảnh cuối chuỗi

Loại giá trị

Loại	Ý nghĩa	Nguồn thường gặp
`any`	Bất kỳ kiểu nào	Input biểu thức, nhãn động, port tương thích
`voidType`	Sự kiện không có dữ liệu	Output kích hoạt từ node sự kiện
`number` / `integer` / `doubleType`	Số, số nguyên, double	Chỉ báo, tính giá, bộ đếm
`boolType`	Điều kiện boolean	Compare, AND/OR, node tín hiệu
`text`	Văn bản	Nhãn, ghi chú, trạng thái chữ
`symbol`	Cặp giao dịch	Symbol Selector
`timeframe`	Khung thời gian	Bộ lọc khung thời gian
`timestamp`	Thời gian	Bộ lọc ngày, vùng thời gian trên biểu đồ
`seriesNumber`	Chuỗi số	Volume, chuỗi thời gian
`ohlcvSeries`	Chuỗi nến	Open/high/low/close từ Get OHLCV
`chartVisualRef` / `chartPlotRef` / `chartHLineRef`	Tham chiếu đối tượng biểu đồ	Plot, HLine, Fill, template marker lệnh
`price`	Giá	Last Price, Bid/Ask, Mark Price
`orderIntent`	Ý định rủi ro hoặc đặt lệnh	Output node rủi ro, input node đặt lệnh
`orderUpdate`	Biên nhận lệnh	Node sự kiện lệnh
`position` / `balance` / `account`	Vị thế, số dư, snapshot tài khoản	Node thị trường tài khoản/vị thế

Quy tắc biên dịch và kết nối

Blueprint phải có ít nhất một node nguồn sự kiện, nếu không sẽ không chạy.
Luồng dữ liệu phải là đồ thị không vòng lặp. Nếu các node dữ liệu tạo vòng lặp, biên dịch sẽ thất bại.
Nếu luồng sự kiện có vòng lặp, phải thêm logic.gate để giới hạn tần suất, nếu không có thể kích hoạt lặp ở tần suất cao.
Kiểu dữ liệu của port phải khớp. Nếu không khớp, hãy thêm tool.cast_number, tool.cast_integer hoặc tool.cast_bool.
Input port thông thường chỉ cho phép một kết nối. Port hỗ trợ nhiều kết nối sẽ được đánh dấu trong định nghĩa node.
Node đặt lệnh phải kết nối eventIn; nếu không có sự kiện kích hoạt, node sẽ không thực thi.
Khi blueprint có node đặt lệnh, nên kết nối ít nhất một node quản trị rủi ro vào riskInputs. Trình biên dịch có thể cảnh báo rằng có node đặt lệnh nhưng chưa có node rủi ro hoặc node đặt lệnh chưa kết nối input rủi ro.
market.symbol_selector xuất cặp giao dịch từ ngữ cảnh backtest, gắn hoặc debug hiện tại. Nó phù hợp cho template blueprint dùng lại, thay vì hardcode symbol trong template.
market.get_ohlcv với timeframe=runtime sẽ đi theo khung thời gian runtime. Nếu cần bộ lọc khung lớn, hãy chọn rõ 1h, 15m hoặc khung khác.

3. Gợi ý xây dựng chiến lược tần suất cao

Chiến lược tần suất cao hoặc có vòng quay lệnh cao nên ưu tiên kiểm soát tần suất kích hoạt và tần suất đặt lệnh:

Ưu tiên dùng event.on_bar hoặc event.on_bar_close làm trigger chính. Chỉ dùng event.on_tick khi thật sự cần phản ứng theo Tick.
Nếu dùng event.on_tick hoặc event.on_timer với khoảng ngắn, hãy thêm một hoặc nhiều node logic.gate, risk.max_order_rate, logic.once_per_bar ở phía sau.
Nếu không muốn vào lệnh lặp lại trên cùng một nến, dùng logic.once_per_bar hoặc state.last_signal.
Tránh liên tục kéo số lượng nến lớn ở cấp Tick. Đặt market.get_ohlcv.limit theo nhu cầu chỉ báo; 100-300 thường là đủ.
Khung thực thi và khung ra quyết định có thể tách riêng. Ví dụ 15m thực thi, 1h lọc: node sự kiện dùng 15m, node thị trường dùng 1h.
Với chuỗi giao dịch live, nên luôn kết nối risk.kill_switch, risk.order_validation, risk.max_position_size và risk.max_order_rate.
Với chiến lược cần tạm dừng sau thua lỗ, thêm risk.cooldown_after_loss hoặc risk.daily_consecutive_loss_cooldown.

4. Node sự kiện

Node sự kiện là điểm vào thực thi của blueprint. Nếu không có node sự kiện, node thị trường, chỉ báo, logic và lệnh sẽ không tạo frame runtime.

Node ID	Tên	Input chính	Output chính	Tham số	Mục đích và lưu ý
`event.on_start`	OnStart	Không	Trigger `out`	Không	Kích hoạt một lần khi chiến lược khởi động, phù hợp để khởi tạo biến hoặc đọc snapshot ban đầu.
`event.on_stop`	OnStop	`enabled`	Trigger `out`	Không	Kích hoạt một lần khi chiến lược dừng, dùng cho logic kết thúc. Nếu `enabled` không kết nối, mặc định là bật.
`event.on_bar`	OnBar	`timeframe`	Trigger `out`	`timeframe` mặc định `1m`, tùy chọn `1s/1m/5m/15m/1h`	Kích hoạt theo khung thời gian, phù hợp làm điểm vào mặc định của chiến lược.
`event.on_bar_open`	OnBarOpen	`timeframe`	Trigger `out`	Giống OnBar	Kích hoạt khi mỗi nến mở, phù hợp thực thi đầu nến.
`event.on_bar_close`	OnBarClose	`timeframe`	Trigger `out`	Giống OnBar	Kích hoạt khi mỗi nến đóng, dùng nến đã xác nhận để giảm repaint.
`event.on_tick`	OnTick	Không	Trigger `out`	Không	Kích hoạt theo từng Tick, tần suất cao nhất; phải đi kèm giới hạn tần suất và rủi ro.
`event.on_timer`	OnTimer	`enabled`, `intervalSec`	Trigger `out`	`intervalSec=60`, phạm vi 1-86400 giây	Kích hoạt theo khoảng cố định. Input có thể ghi đè tham số.
`event.on_order_update`	OnOrderUpdate	Bộ lọc `symbol`, `side`, `status`	`event`, `order`	Không	Kích hoạt theo biên nhận lệnh/khớp lệnh, phù hợp cập nhật trạng thái hoặc thêm TP/SL sau khi khớp.
`event.on_trade_transaction`	OnTradeTransaction	Bộ lọc `symbol`, `side`, `status`	`event`, `order`	Không	Kích hoạt theo cập nhật giao dịch, phù hợp xử lý trạng thái lệnh chi tiết hơn.
`event.on_position_update`	OnPositionUpdate	Bộ lọc `symbol`, `side`	`event`, `position`	Không	Kích hoạt khi vị thế thay đổi, phù hợp đồng bộ vị thế và cập nhật trạng thái rủi ro.

5. Node thị trường

Node thị trường đọc cặp giao dịch, nến, giá, tài khoản và vị thế từ ngữ cảnh runtime hiện tại.

Node ID	Tên	Input chính	Output chính	Tham số	Mục đích và lưu ý
`market.symbol_selector`	Symbol Selector	`eventIn`	`eventOut`, `symbol`	Không	Xuất cặp giao dịch đang gắn hoặc đang backtest. Không hardcode symbol trong blueprint.
`market.get_ohlcv`	Get OHLCV	`symbol`	`series/open/high/low/close/hlc3/ohlc4/volume/time`	`limit=200`, `timeframe=runtime/1m/5m/15m/1h`	Lấy N nến gần nhất. Chỉ báo thường nối vào `series` hoặc `close`; chỉ báo biến động có thể dùng high/low/close.
`market.last_price`	Get Last Price	`symbol`	`price`	Không	Đọc giá khớp mới nhất, phù hợp điều kiện thời gian thực hoặc mức giá biểu đồ.
`market.bid_ask`	Get Bid/Ask	`symbol`	`bid`, `ask`	Không	Đọc giá mua một và bán một, phù hợp ước tính trượt giá hoặc hướng chủ động/bị động.
`market.mark_price`	Get Mark Price	`symbol`	`price`	Không	Đọc mark price hợp đồng vĩnh viễn, phù hợp kiểm tra rủi ro hợp đồng.
`market.account_snapshot`	Get Balance/Position	`eventIn`	`eventOut`, `balance`, `position`	Không	Đọc snapshot số dư và vị thế tài khoản. Kết nối event input để kiểm soát thời điểm đọc.
`market.position_state`	Get Position State	`symbol`	`qty/absQty/side/entryPrice/openTimeMs/unrealizedPnl/isFlat`	Không	Xuất trạng thái vị thế của cặp hiện tại, thường dùng cho “chỉ vào khi đang trống” và “chỉ thoát khi có vị thế”.

6. Node chỉ báo

Phần lớn node chỉ báo nhận ohlcvSeries và xuất giá trị của bar hiện tại. Khi cần lọc đa khung, đặt Get OHLCV.timeframe thành khung mục tiêu.

Node ID	Tên	Input chính	Output chính	Tham số chính	Trường hợp sử dụng
`indicator.sma`	SMA	`series`	`value`	`period=20`	Đường trung bình đơn giản cho hướng xu hướng và mốc hồi quy về trung bình.
`indicator.ema`	EMA	`series`	`value`	`period=21`	Đường trung bình hàm mũ, phản ứng nhanh hơn SMA.
`indicator.kama`	KAMA	`series`	`value/previous/slope/trend`	`erPeriod=10`, `fastPeriod=2`, `slowPeriod=30`, `slopeLookback=5`	Đường trung bình thích ứng, phù hợp lọc nhiễu trong vùng đi ngang.
`indicator.rsi`	RSI	`series` hoặc high/low/close	`value`	`period=14`	Quá mua/quá bán, phân kỳ động lượng, xác nhận pullback.
`indicator.atr`	ATR	`series` hoặc high/low/close	`value`	`period=14`	Biến động, khoảng stop, bộ lọc biến động thấp.
`indicator.atr_median`	ATR Median	`high/low/close`	`atr/median`	`atrPeriod=14`, `medianPeriod=50`	Kiểm tra biến động hiện tại có cao hơn mức thường hay không.
`indicator.bb`	Bollinger Bands	`series`	`upper/middle/lower`	`period=20`	Breakout Bollinger, hồi quy, lọc độ rộng dải.
`indicator.macd`	MACD	`series`	`macd/signal/hist`	`fastPeriod=12`, `slowPeriod=26`, `signalPeriod=9`	Động lượng xu hướng và lọc đường zero.
`indicator.donchian`	Donchian	`series`	`upper/middle/lower`	`period=20`	Breakout vùng giá và chiến lược kiểu Turtle.
`indicator.candle_streak`	Candle Streak	`open/high/low/close`	`bullStreak/bearStreak/bullMoveAtr/bearMoveAtr/bodyAtr/direction`	`atrPeriod=14`, `minBodyPct=0.00005`	Lọc số nến tăng/giảm liên tiếp và độ mạnh thân nến, tránh đuổi giá quá mức.
`indicator.adx`	ADX	`series` hoặc high/low/close	`value`	`period=14`	Bộ lọc độ mạnh xu hướng, ngưỡng thường dùng 20/25.
`indicator.chop`	CHOP	`series` hoặc high/low/close	`value`	`period=14`	Nhận diện xu hướng/đi ngang; giá trị cao thiên về đi ngang, thấp thiên về xu hướng.
`indicator.vwap`	VWAP	`series`	`value`	`period=20`	Giá trung bình theo khối lượng, phù hợp đánh giá độ lệch giá trong ngày.
`indicator.stoch`	Stoch	`series`	`k/d`	`period=14`, `smoothK=3`, `smoothD=3`	Stochastic cho vào/ra lệnh trong thị trường dao động.
`indicator.stoch_rsi`	Stochastic RSI	`series`	`k/d`	`period=14`, `smoothK=3`, `smoothD=3`	Stochastic áp dụng lên RSI, tín hiệu nhạy hơn.
`indicator.highest`	Highest N	`series`	`value`	`period=20`	Giá trị cao nhất trong N nến gần nhất, dùng làm ngưỡng breakout.
`indicator.lowest`	Lowest N	`series`	`value`	`period=20`	Giá trị thấp nhất trong N nến gần nhất, dùng làm ngưỡng breakdown.
`indicator.ichimoku`	Ichimoku	`series`	`conversion/base/spanA/spanB/lagging`	`conversionPeriod=9`, `basePeriod=26`, `spanBPeriod=52`, `displacement=26`	Ichimoku với cấu trúc xu hướng nhiều thành phần.
`indicator.supertrend`	Supertrend	`series`	`value/trend`	`period=10`, `multiplier=3.0`	Theo xu hướng và tham chiếu stop.
`indicator.fibonacci`	Fibonacci Retracement	`series`	`level0/236/382/500/618/786/100`	`period=100`	Các mức hồi quy Fibonacci trong vùng gần đây.
`indicator.cci`	CCI	`series`	`value`	`period=20`	Commodity Channel Index cho xu hướng và vùng cực trị.
`indicator.williams_r`	Williams %R	`series`	`value`	`period=14`	Oscillator quá mua/quá bán.
`indicator.parabolic_sar`	Parabolic SAR	`series`	`value/trend`	`afStart=0.02`, `afStep=0.02`, `afMax=0.2`	Đảo chiều xu hướng và tham chiếu trailing stop.
`indicator.obv`	OBV	`series`	`value`	Không	On-Balance Volume để xác nhận hướng giá và khối lượng.
`indicator.mfi`	MFI	`series`	`value`	`period=14`	Money Flow Index, chỉ báo quá mua/quá bán có yếu tố khối lượng.
`indicator.volume`	Volume	`seriesNumber`	`value/average`	`period=20`	So sánh volume hiện tại với volume trung bình, giúp lọc breakout giả.
`indicator.keltner`	Keltner Channels	`series`	`upper/middle/lower`	`emaPeriod=20`, `atrPeriod=10`, `multiplier=2.0`	Kênh dựa trên ATR cho breakout và pullback.
`indicator.roc`	ROC	`series`	`value`	`period=12`	Rate of Change để đo tốc độ giá.
`indicator.momentum`	Momentum	`series`	`value`	`period=10`	Oscillator động lượng.
`indicator.smoothed_momentum`	Smoothed Momentum	`series`	`momentum/value/bull/bear`	`period=10`, `smooth=3`	Động lượng đã làm mượt và xuất trực tiếp boolean bullish/bearish.
`indicator.wavetrend`	WaveTrend	`series`	`wt1/wt2/bull/bear/crossOver/crossUnder`	`channelLength=9`, `averageLength=12`, `maLength=3`, `overbought=60`, `oversold=-60`	Oscillator và tín hiệu giao cắt, phù hợp xác nhận pullback.
`indicator.aroon`	Aroon	`series`	`up/down/oscillator`	`period=25`	Nhận diện sức mạnh xu hướng do đỉnh/đáy mới tạo ra.
`indicator.cmf`	CMF	`series`	`value`	`period=20`	Chaikin Money Flow để lọc dòng tiền vào/ra.
`indicator.pivot_points`	Pivot Points	`series`	`pp/r1/r2/r3/s1/s2/s3`	`period=20`	Hỗ trợ, kháng cự, breakout và mục tiêu pullback.

7. Node tín hiệu và logic

Node tín hiệu thường xuất giá trị boolean. Node logic có thể kết hợp điều kiện hoặc điều khiển luồng sự kiện.

Node ID	Tên	Input chính	Output chính	Tham số	Mục đích và lưu ý
`logic.compare`	Compare	`left/right`	`result`	`operator` chọn `> = true`, tránh đặt lệnh lặp lại khi điều kiện giữ true.
`logic.if_else`	If-Else	`eventIn/condition`	`trueOut/falseOut`	Không	Chia luồng sự kiện theo điều kiện.
`bool.expression`	Bool Expression	Input biến động	`result`	`expression`, `variableCount`, bí danh biến	Dùng biểu thức thay cho nhiều tầng Compare/AND/OR/NOT, hỗ trợ `and/or/not`, `&&/
`logic.bool_expr`	Bool Expr	`a/b/c/d`	`result`	`expression`	Node biểu thức boolean cũ, biến cố định là a-d.
`logic.ternary`	Select / Ternary	Input biến động	`result`	`expression`, bí danh biến	Biểu thức ba ngôi, ví dụ `a ? b : c`, phù hợp chọn màu, số hoặc văn bản.
`logic.select_value`	Select Value	`condition/trueValue/falseValue`	`result`	Không	Chọn một trong hai giá trị theo điều kiện boolean.
`logic.gate`	Gate	`eventIn`	`eventOut`	`cooldownSec=10`	Giới hạn luồng sự kiện; rất quan trọng với tần suất cao, Tick và vòng lặp sự kiện.
`logic.once_per_bar`	Once Per Bar	`eventIn`	`eventOut`	Không	Chỉ cho phép một sự kiện trên cùng một nến.

Ghi chú về node biểu thức:

bool.expression, math.expression, tool.number_expr hỗ trợ số lượng biến động; variableCount có phạm vi 1-32.
Biến mặc định là a/b/c...; có thể dùng bí danh như close, emaFast, atr để biểu thức dễ đọc hơn.
Biểu thức boolean phù hợp với `close > ema and rsi node đặt lệnh riskInputs


## 9. Node hàm và node đặt lệnh

Node hàm là các hàm giao dịch kiểu Pine Script, xuất `eventOut`, `triggered` và `label`, nên phù hợp để nối tiếp trong chuỗi chiến lược. Node đặt lệnh giống node hành động cuối chuỗi hơn, thường đặt ở cuối chuỗi giao dịch.

### Node hàm

| Node ID                 | Tên                | Input chính                            | Output chính                | Tham số chính                                                                                               | Mục đích và lưu ý                                                                                                             |
| ----------------------- | ------------------- | --------------------------------------- | ---------------------------- | ------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| `strategy.entry`      | strategy.entry      | `eventIn/when/symbol/riskInputs/plot` | `eventOut/triggered/label` | `enabled`, `entryId`, `direction`, `orderType`, `qtyMode`, `qty`, `limitOffsetPct`, `comment` | Tạo ý định vào lệnh long hoặc short khi `when` đúng. `entryId` là tag chiến lược, không phải ID lệnh của sàn. |
| `strategy.cancel`     | strategy.cancel     | `eventIn/when/riskInputs/plot`        | `eventOut/triggered/label` | `enabled`, `orderId`, `comment`                                                                         | Hủy lệnh sàn được chỉ định; hủy live thường cần `orderId` thật.                                                     |
| `strategy.close`      | strategy.close      | `eventIn/when/symbol/riskInputs/plot` | `eventOut/triggered/label` | `enabled`, `entryId`, `orderType`, `qtyMode`, `qty`, `limitOffsetPct`, `comment`                | Đóng vị thế của cặp hiện tại, theo toàn bộ, số lượng hoặc phần trăm.                                                |
| `strategy.cancel_all` | strategy.cancel_all | `eventIn/when/riskInputs/plot`        | `eventOut/triggered/label` | `enabled`, `comment`                                                                                      | Khi điều kiện đúng, tạo ý định hủy toàn bộ lệnh.                                                                       |
| `strategy.close_all`  | strategy.close_all  | `eventIn/when/symbol/riskInputs/plot` | `eventOut/triggered/label` | `enabled`, `orderType`, `limitOffsetPct`, `comment`                                                   | Khi điều kiện đúng, đóng toàn bộ vị thế của cặp hiện tại.                                                            |
| `strategy.exit`       | strategy.exit       | `eventIn/when/symbol/riskInputs/plot` | `eventOut/triggered/label` | `exitId`, `fromEntry`, `stop`, `limit`, `profit`, `loss`, `trailPoints`, `trailOffset`        | Quy tắc thoát kiểu Pine, có thể cấu hình take profit, stop loss và trailing stop.                                           |

### Node đặt lệnh

| Node ID                  | Tên                 | Input chính                                                    | Output | Tham số chính                                                                                   | Mục đích và lưu ý                                                                                                                  |
| ------------------------ | -------------------- | --------------------------------------------------------------- | ------ | ------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| `strategy.entry_block` | Strategy Entry Block | `eventIn/longCondition/shortCondition/symbol/riskInputs/plot` | Không | `orderType`, `qtyMode`, `qty`, `preferLongWhenBoth`, `longLabel`, `shortLabel`        | Khối vào lệnh cấp chiến lược, nhận cả điều kiện long và short; có thể cấu hình ưu tiên khi cả hai cùng kích hoạt. |
| `strategy.exit_block`  | Strategy Exit Block  | `eventIn/longCondition/shortCondition/symbol/riskInputs/plot` | Không | `orderType`, `qtyMode`, `qty`, `longLabel`, `shortLabel`                                | Khối thoát lệnh cấp chiến lược, tạo ý định đóng vị thế trực tiếp từ điều kiện thoát long/short.                    |
| `order.place_market`   | Place Market Order   | `eventIn/sideInput/riskInputs/plot`                           | Không | `side=buy/sell/auto`, `qtyMode=fixed/percent/quantity`, `qty`                               | Tạo ý định lệnh market.`qty` hiện được hiểu là số tiền USDT; `percent` dùng phần trăm vốn khả dụng.               |
| `order.place_limit`    | Place Limit Order    | `eventIn/sideInput/riskInputs/plot`                           | Không | `side`, `qtyMode`, `qty`, `priceOffsetPct`                                                | Tạo ý định lệnh limit; BUY lệch xuống, SELL lệch lên.                                                                           |
| `order.cancel_order`   | Cancel Order         | `eventIn/riskInputs/plot`                                     | Không | `orderId`                                                                                       | Hủy lệnh sàn được chỉ định.                                                                                                     |
| `order.close_position` | Close Position       | `eventIn/riskInputs/plot`                                     | Không | `qtyMode=all/quantity/percent`, `qty`, `orderType`, `priceOffsetPct`, `reduceOnly=true` | Đóng vị thế hiện tại; mặc định chỉ giảm vị thế.                                                                             |
| `order.set_tpsl`       | Set TP/SL            | `eventIn/riskInputs/plot`                                     | Không | `stopLossPct=1.0`, `takeProfitPct=2.0`                                                        | Đặt ý định take profit và stop loss cho vị thế hoặc lệnh.                                                                      |

Ví dụ chuỗi đặt lệnh:

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. Node trạng thái

Node trạng thái dùng để ghi nhớ biến và tín hiệu trong runtime. Khi cần giữ giá trị qua lần khởi động lại, dùng `persistent_*`.

| Node ID                  | Tên              | Input chính            | Output chính                      | Tham số                          | Mục đích và lưu ý                                                                                           |
| ------------------------ | ----------------- | ----------------------- | ---------------------------------- | --------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
| `state.var_set`        | Var Set           | `value`               | `value`                          | `key=signal`                    | Đặt biến chiến lược hiện tại, vòng đời thường theo instance runtime.                                 |
| `state.var_get`        | Var Get           | Không                  | `value`                          | `key=signal`                    | Đọc biến chiến lược hiện tại.                                                                             |
| `state.counter`        | Counter           | `eventIn`             | `value/eventOut`                 | `initialValue=0`, `step=1`    | Đếm mỗi lần sự kiện kích hoạt, phù hợp thống kê số lần trigger.                                     |
| `state.persistent_set` | Persistent KV Set | `eventIn/value`       | `value/eventOut`                 | `key=last_signal`               | Ghi biến bền vững qua lần khởi động lại.                                                                  |
| `state.persistent_get` | Persistent KV Get | Không                  | `value`                          | `key=last_signal`, `fallback` | Đọc biến bền vững; nếu không tồn tại thì trả về mặc định.                                          |
| `state.rolling_window` | Rolling Window    | `eventIn/value`       | `values/latest/count/eventOut`   | `size=20`                       | Duy trì cửa sổ cuộn của N giá trị số gần nhất.                                                          |
| `state.last_signal`    | Last Signal       | `eventIn/signal`      | `signal/changed/eventOut`        | `key=signal`                    | Lưu tín hiệu trước đó và xuất trạng thái đã thay đổi hay chưa; phù hợp tránh đặt lệnh lặp. |
| `state.overbought`     | Overbought State  | `value/threshold`     | `result`                         | `threshold=70`                  | Giá trị chỉ báo lớn hơn hoặc bằng ngưỡng.                                                               |
| `state.oversold`       | Oversold State    | `value/threshold`     | `result`                         | `threshold=30`                  | Giá trị chỉ báo nhỏ hơn hoặc bằng ngưỡng.                                                               |
| `state.midline`        | Midline State     | `value/threshold`     | `result`                         | `threshold=50`                  | Giá trị chỉ báo lớn hơn hoặc bằng ngưỡng trung tuyến.                                                  |
| `strategy.trend_state` | Trend State       | `changeUp/changeDown` | `state/stateCode/isLong/isShort` | `longCode=B`, `shortCode=S`   | Cũng là node trạng thái, dùng để duy trì trạng thái xu hướng từ tín hiệu chuyển đổi.            |

## 11. Node công cụ

Node công cụ xử lý tính toán trung gian và định dạng. Tính toán phức tạp nên ưu tiên node biểu thức, tính toán đơn giản có thể dùng node cộng/trừ/nhân/chia.

| Node ID               | Tên            | Input chính       | Output chính | Tham số                                          | Mục đích và lưu ý                                                                    |
| --------------------- | --------------- | ------------------ | ------------- | ------------------------------------------------- | ------------------------------------------------------------------------------------------ |
| `math.expression`   | Math Expression | Input biến động | `value`     | `expression`, `variableCount`, bí danh biến | Biểu thức số, hỗ trợ `+ - * / %` và ngoặc.                                        |
| `tool.number_expr`  | Number Expr     | Input biến động | `value`     | `expression`, `variableCount`, bí danh biến | Node biểu thức số cũ, phù hợp thay thế chuỗi Add/Sub/Mul/Div.                      |
| `tool.cast_number`  | Cast -> Number  | `value`          | `value`     | Không                                            | Ép kiểu rõ ràng sang số.                                                              |
| `tool.cast_integer` | Cast -> Int     | `value`          | `value`     | Không                                            | Ép kiểu rõ ràng sang số nguyên.                                                      |
| `tool.cast_bool`    | Cast -> Bool    | `value`          | `value`     | Không                                            | Ép kiểu rõ ràng sang boolean.                                                          |
| `tool.clamp`        | Clamp           | `value`          | `value`     | `min=0`, `max=100`                            | Giới hạn giá trị trong một khoảng.                                                   |
| `tool.normalize`    | Normalize       | `value`          | `value`     | `min=0`, `max=100`                            | Chuẩn hóa giá trị về 0-1.                                                             |
| `tool.add`          | Add             | `a/b`            | `value`     | Không                                            | Cộng.                                                                                     |
| `tool.sub`          | Sub             | `a/b`            | `value`     | Không                                            | Trừ.                                                                                      |
| `tool.mul`          | Mul             | `a/b`            | `value`     | Không                                            | Nhân.                                                                                     |
| `tool.div`          | Div             | `a/b`            | `value`     | Không                                            | Chia.                                                                                      |
| `tool.map_symbol`   | Map Symbol      | `symbol`         | `symbol`    | `exchange=binance/okx/bybit`                    | Ánh xạ cặp giao dịch sang định dạng sàn mục tiêu.                                |
| `tool.tag`          | JSON/Tag        | `value`          | `value/tag` | `tag`                                           | Thêm nhãn văn bản hoặc đoạn JSON vào dữ liệu.                                    |
| `tool.round`        | Round/Precision | `value`          | `value`     | `precision=2`                                   | Xử lý độ chính xác số, phù hợp cho giá, khối lượng và hiển thị biểu đồ. |

## 12. Node biểu đồ

Node biểu đồ dùng để trực quan hóa chiến lược. Một số node nhận `eventIn` để kiểm soát có vẽ bar hiện tại hay không; một số node thuần dữ liệu. Node biểu đồ thường không tham gia quyết định đặt lệnh, nên dùng như đầu ra phụ của chuỗi chiến lược.

### Tham số biểu đồ chung

| Tham số        | Mô tả                                                                                                                       |
| --------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `pane`        | Vùng hiển thị:`main` biểu đồ chính, `chart` lớp biểu đồ, `volume` volume, `indicator:0/1` panel chỉ báo. |
| `visible`     | Có hiển thị hay không.                                                                                                    |
| `zIndex`      | Thứ tự lớp, từ -200 đến 200; giá trị càng cao càng nằm trên.                                                      |
| `layer`       | Lớp render:`background`, `underlay`, `overlay`, `annotation`.                                                        |
| `style`       | Kiểu Plot:`line`, `linebr`, `stepline`, `area`, `histogram`, `columns`, `circles`, `cross`.                  |
| `strokeStyle` | Kiểu đường:`solid`, `dashed`, `dotted`.                                                                             |

### Danh mục node biểu đồ

| Node ID                      | Tên            | Input chính                                            | Output chính | Tham số chính                                                                                        | Mục đích và lưu ý                                                                               |
| ---------------------------- | --------------- | ------------------------------------------------------- | ------------- | ------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------- |
| `chart.color`              | Color           | Không                                                  | `color`     | `color=#FF38BDF8`                                                                                    | Xuất văn bản màu, có thể tái sử dụng cho nhiều node biểu đồ.                             |
| `chart.background`         | Background      | `eventIn/color/startValue/endValue/startTime/endTime` | Không        | `color`, `rangeMode=bars/time`, `startBarsAgo/endBarsAgo`                                        | Vẽ vùng nền theo vùng nến hoặc vùng thời gian.                                                |
| `chart.bar_color`          | Bar Color       | `eventIn`                                             | Không        | `colorMode=single/trend/theme`, màu body/wick/border/up/down                                        | Đổi màu nến, phù hợp trực quan hóa trạng thái xu hướng.                                   |
| `chart.plots`              | Plot            | `color/value`                                         | `plotRef`   | `style`, `color`, `lineWidth`, `histBase`, `offset`, `showLast`, `trackPrice`            | Vẽ đường chỉ báo, cột, vùng diện tích và xuất tham chiếu Plot.                           |
| `strategy.plot_trend_line` | Plot Trend Line | `value/trend`                                         | `plotRef`   | `style`, `upColor`, `downColor`, `neutralColor`, `lineWidth`                                 | Đường chỉ báo tự đổi màu theo trạng thái xu hướng.                                       |
| `chart.fill`               | Fill            | `color/plot1/plot2`                                   | Không        | `color`, `showLast`, `fillGaps`                                                                  | Tô vùng giữa hai tham chiếu Plot/HLine. Hai tham chiếu phải nằm trong cùng panel.             |
| `chart.hline`              | HLine           | `price/color/startValue/endValue/startTime/endTime`   | `hlineRef`  | `price`, `title`, `color`, `linestyle`, `linewidth`, `rangeMode`                           | Vẽ đường ngang và có thể dùng làm tham chiếu Fill.                                          |
| `chart.levels`             | Levels          | `value/color`                                         | Không        | `value`, `color`, `lineWidth`, `strokeStyle`, `label`, tham số vùng                        | Vẽ đường mức giá cho hỗ trợ, kháng cự, TP/SL.                                               |
| `chart.line`               | Line            | `startValue/endValue`                                 | Không        | `lineColor`, `lineWidth`, `strokeStyle`, `leftBarsAgo/rightBarsAgo`                            | Vẽ đoạn thẳng từ bar lịch sử đến hiện tại hoặc offset tương lai.                        |
| `chart.box`                | Box             | `top/bottom/text`                                     | Không        | `fillColor`, `borderColor`, `textColor`, `borderWidth`, `leftBarsAgo/rightBarsAgo`           | Vẽ hộp vùng giá, phù hợp vùng tích lũy hoặc cung/cầu.                                      |
| `chart.tables`             | Tables          | `eventIn` và `value1...valueN` động              | Không        | `title`, `placement`, `itemCount=1-12`, `labelPosition`, `columnCount`, màu và căn chỉnh | Hiển thị dashboard trên biểu đồ.`itemCount` tự mở rộng input giá trị và tham số nhãn. |
| `chart.text`               | Text            | `value`                                               | `text`      | `color`, `textFallback`, `size`, `barsAgo`                                                     | Xuất văn bản. Khi kết nối giá trị, nối theo dạng “text + value”.                           |
| `chart.shapes`             | Shapes          | `value/series/text`                                   | `shape`     | `shape`, `location=abovebar/belowbar/absolute`, màu, kích thước, offset                        | Vẽ marker hình dạng. Nếu `series` là false, thường sẽ không vẽ.                           |
| `chart.plotchar`           | PlotChar        | `series/value/text/shape`                             | Không        | `location`, `value`, `color`, `offset`, `yOffset`                                            | Vẽ văn bản hoặc hình dạng theo điều kiện.`shape` hỗ trợ nhiều kết nối.                |
| `chart.entry_plot`         | Entry Plot      | Không                                                  | `plotRef`   | `shape=arrow_right_sharp`, `size`, `textSize`                                                    | Xuất template biểu đồ cho mở vị thế; việc vẽ thật xảy ra khi lệnh khớp.                  |
| `chart.exit_plot`          | Exit Plot       | Không                                                  | `plotRef`   | `shape=arrow_left_sharp`, `size`, `textSize`                                                     | Xuất template biểu đồ cho đóng vị thế; việc vẽ thật xảy ra khi lệnh khớp.               |

Cách dùng biểu đồ thường gặp:

EMA.value -> chart.plots.value

RSI.value -> chart.tables.value1

Entry Plot.plotRef -> strategy.entry.plot

Exit Plot.plotRef -> strategy.close.plot


## 13. Template chiến lược thường gặp

### Thực thi 15m, lọc xu hướng 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


### Vào lệnh breakout với quản trị rủi ro 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


### Ngăn đặt lệnh lặp từ cùng một tín hiệu

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. Xử lý sự cố

| Vấn đề                            | Kiểm tra trước                                                                                                                                                  |
| ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Blueprint không biên dịch         | Có node nguồn sự kiện hay không; kiểu port có khớp không; luồng dữ liệu có vòng lặp không; input port có kết nối trùng không.                 |
| Chiến lược không kích hoạt     | Khung thời gian sự kiện có đúng không;`when` có true không; `Edge Trigger` đã kích hoạt trước đó chưa; bộ lọc ngày đã hết hạn chưa.  |
| Node đặt lệnh không thực thi    | `eventIn` đã kết nối chưa; `riskInputs` đã kết nối chưa; quản trị rủi ro có từ chối không; chế độ runtime có cho phép giao dịch không. |
| Đặt lệnh lặp ở tần suất cao   | Thêm `logic.gate`, `logic.once_per_bar`, `state.last_signal`, `risk.max_order_rate`.                                                                      |
| Bộ lọc 1h không có hiệu lực    | Kiểm tra `market.get_ohlcv.timeframe` đã đặt rõ là `1h` chưa, tránh dùng nhầm `runtime`.                                                          |
| Chỉ báo trống hoặc bất thường | `limit` có đủ cho chu kỳ chỉ báo không; input có nối đúng chuỗi không; khoảng backtest có đủ nến lịch sử không.                             |
| Biểu đồ không hiển thị         | Node biểu đồ có input cần thiết không;`visible` có bật không; `pane/layer/zIndex` có hợp lý không; hai tham chiếu Fill có cùng panel không.  |
| Không khớp kiểu                   | Thêm `tool.cast_number`, `tool.cast_integer` hoặc `tool.cast_bool`.                                                                                        |

## 15. Danh mục đầy đủ Node ID

Dùng danh mục này để kiểm tra nhanh `schemaId` trong file blueprint.

| Phân loại   | Node ID                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Sự kiện     | `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`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| Thị trường | `market.symbol_selector`, `market.get_ohlcv`, `market.last_price`, `market.bid_ask`, `market.mark_price`, `market.account_snapshot`, `market.position_state`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| Chỉ báo     | `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` |
| Tín hiệu    | `logic.cross_over`, `logic.cross_under`, `signal.enter_range`, `signal.leave_range`, `signal.breakout`, `signal.breakdown`, `strategy.date_range_filter`, `strategy.cross_signal`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| Logic         | `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`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| Rủi ro       | `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`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| Hàm          | `strategy.entry`, `strategy.cancel`, `strategy.close`, `strategy.cancel_all`, `strategy.close_all`, `strategy.exit`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| Đặt lệnh   | `strategy.entry_block`, `strategy.exit_block`, `order.place_market`, `order.place_limit`, `order.cancel_order`, `order.close_position`, `order.set_tpsl`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| Trạng thái  | `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`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| Công cụ     | `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`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| Biểu đồ    | `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`                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |