3.16 CalendarCompression

1. Bot Identity

2. Purpose

CalendarCompression identifies pairs of related Polymarket markets resolving on different dates (e.g. 'Will X happen by June?' vs 'Will X happen by December?') and trades the price differential when it deviates from the fair time-decay spread. The bot buys the underpriced near-expiry leg and/or sells the overpriced far-expiry leg to capture calendar compression.

3. Why This Bot Matters

• Resolution sources differ between pair legs

  Even if markets look related, different oracle sources produce independent resolution paths; the calendar spread is not a true arbitrage.

• Near-expiry market resolves unexpectedly early

  A market may resolve before the expected calendar date (breaking news), collapsing the calendar spread before the far-expiry leg adjusts.

• Both legs resolve YES simultaneously

  If both legs are correlated, a calendar long/short pair may both move adversely on news, doubling losses instead of creating a hedged position.

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

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

{ "max_days_to_resolve": 90 }

if days_to_far_expiry > params.hard: return skip('CAL_PAIR_TOO_LONG_DATED')

{ "require_same_source": true }

if legs[0].source != legs[1].source: return skip('CAL_SOURCE_MISMATCH')

{ "max_position_per_pair": 400 }

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

8. Default Configuration

{
  "bot_id": "strat.calendarcompression",
  "version": "0.1.0",
  "mode": "shadow_only",
  "defaults": {
    "min_gap_bps": 150,
    "max_days_to_resolve": 90,
    "require_same_source": true,
    "max_position_per_pair": 400
  },
  "locked": {
    "require_same_source": {
      "value": true
    },
    "min_gap_bps": {
      "min": 25
    },
    "max_position_per_pair": {
      "max": 800
    }
  }
}

9. Implementation Flow

1. Check KillSwitch; if active, emit no OrderIntents.
2. For each approved calendar pair: verify both legs share the same resolution source.
3. FETCH clob_public metadata for both legs; check resolution dates and open status.
4. Compute days_to_far_expiry; if > 365, skip CAL_PAIR_TOO_LONG_DATED.
5. FETCH ws_market books for both legs; compute near_mid and far_mid.
6. Compute fair_spread from time-decay model; gap_bps = (actual_spread - fair_spread) * 10000.
7. IF gap_bps < hard (25 bps): skip CAL_NO_GAP.
8. IF gap_bps < warning (75 bps): WARN CAL_GAP_MARGINAL; halve size.
9. Compute per-leg size = min(max_position_per_pair/2, available_depth_per_leg).
10. EMIT IOC OrderIntent on underpriced leg; EMIT DecisionReport reason=CAL_SPREAD_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 onPairTick(pair_id, nearBook, farBook):
  ks = FETCH internal.killswitch.status
  IF ks.active: RETURN

  // Source match check
  nearMeta = FETCH clob_public.GET('/markets/' + pair_id.near_market)
  farMeta  = FETCH clob_public.GET('/markets/' + pair_id.far_market)
  IF nearMeta.resolution_source != farMeta.resolution_source:
    EMIT DecisionReport(intent_emitted=false, reason='CAL_SOURCE_MISMATCH')
    RETURN

  // Date range check
  daysToFar = (farMeta.end_date_ms - now_ms()) / 86400000
  IF daysToFar > params.max_days_to_resolve_hard:  // 365
    EMIT DecisionReport(intent_emitted=false, reason='CAL_PAIR_TOO_LONG_DATED')
    RETURN

  // Gap computation
  nearMid = (nearBook.best_bid + nearBook.best_ask) / 2
  farMid  = (farBook.best_bid  + farBook.best_ask)  / 2
  fairSpread = computeFairCalendarSpread(nearMeta, farMeta)
  gapBps = ((farMid - nearMid) - fairSpread) * 10000

  IF gapBps < params.min_gap_bps_hard:  // 25 bps
    IF random() < 0.01:
      EMIT DecisionReport(intent_emitted=false, reason='CAL_NO_GAP')
    RETURN

  sizeMultiplier = 0.5 IF gapBps < params.min_gap_bps_warn ELSE 1.0
  IF sizeMultiplier < 1.0: WARN('CAL_GAP_MARGINAL')

  perLegSize = toPusdUnits(params.max_position_per_pair / 2 * sizeMultiplier)
  EMIT OrderIntent(market=pair_id.near_market, outcome='YES', side='buy',
                   price=nearMid, size_pUSD=perLegSize, tif='IOC', builder=code)
  EMIT DecisionReport(intent_emitted=true, gap_bps=gapBps, reason='CAL_SPREAD_TRADE')

