3.8 News Materiality Trader

1. Bot Identity

2. Purpose

News Materiality Trader positions ahead of the book's full digestion of material news events. It receives news items from the NewsIngest pipeline (Reuters, AP, Bloomberg, league wires), scores them using a NLP materiality classifier, resolves the news entity to one or more watchlisted Polymarket markets via an entity-resolution dictionary, and emits an IOC OrderIntent when materiality_score >= materiality_threshold. A cooldown period (cooldown_s) prevents re-trading the same entity-market pair within the window. Order TTL (order_ttl_s) limits exposure if the IOC is not immediately filled. This is a user-controlled execution tool for reacting to material news before book equilibration; it does not predict resolution outcomes or make performance claims.

3. Why This Bot Matters

• Low-materiality news classified as high

  The bot takes a position based on a rumour or corrected story, entering before the market corrects back, resulting in a loss when the initial price move reverses.

• Entity resolution maps to wrong market

  A news event about 'Team X wins championship' is resolved to a market about a different competition, causing a trade on an unrelated market.

• Book depth insufficient for the news event

  Filling the full IOC at the entry price depletes the top-of-book, causing significant slippage that overwhelms the news edge.

• cooldown_s too short — re-trading the same event

  Multiple news items from the same event (e.g., breaking news + confirmation + detail) trigger multiple entries on the same market before the book has repriced.

• feeRateBps present on signed order (V1 pattern)

  CTFExchangeV2 rejects orders with feeRateBps. Fees are operator-set at match time. The signed order must not contain this field.

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

{ "materiality_threshold": 0.72 }

if score < params.hard: return skip('NEWS_MATERIALITY_TOO_LOW')

{ "cooldown_s": 120 }

if params.cooldown_s < params.hard: raise ConfigError('PARAMETER_CHANGE_REQUIRES_APPROVAL')

{ "order_ttl_s": 90 }

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

{ "max_position_usd": 300 }

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

8. Default Configuration

{
  "bot_id": "strat.news_materiality_trader",
  "version": "2.1.0",
  "mode": "limited_live",
  "defaults": {
    "materiality_threshold": 0.72,
    "cooldown_s": 120,
    "order_ttl_s": 90,
    "max_position_usd": 300
  },
  "locked": {
    "materiality_threshold": {
      "min": 0.4
    },
    "cooldown_s": {
      "min": 20
    },
    "order_ttl_s": {
      "max": 300
    },
    "max_position_usd": {
      "max": 750
    }
  }
}

9. Implementation Flow

1. Check KillSwitch active flag; if active, emit no OrderIntents.
2. Subscribe to NewsIngest internal bus for materiality-scored news events.
3. On each news event: check materiality_score >= materiality_threshold hard floor (0.40); if below, skip NEWS_MATERIALITY_TOO_LOW (sampled 1/100).
4. Run entity-resolution: map news entity to Polymarket condition ID(s) via entity-resolution dictionary. If no match, skip NEWS_MATERIALITY_NO_MARKET_MATCH.
5. For each matched market: confirm market is open and not approaching resolution (< 30 min to close) via clob_public.
6. Check cooldown: if last trade on this entity-market pair was < cooldown_s seconds ago, skip NEWS_MATERIALITY_COOLDOWN_ACTIVE.
7. If materiality_score < warning threshold (0.72): WARN NEWS_MATERIALITY_SCORE_MARGINAL; reduce size to 50% of max_position_usd.
8. Fetch top-of-book depth from clob_public; set orderSize = min(depth, max_position_usd) * sizeMultiplier.
9. Check recent market volatility (ws_market): if price has already moved > 50% of expected news impact, skip NEWS_MATERIALITY_ALREADY_DIGESTED.
10. Emit OrderIntent: outcome=YES (or NO depending on event direction), side=buy, price=best_ask, size_pUSD=orderSize, tif=IOC, builder={code, fee_bps:25}.
11. Note: fees are operator-set at match time in V2 — feeRateBps is NOT on the signed order.
12. Register cooldown state: last_trade_ms for entity-market pair.
13. Emit DecisionReport with intent_emitted=true, materiality_score, entity_id, market_id, reason NEWS_MATERIALITY_TRADE_TRIGGERED.

10. Reference Implementation

Consumes news events from the NewsIngest internal bus, scores materiality via NLP classifier, resolves entities to open Polymarket markets, and emits IOC OrderIntents when materiality exceeds threshold and cooldown has elapsed.

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

