2.2 AntiToxicFill

1. Bot Identity

Operational profile

2. Purpose

AntiToxicFill detects toxic order-flow patterns on the target market immediately before order submission and reshapes or cancels the ExecutionPlan to avoid being adversely selected. It monitors three primary toxicity signals: one-sided sweeps through more than three book levels in the last 5 seconds, a cancel-storm on the opposite side, and realised post-fill drift over a rolling window. If an adverse news event is detected within ±30 seconds of a planned fill, the bot enters a cooldown. Depending on signal severity, AntiToxicFill either widens the limit price by requote_widen_bps, reduces the order size by downsize_factor, or cancels the order outright. It cannot alter the trade direction, market, or outcome leg.

3. Why This Bot Matters

• Toxic sweep not detected before submission

  The system fills against an informed counterparty that has just swept the book on privileged news, resulting in immediate adverse mark-to-market on the filled position.

• Cancel-storm ignored on opposite side

  Mass cancellations on the opposite side of the book signal that the market is repricing. Submitting a resting order into this environment leads to a fill at a price that is immediately stale.

• Post-fill drift not tracked across rolling window

  Systematic adverse drift after fills indicates chronic toxic flow on the market. Without reshaping, the strategy will continue to be adversely selected until cumulative losses exceed risk limits.

• News-window cooldown not applied

  News events arriving within ±30 seconds of a fill represent the highest toxicity risk. Filling in this window without a cooldown leads to significant slippage on information-driven price moves.

No worked examples on this bot yet. Worked examples are optional but strongly recommended — they turn an abstract failure mode into something a developer can verify in a fixture.

4. Required Polymarket Inputs

5. Required Internal Inputs

6. Parameter Guide

7. Detailed Parameter Instructions

{ "cooldown_s": 30 }

if cooldown_s > params.hard: raise ConfigError('PARAMETER_CHANGE_REQUIRES_APPROVAL')

{ "requote_widen_bps": 20 }

widenedPrice = BUY ? price * (1 - requote_widen_bps/10000) : price * (1 + requote_widen_bps/10000)

{ "downsize_factor": 0.5 }

finalSize = max(originalSize * downsize_factor, originalSize * 0.1)

{ "news_window_s": 30 }

newsHit = any(abs(event.ts_ms - fill_planned_ms) <= news_window_s * 1000 for event in news_feed)

8. Default Configuration

{
  "bot_id": "exec.antitoxicfill",
  "version": "2.0.0",
  "mode": "limited_live",
  "defaults": {
    "cooldown_s": 30,
    "requote_widen_bps": 20,
    "downsize_factor": 0.5,
    "news_window_s": 30
  },
  "locked": {
    "cooldown_s": {
      "max": 120
    },
    "requote_widen_bps": {
      "max": 100
    },
    "news_window_s": {
      "max": 60
    }
  }
}

9. Implementation Flow

1. Receive ExecutionPlan from SmartRouter; load associated ObservationReport and RiskVote from the internal bus.
2. Check KillSwitch active flag; if active, discard the ExecutionPlan and emit no ExecutionReport.
3. Check whether the market is in cooldown (cooldown state keyed by market_id in Redis); if in cooldown, hold the plan and re-evaluate after cooldown expires.
4. Fetch CLOB V2 top-10 book snapshot from clob_public; subscribe to ws_market trade tape for the target market.
5. Evaluate sweep signal: count book levels consumed on one side in the last 5 seconds using the ws_market trade tape. If > 3 levels consumed, set sweep_detected = true.
6. Evaluate cancel-storm signal: count cancel events on the opposite side in the last 5 seconds from the ws_market feed. If cancel_count_5s > cancel_storm_threshold (default 10), set cancel_storm_detected = true.
7. Evaluate post-fill drift: compute mean realised drift in bps over the last drift_window_s seconds using the recent fill tape. If drift_bps > drift_threshold_bps, set drift_detected = true.
8. Check NewsIngest feed: if any adverse event timestamp falls within ±news_window_s of the planned fill, set news_hit = true.
9. Determine action: if news_hit or (sweep_detected AND cancel_storm_detected): enter cooldown, cancel order, emit ANTITOXICFILL_NEWS_COOLDOWN or ANTITOXICFILL_SWEEP_CANCEL_STORM. If single signal or adverse RiskVote: apply downsize_factor and requote_widen_bps, emit RESHAPE. If no signals: approve and pass ExecutionPlan through unchanged.
10. On RESHAPE: compute widenedPrice (tick-aligned, using buildOrderTypedData metadata), apply downsize_factor to size, construct updated ExecutionPlan, forward to signing.
11. Emit ExecutionReport to polytraders.reports.execution (partition by trace_id, WAL-then-retry, retention 7y) with verdict, reason_code, original and reshaped parameters, and all signal flags.

