3.14 Liquidity-Pulse

1. Bot Identity

2. Purpose

Liquidity-Pulse is a market-analytics tool that monitors emerging Polymarket markets for early liquidity opportunities. When a market's volume and attention signal crosses configured thresholds, the bot emits an OrderIntent for user-controlled maker quote placement. All execution decisions remain with the user; this bot provides structured analytics and sizing recommendations only.

3. Why This Bot Matters

• Quote placed before sufficient volume confirmation

  Early quotes on unproven markets may sit unmatched or attract adverse selection from informed traders who discovered the market first.

• Spread tightening faster than quote updates

  Quotes placed at the initial wide spread become the worst price on the book as other makers tighten, leading to adverse selection.

• Market resolves before position unwinds

  Short-lived markets may reach resolution before an early maker position can be exited, forcing settlement at a potentially unfavorable resolution price.

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

{ "initial_spread_bps": 200 }

if params.initial_spread_bps < params.hard: return skip('LP_SPREAD_BELOW_FLOOR')

{ "tighten_at_volume_usd": 5000 }

if total_volume >= params.tighten_at_volume_usd: spread = initial_spread_bps * 0.5

{ "max_pre_event_position_usd": 300 }

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

{ "event_lead_time_h": 24 }

if hours_to_event < params.hard: return skip('LP_TOO_CLOSE_TO_RESOLUTION')

8. Default Configuration

{
  "bot_id": "strat.liquidity_pulse",
  "version": "0.1.0",
  "mode": "shadow_only",
  "defaults": {
    "initial_spread_bps": 200,
    "tighten_at_volume_usd": 5000,
    "max_pre_event_position_usd": 300,
    "event_lead_time_h": 24
  },
  "locked": {
    "initial_spread_bps": {
      "min": 50
    },
    "max_pre_event_position_usd": {
      "max": 750
    },
    "event_lead_time_h": {
      "min": 1
    }
  }
}

9. Implementation Flow

1. Check KillSwitch; if active, emit no OrderIntents.
2. FETCH gamma market metadata; compute hours_to_event.
3. IF hours_to_event < hard (1h): skip LP_TOO_CLOSE_TO_RESOLUTION.
4. FETCH attention signal from market scanner; if below threshold, skip.
5. FETCH ws_market book; compute current spread and total_volume.
6. Compute recommended spread: initial_spread_bps * (0.5 if total_volume >= tighten_at_volume_usd else 1.0).
7. IF recommended_spread < spread_hard (50 bps): skip LP_SPREAD_BELOW_FLOOR.
8. Compute position_size = min(max_pre_event_position_usd, available_capital).
9. Adjust size down 50% if hours_to_event < warning (6h).
10. EMIT OrderIntent: post_only=true, bid=mid-spread/2, ask=mid+spread/2, size=position_size, builder=code.
11. EMIT DecisionReport with intent_emitted=true, reason=LP_QUOTE_EMITTED.

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 onAttentionSignal(market_id, attentionSignal):
  ks = FETCH internal.killswitch.status
  IF ks.active: RETURN

  // Resolve event lead time
  meta = FETCH gamma.GET('/markets/' + market_id)
  hoursToEvent = (meta.end_date_ms - now_ms()) / 3600000
  IF hoursToEvent < params.event_lead_time_h_hard:  // 1h
    EMIT DecisionReport(intent_emitted=false, reason='LP_TOO_CLOSE_TO_RESOLUTION')
    RETURN

  // Book and volume snapshot
  book = FETCH ws_market.book(market_id)
  totalVolume = book.total_traded_volume_usd
  mid = (book.best_bid + book.best_ask) / 2

  // Spread computation
  spreadBps = params.initial_spread_bps
  IF totalVolume >= params.tighten_at_volume_usd:
    spreadBps = spreadBps * 0.5

  IF spreadBps < params.initial_spread_bps_hard:  // 50 bps
    EMIT DecisionReport(intent_emitted=false, reason='LP_SPREAD_BELOW_FLOOR')
    RETURN

  IF spreadBps < params.initial_spread_bps_warn:  // 100 bps
    WARN('LP_TIGHT_SPREAD')

  // Sizing
  sizeMultiplier = 0.5 IF hoursToEvent < params.event_lead_time_h_warn ELSE 1.0  // < 6h
  orderSize = toPusdUnits(params.max_pre_event_position_usd * sizeMultiplier)

  bidPrice = mid - (spreadBps / 20000)
  askPrice = mid + (spreadBps / 20000)

  EMIT OrderIntent(market=market_id, outcome='YES', side='buy', price=bidPrice,
                   size_pUSD=orderSize, tif='GTC', post_only=true, builder=internalBuilderCode)
  EMIT DecisionReport(intent_emitted=true, spread_bps=spreadBps, reason='LP_QUOTE_EMITTED')

