Opções Avançadas de Bot e Referência de JSON Bruto

Onde este payload funciona

Use o mesmo payload de criação de bot em três lugares: o painel web, o endpoint REST de criação de bot e os clientes de chat via `/bots create` seguido de um único objeto JSON. O esquema do backend é a fonte da verdade — os clientes de chat adicionam aliases de conveniência para o modo de criação rápida, mas o JSON bruto ignora esses aliases e usa os nomes de campo canônicos mostrados aqui.

Regras do JSON bruto

Envie um único objeto JSON, não fragmentos parciais. No Telegram/Discord o formato é `/bots create` seguido de um objeto JSON.
Use sintaxe JSON real: chaves entre aspas duplas, strings entre aspas duplas, `true`/`false` em minúsculas, vírgulas entre os campos e colchetes para arrays.
Use porcentagens fracionárias na maioria dos campos de risco. Exemplo: `0.05` significa 5%, `0.25` significa 25% e `1` significa 100%.
Os números podem ser inteiros ou decimais. Referências UUID como `credential_id` devem ser strings.
Se você omitir campos opcionais, o backend preenche muitos deles com padrões. Esses padrões estão documentados na seção 3.
Os padrões do fluxo de criação do backend diferem do template de chat em alguns pontos. Para um comportamento previsível, defina os campos explicitamente em vez de confiar no template.

Menor payload válido

Este é o mínimo que o backend aceita para um bot spot padrão. Todo o resto é preenchido pelos padrões da próxima seção.

Bot spot mínimo

{
  "name": "btc-sim",
  "broker": "binance_spot",
  "symbol": "BTCUSDT",
  "quantity": 0.01
}

Padrões do backend quando campos são omitidos

Estes são os padrões aplicados no momento da criação na API de bots do backend. Um payload JSON bruto que omite esses campos herda os valores listados aqui — não o que o template de chat porventura exibe.

is_minimal

true

simulation_mode

true

only_best_signal

false

sensitivity_buy

1.0

sensitivity_sell

1.0

threshold

0.95

position_sizing_mode

fixed_quantity

stop_loss_partial

0.05

stop_loss_lower_half_average

0.05

stop_loss_last

0.05

stop_loss_trailing_start

0.02

stop_loss_trailing_end

0.01

take_profit_partial

0.10

take_profit_lower_half_average

0.15

take_profit_last

0.20

take_profit_trailing_start

0.05

take_profit_trailing_end

0.03

ema_short_period

200

ema_long_period

1000

bollinger_period

250

signal_period

tenkan_period

kijun_period

senkou_span_b_period

chikou_span_period

ema_exponent

1.0

bollinger_exponent

1.15

macd_exponent

1.25

rsi_exponent

1.15

vwap_exponent

ichimoku_exponent

1.5

selling_exponent

2.5

timeframe

profit

total_trades

winning_trades

is_active

true on create

Template de chat ≠ padrões do backend

O template do bot de chat anuncia `timeframe: "15m"`, exemplos mais ricos de stop/take e `is_minimal: false`. Se você enviar um payload JSON bruto pequeno sem esses campos, o backend ainda usa por padrão `timeframe: "1m"`, `is_minimal: true` e seus próprios valores internos de stop/take. Se um valor for importante para você, escreva-o explicitamente.

Campos avançados de nível superior

Estes são os campos avançados mais úteis além de `name`, `broker`, `symbol` e `quantity`.

watchliststring[]

Lista opcional de símbolos a escanear. Quando `only_best_signal=true`, o backend garante que o `symbol` principal seja incluído mesmo que você o tenha esquecido.

only_best_signalboolean

Diz ao bot para escolher o melhor sinal da watchlist em vez de negociar apenas o símbolo principal. Se for true e `watchlist` estiver vazia, o backend preenche a lista com o símbolo principal.

simulation_modeboolean

Interruptor de paper trading. Assume `true` por padrão quando omitido no fluxo de criação do backend, de modo que o JSON bruto pode iniciar com segurança em simulação a menos que você o desligue explicitamente.

is_minimalboolean

Marca o bot como um bot mínimo/básico. Assume `true` por padrão no fluxo de criação do backend, mesmo que o template de chat mostre um payload de exemplo mais rico.

position_sizing_modefixed_quantity | percent_of_equity | risk_per_trade

Modo de dimensionamento. `fixed_quantity` usa `quantity` diretamente. `percent_of_equity` requer `balance_allocation_pct`. `risk_per_trade` requer `risk_per_trade_pct`.

