1.13 TailLossSimulator

1. Bot Identity

Operational profile

2. Purpose

TailLossSimulator applies scripted adverse shock scenarios to the combined portfolio (open positions plus the proposed order) and rejects or downsizes the order if the simulated tail loss exceeds the configured maximum. It acts as a pre-trade stress test, replacing post-hoc margin calls with a forward-looking gate.

3. Why This Bot Matters

• Tail loss unquantified before sizing up

  Adding a new position without a stress test can push the portfolio into a tail regime where a single adverse resolution event causes losses far beyond the user's tolerance.

• Correlated shock undetected

  A scripted scenario that resolves all markets in the same direction reveals hidden concentration risk that individual position limits would miss.

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_tail_loss_usd": 500 }

if (maxScenarioLoss > params.max_tail_loss_usd) return reshape_or_reject('TAIL_LOSS_EXCEEDED');

{ "shock_scenarios": ["all_yes_resolves", "all_no_resolves", "macro_adverse_shift"] }

const scenarioLosses = params.shock_scenarios.map(s => runScenario(portfolio, s));

{ "tail_percentile": 0.05 }

const tailLoss = cvar(scenarioLossDistribution, params.tail_percentile);

8. Default Configuration

{
  "bot_id": "risk.tail_loss_simulator",
  "version": "0.1.0",
  "mode": "hard_guard",
  "defaults": {
    "max_tail_loss_usd": 500,
    "shock_scenarios": [
      "all_yes_resolves",
      "all_no_resolves",
      "macro_adverse_shift"
    ],
    "tail_percentile": 0.05
  },
  "locked": {
    "max_tail_loss_usd": {
      "min": 50
    }
  }
}

9. Implementation Flow

1. Receive OrderIntent with market_id, side, size_usd.
2. Check KillSwitch; if active, HARD_REJECT(KILL_SWITCH_ACTIVE).
3. Load open positions and current prices to construct current portfolio state.
4. Append proposed order to the portfolio (as if filled).
5. Load shock scenario library and run each configured scenario against the proposed portfolio.
6. For each scenario, compute the portfolio value change (loss if negative).
7. Take the maximum loss across all scenarios as the tail loss estimate.
8. If tail_loss > max_tail_loss_usd.hard: compute safe_size_usd that would keep tail_loss within limit.
9. If safe_size_usd > 0: RESHAPE with constraints.max_size_usd = safe_size_usd. Else HARD_REJECT(TAIL_LOSS_EXCEEDED).
10. If tail_loss > max_tail_loss_usd.warning: attach WARN annotation; APPROVE.
11. All checks passed — APPROVE with worst_case_loss 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 evaluateTailLoss(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)
  prices = FETCH clob_public.prices(ALL position.market_ids)
  scenarios = FETCH internal.shock_scenario_library()
  IF positions IS NULL OR prices IS NULL OR scenarios IS NULL:
    EMIT RiskVote(HARD_REJECT, TAIL_LOSS_DATA_UNAVAILABLE); RETURN

  proposedPortfolio = positions + [intent as position]
  scenarioLosses = []
  FOR scenario IN params.shock_scenarios:
    shockedPrices = applyShock(prices, scenarios[scenario])
    pnl = computePortfolioPnL(proposedPortfolio, shockedPrices)
    scenarioLosses.append(-pnl if pnl < 0 else 0)

  tailLoss = max(scenarioLosses)

  IF tailLoss > params.max_tail_loss_usd:
    safeSize = binarySearchSafeSize(positions, intent, scenarios, prices, params)
    IF safeSize > 0:
      EMIT RiskVote(RESHAPE_REQUIRED, TAIL_LOSS_EXCEEDED,
                    constraints={max_size_usd: safeSize}); RETURN
    EMIT RiskVote(HARD_REJECT, TAIL_LOSS_EXCEEDED); RETURN

  IF tailLoss > params.max_tail_loss_usd * 0.8:
    annotations.append(WARN(TAIL_LOSS_APPROACHING, tail_loss=tailLoss))

  EMIT RiskVote(APPROVE, worst_case_loss=tailLoss)

