4.3 OrderFlowAnalyzer

1. Bot Identity

2. Purpose

OrderFlowAnalyzer subscribes to ws_market for real-time trade prints and clob_public for order-book snapshots, then classifies each flow event as toxic (informed, likely to precede adverse price movement), benign (noise/retail), or informed (structural, correlated with neg-risk rebalancing). It emits an ObservationReport for every toxic flip and samples 1/10 routine ticks. Output feeds liquidity-aware strategies and the LiquidityGuard risk bot. OrderFlowAnalyzer is strictly read-only — it never submits or signs orders.

3. Why This Bot Matters

• Toxic flow not detected before entry

  Strategy enters a market being targeted by informed traders; adverse selection erodes edge within seconds of fill.

• Order-book imbalance not propagated to LiquidityGuard

  LiquidityGuard uses stale depth figures; permits entry at sizes that would incur >2× expected slippage.

• Informed neg-risk flow misclassified as benign

  Neg-risk rebalancing activity (bulk outcome swaps) treated as noise; strategy takes wrong side of a structural price shift.

• Microstructure features computed from stale snapshot

  Stale imbalance and micro-volatility signals produce incorrect flow classification, causing either over-trading or missed entries.

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

{ "imbalance_window_s": 30 }

if (p.imbalance_window_s < p.hard) throw ConfigError('PARAMETER_CHANGE_REQUIRES_APPROVAL');

{ "micro_vol_window_s": 60 }

if (p.micro_vol_window_s < p.hard) throw ConfigError('PARAMETER_CHANGE_REQUIRES_APPROVAL');

{ "publish_rate_hz": 1 }

if (p.publish_rate_hz > p.hard) throw ConfigError('PARAMETER_CHANGE_REQUIRES_APPROVAL');

{ "queue_position_method": "pro_rata" }

// not yet authored

8. Default Configuration

{
  "bot_id": "intel.orderflowanalyzer",
  "version": "2.1.0",
  "mode": "general_live",
  "defaults": {
    "imbalance_window_s": 30,
    "micro_vol_window_s": 60,
    "publish_rate_hz": 1,
    "queue_position_method": "pro_rata"
  },
  "locked": {
    "imbalance_window_s": {
      "min": 5
    },
    "micro_vol_window_s": {
      "min": 10
    },
    "publish_rate_hz": {
      "max": 10
    }
  }
}

9. Implementation Flow

1. Subscribe to ws_market for trade prints (taker_side, size_pusd, price, timestamp_ms) for all tracked markets.
2. Subscribe to clob_public for order-book snapshots (top-50 bid/ask levels) per market at publish_rate_hz.
3. On each trade print: append to rolling imbalance buffer (imbalance_window_s). Compute bid_ask_imbalance = (bid_depth - ask_depth) / total_depth.
4. Compute micro_vol: std-dev of last N trade prices within micro_vol_window_s.
5. Classify flow_class: TOXIC if (taker_side==BUY AND imbalance < -0.3) OR (taker_side==SELL AND imbalance > 0.3) OR print_size_pusd > 2× avg_print_size; INFORMED if neg_risk_flag AND abs(imbalance) > 0.5; BENIGN otherwise.
6. Check KillSwitch; if active, continue computing but suppress emissions.
7. Apply sampling: if flow_class == TOXIC or last ObservationReport for this market > 1/publish_rate_hz s ago → emit-every. Otherwise sample-1/10.
8. Emit ObservationReport with: report_id, trace_id, condition_id, flow_class, bid_ask_imbalance, micro_vol, print_size_pusd, taker_side, book_depth_pusd, neg_risk_flag, warnings.
9. Log per-market cycle: flow_class distribution, imbalance, micro_vol, prints_received, emitted.

10. Reference Implementation

Subscribes to ws_market for trade prints and clob_public for book snapshots, computes rolling imbalance and micro-volatility features, classifies each flow event as TOXIC/BENIGN/INFORMED, and emits ObservationReports with per-market sampling (emit-every for TOXIC flips, sample-1/10 for routine ticks).

