Kaique Mitsuo Silva Yamamoto
Mercado financeiroAutomação de EstratégiasTradingView / Pine Script

TradingHelperLib — Biblioteca Pine Script para Automação de Ordens

Guia completo da biblioteca TradingHelperLib: cálculo de ordens limite, gestão de risco, P&L, liquidação, DCA (Fixed, Fibonacci, Martingale) e exemplos práticos em Pine Script v6.

A TradingHelperLib é uma biblioteca open-source para Pine Script publicada por SwSpace no TradingView. Ela encapsula os cálculos repetitivos que aparecem em qualquer estratégia séria: preços de ordem limite, P&L, liquidação, margem, stop-loss dinâmico, trailing stop e gestão de DCA — tudo em funções reutilizáveis e testadas.

Link do script original: TradingHelperLib — SwSpace (TradingView)

Por que usar uma biblioteca utilitária?

Quando se desenvolve estratégias em Pine Script, os mesmos cálculos aparecem repetidamente:

  • Quanto o preço precisa recuar para preencher minha ordem limite?
  • Qual é meu stop-loss considerando a volatilidade atual?
  • Em que ponto serei liquidado com essa alavancagem?
  • Qual o multiplicador certo para um DCA progressivo?

Sem uma biblioteca, esses cálculos ficam espalhados em múltiplos scripts com variações sutis que geram bugs difíceis de rastrear. A TradingHelperLib consolida tudo isso em uma API limpa.

Importando a biblioteca

//@version=6
import SwSpace/TradingHelperLib/2 as th

A versão 2 inclui todas as funções de TP/SL/trailing stop que não existiam na v1.

Módulo 1 — Ordens Limite

calcLimitPrice()

Calcula o preço de uma ordem limite com desvio configurável em relação ao preço atual.

// Sintaxe
th.calcLimitPrice(basePrice, deviationPct)

// Exemplo: ordem de compra 0.2% abaixo do fechamento
limitBuy = th.calcLimitPrice(close, -0.2)

// Exemplo: ordem de venda 0.15% acima
limitSell = th.calcLimitPrice(close, 0.15)

Por que isso importa: bots de automação frequentemente precisam enviar ordens limite ligeiramente fora do preço de mercado para garantir execução (maker orders em exchanges de cripto, por exemplo). Um desvio de 0.1% a 0.3% é comum.

checkLimitFill()

Verifica se uma ordem limite foi preenchida, comparando o preço-alvo com o high/low do candle atual.

// Para posição long: a ordem compra foi preenchida?
filled = th.checkLimitFill(limitPrice, "long")

if filled
    // Registrar entrada, calcular SL/TP...

Lógica interna: uma ordem limite de compra é considerada preenchida quando o low do candle toca ou passa abaixo do preço-alvo. Para venda, quando o high toca ou supera o preço-alvo.

Módulo 2 — Cálculos de Pip

f_pipValue() e f_pipsToPrice()

Abstraem a conversão entre pips e preço absoluto, considerando as características do símbolo.

// Valor monetário de 1 pip no símbolo atual
pipVal = th.f_pipValue()

// Converter 50 pips em variação de preço
priceMove = th.f_pipsToPrice(50)

// Stop-loss de 30 pips abaixo da entrada
stopLoss = entryPrice - th.f_pipsToPrice(30)

Contexto: em forex, 1 pip vale 0.0001 para pares como EUR/USD mas 0.01 para pares como USD/JPY. Hardcodar esse valor é fonte de bugs quando o script é aplicado a símbolos diferentes.

Módulo 3 — Profit & Loss

calcPnlLong() e calcPnlShort()

Calculam o P&L atual de uma posição aberta, em valor absoluto ou percentual.

// P&L de uma posição long
pnl = th.calcPnlLong(
    entryPrice  = 100.0,
    currentPrice = close,
    quantity    = 1.0
)

// P&L de uma posição short
pnlShort = th.calcPnlShort(
    entryPrice   = 100.0,
    currentPrice = close,
    quantity     = 1.0
)

Caso de uso típico: exibir no gráfico o P&L flutuante de posições abertas controladas pelo script, ou acionar lógica de saída parcial quando o lucro atinge determinado patamar.

// Fechar 50% quando P&L > 2%
if th.calcPnlLong(entryPrice, close, qty) > 0.02
    strategy.close("Long", qty_percent=50)

Módulo 4 — Preço de Liquidação

calcLiqPriceLongSimple() e calcLiqPriceShortSimple()

Estimam o preço de liquidação para posições alavancadas.

leverage = 10.0  // 10x de alavancagem

liqLong  = th.calcLiqPriceLongSimple(entryPrice, leverage)
liqShort = th.calcLiqPriceShortSimple(entryPrice, leverage)

// Plotar no gráfico como referência visual
plot(liqLong,  "Liq Long",  color=color.red,   style=plot.style_circles)
plot(liqShort, "Liq Short", color=color.green, style=plot.style_circles)

Fórmula simplificada:

  • Long: entryPrice * (1 - 1/leverage)
  • Short: entryPrice * (1 + 1/leverage)

