Skip to main content
← Back to Docs
🤖Bot Builder

Bot Execution Engine

How bots run via cron, paper vs live mode

The bot execution engine is the cron-driven runtime that actually executes your bot strategies. Understanding how it works helps you debug unexpected bot behavior and tune for performance.

Architecture

The execution engine is a Vercel cron job that runs every 15 minutes:

  1. Trigger. Vercel cron hits /api/cron/execute-bots at 0/15/30/45 past every hour.
  2. Authentication. The endpoint verifies the request came from Vercel using a signed token.
  3. Bot enumeration. Fetches all bots with status="running" from the database.
  4. Strategy dispatch. For each bot, loads the appropriate strategy template (EV Follower, ARB Hunter, etc.).
  5. Market evaluation. The strategy examines current market state against the bot's parameters.
  6. Order placement. When conditions match, the engine submits orders via the Polymarket CLOB API (Live mode) or records simulated fills (Paper mode).
  7. Audit logging. Every action — evaluation, trade, error — is logged to the audit trail.

Why 15 Minutes?

The choice of 15-minute intervals balances several factors:

  • •Polymarket rate limits. The CLOB API allows 10 trades/minute per user. Across all bots × all users, we have to stay under aggregate limits.
  • •Cost. Each cron tick scans all markets for all bots. More frequent = more compute = higher costs.
  • •Diminishing returns. Prediction markets are slower-moving than crypto or equities. A 5-minute vs 15-minute granularity rarely captures more alpha.
  • •Vercel free tier compatibility. Our cron schedule fits within Vercel's hobby tier limits.

For users on the Bot plan who want faster execution, TWAP orders are not bound by the 15-minute cron — they execute on per-minute slices via a separate cron.

Limits That Are Actually Enforced

Bots are braked by money and by open positions, not by a trade counter:

  • •Per trade: $25 by default for automation, raisable in Settings → Trading.
  • •Per bot, per day: $100 by default, plus an optional trade-count cap you set on the bot itself.
  • •Per bot, at once: 3 open live positions, and never two in the same market on the same day.
  • •Per profile, per day: a total budget reserved atomically before each order, so two bots cannot spend the same dollar.

Hit a cap and the order is refused, logged, and reported to you — the bot moves on instead of retrying.

What Happens When a Trade Fails

The CLOB API can fail for several reasons:

  • •Network error. The idempotency reservation is kept and the order goes to reconciliation — a second order is never sent blind.
  • •Insufficient balance. Refused before reaching the venue, logged and reported to you; the bot is not paused for it.
  • •Market closed. Logged, and the bot moves on to the next opportunity.
  • •Price slipped. If the price moved outside your limit, the order does not cross and the bot retries next cycle.

A failed trade doesn't break execution: it's logged and the bot continues.

Monitoring Your Bots

Three surfaces tell you what your bots are doing:

  • •Performance (Bot plan) — P&L per bot with live and paper kept apart, win rate, number of trades and the positions still open.
  • •Security → audit log — the trail of every sensitive action on the account, including a live order that was refused and why (kill switch, daily cap, plan, region).
  • •Notifications — fills and failures reach you in-app and, if you verified the channel, on Telegram or WhatsApp. A bot that hits its max loss pauses itself and tells you.

If a bot shows no trades when you expected some, the audit log is where the reason is. There is no per-cycle skip log: a cycle that finds nothing simply does nothing.

Manually Triggering Execution

The "Execute now" button on the Bots page (available to Bot plan users) lets you trigger an immediate cycle without waiting for the next cron tick. Useful for:

  • •Testing parameter changes without waiting 15 minutes
  • •Capturing time-sensitive signals you've identified manually
  • •Verifying connectivity after CLOB API maintenance

Manual triggers count toward your daily rate limit. Don't spam this button.

Stopping a Bot

Three ways to stop a bot:

  1. Pause. Bot keeps existing positions, doesn't take new ones. Use for short breaks.
  2. Stop. Bot is fully deactivated. Open positions stay; close them manually.
  3. Kill switch (global). Settings → Trading → Kill Switch immediately stops ALL bots and ALL automated execution. Use for emergencies.

Kill switch is the right call if you see unexpected behavior — pause to investigate, then re-enable when you're sure.

Audit Trail

Every bot action is logged to the bot_audit_logs table with:

  • •Timestamp
  • •Bot ID
  • •Action type (evaluate, place_order, close_order, error)
  • •Market involved
  • •Decision rationale (which condition triggered or why skipped)
  • •Order details (size, price, direction)
  • •Outcome (filled, rejected, partial)

You can export audit logs as CSV from the bot detail page. Useful for:

  • •Tax reporting (Form 8949 export available)
  • •Strategy review ("why did the bot pass on this market?")
  • •Debugging when behavior doesn't match expectations
  • •Compliance documentation if you're trading professionally

Common Bot Execution Issues

Bot shows "running" but never trades.

  • •Check skip log — likely all signals are below your min edge threshold.
  • •Try lowering min_edge slightly, but don't go below 5pp.
  • •Verify category filters aren't too narrow.

Bot trades too much.

  • •Daily trade limit is too high.
  • •Min edge is too low — you're catching noise.
  • •Add additional filters (min confidence, min volume).

Bot trades only one platform.

  • •Check the Polymarket vs Kalshi toggle in bot config.
  • •Verify the other platform's status indicator is green.

Live bot stopped trading suddenly.

  • •Check CLOB API status (might be down).
  • •Check your CLOB API credentials haven't expired.
  • •Check your Polymarket wallet has USDC balance.

Related Docs

← All Documentation