10. Reference Implementation

On each ExecutionPlan received from SmartRouter, AntiToxicFill evaluates three toxic-flow signals (sweep, cancel-storm, post-fill drift) and a news-event check, then either passes the plan unchanged, reshapes it (widen price, reduce size), or cancels it and enters a market-level cooldown. Emits ExecutionReport to polytraders.reports.execution.

Pseudocode is language-agnostic. FETCH = read input. EMIT = produce output. Translate to TS/Python/Go/Rust.

FUNCTION evaluatePlan(plan, observationReport, riskVotes):
  // --- 0. KillSwitch gate ---
  ks = FETCH internal.killswitch.status
  IF ks.active:
    EMIT ExecutionReport(plan, HARD_REJECT, KILL_SWITCH_ACTIVE)
    RETURN

  // --- 1. Cooldown check ---
  cooldownKey = 'cooldown:' + plan.market_id
  IF FETCH redis.GET(cooldownKey) IS NOT NULL:
    EMIT ExecutionReport(plan, HOLD, ANTITOXICFILL_COOLDOWN_ACTIVE)
    RETURN  // Re-evaluate after TTL

  // --- 2. Fetch market book + trade tape ---
  book = FETCH clob_public.GET('/book?market=' + plan.market_id + '&depth=10')
  tape = FETCH ws_market.recent_fills(plan.market_id, last_n=100)
  IF book IS NULL OR tape IS NULL:
    // Safe fallback: apply conservative defaults
    widenBps = params.requote_widen_bps * 2  // 40 bps default fallback
    finalSize = plan.size_usd * params.downsize_factor
    EMIT ExecutionReport(plan, RESHAPE, ANTITOXICFILL_FEED_UNAVAILABLE,
                         reshaped_price=widenPrice(plan, widenBps),
                         reshaped_size=finalSize)
    RETURN

  // --- 3. Evaluate sweep signal ---
  // Count levels consumed on plan.side in last 5 seconds
  recentTrades = [t FOR t IN tape IF now_ms() - t.ts_ms <= 5000
                  AND t.aggressor_side == plan.side]
  levelsConsumed = COUNT DISTINCT price levels in recentTrades
  sweepDetected = (levelsConsumed > 3)

  // --- 4. Evaluate cancel-storm signal ---
  // Count cancels on opposite side in last 5 seconds
  oppSide = 'SELL' IF plan.side == 'BUY' ELSE 'BUY'
  recentCancels = FETCH ws_market.recent_cancels(plan.market_id, side=oppSide, window_ms=5000)
  cancelStormDetected = (COUNT(recentCancels) > 10)

  // --- 5. Evaluate post-fill drift ---
  driftBps = computeRollingDrift(tape, window_s=params.drift_window_s)  // mean bps drift post-fill
  driftDetected = (driftBps > params.drift_threshold_bps)  // default: 30 bps

  // --- 6. Check news feed ---
  newsEvents = FETCH internal.newsingest.recent(plan.market_id)
  newsHit = ANY(abs(e.ts_ms - plan.planned_fill_ms) <= params.news_window_s * 1000
                FOR e IN newsEvents)

  // --- 7. Check adverse RiskVote ---
  adverseVote = ANY(v.verdict == 'RESHAPE' AND 'toxicity' IN v.tags FOR v IN riskVotes)

  // --- 8. Determine action ---
  IF newsHit OR (sweepDetected AND cancelStormDetected):
    // Hard cancel + cooldown
    reason = ANTITOXICFILL_NEWS_COOLDOWN IF newsHit ELSE ANTITOXICFILL_SWEEP_CANCEL_STORM
    redis.SET(cooldownKey, 1, EX=params.cooldown_s)
    EMIT ExecutionReport(plan, HARD_REJECT, reason)
    RETURN

  IF sweepDetected OR cancelStormDetected OR driftDetected OR adverseVote:
    // Reshape: widen price + downsize
    signalStrength = COUNT([sweepDetected, cancelStormDetected, driftDetected, adverseVote])
    widenBps = params.requote_widen_bps IF signalStrength == 1 ELSE params.requote_widen_bps_warning
    newPrice = widenPrice(plan, widenBps)          // BUY: lower; SELL: raise
    newPrice = tickAlign(newPrice, book.tick_size)  // snap to valid tick
    newSize = max(plan.size_usd * params.downsize_factor,
                  plan.size_usd * 0.1)             // clamp to hard floor
    reshapedPlan = plan WITH price=newPrice, size_usd=newSize
    EMIT ExecutionReport(reshapedPlan, RESHAPE, ANTITOXICFILL_RESHAPE,
                         widen_bps_applied=widenBps,
                         downsize_factor_applied=params.downsize_factor)
    FORWARD reshapedPlan TO signing
    RETURN

  // --- 9. Pass through ---
  EMIT ExecutionReport(plan, PASS, ANTITOXICFILL_PASS)
  FORWARD plan TO signing