Atenção: estas são estimativas simplificadas. Exchanges aplicam taxas de manutenção de margem que tornam a liquidação real ligeiramente diferente. Use como referência, não como valor exato.

Módulo 5 — Margem e Tamanho de Posição

calcMargin() e calcNotional()

Convertem entre o valor nocional de uma posição e a margem necessária.

leverage    = 5.0
notional    = 10000.0  // $10.000 em posição

// Margem necessária para essa posição
margin = th.calcMargin(notional, leverage)
// → $2.000 (20% de $10.000 com 5x)

// Posição máxima com $500 de margem disponível
maxPosition = th.calcNotional(500, leverage)
// → $2.500

Aplicação prática: ao desenvolver estratégias para mercados de futuros ou cripto com alavancagem, essas funções ajudam a dimensionar corretamente cada trade com base no capital disponível.

Módulo 6 — Take Profit, Stop Loss e Trailing Stop

Estas funções foram adicionadas na versão 2 e são as mais usadas em automação completa.

f_checkTPHit()

Detecta se o take profit foi atingido no candle atual.

tpHit = th.f_checkTPHit(
    entryPrice = entryPrice,
    tpPrice    = takeProfit,
    direction  = "long"
)

if tpHit
    strategy.close("Long", comment="TP atingido")

f_calcSLPrice()

Calcula o preço de stop-loss a partir de uma distância em percentual ou pips.

// Stop-loss 1.5% abaixo da entrada (long)
sl = th.f_calcSLPrice(entryPrice, 1.5, "long")

// Stop-loss 2% acima da entrada (short)
sl = th.f_calcSLPrice(entryPrice, 2.0, "short")

f_calcTSValue()

Gerencia trailing stop: retorna o novo nível de stop quando o preço se move a favor.

trailingPct = 1.0  // trailing de 1%

newTS = th.f_calcTSValue(
    currentPrice  = close,
    trailingPct   = trailingPct,
    currentSL     = stopLevel,
    direction     = "long"
)

// O trailing stop só sobe (long) ou só desce (short), nunca volta
stopLevel := math.max(stopLevel, newTS)

Módulo 7 — DCA (Dollar Cost Averaging)

A função f_multiplier() é uma das mais poderosas da biblioteca. Ela calcula o multiplicador de tamanho de posição para estratégias de DCA — onde cada entrada adicional em uma posição perdedora tem um tamanho diferente do anterior.

Os três modos

Modo Fixed (fixo)

Todas as entradas têm o mesmo tamanho.

mult = th.f_multiplier(
    mode       = "fixed",
    step       = orderNumber,  // Número da ordem (1, 2, 3...)
    multiplier = 1.0
)
// Resultado: sempre 1.0x — tamanho constante

Quando usar: quando você quer médias simples sem aumentar o risco.

Modo Fibonacci

Os tamanhos seguem a proporção da sequência de Fibonacci: 1, 1, 2, 3, 5, 8...

mult = th.f_multiplier(
    mode = "fibonacci",
    step = orderNumber
)
// Order 1: 1x | Order 2: 1x | Order 3: 2x | Order 4: 3x | Order 5: 5x

Matemática: cada termo é a soma dos dois anteriores. O crescimento é progressivo, mas mais controlado que o Martingale.

Quando usar: DCA agressivo em ativos com alta convicção, onde você aceita aumentar a exposição gradualmente.

Modo Martingale

Cada ordem tem o dobro do tamanho da anterior.

mult = th.f_multiplier(
    mode       = "martingale",
    step       = orderNumber,
    multiplier = 2.0
)
// Order 1: 1x | Order 2: 2x | Order 3: 4x | Order 4: 8x | Order 5: 16x

Quando usar: raramente em trading real.

Aviso crítico sobre Martingale: matematicamente, o sistema de Martingale é destrutivo em sequências longas de perdas. Com 7 ordens e multiplicador 2x, o tamanho da última ordem é 64x a primeira. Uma sequência adversa pode zerar a conta antes do preço se recuperar. Use apenas em contexto educacional, em backtesting com capital ilimitado, ou com um limite rígido de ordens máximas.

Estratégia DCA completa — exemplo prático

//@version=6
strategy("DCA com TradingHelperLib", overlay=true, initial_capital=10000,
         default_qty_type=strategy.fixed, default_qty_value=1)

import SwSpace/TradingHelperLib/2 as th

// Parâmetros
baseQty     = input.float(0.1,       "Quantidade base")
maxOrders   = input.int(5,           "Máximo de ordens DCA")
dcaStep     = input.float(1.0,       "Desvio entre ordens (%)")
dcaMode     = input.string("fibonacci", "Modo DCA", options=["fixed","fibonacci","martingale"])
tpPct       = input.float(2.0,       "Take Profit (%)")
leverage    = input.float(1.0,       "Alavancagem")

// Estado
var float  entryPrice  = na
var int    orderCount  = 0
var float  totalQty    = 0.0
var float  stopLevel   = na

// Condição de entrada inicial
longEntry = ta.crossover(ta.ema(close, 9), ta.ema(close, 21))