SDK calls used

• clob_public.prices(market_ids)
• internal.open_positions(user_id)
• internal.shock_scenario_library()
• internal.killswitch.status()

Complexity: O(S * N) where S = scenarios (default 3), N = open positions

11. Wire Examples

Input — what arrives on the wire

OrderIntent — tail loss would be exceeded — internal

{
  "intent_id": "int_e5f6a7b8c9d00005",
  "market_id": "0x3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d",
  "size_usd": 500,
  "side": "BUY",
  "generated_at_ms": 1746800000000
}

Output — what the bot emits

RiskVote — RESHAPE_REQUIRED

{
  "guard_id": "risk.tail_loss_simulator",
  "decision": "RESHAPE_REQUIRED",
  "severity": "WARN",
  "reason_code": "TAIL_LOSS_EXCEEDED",
  "message": "Tail loss 620 pUSD under 'all_yes_resolves' exceeds 500. Resized to 320.",
  "constraints": {
    "max_size_usd": 320
  },
  "checked_at": "2026-05-10T12:00:00Z"
}

12. Decision Logic

13. Standard Decision Output

This bot returns a RiskVote object. See RiskVote schema.

{
  "guard_id": "risk.tail_loss_simulator",
  "decision": "RESHAPE_REQUIRED",
  "severity": "WARN",
  "reason_code": "TAIL_LOSS_EXCEEDED",
  "message": "Proposed order produces tail loss 620 pUSD under scenario 'all_yes_resolves'. Resized to keep tail loss <= 500 pUSD.",
  "constraints": {
    "max_size_usd": 320
  },
  "inputs_used": [
    "internal.positions",
    "internal.shock_scenarios",
    "clob_public.prices"
  ],
  "checked_at": "2026-05-10T12:00:00Z"
}

14. Reason Codes

15. Metrics & Logs

Metrics emitted

Alerts

16. Developer Reporting

{
  "bot_id": "risk.tail_loss_simulator",
  "decision": "RESHAPE_REQUIRED",
  "reason_code": "TAIL_LOSS_EXCEEDED",
  "inputs_used": [
    "internal.positions",
    "internal.shock_scenarios",
    "clob_public.prices"
  ],
  "metrics": {
    "worst_scenario": "all_yes_resolves",
    "tail_loss_usd": 620,
    "safe_size_usd": 320,
    "max_tail_loss_usd": 500
  },
  "checked_at": "2026-05-10T12:00:00Z"
}

17. Plain-English Reporting

18. Failure-Mode Block

19. Failure-Injection Recipes

20. State & Persistence

Cold-start recovery

On cold start, portfolio snapshot fetched from CLOB before first evaluation. Scenario library loaded from Redis.

21. Concurrency & Idempotency

22. Dependencies

Depends on (must run first)

Emits to (downstream consumers)

External services

23. Security Surfaces

Abuse vectors considered

• Submitting a low-notional order to establish a position then sizing up in a second order after the first passes the stress test
• Manipulating the position cache to show a smaller portfolio, reducing apparent tail risk

Mitigations

• Portfolio snapshot is refreshed every 10s from CLOB, limiting the staleness window
• Idempotency deduplication prevents rapid sequential submissions from bypassing the per-intent evaluation

24. Polymarket V2 Compatibility

25. Versioning & Migration

Migration history

26. Acceptance Tests

Unit Tests

Integration Tests

Property Tests

27. Operational Runbook

TailLossSimulator incidents are typically caused by a concentrated portfolio approaching the tail loss ceiling, or by stale scenario data. Verify the scenario library is current before adjusting parameters.

On-call actions

Manual overrides

• polytraders risk update-scenarios --scenario-file <path> — After a market structure change that requires new or revised shock scenarios.

Healthcheck

GET /internal/health/taillosssimulator → green: Scenario library loaded, CLOB prices reachable, portfolio snapshot age < 30s; red: Scenario library missing, CLOB unreachable, or snapshot age > 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%