FUNCTION onNewsEvent(newsItem):
  // --- 0. KillSwitch gate ---
  ks = FETCH internal.killswitch.status
  IF ks.active: RETURN

  // --- 1. Materiality score gate ---
  score = newsItem.materiality_score  // from NLP classifier
  IF score < params.materiality_threshold_hard:  // 0.40
    IF random() < 0.01:
      EMIT DecisionReport(intent_emitted=false, reason='NEWS_MATERIALITY_TOO_LOW', score=score)
    RETURN

  // --- 2. Entity resolution ---
  markets = FETCH internal.entityDict.resolve(newsItem.entity_id)
  IF NOT markets:
    EMIT DecisionReport(intent_emitted=false, reason='NEWS_MATERIALITY_NO_MARKET_MATCH')
    RETURN

  FOR market_id IN markets:
    // --- 3. Market status check ---
    mkt = FETCH clob_public.GET('/markets/' + market_id)
    IF mkt.closed OR mkt.resolved OR mkt.minutes_to_close < 30:
      CONTINUE

    // --- 4. Cooldown check ---
    lastTrade = FETCH state.lastTradeMs(newsItem.entity_id, market_id)
    IF (now_ms() - lastTrade) < params.cooldown_s * 1000:
      EMIT DecisionReport(intent_emitted=false, reason='NEWS_MATERIALITY_COOLDOWN_ACTIVE')
      CONTINUE

    // --- 5. Already-digested check ---
    recentMove = FETCH ws_market.priceChangeSinceMs(market_id, newsItem.received_at_ms)
    IF recentMove > 0.5 * expectedNewsImpact(score):
      EMIT DecisionReport(intent_emitted=false, reason='NEWS_MATERIALITY_ALREADY_DIGESTED')
      CONTINUE

    // --- 6. Size determination ---
    sizeMultiplier = 0.5 IF score < params.materiality_threshold ELSE 1.0
    IF sizeMultiplier < 1.0: WARN('NEWS_MATERIALITY_SCORE_MARGINAL')
    depth = FETCH clob_public.depth(market_id, side='YES')
    orderSize = toPusdUnits(min(depth, params.max_position_usd) * sizeMultiplier)

    // --- 7. Emit IOC OrderIntent (V2: no feeRateBps) ---
    side = 'buy' IF newsItem.direction == 'positive' ELSE 'sell'
    EMIT OrderIntent(
      market_id = market_id, outcome = 'YES', side = side,
      price = mkt.best_ask, size_pUSD = orderSize, tif = 'IOC', post_only = false,
      builder = {code: internal.builder_code, fee_bps: 25}
    )

    // --- 8. Register cooldown ---
    SET state.lastTradeMs(newsItem.entity_id, market_id, now_ms())

    EMIT DecisionReport(intent_emitted=true, materiality_score=score,
                        entity_id=newsItem.entity_id, market_id=market_id,
                        reason='NEWS_MATERIALITY_TRADE_TRIGGERED')

SDK calls used

• fetchClobPublic('/markets/' + market_id)
• ws_market.subscribe('book', [market_id])
• internal.entityDict.resolve(entity_id)
• internal.newsingest.subscribe()
• internal.killswitch.status()
• toPusdUnits(rawFloat)
• buildOrderTypedData(orderParams, { name: 'CTFExchange', version: '2', chainId: 137 })
• internal.builder_code

Complexity: O(n_markets_matched) per news event; typically O(1) for single-entity events

11. Wire Examples

Input — what arrives on the wire

NewsIngest event — high materiality, entity resolved — internal (NewsIngest bus)

{
  "event_id": "news_01HXNMT000EVENT",
  "entity_id": "entity_candidate_A_primary",
  "headline": "Candidate A wins state primary by large margin",
  "source": "Reuters",
  "materiality_score": 0.81,
  "direction": "positive",
  "matched_market_ids": [
    "0xnewsmat000000000000000000000000000000000000000000000000000000001"
  ],
  "received_at_ms": 1746790600000
}

Output — what the bot emits

OrderIntent — news IOC buy YES (builder-attributed)