// Primeira entrada
if longEntry and orderCount == 0 and strategy.position_size == 0
    entryPrice := close
    orderCount := 1
    totalQty   := baseQty
    strategy.entry("DCA-1", strategy.long, qty=baseQty)
    stopLevel  := th.f_calcSLPrice(close, 3.0, "long")

// Entradas adicionais de DCA
if strategy.position_size > 0 and orderCount < maxOrders
    targetPrice = entryPrice * (1 - (dcaStep * orderCount / 100))
    filled = th.checkLimitFill(targetPrice, "long")

    if filled
        mult    = th.f_multiplier(dcaMode, orderCount + 1, 2.0)
        newQty  = baseQty * mult
        totalQty := totalQty + newQty
        entryPrice := (entryPrice * (totalQty - newQty) + targetPrice * newQty) / totalQty
        orderCount := orderCount + 1
        strategy.entry("DCA-" + str.tostring(orderCount), strategy.long, qty=newQty)

// Take Profit
tpPrice = entryPrice * (1 + tpPct / 100)
tpHit   = th.f_checkTPHit(entryPrice, tpPrice, "long")

if tpHit and strategy.position_size > 0
    strategy.close_all(comment="TP")
    orderCount := 0
    totalQty   := 0.0
    entryPrice := na

// Stop Loss
if strategy.position_size > 0 and close < stopLevel
    strategy.close_all(comment="SL")
    orderCount := 0
    totalQty   := 0.0
    entryPrice := na

// Visual
plot(entryPrice, "Preço médio", color=color.yellow, style=plot.style_circles)
plot(tpPrice,    "Take Profit", color=color.green,  style=plot.style_circles)
plot(stopLevel,  "Stop Loss",   color=color.red,    style=plot.style_circles)

Comparativo dos modos DCA

OrdemFixed (1x)FibonacciMartingale (2x)
1ª1x1x1x
2ª1x1x2x
3ª1x2x4x
4ª1x3x8x
5ª1x5x16x
Total (5 ordens)5x12x31x

O modo Fibonacci oferece um equilíbrio entre agressividade e controle de risco — cresce progressivamente, mas não de forma exponencial como o Martingale.

Funções utilitárias extras

Conversão percentual-preço

// Converter 2% de variação em preço absoluto
delta = th.pctToPrice(close, 2.0)

Cálculo de taxas

// Taxa de uma operação com 0.1% de comissão
fee = th.calcFee(notional, 0.1)

Timeframe para barras

// Quantas barras do gráfico atual equivalem a 1 hora?
barsIn1h = th.tfToBars("60")

Quando usar a TradingHelperLib

CenárioVale usar?
Bot com ordens limite e DCASim — core use case
Indicador visual simplesNão — overhead desnecessário
Estratégia com alavancagem e liquidaçãoSim — cálculos de margem embutidos
Scalping de alta frequênciaParcialmente — depende das funções
Aprendizado de Pine ScriptSim — boa referência de implementação

Boas práticas ao usar a biblioteca

  1. Defina maxOrders sempre que usar DCA — sem limite, sequências adversas consomem capital indefinidamente.
  2. Evite Martingale em live trading sem um stop total de estratégia baseado em drawdown máximo da conta.
  3. Use calcLiqPriceLong/Short como linha de referência no gráfico ao operar com alavancagem — saber onde está a liquidação muda o comportamento de gestão de risco.
  4. Valide com backtesting extenso antes de qualquer deploy via webhook — especialmente para modos DCA com Fibonacci que acumulam posições grandes.
  5. Teste em múltiplos timeframes — o comportamento do DCA muda drasticamente entre M5, H1 e D1.

Referências

Aviso Legal: Conteúdo educativo. Não constitui recomendação de investimento. A estratégia Martingale é apresentada exclusivamente para fins didáticos — seu uso em trading real com capital próprio apresenta risco elevado de perda total.

Automação no TradingView: Pine Script v6, indicadores e webhooks

Guia completo para automação de estratégias no TradingView usando Pine Script v6.

Estratégias TradingView

Coleção de estratégias Pine Script documentadas: sistemas de tendência, trailing stops e filtros de notícias econômicas.

On this page

Por que usar uma biblioteca utilitária?Importando a bibliotecaMódulo 1 — Ordens LimitecalcLimitPrice()checkLimitFill()Módulo 2 — Cálculos de Pipf_pipValue() e f_pipsToPrice()Módulo 3 — Profit & LosscalcPnlLong() e calcPnlShort()Módulo 4 — Preço de LiquidaçãocalcLiqPriceLongSimple() e calcLiqPriceShortSimple()Módulo 5 — Margem e Tamanho de PosiçãocalcMargin() e calcNotional()Módulo 6 — Take Profit, Stop Loss e Trailing Stopf_checkTPHit()f_calcSLPrice()f_calcTSValue()Módulo 7 — DCA (Dollar Cost Averaging)Os três modosModo Fixed (fixo)Modo FibonacciModo MartingaleEstratégia DCA completa — exemplo práticoComparativo dos modos DCAFunções utilitárias extrasConversão percentual-preçoCálculo de taxasTimeframe para barrasQuando usar a TradingHelperLibBoas práticas ao usar a bibliotecaReferências