1.11 CorrelationShockGuard

1. Bot Identity

Operational profile

2. Purpose

CorrelationShockGuard monitors the rolling pairwise return correlation of open positions and blocks new orders when the portfolio correlation exceeds the configured ceiling. It detects sudden hidden correlation shocks where previously independent markets begin resolving together, increasing tail risk beyond what the capital model assumes.

3. Why This Bot Matters

• Hidden correlation shock

  Markets that appeared independent begin resolving together (e.g. macro shock, shared underlying fact), transforming the portfolio's diversification into concentrated tail risk with no warning.

• New order added during correlation spike

  Adding a new position while portfolio correlation is elevated amplifies the shock exposure instead of providing diversification.

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

{ "max_portfolio_correlation": 0.6 }

if (avgCorr > params.max_portfolio_correlation) return reject('CORRELATION_SHOCK_DETECTED');

{ "lookback_periods": 20 }

corrMatrix = computeRollingCorr(priceSeries, params.lookback_periods);

{ "min_positions_to_check": 3 }

if (openPositions.length < params.min_positions_to_check) return approve('CORRELATION_SHOCK_SKIPPED');

8. Default Configuration

{
  "bot_id": "risk.correlation_shock_guard",
  "version": "0.1.0",
  "mode": "hard_guard",
  "defaults": {
    "max_portfolio_correlation": 0.6,
    "lookback_periods": 20,
    "min_positions_to_check": 3
  },
  "locked": {
    "max_portfolio_correlation": {
      "max": 0.8
    }
  }
}

9. Implementation Flow

1. Receive OrderIntent with market_id and strategy context.
2. Check KillSwitch; if active, HARD_REJECT(KILL_SWITCH_ACTIVE).
3. Load open position list and price series for each from data_api.
4. If open positions < min_positions_to_check, APPROVE immediately (skip).
5. Compute rolling pairwise return correlations over lookback_periods.
6. Compute average pairwise correlation across the matrix.
7. If avg_corr > max_portfolio_correlation.hard, HARD_REJECT(CORRELATION_SHOCK_DETECTED).
8. If avg_corr > max_portfolio_correlation.warning, attach WARN annotation; APPROVE.
9. All checks passed — APPROVE with correlation_score attached.

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 evaluateCorrelation(intent):
  ks = FETCH internal.killswitch.status
  IF ks.active: EMIT RiskVote(HARD_REJECT, KILL_SWITCH_ACTIVE); RETURN

  positions = FETCH internal.open_positions(intent.user_id)
  IF len(positions) < params.min_positions_to_check:
    EMIT RiskVote(APPROVE); RETURN

  priceSeries = {}
  FOR pos IN positions:
    series = FETCH data_api.price_series(pos.market_id, params.lookback_periods)
    IF series IS NULL:
      EMIT RiskVote(HARD_REJECT, CORRELATION_SHOCK_DATA_UNAVAILABLE); RETURN
    priceSeries[pos.market_id] = series

  returns = {m: diff(priceSeries[m]) FOR m IN priceSeries}
  corrMatrix = pairwise_corr(returns)
  avgCorr = mean(upper_triangle(corrMatrix))

  IF avgCorr > params.max_portfolio_correlation:
    EMIT RiskVote(HARD_REJECT, CORRELATION_SHOCK_DETECTED,
                  avg_corr=avgCorr); RETURN
  IF avgCorr > params.max_portfolio_correlation * 0.75:
    annotations.append(WARN(CORRELATION_SHOCK_APPROACHING))

  EMIT RiskVote(APPROVE, correlation_score=avgCorr)

SDK calls used

• data_api.price_series(market_id, lookback)
• internal.open_positions(user_id)
• internal.killswitch.status()

Complexity: O(N^2) where N = number of open positions (max ~20)

11. Wire Examples

Input — what arrives on the wire

OrderIntent — correlation shock active — internal

{
  "intent_id": "int_c3d4e5f6a7b80003",
  "market_id": "0x2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b3c",
  "size_usd": 300,
  "generated_at_ms": 1746800000000
}

Output — what the bot emits

RiskVote — HARD_REJECT

{
  "guard_id": "risk.correlation_shock_guard",
  "decision": "HARD_REJECT",
  "severity": "HARD",
  "reason_code": "CORRELATION_SHOCK_DETECTED",
  "message": "Avg pairwise correlation 0.72 exceeds ceiling 0.60.",
  "constraints": {},
  "checked_at": "2026-05-10T10:00:00Z"
}

12. Decision Logic

13. Standard Decision Output

This bot returns a RiskVote object. See RiskVote schema.

{
  "guard_id": "risk.correlation_shock_guard",
  "decision": "HARD_REJECT",
  "severity": "HARD",
  "reason_code": "CORRELATION_SHOCK_DETECTED",
  "message": "Portfolio avg pairwise correlation 0.72 exceeds hard ceiling 0.60. New orders blocked.",
  "constraints": {},
  "inputs_used": [
    "data_api.price_series",
    "internal.positions",
    "internal.killswitch.status"
  ],
  "checked_at": "2026-05-10T10:00:00Z"
}

14. Reason Codes

15. Metrics & Logs

Metrics emitted

Alerts

16. Developer Reporting

{
  "bot_id": "risk.correlation_shock_guard",
  "decision": "HARD_REJECT",
  "reason_code": "CORRELATION_SHOCK_DETECTED",
  "inputs_used": [
    "data_api.price_series",
    "internal.positions"
  ],
  "metrics": {
    "avg_pairwise_corr": 0.72,
    "num_positions": 5,
    "lookback_periods": 20,
    "hard_ceiling": 0.6
  },
  "checked_at": "2026-05-10T10:00:00Z"
}

17. Plain-English Reporting

18. Failure-Mode Block

19. Failure-Injection Recipes

20. State & Persistence

Cold-start recovery

On cold start, price series is populated from data_api before first evaluation. Insufficient data causes check to be skipped.

21. Concurrency & Idempotency

22. Dependencies

Depends on (must run first)

Emits to (downstream consumers)

External services

23. Security Surfaces

Abuse vectors considered

• Injecting manipulated price data to artificially lower apparent correlation
• Submitting orders rapidly before correlation spike is detected

Mitigations

• Price series sourced exclusively from data_api with provenance timestamp validation
• Idempotency deduplication prevents rapid concurrent submissions from the same user

24. Polymarket V2 Compatibility

25. Versioning & Migration

Migration history

26. Acceptance Tests

Unit Tests

Integration Tests

Property Tests

27. Operational Runbook

CorrelationShockGuard incidents are typically caused by a macro market event driving correlated resolution across multiple markets. Verify the correlation is genuine before pausing the guard.

On-call actions

Manual overrides

• polytraders risk disable-check risk.correlation_shock_guard --duration 300s — During a known data feed issue causing false data unavailability rejections; requires risk pod lead approval.

Healthcheck

GET /internal/health/correlationshockguard → green: data_api reachable, price series populated for all tracked positions, avg_corr below warning threshold; red: data_api unreachable, price series stale > lookback_periods, or avg_corr above hard ceiling

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%