Documentação detalhada dos nós de blueprint

Aviso de risco: Os nós de blueprint podem gerar acções de trading automáticas, mas uma combinação de nós não garante lucro. Antes de negociar em real, faça backtest e valide em modo Paper ou com capital reduzido. Não active permissões de levantamento nas chaves API da exchange.

1. Como funcionam os blueprints

Um blueprint pode ser entendido como um “fluxograma de estratégia orientado por eventos”. Um blueprint executável normalmente contém estes grupos de nós:

Nós de evento: Determinam quando a estratégia corre, por exemplo no arranque, a cada vela, a cada Tick, por temporizador ou por recibo de ordem.
Nós de mercado: Lêem o par montado actual, velas, último preço, livro de ordens, conta e posição.
Nós de indicador: Calculam indicadores técnicos a partir de velas ou séries numéricas.
Nós de sinal/lógica: Convertem indicadores e preços em condições booleanas para decidir entradas, saídas ou desenho no gráfico.
Nós de risco: Adicionam limites de frequência, kill switch, validação de quantidade mínima, limite máximo de posição, cooldown, stop loss e take profit.
Nós de ordem/função: Geram acções de entrada, saída, fecho, cancelamento e regras de saída.
Nós de estado: Guardam variáveis, mantêm contadores, persistem estado e detectam alterações de sinal.
Nós de ferramenta: Executam expressões, conversões de tipo, operações aritméticas, normalização e arredondamento de precisão.
Nós de gráfico: Mostram linhas de indicador, linhas horizontais, fundos, marcadores, tabelas e marcadores de ordens no gráfico.

Uma cadeia de estratégia típica:

OnBar / OnBarClose
  -> Symbol Selector
  -> Get OHLCV
  -> Nós de indicador
  -> Nós de sinal/lógica
  -> Nós de risco
  -> strategy.entry / strategy.close / nós de ordem

Se o período de execução for 15m, mas o filtro de mercado usar dados de 1h, configure normalmente assim:

event.on_bar(timeframe=15m)
  -> market.symbol_selector
  -> market.get_ohlcv(timeframe=1h, limit=200)
  -> Indicadores e filtros de 1h
  -> Cadeia de execução 15m

2. Portas, ligações e parâmetros

Cada nó é composto por portas de entrada, portas de saída e parâmetros.

Conceito	Descrição
Porta de entrada	Recebe eventos ou dados. Quando não está ligada, alguns nós usam os valores predefinidos dos parâmetros.
Porta de saída	Emite eventos, números, booleanos, pares, intenções de ordem, referências de gráfico e outros valores.
Parâmetro	Configurado no painel de propriedades à direita. Parâmetros expostos aparecem no painel de parâmetros da estratégia e podem ser alterados ao montar.
Entrada `multi`	Permite várias ligações para a mesma porta de entrada. Exemplos comuns:`riskInputs`, `plot` de ordens e `chart.plotchar.shape`.

Tipos de fluxo

Tipo de fluxo	Finalidade	Cenários comuns
`event`	Controla a ordem de execução e os efeitos secundários	`eventIn` -> ordem, escrita de estado, desenho no gráfico
`data`	Transmite valores de dados	Preço, indicador, condição booleana, par, intenção de risco
`ui`	Tipo histórico para cadeias visuais de gráfico/interface	Actualmente, os nós de gráfico são sobretudo nós visuais terminais

Tipos de valor

Tipo	Significado	Origem comum
`any`	Qualquer tipo de valor	Inputs de expressão, etiquetas dinâmicas, portas de compatibilidade
`voidType`	Evento sem dados	Outputs de trigger dos nós de evento
`number` / `integer` / `doubleType`	Número, inteiro, dupla precisão	Indicadores, cálculos de preço, contadores
`boolType`	Condição booleana	Compare, AND/OR, nós de sinal
`text`	Texto	Etiquetas, comentários, texto de estado
`symbol`	Par de trading	Symbol Selector
`timeframe`	Período	Filtros de período
`timestamp`	Tempo	Filtros de data, intervalos temporais no gráfico
`seriesNumber`	Série numérica	Volume e série temporal
`ohlcvSeries`	Série de velas	Open/high/low/close de Get OHLCV
`chartVisualRef` / `chartPlotRef` / `chartHLineRef`	Referência de objecto de gráfico	Plot, HLine, Fill, templates de marcador de ordem
`price`	Preço	Last Price, Bid/Ask, Mark Price
`orderIntent`	Intenção de risco ou ordem	Outputs de nós de risco, inputs de nós de ordem
`orderUpdate`	Recibo de ordem	Nós de evento de ordem
`position` / `balance` / `account`	Posição, saldo, snapshot de conta	Nós de mercado de conta/posição

Regras de compilação e ligação

