3.20 NarrativeCrowdingFade

1. Bot Identity

2. Purpose

NarrativeCrowdingFade detects Polymarket binary markets where social attention and narrative momentum have pushed prices above the statistical base rate. When attention Z-score and price drift signal crowding, the bot fades the move — taking the opposite position to capture reversion toward the base rate.

3. Why This Bot Matters

• News is genuinely paradigm-shifting

  If the crowded narrative reflects real new information rather than sentiment overshoot, the fade position loses as the market price correctly adjusts to the new fundamental.

• Stale input data

  Acting on stale signals for NarrativeCrowdingFade produces trades based on outdated market conditions, generating adverse fills.

• KillSwitch not respected

  Emitting OrderIntents while KillSwitch is active bypasses risk controls.

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

{ "min_attention_zscore": 2.0 }

if attention_zscore < params.hard: return skip('NCF_ATTENTION_BELOW_FLOOR')

{ "min_drift_bps": 200 }

if drift_bps < params.hard: return skip('NCF_NO_DRIFT')

{ "max_position_per_event": 400 }

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

{ "cool_off_after_news": 300 }

if in_cooloff(market_id): return skip('NCF_COOLOFF_ACTIVE')

8. Default Configuration

{
  "bot_id": "strat.narrativecrowdingfade",
  "version": "0.1.0",
  "mode": "shadow_only",
  "defaults": {
    "min_attention_zscore": 2.0,
    "min_drift_bps": 200,
    "max_position_per_event": 400,
    "cool_off_after_news": 300
  },
  "locked": {
    "min_attention_zscore": {
      "min": 1.0
    },
    "min_drift_bps": {
      "min": 50
    },
    "max_position_per_event": {
      "min": 800
    },
    "cool_off_after_news": {
      "min": 0
    }
  }
}

9. Implementation Flow

1. Check KillSwitch; if active, emit no OrderIntents.
2. FETCH NarrativeCrowdingFade analytics signal from internal engine.
3. IF signal below hard floor: SKIP, emit sampled DecisionReport NCF_NO_EDGE.
4. FETCH clob_public market status; skip if closed or resolved.
5. FETCH ws_market book; compute current mid and available depth.
6. IF signal < warning threshold: WARN NCF_MARGINAL; reduce size 50%.
7. Compute order size = min(max_size_param, available_depth).
8. EMIT IOC OrderIntent with builder code.
9. EMIT DecisionReport with intent_emitted=true, reason=NCF_TRADE.

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

  // Hard floor gate
  IF signal.score < params.min_attention_zscore_hard:
    IF random() < 0.01:
      EMIT DecisionReport(intent_emitted=false, reason='NCF_NO_EDGE')
    RETURN

  mkt = FETCH clob_public.GET('/markets/' + market_id)
  IF mkt.closed OR mkt.resolved: RETURN

  // Warning threshold check
  sizeMultiplier = 0.5 IF signal.score < params.min_attention_zscore_warn ELSE 1.0
  IF sizeMultiplier < 1.0: WARN('NCF_MARGINAL')

  // Book snapshot
  book = FETCH ws_market.book(market_id)
  mid = (book.best_bid + book.best_ask) / 2
  depth = FETCH clob_public.depth(market_id)

  // Size computation
  orderSize = toPusdUnits(min(params.min_drift_bps * sizeMultiplier, depth.available))

  EMIT OrderIntent(market=market_id, outcome='YES', side='buy', price=mid,
                   size_pUSD=orderSize, tif='IOC', builder=internalBuilderCode)
  EMIT DecisionReport(intent_emitted=true, signal_score=signal.score,
                      reason='NCF_TRADE')

SDK calls used

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

Complexity: O(1) per signal update per market

11. Wire Examples

Input — what arrives on the wire

NarrativeCrowdingFade analytics signal — internal (analytics engine)

{
  "market_id": "0xnarrativ000000000000000000000000000000000000000000000000000000000001",
  "signal_score": "0.75",
  "received_at_ms": 1746790800000
}

Output — what the bot emits

OrderIntent — NarrativeCrowdingFade IOC buy YES

{
  "intent_id": "oi_01HNCF0000001A",
  "market_id": "0xnarrativ000000000000000000000000000000000000000000000000000000000001",
  "outcome": "YES",
  "side": "buy",
  "price": "0.540",
  "size_pUSD": "200.00",
  "tif": "IOC",
  "builder": {
    "code": "0x706f6c7974726164657273000000000000000000000000000000000000000000",
    "fee_bps": 25
  },
  "decision": {
    "signal_score": 0.75,
    "reasons": [
      "NCF_TRADE"
    ]
  }
}

12. Decision Logic

13. Standard Decision Output

This bot returns a OrderIntent object. See OrderIntent schema.

{
  "intent_id": "oi_01HNCF0000001A",
  "trace_id": "tr_01HNCF000TR001",
  "market_id": "0xnarrativ000000000000000000000000000000000000000000000000000000000001",
  "outcome": "YES",
  "side": "buy",
  "price": "0.540",
  "size_pUSD": "200.00",
  "tif": "IOC",
  "post_only": false,
  "builder": {
    "code": "0x706f6c7974726164657273000000000000000000000000000000000000000000",
    "fee_bps": 25
  },
  "negrisk_aware": false,
  "decision": {
    "signal_score": 0.75,
    "reasons": [
      "NCF_TRADE"
    ]
  },
  "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.narrativecrowdingfade",
  "market_id": "0xnarrativ000000000000000000000000000000000000000000000000000000000001",
  "signal_score": 0.75,
  "intent_emitted": true,
  "reason": "NCF_TRADE",
  "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, signals rebuilt from next analytics engine poll.

21. Concurrency & Idempotency

22. Dependencies

Depends on (must run first)

Emits to (downstream consumers)

External services

23. Security Surfaces

Abuse vectors considered

• Signal injection to produce false NarrativeCrowdingFade trades
• Order sizing parameter manipulation to exceed position limits

Mitigations

• NarrativeCrowdingFade analytics signals sourced from authenticated internal engine only
• Hard limits on position size enforced before OrderIntent emission
• Builder code injected from secure internal config

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

NarrativeCrowdingFade incidents are typically stale analytics feeds or kill-switch activations. Hard-floor skips are normal.

On-call actions

Manual overrides

• —

Healthcheck

GET /internal/health/narrativecrowdingfade -> 200 if Analytics engine active; signal age < 60s; KillSwitch inactive.. Red: Analytics engine 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%