# RiskState

> Decision and risk infrastructure for crypto capital

RiskState is three deterministic engines sharing one audit trail, for BTC/USD and ETH/USD (spot, perpetual futures, DeFi borrowing):

1. **Structure Engine (navigator)** — "Are we near an inflection?" Maps the market's structure: breakout/breakdown triggers, the 180-day range, friction levels, and validated events with a public, base-rate-adjusted track record. `POST https://api.riskstate.ai/v1/market-structure` (API key). Live view: https://app.riskstate.ai/structure
2. **Playbook Engine (strategist)** — "Is there a setup to trade?" A locked registry of pre-defined setups evaluated live against market state; every fire carries the navigator's vote and the gate's verdict. `GET https://api.riskstate.ai/api/playbook-data` (public, no key). Live view: https://app.riskstate.ai/playbooks
3. **Risk Engine (governor)** — "How much is allowed?" Live market state in, a pre-trade gate out: policy level, max exposure, leverage cap, allowed/blocked actions, and a SHA-256 policy hash. `POST https://api.riskstate.ai/v1/risk-state` (API key). Portfolio-level v2: aggregation, stress scenarios, loss distributions. Live view: https://app.riskstate.ai/risk-gate

The engines do not predict prices or execute trades. They describe the market, say when a pre-defined setup is live, and govern how much risk is permitted — every decision hashed and measured against forward returns.

## Risk Engine endpoint

POST https://api.riskstate.ai/v1/risk-state

Authentication: Bearer token (API key)
Content-Type: application/json

### Request

```json
{
  "asset": "BTC",
  "include_details": true
}
```

### Response (simplified)

```json
{
  "exposure_policy": {
    "policy_level": "CAUTIOUS",
    "max_size_pct": 47,
    "max_leverage": "1.5x",
    "allowed_actions": ["DCA", "WAIT", "LIMIT_LONG_CONFIRMED"],
    "blocked_actions": ["LEVERAGE_GT_2X", "NEW_SHORT"],
    "binding_constraint": {
      "source": "MACRO",
      "reason": "Risk-off macro environment with normal coupling"
    }
  },
  "classification": {
    "market_regime": "RANGE",
    "cycle_phase": "POST-PEAK",
    "direction": "SIDEWAYS",
    "composite_score": 48
  }
}
```

## Assets Supported

- BTC (Bitcoin)
- ETH (Ethereum)

## Integration Methods

- REST API: three endpoints, one per engine (see above)
- Remote MCP (keyless, for claude.ai and ChatGPT custom connectors): https://api.riskstate.ai/mcp — tools: get_risk_state, get_market_structure, get_playbook_status. Setup: https://riskstate.ai/connect
- MCP server (npm, full responses, API key): @riskstate/mcp-server — tools: get_risk_state, get_market_structure, get_playbook_status, check_trade
- SDKs: npm @riskstate/market-structure-engine, @riskstate/trading-playbook-engine · PyPI riskstate-market-structure, riskstate-trading-playbook
- SKILL.md: agent discovery — https://github.com/Riskstate/risk-engine/blob/main/SKILL.md
- Reference agent architectures: https://riskstate.ai/agent-setups

## Documentation

- API Reference (v1, production-stable): https://riskstate.ai/docs/api
- API Reference (v2 alpha — portfolio aggregation, stress scenarios, shadow backtest, probabilistic loss distributions): https://riskstate.ai/docs/api-v2
- Methodology: https://riskstate.ai/docs/methodology
- Backtest framework: https://riskstate.ai/docs/backtest
- Audit Log: https://riskstate.ai/docs/audit
- Policy Config: https://riskstate.ai/docs/policy-config
- Institutional Integration Guide: https://riskstate.ai/docs/institutional
- Structure Engine: https://riskstate.ai/docs/structure-engine
- Playbook Engine: https://riskstate.ai/docs/playbook-engine
- Risk Engine guide (live view): https://riskstate.ai/docs/risk-engine-guide
- The stack (builders): https://riskstate.ai/stack
- MCP docs: https://riskstate.ai/docs/mcp · npm: https://www.npmjs.com/package/@riskstate/mcp-server

## Research (dated, citable validation reports)

- Research index: https://riskstate.ai/docs/research
- Backtesting the Policy, Not the Signal (11 Jun 2026 — exposure-matched audit of the sizing output; pre-registers realized-volatility-first sizing for score_v4): https://riskstate.ai/docs/research/policy-backtest-2026-06-11
- First Out-of-Sample Check of the Composite Quintile Contrast (18 May 2026 — pre-registered signal validation; OOS weakened, not disproven): https://riskstate.ai/docs/research/oos-validation-2026-05-18

## Blog (educational guides)

- Blog index: https://riskstate.ai/blog
- Position sizing calculator guide: https://riskstate.ai/blog/crypto-position-sizing-calculator-guide
- Short squeeze vs long squeeze detection: https://riskstate.ai/blog/crypto-short-squeeze-long-squeeze-detection
- BTC and ETH market cycle phases: https://riskstate.ai/blog/btc-eth-market-cycle-phases-guide
- Risk management fundamentals: https://riskstate.ai/blog/how-to-manage-risk-in-crypto-trading
- AI trading agent guardrails: https://riskstate.ai/blog/ai-trading-agent-guardrails-risk-limits

## Key Concepts

- **Policy Engine**: 5-level system (BLOCK Survival, BLOCK Defensive, CAUTIOUS, GREEN Selective, GREEN Expansion) that governs what an agent is allowed to do
- **Binding Constraint**: The single tightest cap (Rules, DeFi, Macro, or Cycle) that determines the current policy level
- **Composite Score**: 0-100 weighted score from 8 signal families (technical, derivatives, on-chain, sentiment, flow, liquidity, macro, cycle)
- **Deterministic**: Same market inputs always produce the same policy output, verified via SHA-256 policy hash

## Contact

- Website: https://riskstate.ai
- Twitter: https://x.com/riskstate_ai
- Email: hello@likido.xyz
- Security: security@likido.xyz