O blueprint deve ter pelo menos um nó fonte de evento; caso contrário, não será executado.
O fluxo de dados deve ser um grafo sem ciclos. Se os nós de dados formarem um ciclo, a compilação falha.
Se o fluxo de eventos tiver um ciclo, adicione logic.gate para throttling, caso contrário podem ocorrer triggers repetidos em alta frequência.
Os tipos das portas de dados devem coincidir. Se não coincidirem, insira tool.cast_number, tool.cast_integer ou tool.cast_bool.
Uma porta de entrada normal aceita apenas uma ligação. Portas que suportam várias ligações são marcadas na definição do nó.
Nós de ordem devem ligar eventIn; sem evento, não executam.
Quando há nós de ordem, recomenda-se ligar pelo menos um nó de risco a riskInputs. O compilador pode avisar que existem nós de ordem sem nós de risco ou que o nó de ordem não tem input de risco.
market.symbol_selector emite o par do contexto actual de backtest, montagem ou debug. É adequado para templates reutilizáveis e evita hardcode do par.
market.get_ohlcv com timeframe=runtime segue o período de execução. Para filtros de período superior, escolha explicitamente 1h, 15m ou outro período.

3. Recomendações para estratégias de alta frequência

Estratégias de alta frequência ou de elevado turnover devem controlar primeiro a frequência de triggers e de ordens:

Prefira event.on_bar ou event.on_bar_close como trigger principal. Use event.on_tick apenas quando for realmente necessária reacção ao nível do Tick.
Se usar event.on_tick ou um event.on_timer curto, adicione a jusante um ou mais de logic.gate, risk.max_order_rate e logic.once_per_bar.
Se não quiser entradas repetidas na mesma vela, use logic.once_per_bar ou state.last_signal.
Evite pedir repetidamente uma grande quantidade de velas ao nível do Tick. Defina market.get_ohlcv.limit conforme o indicador; 100-300 costuma ser suficiente.
O período de execução e o período de decisão podem ser separados. Exemplo: execução 15m com filtro 1h significa evento em 15m e nó de mercado em 1h.
Em cadeias live, mantenha por defeito risk.kill_switch, risk.order_validation, risk.max_position_size e risk.max_order_rate.
Para estratégias que pausam após perdas, adicione risk.cooldown_after_loss ou risk.daily_consecutive_loss_cooldown.

4. Nós de evento

Os nós de evento são a entrada de execução do blueprint. Sem nó de evento, os nós de mercado, indicador, lógica e ordem não formam frames de runtime.

Node ID	Nome	Inputs principais	Outputs principais	Parâmetros	Finalidade e notas
`event.on_start`	OnStart	Nenhum	Trigger `out`	Nenhum	Dispara uma vez quando a estratégia inicia. Útil para inicializar variáveis ou ler o snapshot inicial.
`event.on_stop`	OnStop	`enabled`	Trigger `out`	Nenhum	Dispara uma vez quando a estratégia pára. Útil para lógica de encerramento. Se `enabled` não estiver ligado, é tratado como activo por defeito.
`event.on_bar`	OnBar	`timeframe`	Trigger `out`	`timeframe` predefinido `1m`, opções `1s/1m/5m/15m/1h`	Dispara por período e é recomendado como entrada padrão da estratégia.
`event.on_bar_open`	OnBarOpen	`timeframe`	Trigger `out`	Igual a OnBar	Dispara na abertura de cada vela. Útil para execução na abertura.
`event.on_bar_close`	OnBarClose	`timeframe`	Trigger `out`	Igual a OnBar	Dispara no fecho de cada vela. Usa velas confirmadas para reduzir repaint.
`event.on_tick`	OnTick	Nenhum	Trigger `out`	Nenhum	Dispara a cada Tick e tem a frequência mais alta; deve ser combinado com throttling e risco.
`event.on_timer`	OnTimer	`enabled`, `intervalSec`	Trigger `out`	`intervalSec=60`, intervalo 1-86400 segundos	Dispara em intervalo fixo. Os inputs podem substituir os parâmetros.
`event.on_order_update`	OnOrderUpdate	Filtros `symbol`, `side`, `status`	`event`, `order`	Nenhum	Dispara por recibos de ordem/execução. Útil para actualizar estado ou adicionar TP/SL após execução.
`event.on_trade_transaction`	OnTradeTransaction	Filtros `symbol`, `side`, `status`	`event`, `order`	Nenhum	Dispara por actualizações de transacção. Útil para tratamento mais fino do estado de ordens.
`event.on_position_update`	OnPositionUpdate	Filtros `symbol`, `side`	`event`, `position`	Nenhum	Dispara quando a posição muda. Útil para sincronização de posição e estado de risco.

5. Nós de mercado

Os nós de mercado lêem par, velas, preços, conta e posição a partir do contexto de runtime actual.

