1.4 LiquidityGuard

1. Bot Identity

Operational profile

2. Purpose

LiquidityGuard prevents strategies from placing orders that would consume too much of the visible order-book depth on a given market. It checks book depth, spread, and top-of-book freshness on every OrderIntent and either approves, downsizes, or rejects the order. It cannot change the market, the direction, or the strategy intent — only the size and the timing of execution.

3. Why This Bot Matters

• Thin-book consumption

  An oversized order eats through the visible top-of-book and walks the price several ticks against the user before fully filling, resulting in worse-than-expected execution.

• Stale book approved

  If depth data is not refreshed, the system may believe there is enough liquidity when the book has thinned out since the last snapshot, leading to surprise price impact.

• Excessive spread ignored

  Trading into a wide spread means crossing more slippage than the strategy priced in, which can turn a positive-expected-value order into a losing one.

• No size floor on top-of-book

  An order placed on a market with near-zero resting size can move the price dramatically even for small notional amounts.

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

{ "max_pct_of_visible_depth": 25 }

if (orderSizeUsd / visibleDepthUsd > p.hard) return reject('INSUFFICIENT_VISIBLE_DEPTH'); else if (orderSizeUsd / visibleDepthUsd > p.default) return reshape({ max_size_usd: visibleDepthUsd * p.default });

{ "min_top_of_book_usd": 250 }

if (topOfBookUsd < p.hard) return reject('INSUFFICIENT_VISIBLE_DEPTH'); else if (topOfBookUsd < p.default) return reshape({ max_size_usd: topOfBookUsd });

{ "max_spread_multiple": 2.5 }

const mult = currentSpread / medianSpread30d; if (mult > p.hard) return reject('SPREAD_TOO_WIDE'); else if (mult > p.default) return warn('SPREAD_TOO_WIDE');

{ "stale_top_seconds": 60 }

const ageSeconds = (Date.now() - bookLastUpdatedMs) / 1000; if (ageSeconds > p.hard) return reject('STALE_MARKET_DATA'); else if (ageSeconds > p.default) return warn('STALE_MARKET_DATA');

8. Default Configuration

{
  "bot_id": "risk.liquidity_guard",
  "version": "1.0.0",
  "mode": "hard_guard",
  "defaults": {
    "max_pct_of_visible_depth": 25,
    "min_top_of_book_usd": 250,
    "max_spread_multiple": 2.5,
    "stale_top_seconds": 60
  },
  "locked": {
    "min_top_of_book_usd": {
      "min": 50
    },
    "stale_top_seconds": {
      "max": 120
    }
  }
}

9. Implementation Flow

1. Receive OrderIntent from Strategy layer including market_id, side, size_usd, and price.
2. Check KillSwitch active flag from KillSwitch service; if active, return REJECT with reason code KILL_SWITCH_ACTIVE immediately.
3. Pull top 50 levels from the CLOB WebSocket book channel for the target market_id.
4. Check top-of-book last-update timestamp; if age > stale_top_seconds hard limit, return REJECT with STALE_MARKET_DATA.
5. Compute total visible_depth_usd from top 50 levels on the relevant side. If top-of-book USD < min_top_of_book_usd hard floor, return REJECT with INSUFFICIENT_VISIBLE_DEPTH.
6. Compute current spread in percentage points and compare to median30d spread from Data API. If spread_multiple > max_spread_multiple hard ceiling, return REJECT with SPREAD_TOO_WIDE.
7. Compute pct_of_depth = order.size_usd / visible_depth_usd. If > hard ceiling (60%), return REJECT with INSUFFICIENT_VISIBLE_DEPTH.
8. If pct_of_depth > default threshold (25%), compute safe_size_usd = visible_depth_usd × 0.25 and return RESHAPE_REQUIRED with constraints.max_size_usd = safe_size_usd.
9. If spread_multiple > warning threshold, attach a warning annotation to the approval without blocking.
10. Return APPROVE with inputs_used list and checked_at timestamp.

10. Reference Implementation

Fetches the top-50 CLOB book for the target market, checks KillSwitch, then evaluates depth, spread, and book freshness against configured thresholds. Returns a RiskVote of APPROVE, RESHAPE_REQUIRED, or HARD_REJECT.

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

