4.13 LiquidityForecastModel

1. Bot Identity

2. Purpose

Predict near-term book depth and trade pacing per market for sizing decisions.

3. Why This Bot Matters

• Strategies size on stale liquidity

  Sizing decisions made from current top-of-book ignore that depth can collapse seconds before fill. A forecast — even a coarse one — gives strategies a concrete number to clamp size against before submitting an OrderIntent.

• Execution router under-quotes its own fill probability

  Without forward-looking depth, smartrouter can only react to the book it sees. With a forecast, it can prefer a passive ladder that is expected to refill, instead of crossing into thin liquidity that disappears mid-fill.

• Risk caps lag the actual market

  Static per-market notional caps assume yesterday's depth. A liquidity forecast lets Risk widen or tighten caps in line with predicted near-term depth, reducing both missed opportunities in deep books and oversize entries in thin ones.

• Operators have no leading indicator before a liquidity collapse

  When depth dries up before a known event (a debate, a game start), having no model means the team only sees the collapse on the chart after it happens. A forecast emits a warning the operator can act on.

4. Required Polymarket Inputs

5. Required Internal Inputs

6. Parameter Guide

7. Detailed Parameter Instructions

{ "forecast_horizon_s": 3600 }

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

{ "min_liquidity_pusd": 1000 }

if (forecast_pusd < p.min_liquidity_pusd.hard) emit('LIQUIDITYFORECAST_LOW_FORECAST');

8. Default Configuration

{
  "bot_id": "intel.liquidityforecastmodel",
  "version": "0.1.0",
  "mode": "planned",
  "defaults": {
    "forecast_horizon_s": 3600,
    "min_liquidity_pusd": 1000
  },
  "locked": {
    "forecast_horizon_s": {
      "max": 86400
    },
    "min_liquidity_pusd": {
      "min": 100
    }
  }
}

9. Implementation Flow

— not yet authored —

10. Reference Implementation

Pseudocode is language-agnostic. FETCH = read input. EMIT = produce output. IF/THEN/ELSE = decision. Translate directly to TypeScript, Python, Go, or Rust.

FUNCTION forecastLiquidity(condition_id, horizon_s):
  // 0. KillSwitch check
  IF FETCH internal.killswitch.status == ACTIVE:
    RETURN

  // 1. Fetch order book snapshot
  book = FETCH clob_public.GET('/book?token_id=' + condition_id)
  IF book IS NULL:
    EMIT WARN 'STALE_DATA'
    RETURN

  // 2. Compute current depth
  bid_depth_pusd = sum(l.size * l.price for l in book.bids)
  ask_depth_pusd = sum(l.size for l in book.asks)

  // 3. Fetch historical fill rate from Data API
  fill_rate = FETCH data.GET('/fills?condition_id=' + condition_id + '&window=3600')

  // 4. Forecast using exponential decay model
  forecast_pusd = forecastDepth(bid_depth_pusd, ask_depth_pusd, fill_rate, horizon_s)

  // 5. Check against min_liquidity_pusd threshold
  IF forecast_pusd < min_liquidity_pusd:
    EMIT WARN 'LIQUIDITYFORECAST_LOW_FORECAST'

  // 6. Emit ObservationReport
  EMIT ObservationReport {
    report_id: gen_id(),
    kind: 'ObservationReport',
    condition_id: condition_id,
    current_bid_depth_pusd: bid_depth_pusd,
    current_ask_depth_pusd: ask_depth_pusd,
    forecast_pusd: forecast_pusd,
    horizon_s: horizon_s,
    emitted_at_ms: now_ms()
  }

SDK calls used

• clob_public.GET('/book?token_id=<condition_id>')
• data.GET('/fills?condition_id=<condition_id>&window=3600')
• internal.killswitch.status

Complexity: O(B) per condition_id where B = order book depth levels

11. Wire Examples

Input — what arrives on the wire

{
  "label": "CLOB V2 order book snapshot for liquidity forecast",
  "source": "clob_public",
  "payload": {
    "condition_id": "0xf1a2b30000000000000000000000000000000000000000000000000000000000",
    "bids": [
      {
        "price": "0.67",
        "size": "5000"
      },
      {
        "price": "0.66",
        "size": "3000"
      }
    ],
    "asks": [
      {
        "price": "0.69",
        "size": "4500"
      },
      {
        "price": "0.70",
        "size": "2000"
      }
    ],
    "timestamp_ms": 1746703000000
  }
}

Output — what the bot emits

{
  "label": "ObservationReport — liquidity forecast",
  "payload": {
    "report_id": "rep_lfm_0xf1a2_1746703000000",
    "trace_id": "trc_0xbeef0102030405060714",
    "bot_id": "intel.liquidityforecastmodel",
    "kind": "ObservationReport",
    "condition_id": "0xf1a2b30000000000000000000000000000000000000000000000000000000000",
    "current_bid_depth_pusd": 5350,
    "current_ask_depth_pusd": 6500,
    "forecast_pusd": 4800,
    "horizon_s": 3600,
    "emitted_at_ms": 1746703005000
  }
}

12. Decision Logic

13. Standard Decision Output

This bot returns a RiskVote object. See RiskVote schema.

{
  "report_id": "rep_lfm_0xf1a2_1746703000000",
  "trace_id": "trc_0xbeef0102030405060714",
  "bot_id": "intel.liquidityforecastmodel",
  "kind": "ObservationReport",
  "condition_id": "0xf1a2b30000000000000000000000000000000000000000000000000000000000",
  "current_bid_depth_pusd": 5350,
  "current_ask_depth_pusd": 6500,
  "forecast_pusd": 4800,
  "horizon_s": 3600,
  "low_forecast": false,
  "emitted_at_ms": 1746703005000
}

14. Reason Codes

15. Metrics & Logs

Metrics emitted

Alerts

Dashboards

• Grafana — Intelligence / LiquidityForecastModel forecast_pusd per market

16. Developer Reporting

{
  "bot_id": "intel.liquidityforecastmodel",
  "condition_id": "0xf1a2b30000000000000000000000000000000000000000000000000000000000",
  "current_bid_depth_pusd": 5350,
  "current_ask_depth_pusd": 6500,
  "forecast_pusd": 4800,
  "fill_rate": 0.72,
  "low_forecast": false,
  "killswitch_active": false
}

17. Plain-English Reporting

18. Failure-Mode Block

19. Failure-Injection Recipes

20. State & Persistence

Cold-start recovery

On cold start, re-compute on first poll cycle; no historical backfill required.

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

• Adversary places large spoofed orders to inflate apparent order book depth and mislead forecast
• Rapid order cancellations during forecast window cause overestimate of available liquidity

Mitigations

• Forecast uses fill_rate weighting to discount unfilled book depth that never converts to trades
• Forecasts are informational only — LiquidityGuard applies independent depth checks at execution time

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

LiquidityForecastModel incidents are typically CLOB API outages. Low forecasts are signals, not errors. Extended outages will leave strategies without forward liquidity data.

On-call actions

Manual overrides

• force_recompute — POST /internal/liquidityforecastmodel/recompute?condition_id=<id> to trigger immediate recompute — After CLOB API recovery or suspected stale forecast

Healthcheck

Endpoint: /internal/health/liquidityforecastmodel | Green: Last forecast < 5 min ago AND Redis reachable AND CLOB API returning 200 | Red: No forecast for > 15 min OR Redis unreachable

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%