3.7 Cross-Venue Arb

1. Bot Identity

2. Purpose

Cross-Venue Arb identifies price divergences between Polymarket and external prediction markets (Kalshi, PredictIt) that share an identical resolution source, then emits an OrderIntent to trade the cheaper leg on Polymarket. Both venues must resolve via the same authority; any mismatch blocks the trade.

3. Why This Bot Matters

• Resolution source mismatch

  Two venues may look identical but resolve differently. Trading on a false parity creates an unhedged directional position rather than an arbitrage.

• Stale external venue data

  Cross-venue prices update asynchronously. Stale Kalshi or PredictIt snapshots produce phantom gaps that evaporate before the order lands.

• Fee drag understated

  Both venues charge fees; if min_gap_bps_after_fees is set too low, ostensible arb edges are consumed by combined fee drag leaving no profit.

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_gap_bps_after_fees": 150 }

if gap_bps < params.hard: return skip('CROSS_VENUE_NO_EDGE')

{ "require_resolution_source_match": true }

if not sources_match(pm_market, ext_market): return skip('CROSS_VENUE_SOURCE_MISMATCH')

{ "allowed_venues": ["kalshi", "predictit"] }

if venue not in params.allowed_venues: skip()

{ "manual_approval_required": true }

if not pair_approved(pm_id, ext_id): return skip('CROSS_VENUE_PAIR_NOT_APPROVED')

8. Default Configuration

{
  "bot_id": "strat.cross_venue_arb",
  "version": "0.1.0",
  "mode": "shadow_only",
  "defaults": {
    "min_gap_bps_after_fees": 150,
    "require_resolution_source_match": true,
    "manual_approval_required": true
  },
  "locked": {
    "require_resolution_source_match": {
      "value": true
    },
    "min_gap_bps_after_fees": {
      "min": 30
    }
  }
}

9. Implementation Flow

1. Check KillSwitch; if active, emit no OrderIntents.
2. For each approved (pm_market, ext_market) pair: verify resolution sources match.
3. FETCH clob_public market status; skip if closed or resolved.
4. FETCH ws_market book for pm_market; FETCH external venue snapshot for ext_market.
5. Compute gap_bps = (ext_price - pm_mid) * 10000 (or reverse if ext cheaper).
6. Deduct estimated fees from both venues; compute net_gap_bps.
7. IF net_gap_bps < hard (30 bps): SKIP, emit sampled DecisionReport CROSS_VENUE_NO_EDGE.
8. IF net_gap_bps < warning (80 bps): WARN CROSS_VENUE_EDGE_MARGINAL; reduce size 50%.
9. Compute order size = min(max_position_per_pair_usd, available_depth_usd).
10. EMIT IOC OrderIntent: side=buy, price=best_ask_pm, size_pUSD=orderSize, builder=code.
11. EMIT DecisionReport with intent_emitted=true, gap_bps, venues, reason CROSS_VENUE_EDGE_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 onSnapshot(pair_id, pmMarket, extMarket, pmMid, extPrice):
  ks = FETCH internal.killswitch.status
  IF ks.active: RETURN

  // Verify resolution source match
  pmMeta = FETCH clob_public.GET('/markets/' + pmMarket)
  IF pmMeta.resolution_source != extMarket.resolution_source:
    EMIT DecisionReport(intent_emitted=false, reason='CROSS_VENUE_SOURCE_MISMATCH')
    RETURN

  IF pmMeta.closed OR pmMeta.resolved: RETURN

  // Check snapshot freshness
  IF snapshotAge(extMarket) > 10000:  // ms
    EMIT DecisionReport(intent_emitted=false, reason='STALE_MARKET_DATA')
    RETURN

  // Compute gap
  rawGap = (extPrice - pmMid) * 10000
  fees = estimatedFees(pmMid)
  netGap = rawGap - fees

  IF netGap < params.min_gap_bps_after_fees_hard:  // 30 bps
    IF random() < 0.01:
      EMIT DecisionReport(intent_emitted=false, reason='CROSS_VENUE_NO_EDGE')
    RETURN

  sizeMultiplier = 0.5 IF netGap < params.min_gap_bps_after_fees_warn ELSE 1.0
  IF sizeMultiplier < 1.0: WARN('CROSS_VENUE_EDGE_MARGINAL')

  depth = FETCH clob_public.depth(pmMarket)
  orderSize = toPusdUnits(min(params.max_position_per_pair_usd * sizeMultiplier, depth.available))

  EMIT OrderIntent(market=pmMarket, outcome='YES', side='buy', price=pmMid,
                   size_pUSD=orderSize, tif='IOC', builder=internalBuilderCode)
  EMIT DecisionReport(intent_emitted=true, gap_bps=netGap, reason='CROSS_VENUE_EDGE_TRADE')