FUNCTION evaluateLiquidity(intent):
  // --- 0. KillSwitch gate ---
  ks = FETCH internal.killswitch.status
  IF ks.active:
    EMIT RiskVote(decision=HARD_REJECT, reason=KILL_SWITCH_ACTIVE)
    RETURN

  // --- 1. Fetch book ---
  book = fetchClobPublic('/book?market=' + intent.market_id)
  IF book IS NULL OR book.updated_at IS NULL:
    EMIT RiskVote(decision=HARD_REJECT, reason=STALE_MARKET_DATA)
    RETURN

  // --- 2. Staleness check ---
  ageSeconds = (now_ms() - book.updated_at_ms) / 1000
  IF ageSeconds > params.stale_top_seconds.hard:
    EMIT RiskVote(decision=HARD_REJECT, reason=STALE_MARKET_DATA)
    RETURN

  // --- 3. Compute depth ---
  side = IF intent.side == BUY THEN book.asks ELSE book.bids
  visibleDepthUsd = SUM(level.price * level.size * collateralDecimals
                        FOR level IN side[:50])
  topOfBookUsd = side[0].price * side[0].size

  // --- 4. Top-of-book floor ---
  IF topOfBookUsd < params.min_top_of_book_usd.hard:
    EMIT RiskVote(decision=HARD_REJECT, reason=INSUFFICIENT_VISIBLE_DEPTH)
    RETURN

  // --- 5. Spread check ---
  spread = book.asks[0].price - book.bids[0].price
  median30d = FETCH fetchClobPublic('/spread-stats?market=' + intent.market_id).median30d
  spreadMultiple = spread / median30d
  IF spreadMultiple > params.max_spread_multiple.hard:
    EMIT RiskVote(decision=HARD_REJECT, reason=SPREAD_TOO_WIDE)
    RETURN

  // --- 6. NegRisk check (optional) ---
  IF intent.neg_risk AND isStale(book, params.stale_top_seconds.default):
    EMIT RiskVote(decision=WARN, reason=LIQUIDITY_GUARD_NEGRISK_THIN_BOOK)

  // --- 7. Depth percentage ---
  pctOfDepth = intent.size_usd / visibleDepthUsd
  IF pctOfDepth > params.max_pct_of_visible_depth.hard:
    EMIT RiskVote(decision=HARD_REJECT, reason=INSUFFICIENT_VISIBLE_DEPTH)
    RETURN

  IF pctOfDepth > params.max_pct_of_visible_depth.default:
    safeSizeUsd = visibleDepthUsd * params.max_pct_of_visible_depth.default
    safeSizeUsd = toUsdcUnits(safeSizeUsd)  // round to pUSD precision
    EMIT RiskVote(decision=RESHAPE_REQUIRED,
                  reason=INSUFFICIENT_VISIBLE_DEPTH,
                  constraints={ max_size_usd: safeSizeUsd })
    RETURN

  // --- 8. Happy path ---
  EMIT RiskVote(decision=APPROVE, checked_at=now_iso())

Helpers used

SDK calls used

• fetchClobPublic('/book?market=0xabc123...&side=asks&depth=50')
• fetchClobPublic('/spread-stats?market=0xabc123...')
• fetchClobPublic('/markets/0xabc123...')
• internal.killswitch.status()

Complexity: O(N) where N = book depth levels (max 50)

11. Wire Examples

Input — what arrives on the wire

OrderIntent from strategy — internal

{
  "intent_id": "int_7f3a1b2c9d4e5f60",
  "market_id": "0x3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f3a4b",
  "side": "BUY",
  "outcome": "YES",
  "size_usd": 1850,
  "price": 0.62,
  "neg_risk": false,
  "generated_at": "2026-05-09T05:51:00Z"
}

CLOB book snapshot (ws_market) — ws_market

{
  "market": "0x3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f3a4b",
  "asks": [
    {
      "price": "0.62",
      "size": "820"
    },
    {
      "price": "0.63",
      "size": "1200"
    },
    {
      "price": "0.64",
      "size": "3180"
    }
  ],
  "bids": [
    {
      "price": "0.61",
      "size": "950"
    },
    {
      "price": "0.60",
      "size": "2100"
    }
  ],
  "updated_at_ms": 1746768672000
}

Output — what the bot emits

RiskVote — RESHAPE_REQUIRED (order too large for visible depth)

