4.4 CrossMarketGraph

1. Bot Identity

2. Purpose

CrossMarketGraph builds and maintains a directed graph of semantically equivalent and logically linked Polymarket markets by embedding market titles and rules text, applying cosine-similarity clustering, and supplementing with manual override pairs. Each node is a condition_id; each edge carries a relation_type (SAME_EVENT, COMPLEMENTARY, NEG_RISK_SIBLING, SUPERSEDES) and a confidence score. The graph is the foundation for cross-market correlation signals used by SumToOneArb and liquidity-aware strategies to detect near-duplicate markets and hedge opportunities. CrossMarketGraph is strictly read-only — it never submits or signs orders.

3. Why This Bot Matters

• Near-duplicate markets not detected

  SumToOneArb cannot identify arbitrage opportunities where two markets resolve the same event; edge goes unexploited and probability discrepancies persist.

• Stale graph used during rapid market creation spree

  New markets linked to a live event are not added to the graph in time; strategy enters both sides of a newly duplicated market, creating an unintended hedge.

• Neg-risk siblings not identified

  Strategy holds positions on multiple outcomes of the same neg-risk event without knowing they are structurally linked, over-exposing the book to a single resolution.

• Incorrect SUPERSEDES edge causes stale-market entry

  A superseded market is incorrectly treated as live; strategy generates an intent for a market that has already been replaced by an updated version.

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

{ "cluster_threshold": 0.85 }

if (p.cluster_threshold < p.hard) throw ConfigError('PARAMETER_CHANGE_REQUIRES_APPROVAL');

{ "rebuild_interval_s": 300 }

if (p.rebuild_interval_s < p.hard) throw ConfigError('PARAMETER_CHANGE_REQUIRES_APPROVAL');

{ "max_edges_per_node": 20 }

if (p.max_edges_per_node > p.hard) throw ConfigError('PARAMETER_CHANGE_REQUIRES_APPROVAL');

8. Default Configuration

{
  "bot_id": "intel.crossmarketgraph",
  "version": "2.1.0",
  "mode": "limited_live",
  "defaults": {
    "cluster_threshold": 0.85,
    "rebuild_interval_s": 300,
    "max_edges_per_node": 20,
    "logical_relation_types": [
      "SAME_EVENT",
      "COMPLEMENTARY",
      "NEG_RISK_SIBLING",
      "SUPERSEDES"
    ]
  },
  "locked": {
    "cluster_threshold": {
      "min": 0.65
    },
    "rebuild_interval_s": {
      "min": 30
    },
    "max_edges_per_node": {
      "max": 100
    }
  }
}

9. Implementation Flow

1. On each rebuild cycle (rebuild_interval_s), FETCH full live market list from Gamma API including title, rules_text, condition_id, neg_risk, enable_neg_risk, active, closed.
2. For each market, compute embedding vector via local sentence-embedding model over title + ' ' + rules_text[:512].
3. Apply manual_pair_overrides first: inject edges with confidence=1.0 and the specified relation_type.
4. For each pair of active markets, compute cosine_similarity(embed_a, embed_b).
5. If cosine_similarity >= cluster_threshold: add directed edge (condition_id_a -> condition_id_b) with relation_type inferred by heuristic: NEG_RISK_SIBLING if both neg_risk=true and same parent; SUPERSEDES if one is closed and one is the replacement; COMPLEMENTARY if titles match a complement pattern (e.g. 'Yes/No' mirror); SAME_EVENT otherwise.
6. Cap outbound edges per node at max_edges_per_node, keeping highest-confidence edges.
7. Check KillSwitch. If active, update graph in memory but suppress ObservationReport emissions.
8. For each new or changed edge (compared to previous graph snapshot), emit an ObservationReport with: report_id, trace_id, condition_id_a, condition_id_b, relation_type, confidence, edge_direction, graph_version.
9. Log per-rebuild summary: nodes_total, edges_total, new_edges, dropped_edges, clusters_found, rebuild_latency_ms.

10. Reference Implementation

On each rebuild cycle, fetches all live markets from Gamma API, computes sentence embeddings, applies cosine-similarity clustering above cluster_threshold, injects manual overrides, caps edges per node, and emits ObservationReports for new or changed edges.

