3.12 Mean-Reversion Sniper

1. Bot Identity

2. Purpose

Mean-Reversion Sniper fades price momentum in markets that have overreacted to recent information. It monitors markets where the best-ask for YES tokens exceeds price_threshold (default 0.80), computes a rolling z-score of the price change over a lookback window, and checks for order-book signals of a momentum reversal (aggressor side flips and large cancels on the heavy side). When z_score >= z_score_min and no active news cycle is detected by the NewsIngest event-density feed, the bot emits an IOC OrderIntent to sell YES tokens at or above price_threshold. An automatic time exit (time_exit_s) and stop-loss (stop_bps) control downside risk. This is a user-controlled execution tool; it does not predict outcomes or make performance claims.

3. Why This Bot Matters

• Fading during an active news cycle

  If a material news event is causing the price to move permanently higher, fading it produces a directional loss rather than a mean-reversion gain. NewsIngest event-density gate must be respected.

• z-score computed on too short a lookback

  Short lookbacks produce noisy z-scores that trigger on normal intraday price variation, leading to repeated small losses from false fades.

• Stop-loss not configured or too wide

  Without a stop-loss, an overreaction that continues (e.g., genuine resolution signal) produces an uncapped loss on the short YES position.

• feeRateBps present on signed order (V1 pattern)

  CTFExchangeV2 rejects orders with feeRateBps. Fees are operator-set at match time. The signed order must not contain this field.

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

{ "price_threshold": 0.8 }

if price >= params.hard: return skip('MEAN_REVERSION_PRICE_TOO_HIGH')

{ "z_score_min": 2.5 }

if z_score < params.hard: return skip('MEAN_REVERSION_Z_TOO_LOW')

{ "stop_bps": 150 }

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

{ "time_exit_s": 120 }

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

8. Default Configuration

{
  "bot_id": "strat.mean_reversion_sniper",
  "version": "2.1.0",
  "mode": "limited_live",
  "defaults": {
    "price_threshold": 0.8,
    "z_score_min": 2.5,
    "stop_bps": 150,
    "time_exit_s": 120
  },
  "locked": {
    "price_threshold": {
      "max": 0.95
    },
    "z_score_min": {
      "min": 1.0
    },
    "stop_bps": {
      "max": 400
    },
    "time_exit_s": {
      "max": 300
    }
  }
}

9. Implementation Flow

1. Check KillSwitch active flag; if active, emit no OrderIntents; close any open fade positions.
2. Subscribe to ws_market book and trade-tape streams for markets with best_ask_YES >= price_threshold.
3. On each price tick: compute rolling z-score of price change over lookback window (default 20 ticks).
4. Gate 1 — Price threshold: if best_ask_YES >= 0.95 (hard): skip MEAN_REVERSION_PRICE_TOO_HIGH.
5. Gate 2 — NewsIngest: if active news cycle on market entity: skip MEAN_REVERSION_NEWS_ACTIVE.
6. Gate 3 — Z-score: if z_score < 1.0 (hard): skip MEAN_REVERSION_Z_TOO_LOW (sampled 1/100).
7. Gate 4 — Reversal signal: check aggressor side flip (taker-sell ratio rising) and large cancels on bid side.
8. If z_score < 2.5 (warning): WARN MEAN_REVERSION_Z_MARGINAL; reduce size to 50% of max_position_usd.
9. Fetch top-of-book YES ask depth; set orderSize = min(depth, max_position_usd) * sizeMultiplier.
10. Emit OrderIntent: outcome=YES, side=sell, price=best_ask_YES, size_pUSD=orderSize, tif=IOC, builder={code, fee_bps:25}.
11. Note: fees are operator-set at match time in V2 — feeRateBps is NOT on the signed order.
12. Register position in state: entry_price, entry_time_ms, stop_price=entry_price+stop_bps/10000, exit_deadline_ms=now_ms()+time_exit_s*1000.
13. Monitor position: if price rises above stop_price → emit buy IOC to close; if time > exit_deadline → emit buy IOC to close.
14. Emit DecisionReport with intent_emitted=true, z_score, price_at_entry, reason MEAN_REVERSION_FADE_INITIATED.

10. Reference Implementation

Monitors markets for statistically unusual price spikes above price_threshold, checks NewsIngest event-density gate, and emits IOC sell OrderIntents when z_score >= z_score_min with reversal signals present. Manages open positions with stop-loss and time exit.

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