Node ID	Nome	Inputs principais	Outputs principais	Parâmetros	Finalidade e notas
`market.symbol_selector`	Symbol Selector	`eventIn`	`eventOut`, `symbol`	Nenhum	Emite o par actualmente montado ou em backtest. Não faça hardcode do symbol no blueprint.
`market.get_ohlcv`	Get OHLCV	`symbol`	`series/open/high/low/close/hlc3/ohlc4/volume/time`	`limit=200`, `timeframe=runtime/1m/5m/15m/1h`	Obtém as N velas mais recentes. Indicadores normalmente ligam a `series` ou `close`; indicadores de volatilidade podem usar high/low/close.
`market.last_price`	Get Last Price	`symbol`	`price`	Nenhum	Lê o último preço negociado, útil para condições em tempo real ou níveis no gráfico.
`market.bid_ask`	Get Bid/Ask	`symbol`	`bid`, `ask`	Nenhum	Lê melhor bid e melhor ask, útil para estimar slippage ou execução activa/passiva.
`market.mark_price`	Get Mark Price	`symbol`	`price`	Nenhum	Lê o mark price de futuros perpétuos, útil para verificações de risco em derivados.
`market.account_snapshot`	Get Balance/Position	`eventIn`	`eventOut`, `balance`, `position`	Nenhum	Lê o saldo e o snapshot de posições. Ligue o input de evento para controlar quando lê.
`market.position_state`	Get Position State	`symbol`	`qty/absQty/side/entryPrice/openTimeMs/unrealizedPnl/isFlat`	Nenhum	Emite o estado da posição do par actual. Usado para “entrar apenas sem posição” e “sair apenas com posição”.

6. Nós de indicador

A maioria dos nós de indicador recebe ohlcvSeries e emite o valor do bar actual. Para filtros multi-timeframe, defina Get OHLCV.timeframe para o período pretendido.