balance_allocation_pctdecimal (0, 1]

Obrigatório quando `position_sizing_mode=percent_of_equity`. Use frações, não porcentagens inteiras: `0.25` significa 25% do patrimônio.

risk_per_trade_pctdecimal (0, 1]

Obrigatório quando `position_sizing_mode=risk_per_trade`. Também expresso como fração: `0.01` significa 1% de risco por operação.

credential_idUUID string

Referencie uma credencial já salva em vez de enviar chaves brutas da exchange inline. Se isto estiver presente, o backend ignora `api_key`, `secret_key` e `passphrase` inline para armazenamento.

strategy_idUUID string

ID opcional de agrupamento/referência de estratégia. Útil quando o bot pertence a um fluxo de nível superior ou a uma entrada de catálogo.

org_idUUID string

Escopo de organização opcional. O usuário autenticado deve ter pelo menos acesso de nível trader naquela organização.

leverageinteger

Configuração exclusiva de futuros. Pode ser omitida com segurança para bots spot/on-chain. Combine-a com `margin_type` e, opcionalmente, `position_side`.

margin_typestring

Geralmente `cross` ou `isolated`. Os clientes de chat aceitam esses valores em minúsculas e os repassam.

position_sidestring

Geralmente `both`, `long` ou `short`, dependendo das capacidades da corretora e do modo hedge.

timeframestring

Timeframe de kline como `1m`, `5m`, `15m`, `1h`. O padrão do backend é `1m` se omitido do JSON bruto.

chainstring

Obrigatório quando `broker` é `onchain` (e recomendado para `pancakeswap`/`sushiswap`). Valores de exemplo incluem `polygon`, `ethereum` ou `bsc`.

indicator_config.bot_typesignal | grid

Modo de execução embutido dentro de `indicator_config`. Omita-o ou defina `signal` para o motor de estratégia baseado em indicadores. Defina `grid` para ativar o trading em grade.

indicator_config.grid_configobject

Obrigatório quando `indicator_config.bot_type=grid`. Deve incluir limites de preço válidos, contagem de grade e alocação total de cotação. Veja a seção 6.

indicator_config.ml_configobject

Configurações opcionais de machine learning. `enabled=true` é restrito aos planos VIP, Fund e Enterprise no backend. Veja a seção 7.

Config de indicadores

`indicator_config` é o objeto de personalização profunda. Alguns campos são pesos de sinal, alguns são períodos/limiares, e dois deles colocam o bot em modos de execução alternativos (grade na seção 6, ML na seção 7).

sma_weightdecimal

Peso do sinal para a contribuição da média móvel simples.

ema_weightdecimal

Peso do sinal para a contribuição da EMA.

wma_weightdecimal

Peso do sinal para a contribuição da WMA.

hma_weightdecimal

Peso do sinal para a contribuição da HMA.

vwma_weightdecimal

Peso do sinal para a contribuição da VWMA.

macd_weightdecimal

Peso do sinal para a contribuição do MACD.

adx_weightdecimal

Peso do sinal para a contribuição do ADX.

parabolic_sar_weightdecimal

Peso do sinal para a contribuição do Parabolic SAR.

ichimoku_weightdecimal

Peso do sinal para a contribuição do Ichimoku.

supertrend_weightdecimal

Peso do sinal para a contribuição do Supertrend.

rsi_weightdecimal

Peso do sinal para a contribuição do RSI.

stoch_rsi_weightdecimal

Peso do sinal para a contribuição do Stoch RSI.

mfi_weightdecimal

Peso do sinal para a contribuição do MFI.

cci_weightdecimal

Peso do sinal para a contribuição do CCI.

momentum_weightdecimal

Peso do sinal para a contribuição do momentum.

roc_weightdecimal

Peso do sinal para a contribuição da taxa de variação (ROC).

bollinger_weightdecimal

Peso do sinal para a contribuição das Bandas de Bollinger.

atr_weightdecimal

Peso do sinal para a contribuição do ATR.

keltner_weightdecimal

Peso do sinal para a contribuição do canal de Keltner.

donchian_weightdecimal

Peso do sinal para a contribuição do Donchian.

obv_weightdecimal

Peso do sinal para a contribuição do OBV.

vwap_weightdecimal

Peso do sinal para a contribuição do VWAP.

volume_osc_weightdecimal

Peso do sinal para a contribuição do oscilador de volume.

