RiskGate

Why this is a page and not a convention

The bot interface already says a bot "must not submit orders directly". That is a convention, and a convention is a reasonable control for code we write and review. It is not a control for code a stranger uploads. RiskGate turns the convention into structure: user code physically cannot hold a signer, so the rule holds whether or not the author intended to follow it.

The path

proposal  (user bot | AI suggestion | manual | our strategy)
    │
    ├─ 1. ADMISSION      scope, schema, freshness, bot state
    │                    reject ⇒ RISK_ADMISSION_*
    │
    ├─ 2. HARD GUARDRAILS run in order, any REJECT ends it
    │      killswitch          → RISK_KILLSWITCH_TRIPPED
    │      compliancegate      → RISK_GEOFENCE_BLOCK
    │      markethaltguard     → RISK_MARKET_HALTED
    │      stalebookguard      → RISK_BOOK_STALE_15S
    │      selftradewashguard  → RISK_SELF_TRADE
    │      contractaddrguard   → SEC_CONTRACT_MISMATCH
    │
    ├─ 3. ENVELOPE CHECKS user-tunable above the platform floor
    │      exposureguard       → RISK_EXPOSURE_CAP
    │      drawdownguard       → RISK_DRAWDOWN_LIMIT
    │      correlationshock    → RISK_CORRELATED_EXPOSURE
    │      liquidityguard      → RISK_INSUFFICIENT_DEPTH
    │      feeandgasguard      → RISK_FEE_UNECONOMIC
    │
    ├─ 4. SHAPING         may downsize or re-price, never flip direction
    │      smartrouter, antitoxicfill, pricebandvalidator,
    │      queuewarden, fee_slippage_estimator
    │
    ├─ 5. ATOMIC RESERVE  reserve exposure INCLUDING pending + partials
    │                    reject ⇒ RISK_RESERVE_CONFLICT
    │
    ├─ 6. SIGN            scoped session key, method whitelist
    │                    refusal ⇒ SEC_SIGNATURE_REFUSED
    │
    └─ 7. SUBMIT + RECONCILE
                         mismatch ⇒ freeze, GOV_RECONCILE_MISMATCH

What the user may and may not change

Three caps, not one

A frequent design error is a single per-order cap. Three independent caps are required, and a proposal must satisfy all three:

• Per order. The obvious one. Cheap to check, weakest protection.
• Per bot. Aggregate open exposure for one user bot, including pending orders and partial fills. This is what stops a bot from opening the same position sixty times in a minute.
• Per account. Aggregate across every bot the user runs, plus manual positions. This is what stops twenty bots each individually within budget from collectively concentrating the whole bankroll into one correlated bet.

Correlation is a first-class cap

Prediction markets correlate in ways that are not obvious from market ids. Two markets on the same game, on the same team's season, on the same election, or resolving from the same oracle are one bet wearing several hats. The chain therefore evaluates a correlation cluster, not a market, using intel.crossmarketgraph and risk.correlationshockguard.

• Same event, different market phrasing — treated as one cluster.
• Same resolution source — oracle-risk correlated even when the questions differ.
• Same underlying (team, candidate, ticker) across dates — correlated with decay.
• Negative-risk sets that must sum to one — algebraically linked, not merely correlated.

The user's max_correlated_exposure_pct applies to the cluster. A user who does not understand this will otherwise believe they hold six diversified positions while holding one position six times.

Reject, reshape, quarantine

Every outcome carries a code from the reason-code registry. Free text is not an acceptable substitute: the user's log, the notification, the audit trail, and the analytics all key off the code.

Failing closed

If a guardrail cannot reach the data it needs to make a decision, the answer is REJECT. Not "allow because the check is unavailable". This is the single most common way trading systems lose money in ways nobody predicted, and it usually enters the codebase as a reasonable-looking try/catch with a permissive default.

// WRONG — fails open. Ships as a "resilience" improvement.
try { vote = await exposureGuard.check(intent); }
catch { vote = ALLOW; }

// RIGHT — fails closed, and says why.
try { vote = await exposureGuard.check(intent); }
catch (e) { vote = REJECT("RISK_GUARD_UNAVAILABLE", { guard: "exposure", err: e }); }