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:
risk_flags.structural_blockers — if non-empty, ABORT new entriesexposure_policy.blocked_actions — actions the agent MUST NOT takeexposure_policy.reduce_recommended — reduce exposure if trueexposure_policy.max_size_fraction — maximum position sizeexposure_policy.max_leverage — maximum leverage allowedexposure_policy.direction_bias — preferred trade directionpolicy_level — informational summary only, do not use for enforcement
Decision rules by policy level
policy_level | Summary | Key constraints |
|---|
| 1 (BLOCK Survival) | No new positions | blocked_actions: [NEW_TRADES, ...], max_leverage: "0x" |
| 2 (BLOCK Defensive) | Wait or hedge only | blocked_actions: [AGGRESSIVE_LONG, ...], max_leverage: "1x" |
| 3 (CAUTIOUS) | DCA with R:R >2:1 | blocked_actions: [LEVERAGE, ALL_IN, ...], max_leverage: "1x" |
| 4 (GREEN Selective) | Trade with confirmation | max_leverage: "1.5x" |
| 5 (GREEN Expansion) | Full operations | max_leverage: "2x" |
policy_level is a convenience label. Always check exposure_policy fields for actual constraints.
Failure modes
| Condition | Agent behavior |
|---|
stale_fields contains core indicators (price, funding, rsi) | Downgrade conviction. Data integrity compromised. |
data_quality_score < 70 | Treat as degraded. Reduce position sizes by 50%. |
data_quality_score < 50 | Treat as unreliable. Do not open new positions. |
confidence_score < 0.5 | Signals conflict heavily. Prefer WAIT over action. |
| HTTP 500 or timeout | Assume worst case (BLOCK). Retry after 60s. |
cached: true + stale_fields non-empty | Re-request after cache TTL (60s) for fresh data. |
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.
