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 sig...
---
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
---
# RiskState — Pre-Trade Risk Layer for Crypto
## What it does
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:
- **max_size_fraction**: Maximum exposure as fraction of portfolio (0.0–1.0). For spot: amount to deploy. For perps: max notional exposure (divide by your leverage for margin).
- **allowed_actions / blocked_actions**: What MAY and MUST NOT be done (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. The assessment is USD-denominated.
## 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](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` | 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://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.
## Example requests
### Minimal (BTC)
```bash
curl -X POST https://api.riskstate.ai/v1/risk-state \
-H "Authorization: Bearer $RISKSTATE_API_KEY" \
-H "Content-Type: application/json" \
-d '{"asset": "BTC"}'
```
### Detailed (with scoring breakdown)
```bash
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}'
```
### DeFi monitoring (with wallet)
```bash
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}'
```
## Example response (minimal)
```json
{
"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](docs/api-v1.md) for full API documentation including all field types, ranges, action enums, risk flags reference, and interpretation guide.
don't have the plugin yet? install it then click "run inline in claude" again.