Node ID	Nome	Inputs principais	Outputs principais	Parâmetros principais	Casos de uso
`indicator.sma`	SMA	`series`	`value`	`period=20`	Média móvel simples para direcção de tendência e linha base de reversão à média.
`indicator.ema`	EMA	`series`	`value`	`period=21`	Média móvel exponencial, mais rápida que a SMA.
`indicator.kama`	KAMA	`series`	`value/previous/slope/trend`	`erPeriod=10`, `fastPeriod=2`, `slowPeriod=30`, `slopeLookback=5`	Média adaptativa para filtrar ruído em lateralização.
`indicator.rsi`	RSI	`series` ou high/low/close	`value`	`period=14`	Sobrecompra/sobrevenda, divergência de momentum, confirmação de pullback.
`indicator.atr`	ATR	`series` ou high/low/close	`value`	`period=14`	Volatilidade, distância de stop, filtro de baixa volatilidade.
`indicator.atr_median`	ATR Median	`high/low/close`	`atr/median`	`atrPeriod=14`, `medianPeriod=50`	Verifica se a volatilidade actual está acima do normal.
`indicator.bb`	Bollinger Bands	`series`	`upper/middle/lower`	`period=20`	Breakout de Bollinger, reversão à média, filtro de largura de banda.
`indicator.macd`	MACD	`series`	`macd/signal/hist`	`fastPeriod=12`, `slowPeriod=26`, `signalPeriod=9`	Momentum de tendência e filtro da linha zero.
`indicator.donchian`	Donchian	`series`	`upper/middle/lower`	`period=20`	Breakout de intervalo e estratégias tipo Turtle.
`indicator.candle_streak`	Candle Streak	`open/high/low/close`	`bullStreak/bearStreak/bullMoveAtr/bearMoveAtr/bodyAtr/direction`	`atrPeriod=14`, `minBodyPct=0.00005`	Filtra sequência de velas altistas/baixistas e força do corpo, evitando perseguir movimentos extremos.
`indicator.adx`	ADX	`series` ou high/low/close	`value`	`period=14`	Filtro de força de tendência, limiares comuns 20/25.
`indicator.chop`	CHOP	`series` ou high/low/close	`value`	`period=14`	Distingue tendência de lateralização; valores altos indicam lateralização, baixos indicam tendência.
`indicator.vwap`	VWAP	`series`	`value`	`period=20`	Preço médio ponderado por volume, útil para desvios intradiários.
`indicator.stoch`	Stoch	`series`	`k/d`	`period=14`, `smoothK=3`, `smoothD=3`	Estocástico para entradas/saídas em mercados laterais.
`indicator.stoch_rsi`	Stochastic RSI	`series`	`k/d`	`period=14`, `smoothK=3`, `smoothD=3`	Estocástico aplicado ao RSI, com sinais mais sensíveis.
`indicator.highest`	Highest N	`series`	`value`	`period=20`	Máximo das últimas N velas, usado como limiar de breakout.
`indicator.lowest`	Lowest N	`series`	`value`	`period=20`	Mínimo das últimas N velas, usado como limiar de breakdown.
`indicator.ichimoku`	Ichimoku	`series`	`conversion/base/spanA/spanB/lagging`	`conversionPeriod=9`, `basePeriod=26`, `spanBPeriod=52`, `displacement=26`	Ichimoku para estrutura de tendência com múltiplos componentes.
`indicator.supertrend`	Supertrend	`series`	`value/trend`	`period=10`, `multiplier=3.0`	Seguimento de tendência e referência de stop.
`indicator.fibonacci`	Fibonacci Retracement	`series`	`level0/236/382/500/618/786/100`	`period=100`	Níveis de retracção Fibonacci do intervalo recente.
`indicator.cci`	CCI	`series`	`value`	`period=20`	Commodity Channel Index para tendência e extremos.
`indicator.williams_r`	Williams %R	`series`	`value`	`period=14`	Oscilador de sobrecompra/sobrevenda.
`indicator.parabolic_sar`	Parabolic SAR	`series`	`value/trend`	`afStart=0.02`, `afStep=0.02`, `afMax=0.2`	Reversão de tendência e referência de trailing stop.
`indicator.obv`	OBV	`series`	`value`	Nenhum	On-Balance Volume para confirmação de direcção preço/volume.
`indicator.mfi`	MFI	`series`	`value`	`period=14`	Money Flow Index, indicador de sobrecompra/sobrevenda com volume.
`indicator.volume`	Volume	`seriesNumber`	`value/average`	`period=20`	Compara volume actual com volume médio, ajudando a filtrar falsos breakouts.
`indicator.keltner`	Keltner Channels	`series`	`upper/middle/lower`	`emaPeriod=20`, `atrPeriod=10`, `multiplier=2.0`	Canal baseado em ATR para breakout e pullback.
`indicator.roc`	ROC	`series`	`value`	`period=12`	Rate of Change para medir velocidade do preço.
`indicator.momentum`	Momentum	`series`	`value`	`period=10`	Oscilador de momentum.
`indicator.smoothed_momentum`	Smoothed Momentum	`series`	`momentum/value/bull/bear`	`period=10`, `smooth=3`	Momentum suavizado com outputs booleanos altista/baixista.
`indicator.wavetrend`	WaveTrend	`series`	`wt1/wt2/bull/bear/crossOver/crossUnder`	`channelLength=9`, `averageLength=12`, `maLength=3`, `overbought=60`, `oversold=-60`	Oscilador e sinais de cruzamento para confirmar pullbacks.
`indicator.aroon`	Aroon	`series`	`up/down/oscillator`	`period=25`	Mede força de tendência impulsionada por novos máximos/mínimos.
`indicator.cmf`	CMF	`series`	`value`	`period=20`	Chaikin Money Flow para filtrar entrada/saída de capital.
`indicator.pivot_points`	Pivot Points	`series`	`pp/r1/r2/r3/s1/s2/s3`	`period=20`	Suporte, resistência, breakout e alvos de pullback.

7. Nós de sinal e lógica

Nós de sinal normalmente emitem booleanos. Nós de lógica combinam condições ou controlam o fluxo de eventos.

Node ID	Nome	Inputs principais	Outputs principais	Parâmetros	Finalidade e notas
`logic.compare`	Compare	`left/right`	`result`	`operator` com opções `> = true`, evitando ordens repetidas enquanto a condição permanece verdadeira.
`logic.if_else`	If-Else	`eventIn/condition`	`trueOut/falseOut`	Nenhum	Divide o fluxo de eventos pela condição.
`bool.expression`	Bool Expression	Inputs dinâmicos	`result`	`expression`, `variableCount`, aliases de variáveis	Substitui cadeias Compare/AND/OR/NOT; suporta `and/or/not`, `&&/
`logic.bool_expr`	Bool Expr	`a/b/c/d`	`result`	`expression`	Nó legado de expressão booleana com variáveis fixas a-d.
`logic.ternary`	Select / Ternary	Inputs dinâmicos	`result`	`expression`, aliases de variáveis	Expressão ternária como `a ? b : c`, útil para escolher cor, número ou texto.
`logic.select_value`	Select Value	`condition/trueValue/falseValue`	`result`	Nenhum	Escolhe um de dois valores conforme uma condição booleana.
`logic.gate`	Gate	`eventIn`	`eventOut`	`cooldownSec=10`	Throttling de eventos. Importante para alta frequência, Tick e loops de eventos.
`logic.once_per_bar`	Once Per Bar	`eventIn`	`eventOut`	Nenhum	Permite apenas um evento por vela.

Notas sobre nós de expressão:

bool.expression, math.expression e tool.number_expr suportam número dinâmico de variáveis. variableCount varia de 1 a 32.
As variáveis predefinidas são a/b/c...; use aliases como close, emaFast ou atr para tornar as expressões legíveis.
Expressões booleanas são adequadas para `close > ema and rsi nó de ordem riskInputs


