3.6 Cross-Market Arb

1. Bot Identity

2. Purpose

Cross-Market Arb detects logically constrained relationships between pairs of Polymarket binary markets — e.g. 'Candidate A wins primary' should price at or below 'Candidate A wins general', or 'Team X advances to semi-final' should price at or below 'Team X wins tournament'. When the logical constraint is violated by more than tolerance_bps (after fee buffer), the bot emits a pair of OrderIntents (one per market) to exploit the mispricing. Market pairs must pass manual review before the bot will trade them (require_manual_pair_review=true). This is a user-controlled execution tool; it does not copy trades or make performance claims.

3. Why This Bot Matters

• Logically distinct markets paired incorrectly

  A pair that looks logically constrained but has different resolution conditions may diverge legitimately. Trading a false constraint produces losses when both markets resolve consistently with their actual rules.

• One market resolves while the paired order is still resting

  If market A resolves YES and the paired market B order has not filled, the bot holds a one-sided position with no offsetting settlement path.

• Tolerance_bps too tight on high-spread markets

  The bot may fire on transient spread noise rather than genuine constraint violations, incurring fee costs with no structural edge.

• feeRateBps present on signed order (V1 pattern)

  CTFExchangeV2 rejects orders with feeRateBps. Fees are operator-set at match time. No leg intent may 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

{ "tolerance_bps": 30 }

if violation_bps < params.hard: return skip('CROSS_MARKET_ARB_NO_EDGE')

{ "min_similarity_score": 0.82 }

if similarity < params.hard: raise ConfigError('CROSS_MARKET_ARB_LOW_SIMILARITY')

{ "require_manual_pair_review": true }

assert params.require_manual_pair_review == True

{ "max_legs": 2 }

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

8. Default Configuration

{
  "bot_id": "strat.cross_market_arb",
  "version": "2.1.0",
  "mode": "limited_live",
  "defaults": {
    "tolerance_bps": 30,
    "min_similarity_score": 0.82,
    "require_manual_pair_review": true,
    "max_legs": 2
  },
  "locked": {
    "tolerance_bps": {
      "min": 5
    },
    "min_similarity_score": {
      "min": 0.6
    },
    "require_manual_pair_review": {
      "value": true
    },
    "max_legs": {
      "max": 4
    }
  }
}

9. Implementation Flow

1. Check KillSwitch active flag; if active, emit no OrderIntents.
2. Load registered market-pair registry (manually reviewed pairs only).
3. Subscribe to ws_market book updates for all markets in active pairs.
4. On each book tick: retrieve the latest best-ask for each market in the pair.
5. Validate book freshness (last_seen < 5s); if stale, emit STALE_MARKET_DATA and skip.
6. Confirm both markets in the pair are open and not resolved (clob_public).
7. Compute violation_bps = (p_market_A - p_market_B) * 10000 for pairs where A logically implies B.
8. If violation_bps < tolerance_bps hard floor (5 bps), emit sampled DecisionReport CROSS_MARKET_ARB_NO_EDGE and skip.
9. If violation_bps < warning threshold (30 bps), WARN CROSS_MARKET_ARB_VIOLATION_MARGINAL; reduce leg sizes by 50%.
10. Fetch top-of-book depth for both markets; set legSize = min(depth_A, depth_B, per-leg budget).
11. Emit OrderIntent for market A (sell YES / buy NO — the overpriced side).
12. Emit OrderIntent for market B (buy YES — the underpriced side).
13. Note: fees are operator-set at match time in V2 — feeRateBps is NOT on any signed order.
14. Emit DecisionReport with intent_emitted=true, violation_bps, pair_id, reason CROSS_MARKET_ARB_EDGE_DETECTED.

10. Reference Implementation

Subscribes to CLOB WebSocket book updates for registered market pairs, checks for logical-constraint violations above tolerance_bps, and emits FOK OrderIntents on both legs when a violation is confirmed.

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

