Menu
Pre-trade risk API for crypto trading agents. Returns exposure limits, allowed actions, and policy constraints for BTC/USD and ETH/USD from 30+ real-time signals. Spot, perpetual futures (perps), and DeFi borrowing aware.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
| name | riskstate |
| version | 1.4.0 |
| description | Pre-trade risk API for crypto trading agents. Returns exposure limits, allowed actions, and policy constraints for BTC/USD and ETH/USD from 30+ real-time signals. Spot, perpetual futures (perps), and DeFi borrowing aware. |
| category | risk-management |
| auth | bearer-token |
| env | RISKSTATE_API_KEY |
| endpoint | POST https://api.riskstate.ai/v1/risk-state |
| assets | ["BTC","ETH"] |
| refresh | 60s cache, recommend 5min polling |
| homepage | https://riskstate.ai |
| docs | https://riskstate.ai/docs/api |
| repository | https://github.com/likidodefi/riskstate-docs |
| tags | ["crypto","ai","bitcoin","trading","ethereum","trading-bot","agents","policy-engine","ai-agents","defi","decentralized-finance","ai-trading","agent-skills","defi-risk-management","risk-governance","skills-sh","perpetual-futures","perps","spot-trading","btc-usd","eth-usd"] |
| pricing | free-beta |
| author | RiskState |
| license | proprietary |
Returns dynamic risk permissions for BTC/USD and ETH/USD before capital is deployed. A deterministic policy engine computes how much exposure is allowed based on 30+ real-time signals across macro, on-chain, derivatives, and DeFi health. Applicable to spot, perpetual futures (perps), and DeFi borrowing.
The response tells you:
exposure_policy for enforcement)This is a risk governor, not a trading oracle. The assessment is USD-denominated.
ttl_seconds in response)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
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 enforcementpolicy_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.
| 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. |
API host: All API calls go to https://api.riskstate.ai (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.
curl -X POST https://api.riskstate.ai/v1/risk-state \
-H "Authorization: Bearer $RISKSTATE_API_KEY" \
-H "Content-Type: application/json" \
-d '{"asset": "BTC"}'
curl -X POST https://api.riskstate.ai/v1/risk-state \
-H "Authorization: Bearer $RISKSTATE_API_KEY" \
-H "Content-Type: application/json" \
-d '{"asset": "BTC", "include_details": true}'
curl -X POST https://api.riskstate.ai/v1/risk-state \
-H "Authorization: Bearer $RISKSTATE_API_KEY" \
-H "Content-Type: application/json" \
-d '{"asset": "ETH", "wallet": "0xYOUR_WALLET_ADDRESS", "include_details": true}'
{
"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": []
}
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.