## 9. Nós de função e nós de ordem

Nós de função são funções de trading ao estilo Pine Script. Emitem `eventOut`, `triggered` e `label`, sendo adequados para encadear lógica. Nós de ordem são nós de acção terminal e normalmente ficam no fim da cadeia de trading.

### Nós de função

| Node ID                 | Nome                | Inputs principais                       | Outputs principais           | Parâmetros principais                                                                                        | Finalidade e notas                                                                                                                                    |
| ----------------------- | ------------------- | --------------------------------------- | ---------------------------- | ------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| `strategy.entry`      | strategy.entry      | `eventIn/when/symbol/riskInputs/plot` | `eventOut/triggered/label` | `enabled`, `entryId`, `direction`, `orderType`, `qtyMode`, `qty`, `limitOffsetPct`, `comment` | Gera intenção de entrada longa ou curta quando `when` é verdadeiro. `entryId` é uma etiqueta de estratégia, não um ID de ordem da exchange. |
| `strategy.cancel`     | strategy.cancel     | `eventIn/when/riskInputs/plot`        | `eventOut/triggered/label` | `enabled`, `orderId`, `comment`                                                                         | Cancela uma ordem específica da exchange. Em live, o cancelamento normalmente exige o `orderId` real.                                              |
| `strategy.close`      | strategy.close      | `eventIn/when/symbol/riskInputs/plot` | `eventOut/triggered/label` | `enabled`, `entryId`, `orderType`, `qtyMode`, `qty`, `limitOffsetPct`, `comment`                | Fecha a posição do par actual por total, quantidade ou percentagem.                                                                                 |
| `strategy.cancel_all` | strategy.cancel_all | `eventIn/when/riskInputs/plot`        | `eventOut/triggered/label` | `enabled`, `comment`                                                                                      | Gera intenção de cancelar todas as ordens quando a condição é verdadeira.                                                                        |
| `strategy.close_all`  | strategy.close_all  | `eventIn/when/symbol/riskInputs/plot` | `eventOut/triggered/label` | `enabled`, `orderType`, `limitOffsetPct`, `comment`                                                   | Fecha todas as posições do par actual quando a condição é verdadeira.                                                                            |
| `strategy.exit`       | strategy.exit       | `eventIn/when/symbol/riskInputs/plot` | `eventOut/triggered/label` | `exitId`, `fromEntry`, `stop`, `limit`, `profit`, `loss`, `trailPoints`, `trailOffset`        | Regra de saída ao estilo Pine, com stop loss, take profit e trailing stop.                                                                           |

### Nós de ordem

| Node ID                  | Nome                 | Inputs principais                                               | Output | Parâmetros principais                                                                            | Finalidade e notas                                                                                                                                 |
| ------------------------ | -------------------- | --------------------------------------------------------------- | ------ | ------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| `strategy.entry_block` | Strategy Entry Block | `eventIn/longCondition/shortCondition/symbol/riskInputs/plot` | Nenhum | `orderType`, `qtyMode`, `qty`, `preferLongWhenBoth`, `longLabel`, `shortLabel`        | Bloco de entrada de estratégia que aceita condições longas e curtas. Se ambas dispararem, o lado preferido pode ser configurado.                |
| `strategy.exit_block`  | Strategy Exit Block  | `eventIn/longCondition/shortCondition/symbol/riskInputs/plot` | Nenhum | `orderType`, `qtyMode`, `qty`, `longLabel`, `shortLabel`                                | Bloco de saída de estratégia que gera intenções de fecho directamente a partir de condições long/short.                                      |
| `order.place_market`   | Place Market Order   | `eventIn/sideInput/riskInputs/plot`                           | Nenhum | `side=buy/sell/auto`, `qtyMode=fixed/percent/quantity`, `qty`                               | Gera intenção de ordem de mercado.`qty` é actualmente interpretado como montante em USDT; `percent` usa percentagem de fundos disponíveis. |
| `order.place_limit`    | Place Limit Order    | `eventIn/sideInput/riskInputs/plot`                           | Nenhum | `side`, `qtyMode`, `qty`, `priceOffsetPct`                                                | Gera intenção de ordem limite. BUY desloca para baixo, SELL desloca para cima.                                                                   |
| `order.cancel_order`   | Cancel Order         | `eventIn/riskInputs/plot`                                     | Nenhum | `orderId`                                                                                       | Cancela uma ordem específica da exchange.                                                                                                         |
| `order.close_position` | Close Position       | `eventIn/riskInputs/plot`                                     | Nenhum | `qtyMode=all/quantity/percent`, `qty`, `orderType`, `priceOffsetPct`, `reduceOnly=true` | Fecha a posição actual. Por defeito, apenas reduz posição.                                                                                     |
| `order.set_tpsl`       | Set TP/SL            | `eventIn/riskInputs/plot`                                     | Nenhum | `stopLossPct=1.0`, `takeProfitPct=2.0`                                                        | Define intenção de take profit e stop loss para uma posição ou ordem.                                                                          |