{
  "intent_id": "oi_01HXNMT0000001A",
  "trace_id": "tr_01HXNMT000TR001",
  "market_id": "0xnewsmat000000000000000000000000000000000000000000000000000000001",
  "outcome": "YES",
  "side": "buy",
  "price": "0.438",
  "size_pUSD": "300.00",
  "tif": "IOC",
  "post_only": false,
  "builder": {
    "code": "0x706f6c7974726164657273000000000000000000000000000000000000000000",
    "fee_bps": 25
  },
  "negrisk_aware": false,
  "decision": {
    "materiality_score": 0.81,
    "entity_id": "entity_candidate_A_primary",
    "news_source": "Reuters",
    "reasons": [
      "NEWS_MATERIALITY_TRADE_TRIGGERED"
    ]
  },
  "comment": "fees are operator-set at match time in V2 — feeRateBps is NOT on the signed order"
}

DecisionReport — skipped (score too low), sampled 1/100

{
  "report_id": "dr_01HXNMT999ZZZZ",
  "bot_id": "strat.news_materiality_trader",
  "entity_id": "entity_candidate_B",
  "intent_emitted": false,
  "materiality_score": 0.28,
  "reasons": [
    "NEWS_MATERIALITY_TOO_LOW"
  ],
  "sampled": true,
  "evaluated_at_ms": 1746790601000
}

12. Decision Logic

13. Standard Decision Output

This bot returns a OrderIntent object. See OrderIntent schema.

{
  "intent_id": "oi_01HXNMT0000001A",
  "trace_id": "tr_01HXNMT000TR001",
  "market_id": "0xnewsmat000000000000000000000000000000000000000000000000000000001",
  "outcome": "YES",
  "side": "buy",
  "price": "0.438",
  "size_pUSD": "300.00",
  "tif": "IOC",
  "post_only": false,
  "builder": {
    "code": "0x706f6c7974726164657273000000000000000000000000000000000000000000",
    "fee_bps": 25
  },
  "negrisk_aware": false,
  "decision": {
    "materiality_score": 0.81,
    "entity_id": "entity_candidate_A_primary",
    "news_source": "Reuters",
    "reasons": [
      "NEWS_MATERIALITY_TRADE_TRIGGERED"
    ]
  },
  "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

Dashboards

• Grafana — Strategy / NewsMateriality score distribution and trade frequency
• Grafana — Strategy / NewsMateriality entity resolution hit rate and cooldown blocks

16. Developer Reporting

{
  "bot_id": "strat.news_materiality_trader",
  "market_id": "0xnewsmat000000000000000000000000000000000000000000000000000000001",
  "materiality_score": 0.81,
  "entity_id": "entity_candidate_A_primary",
  "news_source": "Reuters",
  "order_size_pusd": 300.0,
  "price_at_entry": 0.438,
  "cooldown_cleared": true,
  "depth_pusd": 520.0,
  "intent_emitted": true,
  "reason": "NEWS_MATERIALITY_TRADE_TRIGGERED",
  "emitted_at_ms": 1746790600000
}

17. Plain-English Reporting

18. Failure-Mode Block

19. Failure-Injection Recipes

20. State & Persistence

Cold-start recovery

On cold start, cooldown state is cleared (conservative: may re-trade within cooldown on restart). Price state rebuilt from first ws_market tick.

21. Concurrency & Idempotency

22. Dependencies

Depends on (must run first)

Emits to (downstream consumers)

External services

23. Security Surfaces

On-chain contract calls

Abuse vectors considered

• Injecting synthetic news into the NewsIngest feed to trigger trades on specific markets
• Adversary front-runs the bot by monitoring entity-resolution patterns to predict which markets will be traded on material news
• Cooldown manipulation: flooding the system with low-score news to exhaust entity-market pair cooldown windows

Mitigations

• NewsIngest feed is authenticated and sourced only from verified news providers; synthetic injection requires compromising the internal feed
• IOC orders do not rest on the book; adversary cannot exploit known bid/ask placement
• Hard materiality floor (0.40) prevents cooldown exhaustion via noise events
• V2 order timestamp(ms) invalidates replayed signed orders

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

News Materiality Trader incidents are typically high already-digested rates (slow news pipeline latency), NLP classifier outages (blocking all trades), or false-materiality classifications causing unexpected positions. Classifier outages fail-closed and resolve automatically.

On-call actions

Manual overrides

• —
• —

Healthcheck

GET /internal/health/news-materiality-trader -> 200 if NewsIngest feed live, NLP classifier reachable, clob_public reachable, KillSwitch inactive, at least one news event evaluated in last 10 min.

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%