RiskState — Risk Governor for Crypto Trading Agents

What it does

Returns operational risk permissions for crypto trading. A deterministic policy engine computes how much exposure is allowed based on 30+ real-time signals across macro, on-chain, derivatives, and DeFi health.

The response tells you:

• max_size_fraction: Maximum position size as fraction of portfolio (0.0–1.0)
• allowed_actions / blocked_actions: What the agent MAY and MUST NOT do (enum tokens)
• risk_flags: Structural blockers (hard stop) vs contextual risks (reduce conviction)
• binding_constraint: Which cap is limiting and why
• policy_level: 1–5 summary label (informational — use exposure_policy for enforcement)

What it does NOT do

• No trade signals, no entry/exit prices, no predictions
• No portfolio allocation advice
• No order execution or routing
• No historical data or backtesting

This is a risk governor, not a trading oracle.

When to call

• Before opening or sizing positions — check permissions first
• Periodically during holds — every 5 min for active trading, every 4h for holding
• After significant market moves — cache invalidates after 60s (ttl_seconds in response)

Authentication

Request a free API key at https://riskstate.ai (email only). You will receive a key with the rs_live_ prefix. Set it as the RISKSTATE_API_KEY environment variable and pass it as a Bearer token:

Authorization: Bearer $RISKSTATE_API_KEY

Binding precedence

When consuming the response, agents MUST evaluate fields in this order:

1. risk_flags.structural_blockers — if non-empty, ABORT new entries
2. exposure_policy.blocked_actions — actions the agent MUST NOT take
3. exposure_policy.reduce_recommended — reduce exposure if true
4. exposure_policy.max_size_fraction — maximum position size
5. exposure_policy.max_leverage — maximum leverage allowed
6. exposure_policy.direction_bias — preferred trade direction
7. policy_level — informational summary only, do not use for enforcement

Decision rules by policy level

policy_level is a convenience label. Always check exposure_policy fields for actual constraints.

Failure modes

Security

API host: All API calls go to https://riskstate.netlify.app (the /v1/* endpoints). The https://riskstate.ai domain is the landing page only — no API endpoints are served there.

API keys: All keys have the rs_live_ prefix and are rate-limited to 60 req/min. Store your key in the RISKSTATE_API_KEY environment variable. Do not hardcode keys in source code.

Example requests

Minimal (BTC)

curl -X POST https://riskstate.netlify.app/v1/risk-state \
  -H "Authorization: Bearer $RISKSTATE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"asset": "BTC"}'

Detailed (with scoring breakdown)

curl -X POST https://riskstate.netlify.app/v1/risk-state \
  -H "Authorization: Bearer $RISKSTATE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"asset": "BTC", "include_details": true}'

DeFi monitoring (with wallet)

curl -X POST https://riskstate.netlify.app/v1/risk-state \
  -H "Authorization: Bearer $RISKSTATE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"asset": "ETH", "wallet": "0xYOUR_WALLET_ADDRESS", "include_details": true}'

Example response (minimal)

{
  "exposure_policy": {
    "max_size_fraction": 0.42,
    "leverage_allowed": false,
    "max_leverage": "1x",
    "direction_bias": "LONG_PREFERRED",
    "reduce_recommended": false,
    "allowed_actions": ["DCA", "WAIT", "LIGHT_ACCUMULATION", "RR_GT_2"],
    "blocked_actions": ["LEVERAGE", "AGGRESSIVE_LONG", "ALL_IN"]
  },
  "tactical_state": "LEAN BULL",
  "structural_state": "MID",
  "macro_state": "NEUTRAL",
  "market_regime": "TREND",
  "volatility_regime": "NORMAL",
  "policy_level": 3,
  "confidence_score": 0.72,
  "data_quality_score": 85,
  "binding_constraint": {
    "source": "MACRO",
    "reason": "NEUTRAL × NORMAL",
    "reason_codes": ["MACRO_NEUTRAL", "COUPLING_NORMAL"],
    "cap_value": 0.70
  },
  "risk_flags": {
    "structural_blockers": [],
    "context_risks": ["HIGH_FUNDING"]
  },
  "defi": null,
  "policy_hash": "a1b2c3d4e5f6...",
  "scoring_version": "score_v2",
  "version": "1.2.2",
  "timestamp": "2026-03-13T14:30:00.000Z",
  "asset": "BTC",
  "cached": false,
  "ttl_seconds": 60,
  "stale_fields": []
}

Detailed response

Pass "include_details": true in the request body to receive expanded scoring data (composite subscores, positioning intelligence, whale pressure, trend strength, caps breakdown). All minimal fields are included plus: caps, positioning, volatility, whale_pressure, trend_strength, composite, extreme_scores, macro_detail, data_sources, and core_missing.

See docs/api-v1.md for full API documentation including all field types, ranges, action enums, risk flags reference, and interpretation guide.