Helpers used

SDK calls used

• clob_public.GET('/book?market=' + plan.market_id + '&depth=10')
• ws_market.subscribe('last_trade_price', plan.market_id)
• ws_market.subscribe('book', plan.market_id)
• redis.GET('cooldown:' + plan.market_id)
• redis.SET('cooldown:' + plan.market_id, 1, EX=cooldown_s)

Complexity: O(1) per ExecutionPlan evaluation; O(F) for rolling drift scan where F = recent fill count (capped at 100)

11. Wire Examples

Input — what arrives on the wire

ExecutionPlan + ObservationReport with sweep signal — exec.smart_router + internal bus

{
  "intent_id": "int_3c4d5e6f7a8b9c0d",
  "trace_id": "trc_9f8e7d6c5b4a3f2e",
  "market_id": "0x3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c3d4e",
  "side": "BUY",
  "outcome": "YES",
  "price": 0.62,
  "size_usd": 400,
  "order_type": "GTC",
  "planned_fill_ms": 1746769800000,
  "observation_report": {
    "sweep_detected": true,
    "sweep_levels_consumed": 4,
    "cancel_storm_detected": false,
    "cancel_count_5s": 3,
    "drift_bps": 8,
    "news_hit": false
  },
  "risk_votes": [
    {
      "bot_id": "risk.portfolio_guard",
      "verdict": "PASS"
    }
  ]
}

Output — what the bot emits

ExecutionReport — RESHAPE (sweep detected, price widened, size halved)

{
  "report_id": "rep_a1b2c3d4e5f6a7b8",
  "trace_id": "trc_9f8e7d6c5b4a3f2e",
  "bot_id": "exec.antitoxicfill",
  "market_id": "0x3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c3d4e",
  "side": "BUY",
  "outcome": "YES",
  "verdict": "RESHAPE",
  "reason_code": "ANTITOXICFILL_RESHAPE",
  "original_price": 0.62,
  "reshaped_price": 0.61,
  "original_size_usd": 400,
  "reshaped_size_usd": 200,
  "widen_bps_applied": 20,
  "downsize_factor_applied": 0.5,
  "collateral": "pUSD",
  "eip712_domain_version": "2",
  "signals": {
    "sweep_detected": true,
    "cancel_storm_detected": false,
    "drift_detected": false,
    "news_hit": false,
    "drift_bps": 8
  },
  "evaluated_at_ms": 1746769800000
}

ExecutionReport — HARD_REJECT (news hit + cooldown applied)

{
  "report_id": "rep_b2c3d4e5f6a7b8c9",
  "trace_id": "trc_1a2b3c4d5e6f7a8b",
  "bot_id": "exec.antitoxicfill",
  "market_id": "0x3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c3d4e",
  "side": "SELL",
  "outcome": "NO",
  "verdict": "HARD_REJECT",
  "reason_code": "ANTITOXICFILL_NEWS_COOLDOWN",
  "original_price": 0.41,
  "reshaped_price": null,
  "original_size_usd": 300,
  "reshaped_size_usd": null,
  "collateral": "pUSD",
  "cooldown_s_applied": 30,
  "signals": {
    "sweep_detected": false,
    "cancel_storm_detected": false,
    "drift_detected": false,
    "news_hit": true,
    "news_event_delta_ms": -18000
  },
  "evaluated_at_ms": 1746769850000
}

12. Decision Logic

13. Standard Decision Output

This bot returns a ExecutionReport object. See ExecutionReport schema.