FUNCTION onPriceTick(market_id, priceTick):
  // --- 0. KillSwitch gate ---
  ks = FETCH internal.killswitch.status
  IF ks.active: CLOSE_OPEN_POSITIONS(); RETURN

  // --- 1. Manage open positions (stop-loss + time exit) ---
  pos = FETCH state.openPosition(market_id)
  IF pos:
    IF priceTick.best_ask >= pos.stop_price:
      EMIT OrderIntent(side='buy', tif='IOC', size=pos.size, reason='MEAN_REVERSION_STOP_LOSS')
      CLEAR state.openPosition(market_id)
      RETURN
    IF now_ms() >= pos.exit_deadline_ms:
      EMIT OrderIntent(side='buy', tif='IOC', size=pos.size, reason='MEAN_REVERSION_TIME_EXIT')
      CLEAR state.openPosition(market_id)
      RETURN

  // --- 2. Price threshold gate ---
  price = priceTick.best_ask
  IF price >= params.price_threshold_hard:  // 0.95
    EMIT DecisionReport(intent_emitted=false, reason='MEAN_REVERSION_PRICE_TOO_HIGH')
    RETURN
  IF price < params.price_threshold:  // 0.80
    RETURN  // not in fade zone

  // --- 3. NewsIngest gate ---
  newsState = FETCH internal.newsingest.eventDensity(market_id)
  IF newsState.active OR newsState.unavailable:  // fail-closed
    EMIT DecisionReport(intent_emitted=false, reason='MEAN_REVERSION_NEWS_ACTIVE')
    RETURN

  // --- 4. Z-score computation ---
  tape = FETCH ws_market.tradeTape(market_id, lookback_ticks=20)
  zScore = zScoreOfPriceChange(tape)
  IF zScore < params.z_score_min_hard:  // 1.0
    IF random() < 0.01:
      EMIT DecisionReport(intent_emitted=false, reason='MEAN_REVERSION_Z_TOO_LOW', z_score=zScore)
    RETURN

  // --- 5. Reversal signal check ---
  IF NOT reversalSignalPresent(tape):  // aggressor flip + large cancel on bid
    RETURN

  // --- 6. Size determination ---
  sizeMultiplier = 0.5 IF zScore < params.z_score_min ELSE 1.0  // 2.5 warning
  IF sizeMultiplier < 1.0: WARN('MEAN_REVERSION_Z_MARGINAL')
  depth = FETCH clob_public.depth(market_id, side='YES')
  orderSize = toPusdUnits(min(depth, params.max_position_usd) * sizeMultiplier)

  // --- 7. Emit fade OrderIntent (sell YES, IOC, V2: no feeRateBps) ---
  EMIT OrderIntent(
    market_id = market_id, outcome = 'YES', side = 'sell',
    price = price, size_pUSD = orderSize, tif = 'IOC', post_only = false,
    builder = {code: internal.builder_code, fee_bps: 25}
  )

  // --- 8. Register position for stop/time-exit monitoring ---
  SET state.openPosition(market_id, {
    entry_price: price, size: orderSize,
    stop_price: price + params.stop_bps / 10000,
    exit_deadline_ms: now_ms() + params.time_exit_s * 1000
  })

  EMIT DecisionReport(intent_emitted=true, z_score=zScore,
                      price_at_entry=price, reason='MEAN_REVERSION_FADE_INITIATED')

SDK calls used

• ws_market.subscribe('book', [market_id])
• ws_market.subscribe('trade_tape', [market_id])
• fetchClobPublic('/markets/' + market_id + '/orderbook')
• internal.newsingest.eventDensity(market_id)
• internal.killswitch.status()
• toPusdUnits(rawFloat)
• buildOrderTypedData(orderParams, { name: 'CTFExchange', version: '2', chainId: 137 })
• internal.builder_code

Complexity: O(1) per price tick; O(lookback_ticks) for z-score computation

11. Wire Examples

Input — what arrives on the wire

Price tick — YES spike to 0.847, z_score=3.1, no news cycle — ws_market

{
  "market_id": "0xmrsniper00000000000000000000000000000000000000000000000000000001",
  "best_ask_YES": "0.847",
  "z_score_20tick": "3.1",
  "taker_sell_ratio_5s": "0.65",
  "news_active": false,
  "depth_YES_pusd": "410.00",
  "received_at_ms": 1746790200000
}

Output — what the bot emits

OrderIntent — fade sell YES (IOC, builder-attributed)

