4.16 LiquidityDecayMonitor

1. Bot Identity

Operational profile

2. Purpose

Tracks how quickly inside liquidity decays after our orders rest on the book. The output is a per-market liquidity-decay signal (in USD/second) that the smart router and order shaper consume to size and slice future orders. Pure observer — never blocks anything.

3. Why This Bot Matters

• Order shaping with no liquidity model

  Without a decay estimate, the order shaper either over-slices (paying spread many times) or under-slices (eating its own resting depth).

• Static liquidity assumptions

  Polymarket markets have wildly different microstructure across event types; a single config does not fit all of them.

• Hidden execution cost

  Decay is the dominant hidden cost on illiquid markets; making it observable is the first step to controlling it.

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

{ "window_seconds": 60 }

decay = (depth_t0 - depth_now) / window_seconds;

{ "min_observations": 30 }

if (samples >= p.min_observations) emit(decayUsdPerSecond, confidence);

8. Default Configuration

{
  "window_seconds": 60,
  "min_observations": 30
}

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.

for each book_tick:
  baseline = rolling_baseline(market_id, p.window_seconds)
  decay = max(0, baseline - book.top_depth_usd) / p.window_seconds
  if samples(market_id) >= p.min_observations:
    emit_signal('liquidity_decay', market_id, decay, confidence(samples))

11. Wire Examples

Input — what arrives on the wire

{
  "market_id": "0xabc",
  "ts_ms": 1715260000000,
  "top_depth_usd": 87.5
}

Output — what the bot emits

{
  "kind": "liquidity_decay",
  "market_id": "0xabc",
  "value": 12.4,
  "confidence": 0.62
}

12. Decision Logic

13. Standard Decision Output

This bot returns a RiskVote object. See RiskVote schema.

{
  "kind": "liquidity_decay",
  "market_id": "0xabc",
  "value": 12.4,
  "unit": "usd_per_second",
  "confidence": 0.62,
  "ts_ms": 1715260000000
}

14. Reason Codes

15. Metrics & Logs

Metrics emitted

Dashboards

• 4.16 overview dashboard

16. Developer Reporting

"Per emission: market_id, window_seconds, samples, baseline_depth_usd, current_depth_usd, decay_usd_per_second, confidence."

17. Plain-English Reporting

18. Failure-Mode Block

19. Failure-Injection Recipes

20. State & Persistence

Per-market rolling buffers (baseline depth + sample count). In-memory; reseeds on restart.

State stores

Cold-start recovery

Cold-start hydrates from fast KV; missing keys default to safe fallback.

On restart

All in-flight decisions are re-evaluated; no bot decision is trusted across restart without re-emit.

21. Concurrency & Idempotency

22. Dependencies

Depends on (must run first)

Requires (graph.requires)

intel.orderflowanalyzer exec.order_lifecycle_manager

23. Security Surfaces

Read-only on internal data-flow streams. Emits internal signals only.

Signing surface

Reads pending signed orders; never signs on user behalf.

Mitigations

• Rate-limit per source
• Audit-log every override
• Require role-based authz on admin paths

24. Polymarket V2 Compatibility

25. Versioning & Migration

26. Acceptance Tests

Unit Tests

Integration Tests

Property Tests

27. Operational Runbook

If consumers report wildly noisy slice sizes, raise window_seconds. If decay never publishes for a market, check sample count vs min_observations.

On-call actions

Manual overrides

• polytraders bot pause 4.16 — Disables the bot's enforcement layer; downstream consumers fall back to safe defaults.

Healthcheck

GET /healthz/liquidity_decay_monitor → 200 if last successful evaluation < 60s ago.

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%