Pseudocode is language-agnostic. FETCH = read input. EMIT = produce output.

// --- Initialisation ---
embed_model = load_local_embedding_model()
last_graph   = {}        // condition_id -> set of (neighbor_id, relation_type, confidence)
graph_version_counter = 0

FUNCTION rebuildCycle():
  // --- 0. KillSwitch gate ---
  ks = FETCH internal.killswitch.status

  // --- 1. Fetch market list ---
  markets = FETCH gamma_api.GET('/markets?active=true&closed=false')
  IF markets IS NULL:
    LOG WARN 'STALE_DATA — Gamma API unavailable; graph frozen'
    RETURN

  // --- 2. Embed all markets ---
  embeddings = {}
  FOR market IN markets:
    text = market.question + ' ' + market.rules_text[:512]
    embeddings[market.condition_id] = embed_model.encode(text)

  // --- 3. Inject manual overrides ---
  new_graph = {}
  FOR override IN params.manual_pair_overrides:
    addEdge(new_graph, override.condition_id_a, override.condition_id_b,
            override.relation_type, confidence=1.0)

  // --- 4. Cosine similarity clustering ---
  cids = LIST(embeddings.keys())
  FOR i IN range(len(cids)):
    FOR j IN range(i+1, len(cids)):
      sim = cosine_similarity(embeddings[cids[i]], embeddings[cids[j]])
      IF sim < params.cluster_threshold:
        CONTINUE
      rel = inferRelationType(markets[cids[i]], markets[cids[j]], sim)
      addEdge(new_graph, cids[i], cids[j], rel, confidence=sim)
      addEdge(new_graph, cids[j], cids[i], rel, confidence=sim)

  // --- 5. Cap edges per node ---
  FOR node IN new_graph:
    IF len(new_graph[node]) > params.max_edges_per_node:
      new_graph[node] = topN(new_graph[node], params.max_edges_per_node)
      LOG WARN 'CROSSMARKETGRAPH_DENSE_CLUSTER node=' + node

  graph_version_counter += 1
  graph_version = 'cmg_v' + today() + '_' + graph_version_counter

  // --- 6. Diff against last graph ---
  new_edges     = diff_new(new_graph, last_graph)
  dropped_edges = diff_dropped(last_graph, new_graph)

  // --- 7. KillSwitch suppress ---
  IF ks.active:
    LOG INFO 'KILL_SWITCH_ACTIVE — suppressing ObservationReports'
    last_graph = new_graph
    RETURN

  // --- 8. Emit for new/changed edges ---
  FOR (cid_a, cid_b, rel, conf) IN new_edges:
    EMIT ObservationReport {
      report_id:     'rep_cmg_' + cid_a[:6] + '_' + now_ms(),
      trace_id:      new_trace_id(),
      bot_id:        'intel.crossmarketgraph',
      kind:          'ObservationReport',
      condition_id_a: cid_a,
      condition_id_b: cid_b,
      relation_type:  rel,
      confidence:     conf,
      edge_direction: 'bidirectional',
      graph_version:  graph_version,
      warnings:       [],
      emitted_at_ms:  now_ms()
    }

  last_graph = new_graph

FUNCTION inferRelationType(m_a, m_b, sim):
  IF m_a.neg_risk AND m_b.neg_risk AND sameParent(m_a, m_b):
    RETURN 'NEG_RISK_SIBLING'
  IF m_a.closed AND NOT m_b.closed AND sim > 0.95:
    RETURN 'SUPERSEDES'
  IF isComplementPair(m_a.question, m_b.question):
    RETURN 'COMPLEMENTARY'
  RETURN 'SAME_EVENT'

SDK calls used

• gamma_api.GET('/markets?active=true&closed=false')
• embed_model.encode(text)
• cosine_similarity(vec_a, vec_b)

Complexity: O(M²) per rebuild cycle where M = live market count; practical with M ≤ 500 at 5-min cadence

11. Wire Examples

Input — what arrives on the wire