{
  "guard_id": "risk.liquidity_guard",
  "decision": "RESHAPE_REQUIRED",
  "severity": "WARN",
  "reason_code": "INSUFFICIENT_VISIBLE_DEPTH",
  "message": "Order size 1850 pUSD exceeded 25% of 5200 pUSD visible top-50 depth. Resized to 1300 pUSD.",
  "constraints": {
    "max_size_usd": 1300,
    "passive_only": false,
    "close_only": false
  },
  "inputs_used": [
    "clob_public.book.top50",
    "data_api.spread.median30d",
    "internal.killswitch.status"
  ],
  "checked_at": "2026-05-09T05:51:12Z"
}

RiskVote — HARD_REJECT (stale book)

{
  "guard_id": "risk.liquidity_guard",
  "decision": "HARD_REJECT",
  "severity": "HARD",
  "reason_code": "STALE_MARKET_DATA",
  "message": "Book last updated 135s ago; stale_top_seconds hard limit is 120s.",
  "constraints": {},
  "inputs_used": [
    "clob_public.book.top50"
  ],
  "checked_at": "2026-05-09T06:05:00Z"
}

Reproduce locally

curl 'https://clob.polymarket.com/book?market=0x3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f3a4b'

12. Decision Logic

13. Standard Decision Output

This bot returns a RiskVote object. See RiskVote schema.

{
  "guard_id": "risk.liquidity_guard",
  "decision": "RESHAPE_REQUIRED",
  "severity": "WARN",
  "reason_code": "INSUFFICIENT_VISIBLE_DEPTH",
  "message": "Order size 1850 USD exceeded 25% of 5200 USD visible top-of-book depth. Resized to 1300 USD.",
  "constraints": {
    "max_size_usd": 1300,
    "passive_only": false,
    "close_only": false
  },
  "inputs_used": [
    "clob.book.top50",
    "data_api.spread.median30d",
    "internal.killswitch.status"
  ],
  "checked_at": "2026-05-09T05:51:12Z"
}

14. Reason Codes

15. Metrics & Logs

Metrics emitted

Alerts

Dashboards

• Grafana — Risk overview / LiquidityGuard
• Grafana — Market quality / spread and depth heatmap

Log levels

16. Developer Reporting

{
  "bot_id": "risk.liquidity_guard",
  "decision": "RESHAPE_REQUIRED",
  "reason_code": "INSUFFICIENT_VISIBLE_DEPTH",
  "inputs_used": [
    "clob.book.top50",
    "data_api.spread.median30d"
  ],
  "metrics": {
    "visible_depth_usd": 5200,
    "requested_size_usd": 1850,
    "pct_of_depth": 0.356,
    "top_of_book_usd": 820,
    "spread_multiple": 1.4,
    "book_age_seconds": 12
  },
  "safe_size_usd": 1300,
  "checked_at": "2026-05-09T05:51:12Z"
}

17. Plain-English Reporting

18. Failure-Mode Block

19. Failure-Injection Recipes

20. State & Persistence

LiquidityGuard is stateless per evaluation; it holds no persistent state beyond an in-memory cache of the last book snapshot per market.

State stores

Cold-start recovery

On cold start, the cache is empty. The first evaluation for each market_id triggers a fresh CLOB fetch.

On restart

Book snapshots are re-fetched on first evaluation; no durable state is loaded. If the WebSocket reconnects before the first evaluation, snapshots are populated from the reconnection event.

21. Concurrency & Idempotency

22. Dependencies

Depends on (must run first)

Emits to (downstream consumers)

Used by (auto-aggregated)

4.13

External services

23. Security Surfaces

LiquidityGuard is read-only and stateless. It never signs orders or holds secrets.

Signing surface

This bot does NOT sign anything.

Abuse vectors considered

• Replaying a stale book snapshot to bypass depth checks
• Injecting artificially large depth values to allow oversized orders

Mitigations

• per-intent_id idempotency prevents replay of the same evaluation
• book.updated_at_ms is checked against wall clock; any snapshot older than stale_top_seconds is rejected regardless of depth values

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

LiquidityGuard incidents are typically caused by a stale CLOB book feed or an abnormal spread spike. On-call should first confirm whether the WS market feed is connected before adjusting parameters.

On-call actions

Manual overrides

• polytraders bot pause risk.liquidity_guard — Stops emitting RiskVotes; all intents fall through to the next guardrail without a liquidity check. Use only during a known feed outage.
• polytraders bot flush-cache risk.liquidity_guard --market <market_id> — Evicts the in-memory book cache for a specific market, forcing a fresh CLOB fetch on the next evaluation.

Healthcheck

GET /health → 200 if WS market feed is connected and last book update for any tracked market is within stale_top_seconds.

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%