目录 / Riskstate 1.5.0
Riskstate 1.5.0
--- name: riskstate version: 1.5.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/Riskstate/risk-engine 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**: Adverse conditions the engine sees (context; the binding limits are in `blocked_actions` and `max_size_fraction`) - **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. `exposure_policy.blocked_actions` — actions the agent MUST NOT take. If it contains `NEW_TRADES`, ABORT new entries 2. `risk_flags.structural_blockers` — context for the decision, not a stop signal (see below) 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` — advisory direction context (`NEUTRAL` by default; not a signal) 7. `policy_level` — informational summary only, do not use for enforcement `risk_flags.structural_blockers` is context, not a stop signal: it names the adverse conditions the engine sees (for example `EXTREME_FEAR` or `ETF_OUTFLOW`). What the engine treats as binding is already in `blocked_actions` and `max_size_fraction`. Two flags carry their own instruction: `DEFI_LIQUIDATION_RISK` (reduce the position) and `SQUEEZE_RISK` (no leverage). ## Decision rules by policy level | `policy_level` | Summary | Key constraints | |----------------|---------|-----------------| | 1 (BLOCK Survival) | No new positions | `blocked_actions: [NEW_TRADES, ...]`, `max_leverage: "0x"` | | 2 (DEFENSIVE) | New positions up to `max_size_fraction`, no leverage | `allowed_actions: [REDUCED_SIZE_ENTRY, DCA, ...]`, `blocked_actions: [LEVERAGE_GT_1X, 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) **Privacy:** `wallet` is optional. When you send it, the address goes to RiskState and on to Alchemy (our RPC provider) to read the on-chain position. It is not stored: the audit log keeps only a `has_wallet` flag, and wallet responses are not written to the shared cache. An address is a linkable identifier, so omit it unless you need DeFi-aware caps. ```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.
这是模型对公开材料的总结,不是官方声明,请以原链内容为准。
存档时间线
| 版本 | 存档时间 | 内容哈希 | 内容 |
|---|---|---|---|
| v1 | 2026-11-17 20:33 | 95f3b2ae | 可取 |
版本索引永久保留;内容副本只保留最新 1 份,更早版本仅留索引与哈希(存档时间线的证据链不会因此断裂)。
提交举报 / 纠错
侵权举报经核验成立后,我们会即时下线该条目并删除已存的内容副本。