{
  "label": "Gamma API market pair (candidate for SAME_EVENT edge)",
  "source": "gamma_api",
  "payload": [
    {
      "condition_id": "0xabc1230000000000000000000000000000000000000000000000000000000000",
      "question": "Will Candidate A win the 2026 election?",
      "active": true,
      "neg_risk": false,
      "enable_neg_risk": false
    },
    {
      "condition_id": "0xdef4560000000000000000000000000000000000000000000000000000000000",
      "question": "Will Candidate A win the 2026 general election?",
      "active": true,
      "neg_risk": false,
      "enable_neg_risk": false
    }
  ]
}

Output — what the bot emits

{
  "label": "ObservationReport — SAME_EVENT edge detected",
  "payload": {
    "report_id": "rep_cmg_0xabc1_1746702000000",
    "trace_id": "trc_0xcafe0a0b0c0d0e0f",
    "bot_id": "intel.crossmarketgraph",
    "kind": "ObservationReport",
    "condition_id_a": "0xabc1230000000000000000000000000000000000000000000000000000000000",
    "condition_id_b": "0xdef4560000000000000000000000000000000000000000000000000000000000",
    "relation_type": "SAME_EVENT",
    "confidence": 0.92,
    "edge_direction": "bidirectional",
    "graph_version": "cmg_v20260428_301",
    "warnings": [],
    "emitted_at_ms": 1746702000042
  }
}

12. Decision Logic

13. Standard Decision Output

This bot returns a ObservationReport object. See ObservationReport schema.

{
  "report_id": "rep_cmg_0xabc1_1746702000000",
  "trace_id": "trc_0xcafe0a0b0c0d0e0f",
  "bot_id": "intel.crossmarketgraph",
  "kind": "ObservationReport",
  "condition_id_a": "0xabc1230000000000000000000000000000000000000000000000000000000000",
  "condition_id_b": "0xdef4560000000000000000000000000000000000000000000000000000000000",
  "relation_type": "SAME_EVENT",
  "confidence": 0.92,
  "edge_direction": "bidirectional",
  "graph_version": "cmg_v20260428_301",
  "warnings": [],
  "emitted_at_ms": 1746702000042
}

14. Reason Codes

15. Metrics & Logs

Metrics emitted

Alerts

Dashboards

• Grafana — Intelligence / CrossMarketGraph node and edge counts
• Grafana — Intelligence / graph rebuild latency and cluster density

16. Developer Reporting

{
  "bot_id": "intel.crossmarketgraph",
  "rebuild_cycle": 301,
  "rebuild_latency_ms": 4820,
  "nodes_total": 318,
  "edges_total": 1104,
  "new_edges": 7,
  "dropped_edges": 2,
  "clusters_found": 38,
  "manual_overrides_applied": 5,
  "killswitch_active": false
}

17. Plain-English Reporting

18. Failure-Mode Block

19. Failure-Injection Recipes

20. State & Persistence

Cold-start recovery

On cold start, graph is empty. First rebuild cycle populates it. Until first rebuild completes, no ObservationReports are emitted.

21. Concurrency & Idempotency

22. Dependencies

Depends on (must run first)

Emits to (downstream consumers)

External services

23. Security Surfaces

Abuse vectors considered

• Gamma API returning adversarially crafted market titles to manipulate cosine-similarity scores and inject false SAME_EVENT edges
• Manual override list poisoned with a cross-market link that causes downstream arb strategy to take losses

Mitigations

• Embeddings computed on truncated text (512 chars); extreme outliers in similarity space are detectable as anomalies
• Manual overrides require operator-level config change with audit trail
• All ObservationReports are informational only — downstream strategies and risk bots independently validate market state before acting

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

CrossMarketGraph incidents are usually Gamma API outages or embedding model failures causing the graph to freeze. Since the graph is read-only infrastructure, stale graphs affect only new edge discovery — existing positions are unaffected.

On-call actions

Manual overrides

• —

Healthcheck

/internal/health/crossmarketgraph → 200 Last rebuild completed within 2× rebuild_interval_s AND nodes_total > 0 AND no STALE_DATA in last cycle; red if No successful rebuild in > 2× rebuild_interval_s OR embed_failures_total rate > 10/min OR Gamma API unreachable

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%