Exemplo de cadeia de ordens:

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. Nós de estado

Nós de estado memorizam variáveis e sinais durante o runtime. Use `persistent_*` quando o valor precisar sobreviver a reinícios.

| Node ID                  | Nome              | Inputs principais       | Outputs principais                 | Parâmetros                       | Finalidade e notas                                                               |
| ------------------------ | ----------------- | ----------------------- | ---------------------------------- | --------------------------------- | -------------------------------------------------------------------------------- |
| `state.var_set`        | Var Set           | `value`               | `value`                          | `key=signal`                    | Define uma variável de estratégia, normalmente limitada à instância runtime. |
| `state.var_get`        | Var Get           | Nenhum                  | `value`                          | `key=signal`                    | Lê uma variável de estratégia.                                                |
| `state.counter`        | Counter           | `eventIn`             | `value/eventOut`                 | `initialValue=0`, `step=1`    | Conta cada trigger de evento. Útil para estatísticas de activação.           |
| `state.persistent_set` | Persistent KV Set | `eventIn/value`       | `value/eventOut`                 | `key=last_signal`               | Escreve uma variável persistente entre reinícios.                              |
| `state.persistent_get` | Persistent KV Get | Nenhum                  | `value`                          | `key=last_signal`, `fallback` | Lê uma variável persistente. Devolve fallback quando a chave não existe.      |
| `state.rolling_window` | Rolling Window    | `eventIn/value`       | `values/latest/count/eventOut`   | `size=20`                       | Mantém uma janela móvel dos últimos N valores numéricos.                     |
| `state.last_signal`    | Last Signal       | `eventIn/signal`      | `signal/changed/eventOut`        | `key=signal`                    | Guarda o sinal anterior e emite se mudou. Útil para evitar ordens repetidas.    |
| `state.overbought`     | Overbought State  | `value/threshold`     | `result`                         | `threshold=70`                  | Valor do indicador é maior ou igual ao limiar.                                  |
| `state.oversold`       | Oversold State    | `value/threshold`     | `result`                         | `threshold=30`                  | Valor do indicador é menor ou igual ao limiar.                                  |
| `state.midline`        | Midline State     | `value/threshold`     | `result`                         | `threshold=50`                  | Valor do indicador é maior ou igual ao limiar médio.                           |
| `strategy.trend_state` | Trend State       | `changeUp/changeDown` | `state/stateCode/isLong/isShort` | `longCode=B`, `shortCode=S`   | Também é um nó de estado; mantém tendência a partir de sinais de mudança.  |

## 11. Nós de ferramenta

Nós de ferramenta tratam cálculos intermédios e formatação. Prefira nós de expressão para cálculos complexos e nós aritméticos para operações simples.

| Node ID               | Nome            | Inputs principais | Outputs principais | Parâmetros                                              | Finalidade e notas                                                                 |
| --------------------- | --------------- | ----------------- | ------------------ | -------------------------------------------------------- | ---------------------------------------------------------------------------------- |
| `math.expression`   | Math Expression | Inputs dinâmicos | `value`          | `expression`, `variableCount`, aliases de variáveis | Expressão numérica com suporte a `+ - * / %` e parênteses.                    |
| `tool.number_expr`  | Number Expr     | Inputs dinâmicos | `value`          | `expression`, `variableCount`, aliases de variáveis | Nó legado de expressão numérica, útil para substituir cadeias Add/Sub/Mul/Div. |
| `tool.cast_number`  | Cast -> Number  | `value`         | `value`          | Nenhum                                                   | Converte explicitamente para número.                                              |
| `tool.cast_integer` | Cast -> Int     | `value`         | `value`          | Nenhum                                                   | Converte explicitamente para inteiro.                                              |
| `tool.cast_bool`    | Cast -> Bool    | `value`         | `value`          | Nenhum                                                   | Converte explicitamente para booleano.                                             |
| `tool.clamp`        | Clamp           | `value`         | `value`          | `min=0`, `max=100`                                   | Limita um valor a um intervalo.                                                    |
| `tool.normalize`    | Normalize       | `value`         | `value`          | `min=0`, `max=100`                                   | Normaliza um valor para 0-1.                                                       |
| `tool.add`          | Add             | `a/b`           | `value`          | Nenhum                                                   | Adição.                                                                          |
| `tool.sub`          | Sub             | `a/b`           | `value`          | Nenhum                                                   | Subtracção.                                                                      |
| `tool.mul`          | Mul             | `a/b`           | `value`          | Nenhum                                                   | Multiplicação.                                                                   |
| `tool.div`          | Div             | `a/b`           | `value`          | Nenhum                                                   | Divisão.                                                                          |
| `tool.map_symbol`   | Map Symbol      | `symbol`        | `symbol`         | `exchange=binance/okx/bybit`                           | Mapeia o par para o formato da exchange alvo.                                      |
| `tool.tag`          | JSON/Tag        | `value`         | `value/tag`      | `tag`                                                  | Adiciona etiqueta de texto ou fragmento JSON aos dados.                            |
| `tool.round`        | Round/Precision | `value`         | `value`          | `precision=2`                                          | Trata precisão numérica para preços, quantidades e apresentação no gráfico.  |