SDK calls used

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

Complexity: O(1) per snapshot per approved pair

11. Wire Examples

Input — what arrives on the wire

Cross-venue snapshot — Kalshi YES at 0.627, PM mid at 0.610 — internal (cross-venue adapter)

{
  "pair_id": "cvp_kalshi_001",
  "pm_market_id": "0xcva0000000000000000000000000000000000000000000000000000000000001",
  "pm_mid": "0.610",
  "ext_venue": "kalshi",
  "ext_price": "0.627",
  "snapshot_age_ms": 800,
  "received_at_ms": 1746790800000
}

Output — what the bot emits

OrderIntent — cross-venue IOC buy YES

{
  "intent_id": "oi_01HCVA0000001A",
  "market_id": "0xcva0000000000000000000000000000000000000000000000000000000000001",
  "outcome": "YES",
  "side": "buy",
  "price": "0.610",
  "size_pUSD": "200.00",
  "tif": "IOC",
  "builder": {
    "code": "0x706f6c7974726164657273000000000000000000000000000000000000000000",
    "fee_bps": 25
  },
  "decision": {
    "gap_bps": 165.0,
    "reasons": [
      "CROSS_VENUE_EDGE_TRADE"
    ]
  }
}

12. Decision Logic

13. Standard Decision Output

This bot returns a OrderIntent object. See OrderIntent schema.

{
  "intent_id": "oi_01HCVA0000001A",
  "trace_id": "tr_01HCVA000TR001",
  "market_id": "0xcva0000000000000000000000000000000000000000000000000000000000001",
  "outcome": "YES",
  "side": "buy",
  "price": "0.610",
  "size_pUSD": "200.00",
  "tif": "IOC",
  "post_only": false,
  "builder": {
    "code": "0x706f6c7974726164657273000000000000000000000000000000000000000000",
    "fee_bps": 25
  },
  "negrisk_aware": false,
  "decision": {
    "gap_bps": 165.0,
    "pm_mid": 0.61,
    "ext_price": 0.627,
    "venues": [
      "polymarket",
      "kalshi"
    ],
    "reasons": [
      "CROSS_VENUE_EDGE_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.cross_venue_arb",
  "market_id": "0xcva0000000000000000000000000000000000000000000000000000000000001",
  "pm_mid": 0.61,
  "ext_price": 0.627,
  "gap_bps": 165.0,
  "net_gap_bps": 155.0,
  "intent_emitted": true,
  "reason": "CROSS_VENUE_EDGE_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, external snapshots rebuilt from next polling cycle; pair approval loaded from config.

21. Concurrency & Idempotency

22. Dependencies

Depends on (must run first)

Emits to (downstream consumers)

External services

23. Security Surfaces

Abuse vectors considered

• Adversary injects stale cross-venue snapshots to create phantom arb gaps
• Resolution source metadata spoofing to bypass source-match gate

Mitigations

• Cross-venue snapshots have a 10s staleness threshold
• Resolution source comparison uses Polymarket's authoritative clob_public metadata, not user input
• Manual pair approval required before bot trades any new pair

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-Venue Arb incidents are typically stale external feed snapshots (blocking all trades for affected pairs) or kill-switch activations. Source mismatches are expected and logged; escalate only if a previously approved pair suddenly mismatches.

On-call actions

Manual overrides

• —

Healthcheck

GET /internal/health/cross-venue-arb -> 200 if External snapshots age < 10s; ≥1 approved pair active; KillSwitch inactive.. Red: All external feeds stale 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%