{
  "intent_id": "oi_01HXMRS0000001A",
  "trace_id": "tr_01HXMRS000TR001",
  "market_id": "0xmrsniper00000000000000000000000000000000000000000000000000000001",
  "outcome": "YES",
  "side": "sell",
  "price": "0.847",
  "size_pUSD": "300.00",
  "tif": "IOC",
  "post_only": false,
  "builder": {
    "code": "0x706f6c7974726164657273000000000000000000000000000000000000000000",
    "fee_bps": 25
  },
  "negrisk_aware": false,
  "decision": {
    "z_score": 3.1,
    "price_at_entry": 0.847,
    "stop_price": 0.862,
    "exit_deadline_ms": 1746790320000,
    "reasons": [
      "MEAN_REVERSION_FADE_INITIATED"
    ]
  },
  "comment": "fees are operator-set at match time in V2 — feeRateBps is NOT on the signed order"
}

DecisionReport — skipped (news cycle active)

{
  "report_id": "dr_01HXMRS999ZZZZ",
  "bot_id": "strat.mean_reversion_sniper",
  "market_id": "0xmrsniper00000000000000000000000000000000000000000000000000000001",
  "intent_emitted": false,
  "z_score": 2.8,
  "reasons": [
    "MEAN_REVERSION_NEWS_ACTIVE"
  ],
  "sampled": false,
  "evaluated_at_ms": 1746790201000
}

12. Decision Logic

13. Standard Decision Output

This bot returns a OrderIntent object. See OrderIntent schema.

{
  "intent_id": "oi_01HXMRS0000001A",
  "trace_id": "tr_01HXMRS000TR001",
  "market_id": "0xmrsniper00000000000000000000000000000000000000000000000000000001",
  "outcome": "YES",
  "side": "sell",
  "price": "0.847",
  "size_pUSD": "300.00",
  "tif": "IOC",
  "post_only": false,
  "builder": {
    "code": "0x706f6c7974726164657273000000000000000000000000000000000000000000",
    "fee_bps": 25
  },
  "negrisk_aware": false,
  "decision": {
    "z_score": 3.1,
    "price_at_entry": 0.847,
    "stop_price": 0.862,
    "exit_deadline_ms": 1746790320000,
    "reasons": [
      "MEAN_REVERSION_FADE_INITIATED"
    ]
  },
  "comment": "fees are operator-set at match time in V2 \u2014 feeRateBps is NOT on the signed order"
}

14. Reason Codes

15. Metrics & Logs

Metrics emitted

Alerts

Dashboards

• Grafana — Strategy / MeanReversionSniper z-score distribution and fade frequency
• Grafana — Strategy / MeanReversionSniper position hold times and exit reasons

16. Developer Reporting

{
  "bot_id": "strat.mean_reversion_sniper",
  "market_id": "0xmrsniper00000000000000000000000000000000000000000000000000000001",
  "price_at_entry": 0.847,
  "z_score": 3.1,
  "price_threshold": 0.8,
  "news_gate_passed": true,
  "reversal_signal": true,
  "order_size_pusd": 300.0,
  "stop_price": 0.862,
  "exit_deadline_ms": 1746790320000,
  "intent_emitted": true,
  "reason": "MEAN_REVERSION_FADE_INITIATED",
  "emitted_at_ms": 1746790200000
}

17. Plain-English Reporting

18. Failure-Mode Block

19. Failure-Injection Recipes

20. State & Persistence

Cold-start recovery

On cold start, open positions are re-read from clob_auth. z-score cache is rebuilt from first ws_market tape ticks.

21. Concurrency & Idempotency

22. Dependencies

Depends on (must run first)

Emits to (downstream consumers)

External services

23. Security Surfaces

On-chain contract calls

Abuse vectors considered

• Adversary manufactures a price spike to trigger the fade, then reverses to profit from the short position
• Delayed NewsIngest feed allows fading during a genuine news event
• Open fade position exploited if stop-loss level is known

Mitigations

• z_score threshold filters out manufactured spikes lacking sustained momentum
• NewsIngest unavailability treated as active-news (fail-closed); no fade without confirmed clear news gate
• Stop-loss level computed from entry price + stop_bps; not exposed externally
• V2 order timestamp(ms) invalidates replayed signed orders
• IOC orders do not rest on the book; not visible to adversaries post-emission

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

Mean-Reversion Sniper incidents are typically high stop-loss rates (genuine resolution signals being faded), NewsIngest feed outages (causing no-fade lockout), or stale ws_market feeds. High stop-loss rates require immediate review of market conditions.

On-call actions

Manual overrides

• —
• —

Healthcheck

GET /internal/health/mean-reversion-sniper -> 200 if ws_market feed last_seen < 5s, NewsIngest feed live, KillSwitch inactive, Redis reachable.

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%