## 12. Nós de gráfico

Nós de gráfico visualizam a estratégia. Alguns nós recebem `eventIn` para controlar se o bar actual é desenhado; outros são puramente orientados por dados. Nós de gráfico normalmente não participam na decisão de ordem e devem ser usados como saídas laterais.

### Parâmetros comuns de gráfico

| Parâmetro      | Descrição                                                                                                                                    |
| --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `pane`        | Área de apresentação:`main` gráfico principal, `chart` camada do gráfico, `volume` volume, `indicator:0/1` painéis de indicador. |
| `visible`     | Se é apresentado.                                                                                                                             |
| `zIndex`      | Ordem da camada, de -200 a 200. Valores maiores ficam por cima.                                                                                |
| `layer`       | Camada de renderização:`background`, `underlay`, `overlay`, `annotation`.                                                            |
| `style`       | Estilo Plot:`line`, `linebr`, `stepline`, `area`, `histogram`, `columns`, `circles`, `cross`.                                  |
| `strokeStyle` | Estilo de linha:`solid`, `dashed`, `dotted`.                                                                                             |

### Índice de nós de gráfico

| Node ID                      | Nome            | Inputs principais                                       | Outputs principais | Parâmetros principais                                                                                | Finalidade e notas                                                                                             |
| ---------------------------- | --------------- | ------------------------------------------------------- | ------------------ | ----------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
| `chart.color`              | Color           | Nenhum                                                  | `color`          | `color=#FF38BDF8`                                                                                   | Emite texto de cor para reutilizar em vários nós de gráfico.                                                |
| `chart.background`         | Background      | `eventIn/color/startValue/endValue/startTime/endTime` | Nenhum             | `color`, `rangeMode=bars/time`, `startBarsAgo/endBarsAgo`                                       | Desenha uma região de fundo por intervalo de velas ou de tempo.                                               |
| `chart.bar_color`          | Bar Color       | `eventIn`                                             | Nenhum             | `colorMode=single/trend/theme`, cores body/wick/border/up/down                                      | Altera cores das velas, útil para visualizar o estado de tendência.                                          |
| `chart.plots`              | Plot            | `color/value`                                         | `plotRef`        | `style`, `color`, `lineWidth`, `histBase`, `offset`, `showLast`, `trackPrice`           | Desenha linhas de indicador, colunas, áreas e mais. Emite uma referência Plot.                               |
| `strategy.plot_trend_line` | Plot Trend Line | `value/trend`                                         | `plotRef`        | `style`, `upColor`, `downColor`, `neutralColor`, `lineWidth`                                | Linha de indicador que muda de cor conforme o estado de tendência.                                            |
| `chart.fill`               | Fill            | `color/plot1/plot2`                                   | Nenhum             | `color`, `showLast`, `fillGaps`                                                                 | Preenche a área entre duas referências Plot/HLine. As referências devem estar no mesmo painel.              |
| `chart.hline`              | HLine           | `price/color/startValue/endValue/startTime/endTime`   | `hlineRef`       | `price`, `title`, `color`, `linestyle`, `linewidth`, `rangeMode`                          | Desenha uma linha horizontal e pode ser usada como referência de Fill.                                        |
| `chart.levels`             | Levels          | `value/color`                                         | Nenhum             | `value`, `color`, `lineWidth`, `strokeStyle`, `label`, parâmetros de intervalo             | Desenha linhas de preço para suporte, resistência e referência de TP/SL.                                    |
| `chart.line`               | Line            | `startValue/endValue`                                 | Nenhum             | `lineColor`, `lineWidth`, `strokeStyle`, `leftBarsAgo/rightBarsAgo`                           | Desenha um segmento desde um bar histórico até ao actual ou com deslocamento futuro.                         |
| `chart.box`                | Box             | `top/bottom/text`                                     | Nenhum             | `fillColor`, `borderColor`, `textColor`, `borderWidth`, `leftBarsAgo/rightBarsAgo`          | Desenha uma caixa de intervalo de preço, adequada para consolidação ou zonas de oferta/procura.             |
| `chart.tables`             | Tables          | `eventIn` e `value1...valueN` dinâmicos            | Nenhum             | `title`, `placement`, `itemCount=1-12`, `labelPosition`, `columnCount`, cores e alinhamento | Mostra um dashboard no gráfico.`itemCount` expande dinamicamente inputs de valor e parâmetros de etiqueta. |
| `chart.text`               | Text            | `value`                                               | `text`           | `color`, `textFallback`, `size`, `barsAgo`                                                    | Emite texto. Quando um valor está ligado, concatena “texto + valor”.                                        |
| `chart.shapes`             | Shapes          | `value/series/text`                                   | `shape`          | `shape`, `location=abovebar/belowbar/absolute`, cores, tamanho, offset                            | Desenha marcadores de forma. Se `series` for false, normalmente não desenha.                                |
| `chart.plotchar`           | PlotChar        | `series/value/text/shape`                             | Nenhum             | `location`, `value`, `color`, `offset`, `yOffset`                                           | Desenha texto ou formas por condição.`shape` suporta várias ligações.                                   |
| `chart.entry_plot`         | Entry Plot      | Nenhum                                                  | `plotRef`        | `shape=arrow_right_sharp`, `size`, `textSize`                                                   | Emite um template de entrada no gráfico. O desenho real acontece quando a ordem é executada.                 |
| `chart.exit_plot`          | Exit Plot       | Nenhum                                                  | `plotRef`        | `shape=arrow_left_sharp`, `size`, `textSize`                                                    | Emite um template de saída no gráfico. O desenho real acontece quando a ordem é executada.                  |

