Motor de Ejecución de Bots
Cómo los bots se ejecutan vía cron, paper vs live
El motor de ejecución de bots es el runtime impulsado por cron que realmente ejecuta las estrategias de tus bots. Entender cómo funciona te ayuda a depurar comportamientos inesperados de los bots y a optimizar el rendimiento.
Arquitectura
El motor de ejecución es un cron job de Vercel que se ejecuta cada 15 minutos:
- Disparador. El cron de Vercel llama a /api/cron/execute-bots en los minutos 0/15/30/45 de cada hora.
- Autenticación. El endpoint verifica que la solicitud provino de Vercel mediante un token firmado.
- Enumeración de bots. Obtiene de la base de datos todos los bots con status="running".
- Despacho de estrategias. Para cada bot, carga la plantilla de estrategia correspondiente (EV Follower, ARB Hunter, etc.).
- Evaluación del mercado. La estrategia examina el estado actual del mercado frente a los parámetros del bot.
- Colocación de órdenes. Cuando las condiciones coinciden, el motor envía órdenes mediante la API CLOB de Polymarket (modo Live) o registra ejecuciones simuladas (modo Paper).
- Registro de auditoría. Cada acción — evaluación, operación, error — se registra en el historial de auditoría.
¿Por qué 15 minutos?
La elección de intervalos de 15 minutos equilibra varios factores:
- •Límites de tasa de Polymarket. La API CLOB permite 10 operaciones por minuto por usuario. Considerando todos los bots × todos los usuarios, debemos mantenernos por debajo de los límites agregados.
- •Costo. Cada tick del cron escanea todos los mercados para todos los bots. Más frecuencia = más cómputo = mayores costos.
- •Rendimientos decrecientes. Los mercados de predicción se mueven más lento que las criptomonedas o las acciones. Una granularidad de 5 minutos frente a 15 minutos rara vez captura más alpha.
- •Compatibilidad con el plan gratuito de Vercel. Nuestra programación de cron se ajusta a los límites del nivel hobby de Vercel.
Para los usuarios del plan Bot que desean una ejecución más rápida, las órdenes TWAP no están sujetas al cron de 15 minutos: se ejecutan en porciones por minuto mediante un cron independiente.
Límites Que Realmente se Aplican
Los frenos del bot son por DINERO y por posiciones abiertas, no por un contador de operaciones:
- •Por operación: US$ 25 por defecto en automatización, ajustable en Configuración → Trading.
- •Por bot, por día: US$ 100 por defecto, más un tope opcional de número de operaciones que defines en el propio bot.
- •Por bot, simultáneas: 3 posiciones live abiertas, y nunca dos en el mismo mercado el mismo día.
- •Por perfil, por día: un presupuesto total reservado atómicamente antes de cada orden, para que dos bots no gasten el mismo dólar.
Al alcanzar un tope la orden se rechaza, se registra y se te informa: el bot sigue adelante en vez de reintentar. ## Qué Pasa Cuando una Operación Falla
La API del CLOB puede fallar por varios motivos:
- •Error de red. La reserva de idempotencia se mantiene y la orden queda para reconciliar — nunca se envía una segunda orden a ciegas.
- •Saldo insuficiente. Se rechaza antes de tocar la venue, se registra y se te notifica; el bot no se pausa por eso.
- •Mercado cerrado. Se registra y el bot pasa a la siguiente oportunidad.
- •Precio movido. Si el precio se alejó de tu límite, la orden no cruza y el bot reintenta en el ciclo siguiente.
Una operación fallida no rompe la ejecución: queda registrada y el bot continúa. ## Monitoreo de tus Bots
Tres superficies te dicen qué están haciendo tus bots:
- •Rendimiento (plan Bot) — PnL por bot con vivo y papel separados, tasa de acierto, número de operaciones y las posiciones aún abiertas.
- •Seguridad → registro de auditoría — el rastro de cada acción sensible de la cuenta, incluida una orden real rechazada y su motivo (kill switch, tope diario, plan, región).
- •Notificaciones — ejecuciones y fallos llegan en la app y, si verificaste el canal, a Telegram o WhatsApp. Un bot que alcanza su pérdida máxima se pausa solo y te avisa.
Si un bot no operó cuando lo esperabas, el motivo está en el registro de auditoría. No hay un log de descartes por ciclo: un ciclo que no encuentra nada simplemente no hace nada.
Disparar la Ejecución Manualmente
El botón "Ejecutar ahora" en la página de detalle del bot (disponible para los usuarios del plan Bot) te permite disparar un ciclo inmediato sin esperar al siguiente tick del cron. Útil para:
- •Probar cambios de parámetros sin esperar 15 minutos
- •Capturar señales sensibles al tiempo que hayas identificado manualmente
- •Verificar la conectividad después del mantenimiento de la API CLOB
Los disparadores manuales cuentan para tu límite de tasa diario. No abuses de este botón.
Detener un Bot
Tres formas de detener un bot:
- Pausar. El bot conserva las posiciones existentes y no toma nuevas. Úsalo para pausas breves.
- Detener. El bot se desactiva por completo. Las posiciones abiertas permanecen; ciérralas manualmente.
- Kill switch (global). Configuración → Trading → Kill Switch detiene de inmediato TODOS los bots y TODA la ejecución automatizada. Úsalo para emergencias.
El kill switch es la decisión correcta si observas un comportamiento inesperado: pausa para investigar y luego vuelve a habilitarlo cuando estés seguro.
Historial de Auditoría
Cada acción del bot se registra en la tabla bot_audit_logs con:
- •Marca de tiempo
- •ID del bot
- •Tipo de acción (evaluate, place_order, close_order, error)
- •Mercado involucrado
- •Justificación de la decisión (qué condición se activó o por qué se omitió)
- •Detalles de la orden (tamaño, precio, dirección)
- •Resultado (filled, rejected, partial)
Puedes exportar los registros de auditoría como CSV desde la página de detalle del bot. Útil para:
- •Declaración de impuestos (exportación del Formulario 8949 disponible)
- •Revisión de estrategia ("¿por qué el bot pasó de este mercado?")
- •Depuración cuando el comportamiento no coincide con las expectativas
- •Documentación de cumplimiento si operas de forma profesional
Problemas Comunes de Ejecución de Bots
El bot muestra "running" pero nunca opera.
- •Revisa el registro de saltos: es probable que todas las señales estén por debajo de tu umbral mínimo de edge.
- •Intenta bajar min_edge ligeramente, pero no por debajo de 5pp.
- •Verifica que los filtros de categoría no sean demasiado restrictivos.
El bot opera demasiado.
- •El límite diario de operaciones es demasiado alto.
- •El edge mínimo es demasiado bajo: estás capturando ruido.
- •Agrega filtros adicionales (confianza mínima, volumen mínimo).
El bot opera en una sola plataforma.
- •Revisa el interruptor entre Polymarket y Kalshi en la configuración del bot.
- •Verifica que el indicador de estado de la otra plataforma esté en verde.
El bot Live dejó de operar de repente.
- •Revisa el estado de la API CLOB (podría estar caída).
- •Verifica que tus credenciales de la API CLOB no hayan expirado.
- •Verifica que tu billetera de Polymarket tenga saldo en USDC.