SDK calls used

• ws_market.subscribe('book', [market_id])
• gamma.GET('/markets/' + market_id)
• fetchClobPublic('/markets/' + market_id)
• internal.killswitch.status()
• buildOrderTypedData(orderParams, {name:'CTFExchange', version:'2', chainId:137})

Complexity: O(1) per attention signal per market

11. Wire Examples

Input — what arrives on the wire

Attention signal — market gaining volume — internal (market scanner)

{
  "market_id": "0xlp000000000000000000000000000000000000000000000000000000000000001",
  "attention_score": 0.72,
  "total_volume_usd": "850.0",
  "hours_to_event": "36.0",
  "received_at_ms": 1746790800000
}

Output — what the bot emits

OrderIntent — LP GTC post-only maker YES

{
  "intent_id": "oi_01HLP0000001A",
  "market_id": "0xlp000000000000000000000000000000000000000000000000000000000000001",
  "outcome": "YES",
  "side": "buy",
  "price": "0.490",
  "size_pUSD": "150.00",
  "tif": "GTC",
  "post_only": true,
  "builder": {
    "code": "0x706f6c7974726164657273000000000000000000000000000000000000000000",
    "fee_bps": 10
  },
  "decision": {
    "spread_bps": 200,
    "reasons": [
      "LP_QUOTE_EMITTED"
    ]
  }
}

12. Decision Logic

13. Standard Decision Output

This bot returns a OrderIntent object. See OrderIntent schema.

{
  "intent_id": "oi_01HLP0000001A",
  "trace_id": "tr_01HLP000TR001",
  "market_id": "0xlp000000000000000000000000000000000000000000000000000000000000001",
  "outcome": "YES",
  "side": "buy",
  "price": "0.490",
  "size_pUSD": "150.00",
  "tif": "GTC",
  "post_only": true,
  "builder": {
    "code": "0x706f6c7974726164657273000000000000000000000000000000000000000000",
    "fee_bps": 10
  },
  "negrisk_aware": false,
  "decision": {
    "spread_bps": 200,
    "hours_to_event": 36.0,
    "total_volume_usd": 850.0,
    "reasons": [
      "LP_QUOTE_EMITTED"
    ]
  },
  "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

16. Developer Reporting

{
  "bot_id": "strat.liquidity_pulse",
  "market_id": "0xlp000000000000000000000000000000000000000000000000000000000000001",
  "spread_bps": 200,
  "hours_to_event": 36.0,
  "total_volume_usd": 850.0,
  "intent_emitted": true,
  "reason": "LP_QUOTE_EMITTED",
  "emitted_at_ms": 1746790800000
}

17. Plain-English Reporting

18. Failure-Mode Block

19. Failure-Injection Recipes

20. State & Persistence

Cold-start recovery

On cold start, attention signals re-polled from market scanner; spread recomputed from ws_market.

21. Concurrency & Idempotency

22. Dependencies

Depends on (must run first)

Emits to (downstream consumers)

External services

23. Security Surfaces

Abuse vectors considered

• Attention signal injection to force quotes on low-quality markets
• Front-running of posted GTC quotes by adversaries who monitor emerging markets

Mitigations

• Attention signals sourced from authenticated internal market scanner only
• Quote sizes bounded by max_pre_event_position_usd
• GTC quotes can be cancelled by user at any 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

Liquidity-Pulse incidents are typically gamma API outages (blocking event lead-time checks) or kill-switch activations. Near-resolution blocks are expected behavior.

On-call actions

Manual overrides

• —

Healthcheck

GET /internal/health/liquidity-pulse -> 200 if Gamma API responding; ws_market feed age < 5s; KillSwitch inactive.. Red: Gamma API down or KillSwitch active..

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%