FUNCTION evaluatePair(pair_id, bookTick):
  // --- 0. KillSwitch gate ---
  ks = FETCH internal.killswitch.status
  IF ks.active: RETURN

  // --- 1. Registry check ---
  pair = FETCH internal.pairRegistry.get(pair_id)
  IF NOT pair OR NOT pair.manually_approved:
    EMIT DecisionReport(intent_emitted=false, reason='CROSS_MARKET_ARB_PAIR_NOT_APPROVED')
    RETURN

  // --- 2. Staleness check ---
  IF isStale(bookTick, maxAgeS=5):
    EMIT DecisionReport(intent_emitted=false, reason='STALE_MARKET_DATA')
    RETURN

  // --- 3. Market status check ---
  mktA = FETCH clob_public.GET('/markets/' + pair.market_id_A)
  mktB = FETCH clob_public.GET('/markets/' + pair.market_id_B)
  IF mktA.closed OR mktA.resolved OR mktB.closed OR mktB.resolved:
    CANCEL_RESTING_LEGS(pair_id)
    EMIT DecisionReport(intent_emitted=false, reason='MARKET_CLOSED')
    RETURN

  // --- 4. Constraint violation check (A implies B, so p_A should <= p_B) ---
  p_A = bookTick.market_A.best_ask
  p_B = bookTick.market_B.best_ask
  violation_bps = (p_A - p_B) * 10000

  // --- 5. Hard floor ---
  IF violation_bps < params.tolerance_bps_hard:  // 5 bps
    IF random() < 0.01:
      EMIT DecisionReport(intent_emitted=false, reason='CROSS_MARKET_ARB_NO_EDGE', violation_bps=violation_bps)
    RETURN

  // --- 6. Warning threshold ---
  sizeMultiplier = 1.0
  IF violation_bps < params.tolerance_bps:  // 30 bps default
    WARN('CROSS_MARKET_ARB_VIOLATION_MARGINAL')
    sizeMultiplier = 0.5

  // --- 7. Size and emit legs ---
  depthA = FETCH clob_public.depth(pair.market_id_A)
  depthB = FETCH clob_public.depth(pair.market_id_B)
  legSize = toPusdUnits(min(depthA, depthB, legBudget) * sizeMultiplier)

  // Sell the overpriced side (market A)
  EMIT OrderIntent(market_id=pair.market_id_A, outcome='YES', side='sell',
                   price=p_A, size_pUSD=legSize, tif='FOK',
                   builder={code: internal.builder_code, fee_bps: 25})
  // Buy the underpriced side (market B)
  EMIT OrderIntent(market_id=pair.market_id_B, outcome='YES', side='buy',
                   price=p_B, size_pUSD=legSize, tif='FOK',
                   builder={code: internal.builder_code, fee_bps: 25})

  EMIT DecisionReport(intent_emitted=true, violation_bps=violation_bps,
                      pair_id=pair_id, reason='CROSS_MARKET_ARB_EDGE_DETECTED')

SDK calls used

• fetchClobPublic('/markets/' + market_id)
• ws_market.subscribe('book', [market_id_A, market_id_B])
• toPusdUnits(rawFloat)
• buildOrderTypedData(orderParams, { name: 'CTFExchange', version: '2', chainId: 137 })
• internal.killswitch.status()
• internal.pairRegistry.get(pair_id)
• internal.builder_code

Complexity: O(1) per market pair per book tick

11. Wire Examples

Input — what arrives on the wire

Pair book tick — constraint violation detected (45 bps) — ws_market

{
  "pair_id": "pair_nominee_vs_winner_0042",
  "market_id_A": "0xcrossma000000000000000000000000000000000000000000000000000000001b",
  "market_id_B": "0xcrossma000000000000000000000000000000000000000000000000000000001a",
  "p_A_best_ask": "0.455",
  "p_B_best_ask": "0.410",
  "violation_bps": "45.0",
  "depth_A_pusd": "380.00",
  "depth_B_pusd": "290.00",
  "received_at_ms": 1746790200000
}

Output — what the bot emits

OrderIntent — market B leg (buy, FOK, builder-attributed)