Pseudocode is language-agnostic. FETCH = read input. EMIT = produce output.

// --- Initialisation ---
FOR market IN tracked_markets:
  ws_market.subscribe(market.condition_id, handler=onTradePrint)
  imbalance_buffer[market.condition_id] = RollingWindow(imbalance_window_s)
  microvol_buffer[market.condition_id]  = RollingWindow(micro_vol_window_s)

FUNCTION onTradePrint(event):
  cid = event.condition_id

  // --- 1. Staleness gate ---
  IF (now_ms() - event.timestamp_ms) > imbalance_window_s * 1000:
    LOG WARN 'STALE_DATA — skipping stale print'
    RETURN

  // --- 2. Update rolling windows ---
  imbalance_buffer[cid].add(event)
  microvol_buffer[cid].add(event.price)

  // --- 3. Fetch book snapshot ---
  book = fetchClobPublic('/book?market=' + cid + '&depth=50')
  IF book IS NULL:
    flow_class = 'UNKNOWN'; warnings = ['STALE_DATA']
    GOTO emit_check

  bid_depth  = SUM(level.size * level.price FOR level IN book.bids[:50])
  ask_depth  = SUM(level.size * level.price FOR level IN book.asks[:50])
  total_depth = bid_depth + ask_depth
  imbalance   = (bid_depth - ask_depth) / total_depth IF total_depth > 0 ELSE 0

  micro_vol   = STDEV(microvol_buffer[cid].prices())

  // --- 4. Flow classification ---
  avg_print = imbalance_buffer[cid].avg_print_size_pusd()
  neg_risk  = internal.market_cache[cid].neg_risk OR false

  IF (event.taker_side == 'BUY'  AND imbalance < -0.3)   OR (event.taker_side == 'SELL' AND imbalance >  0.3)   OR event.size_pusd > 2 * avg_print:
    flow_class = 'TOXIC'
  ELSE IF neg_risk AND ABS(imbalance) > 0.5:
    flow_class = 'INFORMED'
  ELSE:
    flow_class = 'BENIGN'

  // --- 5. Warnings ---
  warnings = []
  IF total_depth < 2 * liquidity_guard.min_depth_pusd:
    warnings.append('ORDERFLOW_THIN_BOOK')

  :emit_check
  // --- 6. KillSwitch ---
  ks = FETCH internal.killswitch.status
  IF ks.active:
    LOG INFO 'KILL_SWITCH_ACTIVE — suppressing ObservationReport'
    RETURN

  // --- 7. Rate-limit + sampling ---
  IF flow_class == 'TOXIC' OR time_since_last_emit[cid] >= 1/params.publish_rate_hz:
    sampling_applied = false
  ELSE:
    IF random() > 0.1: RETURN     // sample-1/10
    sampling_applied = true

  // --- 8. Emit ---
  report = ObservationReport(
    report_id         = 'rep_ofa_' + cid[:6] + '_' + now_ms(),
    trace_id          = newTraceId(),
    bot_id            = 'intel.orderflowanalyzer',
    kind              = 'ObservationReport',
    condition_id      = cid,
    flow_class        = flow_class,
    bid_ask_imbalance = imbalance,
    micro_vol         = micro_vol,
    print_size_pusd   = event.size_pusd,
    taker_side        = event.taker_side,
    book_depth_pusd   = total_depth,
    neg_risk_flag     = neg_risk,
    sampling_applied  = sampling_applied,
    warnings          = warnings,
    emitted_at_ms     = now_ms()
  )
  EMIT internal.bus.observations <- report
  time_since_last_emit[cid] = now_ms()

SDK calls used

• ws_market.subscribe(condition_id, handler)
• fetchClobPublic('/book?market=<condition_id>&depth=50')

Complexity: O(1) per trade print; O(N) per book snapshot where N = book levels (≤50)

11. Wire Examples

Input — what arrives on the wire

{
  "label": "ws_market trade print",
  "source": "ws_market",
  "payload": {
    "event_type": "trade",
    "condition_id": "0xbcd2340000000000000000000000000000000000000000000000000000000000",
    "taker_side": "BUY",
    "size_pusd": 4200,
    "price": 0.72,
    "timestamp_ms": 1746701000000,
    "maker_order_id": "0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890ab"
  }
}

Output — what the bot emits

{
  "label": "ObservationReport — TOXIC flow detected",
  "payload": {
    "report_id": "rep_ofa_0xbcd2_1746701000000",
    "trace_id": "trc_0xcafe010203040506070809",
    "bot_id": "intel.orderflowanalyzer",
    "kind": "ObservationReport",
    "condition_id": "0xbcd2340000000000000000000000000000000000000000000000000000000000",
    "flow_class": "TOXIC",
    "bid_ask_imbalance": -0.41,
    "micro_vol": 0.018,
    "print_size_pusd": 4200,
    "taker_side": "BUY",
    "book_depth_pusd": 8900,
    "neg_risk_flag": true,
    "sampling_applied": false,
    "warnings": [
      "ORDERFLOW_THIN_BOOK"
    ],
    "emitted_at_ms": 1746701000085
  }
}

12. Decision Logic

13. Standard Decision Output

This bot returns a ObservationReport object. See ObservationReport schema.

{
  "report_id": "rep_ofa_0xbcd2_1746701000000",
  "trace_id": "trc_0xcafe010203040506",
  "bot_id": "intel.orderflowanalyzer",
  "kind": "ObservationReport",
  "condition_id": "0xbcd2340000000000000000000000000000000000000000000000000000000000",
  "flow_class": "TOXIC",
  "bid_ask_imbalance": -0.41,
  "micro_vol": 0.018,
  "print_size_pusd": 4200,
  "taker_side": "BUY",
  "book_depth_pusd": 8900,
  "neg_risk_flag": true,
  "sampling_applied": false,
  "warnings": [
    "ORDERFLOW_THIN_BOOK"
  ],
  "emitted_at_ms": 1746701000085
}

14. Reason Codes

15. Metrics & Logs

Metrics emitted

Alerts

Dashboards

• Grafana — Intelligence / OrderFlowAnalyzer flow classification distribution
• Grafana — Intelligence / per-market imbalance and micro-vol heatmap

16. Developer Reporting

{
  "bot_id": "intel.orderflowanalyzer",
  "cycle_ts_ms": 1746701000000,
  "markets_tracked": 47,
  "prints_received": 312,
  "toxic_flips": 3,
  "informed_events": 1,
  "benign_ticks": 308,
  "emitted": 14,
  "sampled_out": 298,
  "killswitch_active": false
}

17. Plain-English Reporting

18. Failure-Mode Block

19. Failure-Injection Recipes

20. State & Persistence

Cold-start recovery

On cold start, rolling windows are empty. First imbalance_window_s of operation produces no TOXIC classifications until buffers warm up. flow_class=UNKNOWN emitted during warm-up.

21. Concurrency & Idempotency

22. Dependencies

Depends on (must run first)

Emits to (downstream consumers)

Used by (auto-aggregated)

2.14 4.16 1.17 1.18

External services

23. Security Surfaces

Abuse vectors considered

• Adversary floods ws_market with wash-trade prints to trigger false TOXIC classifications, causing strategies to stand down
• Manipulated clob_public book snapshot (e.g. spoofed depth) causing incorrect imbalance computation

Mitigations

• Minimum print_size_pusd threshold prevents single 1-lot prints from triggering TOXIC classification
• Imbalance computed over rolling window — single snapshot manipulation insufficient to flip classification
• All ObservationReports are recommendations only — LiquidityGuard and strategies independently validate depth

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

OrderFlowAnalyzer incidents are usually ws_market disconnections or unusual toxic flow spikes. Disconnections affect all downstream liquidity-aware strategies; page immediately.

On-call actions

Manual overrides

• —

Healthcheck

GET /internal/health/orderflowanalyzer -> 200 if ws_market connected AND prints_received in last 10 s AND no STALE_DATA for any market. RED if ws_market disconnected > 30 s OR zero prints for > 60 s OR STALE_DATA on > 20% of tracked markets.

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%