SDK calls used

• ws_market.subscribe('book', [near_market, far_market])
• fetchClobPublic('/markets/' + market_id)
• buildOrderTypedData(orderParams, {name:'CTFExchange', version:'2', chainId:137})

Complexity: O(1) per pair tick

11. Wire Examples

Input — what arrives on the wire

Calendar pair book tick — near leg at 0.42, far at 0.58 — ws_market

{
  "pair_id": "cal_pair_001",
  "near_market_id": "0xcc000000000000000000000000000000000000000000000000000000000000001",
  "far_market_id": "0xcc000000000000000000000000000000000000000000000000000000000000002",
  "near_mid": "0.420",
  "far_mid": "0.580",
  "days_to_far": "62",
  "received_at_ms": 1746790800000
}

Output — what the bot emits

OrderIntent — calendar spread IOC near leg buy YES

{
  "intent_id": "oi_01HCC0000001A",
  "market_id": "0xcc000000000000000000000000000000000000000000000000000000000000001",
  "outcome": "YES",
  "side": "buy",
  "price": "0.420",
  "size_pUSD": "200.00",
  "tif": "IOC",
  "builder": {
    "code": "0x706f6c7974726164657273000000000000000000000000000000000000000000",
    "fee_bps": 25
  },
  "decision": {
    "gap_bps": 180.0,
    "reasons": [
      "CAL_SPREAD_TRADE"
    ]
  }
}

12. Decision Logic

13. Standard Decision Output

This bot returns a OrderIntent object. See OrderIntent schema.

{
  "intent_id": "oi_01HCC0000001A",
  "market_id": "0xcc000000000000000000000000000000000000000000000000000000000000001",
  "outcome": "YES",
  "side": "buy",
  "price": "0.420",
  "size_pUSD": "200.00",
  "tif": "IOC",
  "post_only": false,
  "builder": {
    "code": "0x706f6c7974726164657273000000000000000000000000000000000000000000",
    "fee_bps": 25
  },
  "negrisk_aware": false,
  "decision": {
    "gap_bps": 180.0,
    "pair_id": "cal_pair_001",
    "leg": "near",
    "reasons": [
      "CAL_SPREAD_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.calendarcompression",
  "pair_id": "cal_pair_001",
  "gap_bps": 180.0,
  "leg": "near",
  "intent_emitted": true,
  "reason": "CAL_SPREAD_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, snapshots rebuilt from next ws_market tick for each leg.

21. Concurrency & Idempotency

22. Dependencies

Depends on (must run first)

Emits to (downstream consumers)

External services

23. Security Surfaces

Abuse vectors considered

• Adversary manipulates one leg's metadata to appear as same-source pair
• Stale far-leg price creating phantom calendar gap

Mitigations

• Resolution source comparison uses clob_public authoritative metadata
• Both leg snapshots must be fresh (< 10s) before spread computation

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

CalendarCompression incidents are typically stale leg feeds or kill-switch activations. Source mismatches are expected for pairs that drifted out of configuration.

On-call actions

Manual overrides

• —

Healthcheck

GET /internal/health/calendarcompression -> 200 if All active pair legs have snapshots < 10s; no source mismatches; KillSwitch inactive.. Red: Any leg stale > 60s 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%