{
  "intent_id": "oi_01HXCMA00001AA",
  "trace_id": "tr_01HXCMA0000TR1",
  "market_id": "0xcrossma000000000000000000000000000000000000000000000000000000001a",
  "outcome": "YES",
  "side": "buy",
  "price": "0.410",
  "size_pUSD": "250.00",
  "tif": "FOK",
  "post_only": false,
  "builder": {
    "code": "0x706f6c7974726164657273000000000000000000000000000000000000000000",
    "fee_bps": 25
  },
  "negrisk_aware": false,
  "decision": {
    "pair_id": "pair_nominee_vs_winner_0042",
    "violation_bps": 45.0,
    "leg": "underpriced_B",
    "reasons": [
      "CROSS_MARKET_ARB_EDGE_DETECTED"
    ]
  },
  "comment": "fees are operator-set at match time in V2 — feeRateBps is NOT on the signed order"
}

DecisionReport — skipped (no edge), sampled 1/100

{
  "report_id": "dr_01HXCMA999ZZZ",
  "bot_id": "strat.cross_market_arb",
  "pair_id": "pair_nominee_vs_winner_0042",
  "intent_emitted": false,
  "violation_bps": 2.1,
  "reasons": [
    "CROSS_MARKET_ARB_NO_EDGE"
  ],
  "sampled": true,
  "evaluated_at_ms": 1746790201000
}

12. Decision Logic

13. Standard Decision Output

This bot returns a OrderIntent object. See OrderIntent schema.

{
  "intent_id": "oi_01HXCMA00001AA",
  "trace_id": "tr_01HXCMA0000TR1",
  "market_id": "0xcrossma000000000000000000000000000000000000000000000000000000001a",
  "outcome": "YES",
  "side": "buy",
  "price": "0.410",
  "size_pUSD": "250.00",
  "tif": "FOK",
  "post_only": false,
  "builder": {
    "code": "0x706f6c7974726164657273000000000000000000000000000000000000000000",
    "fee_bps": 25
  },
  "negrisk_aware": false,
  "decision": {
    "pair_id": "pair_nominee_vs_winner_0042",
    "violation_bps": 45.0,
    "leg": "underpriced_B",
    "reasons": [
      "CROSS_MARKET_ARB_EDGE_DETECTED"
    ]
  },
  "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 / CrossMarketArb violation distribution per pair
• Grafana — Strategy / CrossMarketArb active pairs and intent throughput

16. Developer Reporting

{
  "bot_id": "strat.cross_market_arb",
  "pair_id": "pair_nominee_vs_winner_0042",
  "market_A": "0xcrossma000000000000000000000000000000000000000000000000000000001b",
  "market_B": "0xcrossma000000000000000000000000000000000000000000000000000000001a",
  "p_A": 0.455,
  "p_B": 0.41,
  "violation_bps": 45.0,
  "leg_size_pusd": 250.0,
  "intent_emitted": true,
  "reason": "CROSS_MARKET_ARB_EDGE_DETECTED",
  "emitted_at_ms": 1746790200000
}

17. Plain-English Reporting

18. Failure-Mode Block

19. Failure-Injection Recipes

20. State & Persistence

Cold-start recovery

On cold start, resting leg IDs re-fetched from clob_auth. Book state rebuilt from first ws_market tick per market.

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

• Adversary manufactures a pair violation by moving one market via a large spoof order
• Replaying a signed OrderIntent after the constraint violation has closed
• Injecting a new pair into the registry by bypassing the manual review gate

Mitigations

• All legs use FOK; partial fills are rejected rather than leaving naked positions
• V2 order timestamp(ms) invalidates replays outside the exchange acceptance window
• Pair registry mutations require operator authentication and manual approval flag
• Book staleness check (5s) prevents acting on adversarially manipulated prices

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

Cross-Market Arb incidents are typically stale feeds, market resolutions mid-trade (requiring manual pair review), or false constraint violations from thin-book manipulation. Stale feed incidents resolve automatically; market resolution events require ops review.

On-call actions

Manual overrides

• —
• —

Healthcheck

GET /internal/health/cross-market-arb -> 200 if ws_market feed last_seen < 5s for all active pair markets, Redis reachable, KillSwitch inactive, at least one pair evaluated in last 60s.

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%