{
  "report_id": "rep_a1b2c3d4e5f6a7b8",
  "trace_id": "trc_9f8e7d6c5b4a3f2e",
  "bot_id": "exec.antitoxicfill",
  "market_id": "0x3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c3d4e",
  "side": "BUY",
  "outcome": "YES",
  "verdict": "RESHAPE",
  "reason_code": "ANTITOXICFILL_RESHAPE",
  "original_price": 0.62,
  "reshaped_price": 0.608,
  "original_size_usd": 400,
  "reshaped_size_usd": 200,
  "widen_bps_applied": 20,
  "downsize_factor_applied": 0.5,
  "signals": {
    "sweep_detected": true,
    "cancel_storm_detected": false,
    "drift_detected": false,
    "news_hit": false,
    "drift_bps": 8
  },
  "collateral": "pUSD",
  "eip712_domain_version": "2",
  "evaluated_at_ms": 1746769800000
}

14. Reason Codes

15. Metrics & Logs

Metrics emitted

Alerts

Dashboards

• Grafana — Execution / AntiToxicFill
• Grafana — Order quality / toxic-flow signals and cooldown history

16. Developer Reporting

{
  "report_id": "rep_a1b2c3d4e5f6a7b8",
  "trace_id": "trc_9f8e7d6c5b4a3f2e",
  "bot_id": "exec.antitoxicfill",
  "market_id": "0x3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c3d4e",
  "sweep_levels_consumed": 4,
  "sweep_detected": true,
  "cancel_storm_count_5s": 3,
  "cancel_storm_detected": false,
  "drift_bps": 8,
  "drift_detected": false,
  "news_hit": false,
  "adverse_risk_vote": false,
  "cooldown_active": false,
  "verdict": "RESHAPE",
  "reason_code": "ANTITOXICFILL_RESHAPE",
  "original_price": 0.62,
  "reshaped_price": 0.608,
  "original_size_usd": 400,
  "reshaped_size_usd": 200,
  "requote_widen_bps": 20,
  "downsize_factor": 0.5,
  "tick_size": 0.01,
  "tick_aligned_reshaped_price": 0.61,
  "evaluated_at_ms": 1746769800000
}

17. Plain-English Reporting

18. Failure-Mode Block

19. Failure-Injection Recipes

20. State & Persistence

Cold-start recovery

On restart, cooldown entries are re-read from Redis. Any market with an active cooldown key continues in cooldown. Drift cache is rebuilt from ws_market fill replay on reconnect; first evaluation after restart may use conservative fallback if cache is empty.

21. Concurrency & Idempotency

22. Dependencies

Depends on (must run first)

Emits to (downstream consumers)

Sibling bots (same OrderIntent)

External services

23. Security Surfaces

Abuse vectors considered

• Injecting a fabricated ObservationReport with sweep_detected=false to suppress reshaping and allow toxic-fill through at full size
• Flooding the cooldown Redis key with artificial expiry updates to prevent cooldown from being applied
• Replay of stale ObservationReport to trigger a false cooldown on a non-toxic market, causing missed trading opportunities

Mitigations

• ObservationReport messages are HMAC-signed by the emitting bot; AntiToxicFill validates the signature before processing
• Redis cooldown keys use SETNX with TTL; they cannot be extended by external writers without Redis ACL access
• ObservationReport freshness check: reports older than 10 seconds are discarded with STALE_DATA reason code
• ws_market trade tape is fetched directly from Polymarket WebSocket — not from an internal cache that could be tampered with

24. Polymarket V2 Compatibility

API surfaces declared

Networks supported

25. Versioning & Migration

Migration history

26. Acceptance Tests

Unit Tests

Integration Tests

Property Tests

27. Operational Runbook

AntiToxicFill incidents fall into two categories: sustained cooldowns causing trading pauses on multiple markets simultaneously (possible false-positive storm or genuine market crisis), and feed unavailability causing conservative fallback reshaping that may be overly restrictive.

On-call actions

Manual overrides

• —
• —

Healthcheck

GET /internal/health/antitoxicfill → 200 if ws_market feed connected and last message < 5s ago, Redis cooldown store reachable, NewsIngest feed responding, eval latency p99 < 150ms, cooldowns_active <= 3. RED if ws_market feed disconnected or stale > 10s, Redis unreachable, eval latency p99 > 300ms, or cooldowns_active > 10.

28. Promotion Gates

A bot does not advance to the next readiness state until every gate below is green. Gates are observable from production data — no subjective sign-off.

Promote to Shadow

Promote to Limited live

Promote to General live

29. Developer Checklist

Ready-to-ship score: 27/27 sections complete · 100%