cmf_weightdecimal

Peso do sinal para a contribuição do Chaikin Money Flow.

support_resistance_weightdecimal

Peso do sinal para a contribuição de suporte/resistência.

pivot_points_weightdecimal

Peso do sinal para a contribuição dos pontos de pivô.

fibonacci_weightdecimal

Peso do sinal para a contribuição de Fibonacci.

candles_weightdecimal

Peso do sinal para a contribuição de padrões de candle.

ml_weightdecimal

Peso do sinal para a contribuição do modelo de ML quando ativado.

bollinger_stddevnumber

Multiplicador de desvio padrão para as Bandas de Bollinger.

macd_fast / macd_slow / macd_signalinteger

Tupla de períodos do MACD.

rsi_period / rsi_overbought / rsi_oversoldinteger / decimal

Valores de ajuste do RSI.

stoch_rsi_period / stoch_overbought / stoch_oversoldinteger / decimal

Valores de ajuste do Stoch RSI.

mfi_period / mfi_overbought / mfi_oversoldinteger / decimal

Valores de ajuste do Money Flow Index.

cci_period / cci_overbought / cci_oversoldinteger / decimal

Valores de ajuste do CCI.

momentum_period / roc_period / adx_periodinteger

Comprimentos das janelas de momentum, ROC e ADX.

adx_trend_thresholddecimal

Limiar que define uma tendência forte de ADX.

supertrend_period / supertrend_multiplierinteger / decimal

Configuração do Supertrend.

atr_period / keltner_multiplier / donchian_periodinteger / decimal

Configuração de ATR/Keltner/Donchian.

volume_osc_short / volume_osc_longinteger

Janelas do oscilador de volume.

cmf_period / support_resistance_lookbackinteger

Janelas de CMF e de suporte/resistência.

★

Atalho de comando de chat

No modo de criação rápida, os bots do Telegram e do Discord permitem definir campos de indicadores comuns com flags `key=value` e qualquer campo de indicador arbitrário com o prefixo `ic_`, por exemplo `ic_supertrend_period=10`. No modo JSON bruto, escreva a estrutura aninhada final diretamente em `indicator_config`.

Config de grade (`grid_config`)

Obrigatório quando `indicator_config.bot_type="grid"`. O backend valida estritamente os limites, a contagem de níveis e a alocação de cotação — grades inválidas são rejeitadas no momento da criação.

lower_pricedecimal

Fundo do intervalo da grade. Deve ser maior que 0.

upper_pricedecimal

Topo do intervalo da grade. Deve ser estritamente maior que `lower_price`.

grid_countinteger

Número de níveis da grade. Deve estar entre 2 e 500 (inclusive).

total_quotedecimal

Total da moeda de cotação alocado à grade. Deve ser maior que 0.

spacingarithmetic | geometric

Distribuição dos níveis da grade entre `lower_price` e `upper_price`.

stop_lowerdecimal (optional)

Se definido, deve ser estritamente abaixo de `lower_price`. A grade para quando o preço cai abaixo dele.

stop_upperdecimal (optional)

Se definido, deve ser estritamente acima de `upper_price`. A grade para quando o preço rompe acima dele.

Config de ML (`ml_config`)

Opcional. Fica em `indicator_config.ml_config`. Quando `enabled=true`, a solicitação é restrita por plano.

enabledboolean

Interruptor principal. Definir como `true` é restrito aos planos VIP, Fund e Enterprise; caso contrário, o backend rejeita a chamada de criação.

feature_keysstring[]

Chaves de indicadores alimentadas ao modelo de ML (ex.: `rsi`, `macd`, `adx`, `vwap`). Colunas externas da camada de dados usam o prefixo `ext:` (ex.: `ext:funding_z`, `ext:ofi_z`, `ext:user_meudado_col_chg`) e cada uma deve ser coberta por uma entrada em `feature_specs` — chaves desconhecidas ou sem cobertura são rejeitadas na validação.

feature_specsobject[] (optional)

Especificações da camada de dados que respaldam as chaves `ext:`. Cada spec é `{"kind": ...}` com kind entre `funding`, `taker_flow`, `open_interest`, `basis`, `liquidations`, `macro` (requer `dataset`, ex.: `VIXCLS`) ou `custom` (requer `dataset` = o slug do seu upload). O treinamento as resolve do histórico e o engine ao vivo resolve as MESMAS specs em tempo real — o modelo vê colunas idênticas nos dois momentos. Use o painel Research Data do dashboard para descobrir colunas e triá-las por sinal antes.

data_timeframestring (optional)

Timeframe de kline usado para construir o conjunto de dados de treinamento, ex.: `1h`. Independente do `timeframe` ao vivo do bot.

data_dirstring (optional)

Substituição opcional de caminho para dados de treinamento em cache. A maioria dos usuários deve omitir isto.

horizoninteger (optional)

Número de barras futuras que o modelo tenta prever.

min_samplesinteger (optional)

Número mínimo de amostras de treinamento exigido antes que o modelo produza sinais.

epochsinteger (optional)

Épocas de treinamento. Mais = treinamento mais longo, maior risco de overfitting.

learning_ratenumber (optional)

Taxa de aprendizado do otimizador. Valores comuns: `1e-3` a `1e-4`.

batch_sizeinteger (optional)

Tamanho do mini-lote usado durante o treinamento.

l2_regularizationnumber (optional)

Decaimento de peso L2. Ajuda a combater o overfitting.

validation_splitnumber (optional)

Fração dos dados de treinamento reservada para validação, ex.: `0.2`.

early_stop_patienceinteger (optional)

Interrompe o treinamento após esta quantidade de épocas sem melhora na validação.

label_clipnumber (optional)

Limita os rótulos-alvo para reduzir a influência de outliers no treinamento.

prediction_thresholddecimal (optional)

Limiar de confiança que o modelo deve ultrapassar antes que seu sinal contribua.

signal_weightdecimal (optional)

Peso aplicado ao sinal de ML quando ele dispara (separado de `ml_weight` em `indicator_config`).

Exemplos completos

Bot de futuros com credenciais armazenadas

Use isto quando quiser um bot de futuros ao vivo autenticado sem incluir segredos da exchange no corpo da mensagem.

Bot de futuros com credenciais armazenadas

{
  "name": "btc-futures-live",
  "broker": "binance_futures",
  "symbol": "BTCUSDT",
  "quantity": 0.01,
  "simulation_mode": false,
  "is_minimal": false,
  "timeframe": "15m",
  "leverage": 5,
  "margin_type": "cross",
  "position_side": "both",
  "credential_id": "11111111-2222-3333-4444-555555555555",
  "sensitivity_buy": 1.0,
  "sensitivity_sell": 1.0,
  "threshold": 0.95,
  "stop_loss_partial": 0.05,
  "stop_loss_lower_half_average": 0.05,
  "stop_loss_last": 0.05,
  "stop_loss_trailing_start": 0.02,
  "stop_loss_trailing_end": 0.01,
  "take_profit_partial": 0.1,
  "take_profit_lower_half_average": 0.15,
  "take_profit_last": 0.2,
  "take_profit_trailing_start": 0.05,
  "take_profit_trailing_end": 0.03
}

Scanner de melhor sinal com watchlist

Use isto quando um bot deve observar vários símbolos e agir apenas na oportunidade mais forte.

Scanner de melhor sinal com watchlist

{
  "name": "majors-scanner",
  "broker": "binance_spot",
  "symbol": "BTCUSDT",
  "quantity": 0.005,
  "only_best_signal": true,
  "watchlist": ["BTCUSDT", "ETHUSDT", "SOLUSDT", "BNBUSDT"],
  "timeframe": "5m",
  "indicator_config": {
    "rsi_period": 14,
    "rsi_overbought": 70,
    "rsi_oversold": 30,
    "macd_fast": 12,
    "macd_slow": 26,
    "macd_signal": 9,
    "vwap_weight": 0.4,
    "pivot_points_weight": 0.2
  }
}

Bot de grade

O modo de grade fica em `indicator_config.bot_type="grid"`. O backend valida estritamente os limites e a alocação de cotação.

Bot de grade

{
  "name": "eth-grid",
  "broker": "binance_spot",
  "symbol": "ETHUSDT",
  "quantity": 0.01,
  "simulation_mode": true,
  "indicator_config": {
    "bot_type": "grid",
    "grid_config": {
      "lower_price": 2800,
      "upper_price": 3600,
      "grid_count": 12,
      "total_quote": 1500,
      "spacing": "arithmetic",
      "stop_lower": 2600,
      "stop_upper": 3800
    }
  }
}

Bot on-chain

Quando `broker` é `onchain`, `chain` torna-se obrigatório. Sem ele o backend rejeita a solicitação.

Bot on-chain

{
  "name": "polygon-usdc",
  "broker": "onchain",
  "chain": "polygon",
  "symbol": "WETH/USDC",
  "quantity": 100,
  "simulation_mode": true
}

Config de indicadores com ML ativado

O modo ML é restrito por plano. O formato da solicitação ainda é válido, mas o backend o recusa fora dos planos VIP/Fund/Enterprise.

Config de indicadores com ML ativado

{
  "name": "ml-major-trend",
  "broker": "binance_spot",
  "symbol": "BTCUSDT",
  "quantity": 0.01,
  "indicator_config": {
    "ml_weight": 1.0,
    "ml_config": {
      "enabled": true,
      "model_type": "mlp",
      "hidden_layers": [16, 8],
      "activation": "relu",
      "feature_keys": ["rsi", "macd_hist", "adx", "vwap", "ema_short", "ema_long", "atr", "momentum", "ext:funding_z"],
      "feature_specs": [{ "kind": "funding" }],
      "data_timeframe": "1h",
      "horizon": 6,
      "epochs": 200,
      "batch_size": 64,
      "learning_rate": 0.005,
      "l2_regularization": 0.0001,
      "validation_split": 0.2,
      "early_stop_patience": 15,
      "walk_forward_folds": 4,
      "feature_importance": true,
      "prediction_threshold": 0.002,
      "signal_weight": 1.0
    }
  }
}

Validação e casos extremos

Slugs de `broker` suportados

binance

Alias aceito pelo backend; resolve para Binance Spot na maioria dos caminhos.

binance_spot

Exchange Binance Spot (centralizada).

binance_futures

Binance USDⓈ-M Futures.

coinbase

Coinbase Advanced Trade. Requer `passphrase` para credenciais inline.

kraken

Kraken Spot.

kucoin

KuCoin Spot. Requer `passphrase` para credenciais inline.

coinex

CoinEx Spot.

pancakeswap

PancakeSwap (BSC). Tratado como roteamento de liquidez on-chain.

sushiswap

SushiSwap. Tratado como roteamento de liquidez on-chain.

onchain

Broker on-chain genérico. `chain` é obrigatório (ex.: `polygon`, `ethereum`, `bsc`).

Outras verificações do lado do servidor

`quantity` deve ser maior que zero.
`balance_allocation_pct` e `risk_per_trade_pct` devem ser maiores que 0 e no máximo 1.
`position_sizing_mode=percent_of_equity` sem `balance_allocation_pct` é rejeitado.
`position_sizing_mode=risk_per_trade` sem `risk_per_trade_pct` é rejeitado.
Se `broker=onchain`, `chain` é obrigatório.
Se `indicator_config.bot_type="grid"`, então `grid_config` é obrigatório e deve satisfazer: `lower_price > 0`, `upper_price > lower_price`, `grid_count` entre 2 e 500, `total_quote > 0`, `stop_lower < lower_price` e `stop_upper > upper_price` quando fornecido.
Se `indicator_config.ml_config.enabled=true`, a solicitação é restrita aos planos VIP, Fund e Enterprise.
Se você enviar `credential_id`, o backend não armazena novas chaves de API inline para esse bot.
Para credenciais no estilo Coinbase e KuCoin, inclua `passphrase` ao usar campos de credencial inline.

JSON bruto vs. flags de criação rápida

O Telegram e o Discord oferecem dois estilos de criação. A criação rápida tem esta aparência:

Exemplo de criação rápida

/bots create mybot binance_futures BTCUSDT 0.01 timeframe=5m leverage=10 margin_type=isolated

O modo JSON bruto usa `/bots create` seguido de um objeto JSON completo. A criação rápida é mais fácil para casos simples, mas cobre apenas um subconjunto do esquema do backend e depende da análise de aliases. O JSON bruto é a melhor escolha quando você precisa de watchlists, config de indicadores aninhada, config de grade, config de ML, vínculo de organização ou um payload reutilizável em scripts.

Fluxo de trabalho recomendado

Comece pelo menor payload válido e adicione um recurso avançado de cada vez.
Mantenha `simulation_mode=true` até o payload estar estável.
Use `credential_id` em vez de colar segredos no chat sempre que possível.
Fixe campos-chave explicitamente (`timeframe`, valores de stop/take, modo de dimensionamento) para que os padrões do backend não o surpreendam.
Para bots de grade e bots de ML, teste o JSON exato em simulação primeiro — esses modos são mais sensíveis à configuração do que os bots de sinal padrão.