0.5 NewMarketWatcher

1. Bot Identity

2. Purpose

Poll the Gamma API at high frequency to detect newly listed markets as soon as they appear, parse their initial metadata, and emit ObservationReports so strategies can evaluate early liquidity opportunities before the book fills.

3. Why This Bot Matters

• New markets discovered only on the next slow scan cycle

  Early-entry advantage is lost; book may already be competitive by the time MarketScanner surfaces the market.

• Unvalidated new market metadata forwarded to strategies

  Markets with incomplete rules text or missing resolution dates may produce erroneous strategy decisions.

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

{ "poll_interval_s": 10 }

if (s < params.hard) throw ConfigError('PARAMETER_CHANGE_REQUIRES_APPROVAL');

{ "min_listing_age_s": 30 }

if (age < params.min_listing_age_s) hold();

8. Default Configuration

{
  "bot_id": "disc.new_market_watcher",
  "version": "0.1.0",
  "mode": "shadow_only",
  "defaults": {
    "poll_interval_s": 10,
    "min_listing_age_s": 30,
    "alert_to_strategies": [],
    "require_rule_parse": true
  }
}

9. Implementation Flow

1. On each poll cycle, send a conditional GET to Gamma API using the ETag from the previous response.
2. If ETag matches (304 Not Modified), skip processing — no new markets.
3. If new markets are present, diff against the known condition_id set to identify genuinely new listings.
4. Check KillSwitch; if active, update known set but suppress emissions.
5. For each new market, apply min_listing_age_s hold-off; hold in a pending set.
6. After hold-off, fetch initial book state from CLOB and parse resolution metadata.
7. If require_rule_parse=true, validate that resolution rules text and resolution date are present.
8. Emit ObservationReport with condition_id, initial_book_state, neg_risk, tick_size, resolution_date.
9. Add newly emitted markets to the known condition_id set.
10. Log cycle summary: new_markets_detected, pending_count, emitted_count.

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 pollCycle():
  ks = FETCH internal.killswitch.status

  response = gamma.GET('/markets?active=true&closed=false',
                       headers={'If-None-Match': last_etag})
  IF response.status == 304: RETURN  // no new listings

  last_etag = response.headers['ETag']
  all_ids = {m.condition_id FOR m IN response.markets}
  new_ids = all_ids - known_condition_ids

  FOR condition_id IN new_ids:
    market = response.market(condition_id)
    listing_age_s = now() - market.created_at
    IF listing_age_s < params.min_listing_age_s:
      pending_set.add(condition_id, market); CONTINUE

    IF params.require_rule_parse AND NOT market.rules_text:
      pending_metadata.add(condition_id); CONTINUE  // INCOMPLETE_MARKET_METADATA

    book = FETCH clob_public.GET('/book?market=' + condition_id + '&depth=5')
    initial_state = 'empty' IF book.bids == [] AND book.asks == [] ELSE 'active'

    IF NOT ks.active:
      EMIT ObservationReport(condition_id, listing_age_s, market.neg_risk,
                             market.tick_size, market.resolution_date,
                             initial_state)

    known_condition_ids.add(condition_id)

  // Also re-check pending_metadata set
  FOR cid IN pending_metadata:
    market = gamma.GET('/market/' + cid)
    IF market.rules_text AND NOT ks.active:
      EMIT ObservationReport(cid, ...)
      known_condition_ids.add(cid)

  LOG poll cycle summary

SDK calls used

• gamma.GET('/markets?active=true&closed=false', If-None-Match: <etag>)
• gamma.GET('/market/<condition_id>')
• fetchClobPublic('/book?market=<condition_id>&depth=5')

Complexity: O(N) where N = new markets per poll cycle; amortised O(1) with ETag 304

11. Wire Examples

Input — what arrives on the wire

Gamma API new market entry — gamma_api

{
  "condition_id": "0xaabbccddeeff001122334455667788aabbccddeeff001122334455667788aabb",
  "question": "Will the new legislation pass by September 2026?",
  "active": true,
  "created_at": "2026-05-09T11:29:25Z",
  "neg_risk": false,
  "tick_size": 0.01,
  "resolution_date": "2026-09-01T00:00:00Z",
  "rules_text": "Resolves YES if the bill passes both chambers by midnight UTC on 2026-09-01."
}

Output — what the bot emits

ObservationReport — new market detected

{
  "report_id": "0xff002244668800aabbccddee112233ff002244668800aabbccddee11223344",
  "bot_id": "disc.new_market_watcher",
  "market_id": "0xaabbccddeeff001122334455667788aabbccddeeff001122334455667788aabb",
  "listing_detected_at_ms": 1746789000000,
  "listing_age_s": 35,
  "neg_risk": false,
  "tick_size": 0.01,
  "resolution_date": "2026-09-01T00:00:00Z",
  "initial_book_state": "empty",
  "warnings": [],
  "emitted_at_ms": 1746789035000
}

Reproduce locally

curl -H 'If-None-Match: "abc123"' 'https://gamma-api.polymarket.com/markets?active=true&closed=false'

12. Decision Logic

13. Standard Decision Output

This bot returns a ObservationReport object. See ObservationReport schema.

{
  "report_id": "0xff002244668800aabbccddee112233ff002244668800aabbccddee11223344",
  "bot_id": "disc.new_market_watcher",
  "market_id": "0xaabbccddeeff001122334455667788aabbccddeeff001122334455667788aabb",
  "listing_detected_at_ms": 1746789000000,
  "listing_age_s": 35,
  "neg_risk": false,
  "tick_size": 0.01,
  "resolution_date": "2026-09-01T00:00:00Z",
  "initial_book_state": "empty",
  "warnings": [],
  "emitted_at_ms": 1746789035000
}

14. Reason Codes

15. Metrics & Logs

Metrics emitted

Alerts

Dashboards

• Grafana — Discovery / NewMarketWatcher detection latency

Log levels

16. Developer Reporting

{
  "bot_id": "disc.new_market_watcher",
  "poll_cycle": 4820,
  "new_markets_detected": 2,
  "pending_holdoff": 1,
  "emitted": 1,
  "suppressed_killswitch": 0,
  "known_set_size": 318,
  "polled_at": "2026-05-09T11:30:00Z"
}

17. Plain-English Reporting

18. Failure-Mode Block

19. Failure-Injection Recipes

20. State & Persistence

Cold-start recovery

On cold start, known set is bootstrapped from MarketScanner's current candidate list.

21. Concurrency & Idempotency

22. Dependencies

Depends on (must run first)

Emits to (downstream consumers)

Sibling bots (same OrderIntent)

External services

23. Security Surfaces

Abuse vectors considered

• Gamma API returning spoofed new market metadata to inject fraudulent condition_ids

Mitigations

• condition_id validated against 32-byte hex pattern before entering known set
• require_rule_parse=true ensures minimal metadata quality before emission

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

NewMarketWatcher incidents are typically Gamma API outages or high hold-off backlogs. Bot is read-only; incidents delay new market discovery but do not affect active positions.

On-call actions

Manual overrides

• —

Healthcheck

GET /internal/health/newmarketwatcher → green if Poll cycle completed within 3× poll_interval_s; no Gamma API errors in last 5 minutes.; red if No poll cycle in 3× interval or consecutive Gamma API failures.

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%