Uso comum de gráfico:

EMA.value -> chart.plots.value

RSI.value -> chart.tables.value1

Entry Plot.plotRef -> strategy.entry.plot

Exit Plot.plotRef -> strategy.close.plot


## 13. Templates comuns de estratégia

### Execução 15m, filtro de tendência 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


### Entrada por breakout com risco 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


### Evitar ordens repetidas do mesmo sinal

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. Resolução de problemas

| Problema                             | Verifique primeiro                                                                                                                                        |
| ------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| O blueprint não compila             | Se existe fonte de evento; se os tipos de portas coincidem; se o fluxo de dados tem ciclos; se alguma porta de entrada tem ligações duplicadas.         |
| A estratégia não dispara           | Se o período do evento está correcto; se `when` é true; se `Edge Trigger` já disparou; se o filtro de data expirou.                               |
| O nó de ordem não executa          | Se `eventIn` está ligado; se `riskInputs` está ligado; se o risco rejeitou; se o modo runtime permite trading.                                      |
| Ordens repetidas em alta frequência | Adicione `logic.gate`, `logic.once_per_bar`, `state.last_signal` e/ou `risk.max_order_rate`.                                                      |
| O filtro 1h não funciona            | Verifique se `market.get_ohlcv.timeframe` está explicitamente definido como `1h`; não use `runtime` por engano.                                   |
| Indicador vazio ou anormal           | Se `limit` cobre o período do indicador; se o input está ligado à série correcta; se o intervalo de backtest tem velas históricas suficientes.     |
| O gráfico não aparece              | Se os inputs necessários existem; se `visible` está activo; se `pane/layer/zIndex` é razoável; se as referências de Fill estão no mesmo painel. |
| Tipos incompatíveis                 | Insira `tool.cast_number`, `tool.cast_integer` ou `tool.cast_bool`.                                                                                 |

## 15. Índice completo de Node IDs

Use este índice para verificar rapidamente o `schemaId` em ficheiros blueprint.

| Categoria   | Node IDs                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Eventos     | `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`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| Mercado     | `market.symbol_selector`, `market.get_ohlcv`, `market.last_price`, `market.bid_ask`, `market.mark_price`, `market.account_snapshot`, `market.position_state`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| Indicadores | `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` |
| Sinais      | `logic.cross_over`, `logic.cross_under`, `signal.enter_range`, `signal.leave_range`, `signal.breakout`, `signal.breakdown`, `strategy.date_range_filter`, `strategy.cross_signal`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| Lógica     | `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`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| Risco       | `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`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| Funções   | `strategy.entry`, `strategy.cancel`, `strategy.close`, `strategy.cancel_all`, `strategy.close_all`, `strategy.exit`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| Ordens      | `strategy.entry_block`, `strategy.exit_block`, `order.place_market`, `order.place_limit`, `order.cancel_order`, `order.close_position`, `order.set_tpsl`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| Estado      | `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`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| Ferramentas | `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`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| Gráfico    | `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                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |