Opciones Avanzadas de Bot y Referencia de JSON Crudo

Dónde funciona este payload

Usa el mismo payload de creación de bot en tres lugares: el panel web, el endpoint REST de creación de bot y los clientes de chat mediante `/bots create` seguido de un único objeto JSON. El esquema del backend es la fuente de la verdad: los clientes de chat agregan alias de conveniencia para el modo de creación rápida, pero el JSON crudo omite esos alias y usa los nombres de campo canónicos que se muestran aquí.

Reglas del JSON crudo

Envía un único objeto JSON, no fragmentos parciales. En Telegram/Discord el formato es `/bots create` seguido de un objeto JSON.
Usa sintaxis JSON real: claves entre comillas dobles, cadenas entre comillas dobles, `true`/`false` en minúsculas, comas entre los campos y corchetes para los arreglos.
Usa porcentajes fraccionarios en la mayoría de los campos de riesgo. Ejemplo: `0.05` significa 5%, `0.25` significa 25% y `1` significa 100%.
Los números pueden ser enteros o decimales. Las referencias UUID como `credential_id` deben ser cadenas.
Si omites campos opcionales, el backend completa muchos de ellos con valores por defecto. Esos valores están documentados en la sección 3.
Los valores por defecto del flujo de creación del backend difieren de la plantilla de chat en algunos puntos. Para un comportamiento predecible, define los campos explícitamente en lugar de confiar en la plantilla.

Payload válido más pequeño

Esto es lo mínimo que el backend acepta para un bot spot estándar. Todo lo demás lo completan los valores por defecto de la siguiente sección.

Bot spot mínimo

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

Valores por defecto del backend cuando se omiten campos

Estos son los valores por defecto en el momento de la creación cableados en la API de bots del backend. Un payload JSON crudo que omite estos campos hereda los valores que se enumeran aquí, no lo que la plantilla de chat muestre.

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

Plantilla de chat ≠ valores por defecto del backend

La plantilla del bot de chat anuncia `timeframe: "15m"`, ejemplos más completos de stop/take y `is_minimal: false`. Si envías un payload JSON crudo pequeño sin esos campos, el backend igualmente usa por defecto `timeframe: "1m"`, `is_minimal: true` y sus propios valores internos de stop/take. Si un valor te importa, escríbelo explícitamente.

Campos avanzados de nivel superior

Estos son los campos avanzados más útiles más allá de `name`, `broker`, `symbol` y `quantity`.

watchliststring[]

Lista opcional de símbolos a escanear. Cuando `only_best_signal=true`, el backend garantiza que el `symbol` principal se incluya aunque lo hayas olvidado.

only_best_signalboolean

Le dice al bot que elija la mejor señal de la watchlist en lugar de operar solo el símbolo principal. Si es true y `watchlist` está vacía, el backend llena la lista con el símbolo principal.

simulation_modeboolean

Interruptor de paper trading. Toma `true` por defecto cuando se omite en el flujo de creación del backend, por lo que el JSON crudo puede iniciar con seguridad en simulación a menos que lo desactives explícitamente.

is_minimalboolean

Marca el bot como un bot mínimo/básico. Toma `true` por defecto en el flujo de creación del backend, aunque la plantilla de chat muestre un payload de ejemplo más completo.

position_sizing_modefixed_quantity | percent_of_equity | risk_per_trade

Modo de dimensionamiento. `fixed_quantity` usa `quantity` directamente. `percent_of_equity` requiere `balance_allocation_pct`. `risk_per_trade` requiere `risk_per_trade_pct`.

balance_allocation_pctdecimal (0, 1]

Obligatorio cuando `position_sizing_mode=percent_of_equity`. Usa fracciones, no porcentajes enteros: `0.25` significa 25% del capital.

risk_per_trade_pctdecimal (0, 1]

Obligatorio cuando `position_sizing_mode=risk_per_trade`. También se expresa como fracción: `0.01` significa 1% de riesgo por operación.

credential_idUUID string

Referencia una credencial ya guardada en lugar de enviar claves crudas de la exchange inline. Si esto está presente, el backend ignora `api_key`, `secret_key` y `passphrase` inline para el almacenamiento.

strategy_idUUID string

ID opcional de agrupación/referencia de estrategia. Útil cuando el bot pertenece a un flujo de nivel superior o a una entrada de catálogo.

org_idUUID string

Ámbito de organización opcional. El usuario autenticado debe tener al menos acceso de nivel trader en esa organización.

leverageinteger

Ajuste exclusivo de futuros. Se puede omitir con seguridad para bots spot/on-chain. Combínalo con `margin_type` y, opcionalmente, `position_side`.

margin_typestring

Normalmente `cross` o `isolated`. Los clientes de chat aceptan esos valores en minúsculas y los pasan tal cual.

position_sidestring

Normalmente `both`, `long` o `short`, según las capacidades del bróker y el modo hedge.

timeframestring

Timeframe de kline como `1m`, `5m`, `15m`, `1h`. El valor por defecto del backend es `1m` si se omite del JSON crudo.

chainstring

Obligatorio cuando `broker` es `onchain` (y recomendado para `pancakeswap`/`sushiswap`). Valores de ejemplo incluyen `polygon`, `ethereum` o `bsc`.

indicator_config.bot_typesignal | grid

Modo de ejecución incrustado dentro de `indicator_config`. Omítelo o define `signal` para el motor de estrategia basado en indicadores. Define `grid` para activar el trading en grid.

indicator_config.grid_configobject

Obligatorio cuando `indicator_config.bot_type=grid`. Debe incluir límites de precio válidos, número de grid y asignación total de cotización. Consulta la sección 6.

indicator_config.ml_configobject

Ajustes opcionales de machine learning. `enabled=true` está restringido a los planes VIP, Fund y Enterprise en el backend. Consulta la sección 7.

Config de indicadores

`indicator_config` es el objeto de personalización profunda. Algunos campos son pesos de señal, otros son periodos/umbrales, y dos de ellos cambian el bot a modos de ejecución alternativos (grid en la sección 6, ML en la sección 7).

sma_weightdecimal

Peso de señal para la contribución de la media móvil simple.

ema_weightdecimal

Peso de señal para la contribución de la EMA.

wma_weightdecimal

Peso de señal para la contribución de la WMA.

hma_weightdecimal

Peso de señal para la contribución de la HMA.

vwma_weightdecimal

Peso de señal para la contribución de la VWMA.

macd_weightdecimal

Peso de señal para la contribución del MACD.

adx_weightdecimal

Peso de señal para la contribución del ADX.

parabolic_sar_weightdecimal

Peso de señal para la contribución del Parabolic SAR.

ichimoku_weightdecimal

Peso de señal para la contribución del Ichimoku.

supertrend_weightdecimal

Peso de señal para la contribución del Supertrend.

rsi_weightdecimal

Peso de señal para la contribución del RSI.

stoch_rsi_weightdecimal

Peso de señal para la contribución del Stoch RSI.

mfi_weightdecimal

Peso de señal para la contribución del MFI.

cci_weightdecimal

Peso de señal para la contribución del CCI.

momentum_weightdecimal

Peso de señal para la contribución del momentum.

roc_weightdecimal

Peso de señal para la contribución de la tasa de cambio (ROC).

bollinger_weightdecimal

Peso de señal para la contribución de las Bandas de Bollinger.

atr_weightdecimal

Peso de señal para la contribución del ATR.

keltner_weightdecimal

Peso de señal para la contribución del canal de Keltner.

donchian_weightdecimal

Peso de señal para la contribución del Donchian.

obv_weightdecimal

Peso de señal para la contribución del OBV.

vwap_weightdecimal

Peso de señal para la contribución del VWAP.

volume_osc_weightdecimal

Peso de señal para la contribución del oscilador de volumen.

cmf_weightdecimal

Peso de señal para la contribución del Chaikin Money Flow.

support_resistance_weightdecimal

Peso de señal para la contribución de soporte/resistencia.

pivot_points_weightdecimal

Peso de señal para la contribución de los puntos pivote.

fibonacci_weightdecimal

Peso de señal para la contribución de Fibonacci.

candles_weightdecimal

Peso de señal para la contribución de patrones de velas.

ml_weightdecimal

Peso de señal para la contribución del modelo de ML cuando está activado.

bollinger_stddevnumber

Multiplicador de desviación estándar para las Bandas de Bollinger.

macd_fast / macd_slow / macd_signalinteger

Tupla de periodos del MACD.

rsi_period / rsi_overbought / rsi_oversoldinteger / decimal

Valores de ajuste del RSI.

stoch_rsi_period / stoch_overbought / stoch_oversoldinteger / decimal

Valores de ajuste del Stoch RSI.

mfi_period / mfi_overbought / mfi_oversoldinteger / decimal

Valores de ajuste del Money Flow Index.

cci_period / cci_overbought / cci_oversoldinteger / decimal

Valores de ajuste del CCI.

momentum_period / roc_period / adx_periodinteger

Longitudes de las ventanas de momentum, ROC y ADX.

adx_trend_thresholddecimal

Umbral que define una tendencia fuerte de ADX.

supertrend_period / supertrend_multiplierinteger / decimal

Configuración del Supertrend.

atr_period / keltner_multiplier / donchian_periodinteger / decimal

Configuración de ATR/Keltner/Donchian.

volume_osc_short / volume_osc_longinteger

Ventanas del oscilador de volumen.

cmf_period / support_resistance_lookbackinteger

Ventanas de CMF y de soporte/resistencia.

★

Atajo de comando de chat

En el modo de creación rápida, los bots de Telegram y Discord te permiten definir campos de indicadores comunes con flags `key=value` y cualquier campo de indicador arbitrario con el prefijo `ic_`, por ejemplo `ic_supertrend_period=10`. En el modo JSON crudo, escribe la estructura anidada final directamente en `indicator_config`.

Config de grid (`grid_config`)

Obligatorio cuando `indicator_config.bot_type="grid"`. El backend valida estrictamente los límites, el número de niveles y la asignación de cotización: las grids inválidas se rechazan en el momento de la creación.

lower_pricedecimal

Fondo del rango de la grid. Debe ser mayor que 0.

upper_pricedecimal

Techo del rango de la grid. Debe ser estrictamente mayor que `lower_price`.

grid_countinteger

Número de niveles de la grid. Debe estar entre 2 y 500 (inclusive).

total_quotedecimal

Total de moneda de cotización asignado a la grid. Debe ser mayor que 0.

spacingarithmetic | geometric

Distribución de los niveles de la grid entre `lower_price` y `upper_price`.

stop_lowerdecimal (optional)

Si se define, debe estar estrictamente por debajo de `lower_price`. La grid se detiene cuando el precio cae por debajo de él.

stop_upperdecimal (optional)

Si se define, debe estar estrictamente por encima de `upper_price`. La grid se detiene cuando el precio rompe por encima de él.

Config de ML (`ml_config`)

Opcional. Vive en `indicator_config.ml_config`. Cuando `enabled=true`, la solicitud está restringida por plan.

enabledboolean

Interruptor principal. Definirlo como `true` está restringido a los planes VIP, Fund y Enterprise; de lo contrario, el backend rechaza la llamada de creación.

feature_keysstring[]

Claves de indicadores que se alimentan al modelo de ML (ej.: `rsi`, `macd`, `adx`, `vwap`). Las columnas externas de la capa de datos usan el prefijo `ext:` (ej.: `ext:funding_z`, `ext:ofi_z`, `ext:user_midato_col_chg`) y cada una debe estar cubierta por una entrada en `feature_specs` — las claves desconocidas o sin cobertura se rechazan en la validación.

feature_specsobject[] (optional)

Especificaciones de la capa de datos que respaldan las claves `ext:`. Cada spec es `{"kind": ...}` con kind entre `funding`, `taker_flow`, `open_interest`, `basis`, `liquidations`, `macro` (requiere `dataset`, ej.: `VIXCLS`) o `custom` (requiere `dataset` = el slug de tu subida). El entrenamiento las resuelve del histórico y el engine en vivo resuelve las MISMAS specs en tiempo real — el modelo ve columnas idénticas en ambos momentos. Usa el panel Research Data del dashboard para descubrir columnas y filtrarlas por señal primero.

data_timeframestring (optional)

Timeframe de kline usado para construir el conjunto de datos de entrenamiento, ej.: `1h`. Independiente del `timeframe` en vivo del bot.

data_dirstring (optional)

Anulación opcional de ruta para datos de entrenamiento en caché. La mayoría de los usuarios debería omitir esto.

horizoninteger (optional)

Número de barras futuras que el modelo intenta predecir.

min_samplesinteger (optional)

Número mínimo de muestras de entrenamiento requerido antes de que el modelo produzca señales.

epochsinteger (optional)

Épocas de entrenamiento. Más = entrenamiento más largo, mayor riesgo de overfitting.

learning_ratenumber (optional)

Tasa de aprendizaje del optimizador. Valores comunes: `1e-3` a `1e-4`.

batch_sizeinteger (optional)

Tamaño del mini-lote usado durante el entrenamiento.

l2_regularizationnumber (optional)

Decaimiento de peso L2. Ayuda a combatir el overfitting.

validation_splitnumber (optional)

Fracción de los datos de entrenamiento reservada para validación, ej.: `0.2`.

early_stop_patienceinteger (optional)

Detiene el entrenamiento tras esta cantidad de épocas sin mejora en la validación.

label_clipnumber (optional)

Recorta las etiquetas objetivo para limitar la influencia de valores atípicos en el entrenamiento.

prediction_thresholddecimal (optional)

Umbral de confianza que el modelo debe superar antes de que su señal contribuya.

signal_weightdecimal (optional)

Peso aplicado a la señal de ML cuando se dispara (separado de `ml_weight` en `indicator_config`).

Ejemplos completos

Bot de futuros con credenciales guardadas

Usa esto cuando quieras un bot de futuros en vivo autenticado sin incrustar secretos de la exchange en el cuerpo del mensaje.

Bot de futuros con credenciales guardadas

{
  "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
}

Escáner de mejor señal con watchlist

Usa esto cuando un bot deba observar varios símbolos y actuar solo en la oportunidad más fuerte.

Escáner de mejor señal con 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 grid

El modo grid vive en `indicator_config.bot_type="grid"`. El backend valida estrictamente los límites y la asignación de cotización.

Bot de grid

{
  "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

Cuando `broker` es `onchain`, `chain` se vuelve obligatorio. Sin él, el backend rechaza la solicitud.

Bot on-chain

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

Config de indicadores con ML activado

El modo ML está restringido por plan. El formato de la solicitud sigue siendo válido, pero el backend lo rechaza fuera de los planes VIP/Fund/Enterprise.

Config de indicadores con ML activado

{
  "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
    }
  }
}

Validación y casos límite

Slugs de `broker` admitidos

binance

Alias aceptado por el backend; se resuelve a Binance Spot en la mayoría de las rutas.

binance_spot

Exchange Binance Spot (centralizada).

binance_futures

Binance USDⓈ-M Futures.

coinbase

Coinbase Advanced Trade. Requiere `passphrase` para credenciales inline.

kraken

Kraken Spot.

kucoin

KuCoin Spot. Requiere `passphrase` para credenciales inline.

coinex

CoinEx Spot.

pancakeswap

PancakeSwap (BSC). Se trata como enrutamiento de liquidez on-chain.

sushiswap

SushiSwap. Se trata como enrutamiento de liquidez on-chain.

onchain

Broker on-chain genérico. `chain` es obligatorio (ej.: `polygon`, `ethereum`, `bsc`).

Otras verificaciones del lado del servidor

`quantity` debe ser mayor que cero.
`balance_allocation_pct` y `risk_per_trade_pct` deben ser mayores que 0 y como máximo 1.
`position_sizing_mode=percent_of_equity` sin `balance_allocation_pct` se rechaza.
`position_sizing_mode=risk_per_trade` sin `risk_per_trade_pct` se rechaza.
Si `broker=onchain`, `chain` es obligatorio.
Si `indicator_config.bot_type="grid"`, entonces `grid_config` es obligatorio y debe cumplir: `lower_price > 0`, `upper_price > lower_price`, `grid_count` entre 2 y 500, `total_quote > 0`, `stop_lower < lower_price` y `stop_upper > upper_price` cuando se proporciona.
Si `indicator_config.ml_config.enabled=true`, la solicitud está restringida a los planes VIP, Fund y Enterprise.
Si envías `credential_id`, el backend no almacena nuevas claves de API inline para ese bot.
Para credenciales al estilo de Coinbase y KuCoin, incluye `passphrase` al usar campos de credencial inline.

JSON crudo vs. flags de creación rápida

Telegram y Discord admiten dos estilos de creación. La creación rápida se ve así:

Ejemplo de creación rápida

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

El modo JSON crudo usa `/bots create` seguido de un objeto JSON completo. La creación rápida es más fácil para casos simples, pero cubre solo un subconjunto del esquema del backend y depende del análisis de alias. El JSON crudo es la mejor opción cuando necesitas watchlists, config de indicadores anidada, config de grid, config de ML, vínculo de organización o un payload reutilizable en scripts.

Flujo de trabajo recomendado

Empieza por el payload válido más pequeño y agrega una función avanzada a la vez.
Mantén `simulation_mode=true` hasta que el payload sea estable.
Usa `credential_id` en lugar de pegar secretos en el chat siempre que sea posible.
Fija los campos clave explícitamente (`timeframe`, valores de stop/take, modo de dimensionamiento) para que los valores por defecto del backend no te sorprendan.
Para bots de grid y bots de ML, prueba primero el JSON exacto en simulación: esos modos son más sensibles a la configuración que los bots de señal estándar.