{"id":"693d8dd3-1bcf-42a2-a9de-1e6caec0e353","entityType":"agent","slug":"clawhub-riskstate-riskstate","name":"Clawhub","canonicalUrl":"https://www.xpersona.co/agent/clawhub-riskstate-riskstate","canonicalPath":"/agent/clawhub-riskstate-riskstate","generatedAt":"2026-10-10T21:43:10.136Z","source":"CLAWHUB","claimStatus":"UNCLAIMED","verificationTier":"NONE","summary":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-10T18:49:59.527Z","emptyReason":null},"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.","descriptionLabel":"Source description","evidenceSummary":"Capability contract not published. No trust telemetry is available yet. 1.3K downloads reported by the source. Last updated 10/10/2026.","installCommand":"clawhub skill install s17avrjxb7vs8sb2xqm1097rwx8e5hs6:riskstate","sourceUrl":"https://clawhub.ai/riskstate/riskstate","homepage":"https://clawhub.ai/riskstate/skills/riskstate","primaryLinks":[{"label":"View on ClawHub","url":"https://clawhub.ai/riskstate/riskstate","kind":"source"},{"label":"Homepage","url":"https://clawhub.ai/riskstate/skills/riskstate","kind":"homepage"}],"safetyScore":84,"overallRank":62,"popularityScore":62,"trustScore":null,"claimedByName":null,"isOwner":false,"seoDescription":"Clawhub technical dossier on Xpersona with agent coverage, OPENCLEW support, and live trust metadata."},"coverage":{"evidence":{"source":"public-profile","verified":false,"confidence":"medium","updatedAt":"2026-10-10T18:49:59.527Z","emptyReason":null},"protocols":[{"protocol":"OPENCLEW","label":"OpenClaw","status":"self-declared","notes":"Declared in the public agent profile."}],"capabilities":[],"verifiedCount":0,"selfDeclaredCount":1,"capabilityMatrix":{"rows":[{"key":"OPENCLEW","type":"protocol","support":"unknown","confidenceSource":"profile","notes":"Listed on profile"}],"flattenedTokens":"protocol:OPENCLEW|unknown|profile"}},"adoption":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-10T18:49:59.527Z","emptyReason":null},"stars":null,"forks":null,"downloads":1290,"packageName":null,"latestVersion":"1.4.1","tractionLabel":"1.3K downloads"},"release":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-10T18:49:59.527Z","emptyReason":null},"lastUpdatedAt":"2026-10-10T18:49:59.527Z","lastCrawledAt":"2026-10-10T18:49:59.527Z","lastIndexedAt":null,"nextCrawlAt":"2026-10-11T18:49:59.527Z","lastVerifiedAt":null,"highlights":[{"version":"1.4.1","createdAt":"2026-09-10T11:11:02.413Z","changelog":"Canonical URLs moved to the Riskstate GitHub org; skill migrated to the riskstate publisher.","fileCount":6,"zipByteSize":23512},{"version":"1.4.0","createdAt":"2026-06-08T12:59:20.290Z","changelog":"**Expanded coverage and API endpoint update for pre-trade risk governance.** - Endpoint moved to https://api.riskstate.ai/v1/risk-state (from netlify.app domain) - API now covers spot, perpetual futures (perps), and DeFi borrowing risk for BTC/USD and ETH/USD - Clarified responses are USD-denominated and suitable for pre-trade sizing in all major trading styles - Documentation and example requests/links updated to reflect new endpoint and features - Additional tags added for better discoverability (perpetual-futures, spot-trading, btc-usd, eth-usd)","fileCount":6,"zipByteSize":22826},{"version":"1.2.2","createdAt":"2026-03-25T23:21:13.900Z","changelog":"v1.2.2 — Remove owner/admin key references from agent-facing documentation. Simplified Security section to single key type (rs_live_* prefix) with single env var (RISKSTATE_API_KEY). Eliminates credential ambiguity flagged by OpenClaw scanner. Auth section now explicitly names key prefix and env var together.","fileCount":6,"zipByteSize":17855},{"version":"1.2.1","createdAt":"2026-03-25T23:13:51.526Z","changelog":"v1.2.1 — Standardize credential naming and metadata for marketplace trust scoring. Added env: RISKSTATE_API_KEY to frontmatter. All examples now use $RISKSTATE_API_KEY (was $TOKEN). Full API host in endpoint field. Aligned tags across npm, SKILL.md, and GitHub topics (16 keywords). Fixes OpenClaw scanner \"Suspicious\" flag.","fileCount":5,"zipByteSize":16491},{"version":"1.2.0","createdAt":"2026-03-25T22:58:26.951Z","changelog":"RiskState version 1.2.0 - Expanded skill tags for improved searchability and classification. - Added a new \"Security\" section to documentation, clarifying API host usage and key types. - Stated rate limits and authentication practices for API keys. - No changes to core functionality or API endpoints.","fileCount":5,"zipByteSize":16477},{"version":"1.1.1","createdAt":"2026-03-22T14:31:23.108Z","changelog":"- Improved documentation in SKILL.md with a clear overview of functionality, detailed usage instructions, and example requests/responses. - Clarified the scope: deterministic risk governor for crypto trading agents, returning position limits, allowed/blocked actions, and policy constraints based on 30+ real-time signals. - Provided explicit policy interpretation, field precedence, and agent behavior for degraded/failure modes. - Added details on authentication, supported assets (BTC, ETH), and polling recommendations. - Enhanced API response documentation, including minimal and detailed outputs for better integration guidance.","fileCount":5,"zipByteSize":15821}]},"execution":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No published capability contract is available yet."},"installCommand":"clawhub skill install s17avrjxb7vs8sb2xqm1097rwx8e5hs6:riskstate","setupComplexity":"low","setupSteps":["Install using `clawhub skill install s17avrjxb7vs8sb2xqm1097rwx8e5hs6:riskstate` in an isolated environment before connecting it to live workloads.","No published capability contract is available yet, so validate auth and request/response behavior manually.","Review the upstream CLAWHUB listing at https://clawhub.ai/riskstate/riskstate before using production credentials."],"contract":{"contractStatus":"missing","authModes":[],"requires":[],"forbidden":[],"supportsMcp":false,"supportsA2a":false,"supportsStreaming":false,"inputSchemaRef":null,"outputSchemaRef":null,"dataRegion":null,"contractUpdatedAt":null,"sourceUpdatedAt":null,"freshnessSeconds":null},"invocationGuide":{"preferredApi":{"snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-riskstate-riskstate/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-riskstate-riskstate/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-riskstate-riskstate/trust"},"curlExamples":["curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-riskstate-riskstate/snapshot\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-riskstate-riskstate/contract\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-riskstate-riskstate/trust\""],"jsonRequestTemplate":{"query":"summarize this repo","constraints":{"maxLatencyMs":2000,"protocolPreference":["OPENCLEW"]}},"jsonResponseTemplate":{"ok":true,"result":{"summary":"...","confidence":0.9},"meta":{"source":"CLAWHUB","generatedAt":"2026-10-10T21:43:10.131Z"}},"retryPolicy":{"maxAttempts":3,"backoffMs":[500,1500,3500],"retryableConditions":["HTTP_429","HTTP_503","NETWORK_TIMEOUT"]}},"endpoints":{"dossierUrl":"https://www.xpersona.co/api/v1/agents/clawhub-riskstate-riskstate/dossier","snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-riskstate-riskstate/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-riskstate-riskstate/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-riskstate-riskstate/trust"}},"reliability":{"evidence":{"source":"runtime-metrics","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No trust, reliability, or runtime telemetry is available."},"trust":{"status":"unavailable","handshakeStatus":"UNKNOWN","verificationFreshnessHours":null,"reputationScore":null,"p95LatencyMs":null,"successRate30d":null,"fallbackRate":null,"attempts30d":null,"trustUpdatedAt":null,"trustConfidence":"unknown","sourceUpdatedAt":null,"freshnessSeconds":null},"decisionGuardrails":{"doNotUseIf":["Contract metadata is missing or unavailable for deterministic execution."],"safeUseWhen":[],"riskFlags":["missing_or_unavailable_contract","trust_data_unavailable","schema_references_missing"],"operationalConfidence":"low"},"executionMetrics":{"observedLatencyMsP50":null,"observedLatencyMsP95":null,"estimatedCostUsd":null,"uptime30d":null,"rateLimitRpm":null,"rateLimitBurst":null,"lastVerifiedAt":null,"verificationSource":null},"runtimeMetrics":{"successRate":null,"avgLatencyMs":null,"avgCostUsd":null,"hallucinationRate":null,"retryRate":null,"disputeRate":null,"p50Latency":null,"p95Latency":null,"lastUpdated":null}},"benchmarks":{"evidence":{"source":"no-benchmark-data","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No benchmark suites or observed failure patterns are available."},"suites":[],"failurePatterns":[]},"artifacts":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-10T18:49:59.527Z","emptyReason":null},"readme":"Skill: Clawhub\n\nOwner: riskstate\n\nSummary: 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.\n\nTags: agent-skills:1.2.1, agents:1.2.1, ai:1.2.1, ai-agents:1.2.1, ai-trading:1.2.1, bitcoin:1.2.1, btc:1.1.1, crypto:1.2.1, decentralized-finance:1.2.1, defi:1.2.1, defi-risk-management:1.2.1, eth:1.1.1, ethereum:1.2.1, governance:1.1.1, latest:1.4.1, policy:1.1.1, policy-engine:1.2.1, position-sizing:1.1.1, risk:1.1.1, risk-governance:1.2.1, skills-sh:1.2.1, trading:1.2.1, trading-bot:1.2.1\n\nVersion history:\n\nv1.4.1 | 2026-09-10T11:11:02.413Z | user\n\nCanonical URLs moved to the Riskstate GitHub org; skill migrated to the riskstate publisher.\n\nv1.4.0 | 2026-06-08T12:59:20.290Z | user\n\n**Expanded coverage and API endpoint update for pre-trade risk governance.**\n\n- Endpoint moved to https://api.riskstate.ai/v1/risk-state (from netlify.app domain)\n- API now covers spot, perpetual futures (perps), and DeFi borrowing risk for BTC/USD and ETH/USD\n- Clarified responses are USD-denominated and suitable for pre-trade sizing in all major trading styles\n- Documentation and example requests/links updated to reflect new endpoint and features\n- Additional tags added for better discoverability (perpetual-futures, spot-trading, btc-usd, eth-usd)\n\nv1.2.2 | 2026-03-25T23:21:13.900Z | user\n\nv1.2.2 — Remove owner/admin key references from agent-facing documentation. Simplified Security section to single key type (rs_live_* prefix) with single env var (RISKSTATE_API_KEY). Eliminates credential ambiguity flagged by OpenClaw scanner. Auth section now explicitly names key prefix and env var together.\n\nv1.2.1 | 2026-03-25T23:13:51.526Z | user\n\nv1.2.1 — Standardize credential naming and metadata for marketplace trust scoring. Added env: RISKSTATE_API_KEY to frontmatter. All examples now use $RISKSTATE_API_KEY (was $TOKEN). Full API host in endpoint field. Aligned tags across npm, SKILL.md, and GitHub topics (16 keywords). Fixes OpenClaw scanner \"Suspicious\" flag.\n\nv1.2.0 | 2026-03-25T22:58:26.951Z | user\n\nRiskState version 1.2.0\n\n- Expanded skill tags for improved searchability and classification.\n- Added a new \"Security\" section to documentation, clarifying API host usage and key types.\n- Stated rate limits and authentication practices for API keys.\n- No changes to core functionality or API endpoints.\n\nv1.1.1 | 2026-03-22T14:31:23.108Z | user\n\n- Improved documentation in SKILL.md with a clear overview of functionality, detailed usage instructions, and example requests/responses.\n- Clarified the scope: deterministic risk governor for crypto trading agents, returning position limits, allowed/blocked actions, and policy constraints based on 30+ real-time signals.\n- Provided explicit policy interpretation, field precedence, and agent behavior for degraded/failure modes.\n- Added details on authentication, supported assets (BTC, ETH), and polling recommendations.\n- Enhanced API response documentation, including minimal and detailed outputs for better integration guidance.\n\nArchive index:\n\nArchive v1.4.1: 6 files, 23512 bytes\n\nFiles: CHANGELOG.md (6257b), docs/api-v1.md (27430b), README.md (9875b), skill-card.md (2896b), SKILL.md (7310b), _meta.json (128b)\n\nFile v1.4.1:SKILL.md\n\n---\nname: riskstate\nversion: 1.4.1\ndescription: 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.\ncategory: risk-management\nauth: bearer-token\nenv: RISKSTATE_API_KEY\nendpoint: POST https://api.riskstate.ai/v1/risk-state\nassets: [BTC, ETH]\nrefresh: 60s cache, recommend 5min polling\nhomepage: https://riskstate.ai\ndocs: https://riskstate.ai/docs/api\nrepository: https://github.com/Riskstate/risk-engine\ntags: [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]\npricing: free-beta\nauthor: RiskState\nlicense: proprietary\n---\n\n# RiskState — Pre-Trade Risk Layer for Crypto\n\n## What it does\n\nReturns **dynamic risk permissions** for BTC/USD and ETH/USD before capital is deployed.\nA 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**.\n\nThe response tells you:\n- **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).\n- **allowed_actions / blocked_actions**: What MAY and MUST NOT be done (enum tokens)\n- **risk_flags**: Structural blockers (hard stop) vs contextual risks (reduce conviction)\n- **binding_constraint**: Which cap is limiting and why\n- **policy_level**: 1–5 summary label (informational — use `exposure_policy` for enforcement)\n\n## What it does NOT do\n\n- No trade signals, no entry/exit prices, no predictions\n- No portfolio allocation advice\n- No order execution or routing\n- No historical data or backtesting\n\nThis is a **risk governor**, not a trading oracle. The assessment is USD-denominated.\n\n## When to call\n\n- **Before opening or sizing positions** — check permissions first\n- **Periodically during holds** — every 5 min for active trading, every 4h for holding\n- **After significant market moves** — cache invalidates after 60s (`ttl_seconds` in response)\n\n## Authentication\n\nRequest 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:\n\n```\nAuthorization: Bearer $RISKSTATE_API_KEY\n```\n\n## Binding precedence\n\nWhen consuming the response, agents MUST evaluate fields in this order:\n\n1. `risk_flags.structural_blockers` — if non-empty, ABORT new entries\n2. `exposure_policy.blocked_actions` — actions the agent MUST NOT take\n3. `exposure_policy.reduce_recommended` — reduce exposure if true\n4. `exposure_policy.max_size_fraction` — maximum position size\n5. `exposure_policy.max_leverage` — maximum leverage allowed\n6. `exposure_policy.direction_bias` — preferred trade direction\n7. `policy_level` — informational summary only, do not use for enforcement\n\n## Decision rules by policy level\n\n| `policy_level` | Summary | Key constraints |\n|----------------|---------|-----------------|\n| 1 (BLOCK Survival) | No new positions | `blocked_actions: [NEW_TRADES, ...]`, `max_leverage: \"0x\"` |\n| 2 (BLOCK Defensive) | Wait or hedge only | `blocked_actions: [AGGRESSIVE_LONG, ...]`, `max_leverage: \"1x\"` |\n| 3 (CAUTIOUS) | DCA with R:R >2:1 | `blocked_actions: [LEVERAGE, ALL_IN, ...]`, `max_leverage: \"1x\"` |\n| 4 (GREEN Selective) | Trade with confirmation | `max_leverage: \"1.5x\"` |\n| 5 (GREEN Expansion) | Full operations | `max_leverage: \"2x\"` |\n\n`policy_level` is a convenience label. Always check `exposure_policy` fields for actual constraints.\n\n## Failure modes\n\n| Condition | Agent behavior |\n|-----------|----------------|\n| `stale_fields` contains core indicators (price, funding, rsi) | Downgrade conviction. Data integrity compromised. |\n| `data_quality_score` < 70 | Treat as degraded. Reduce position sizes by 50%. |\n| `data_quality_score` < 50 | Treat as unreliable. Do not open new positions. |\n| `confidence_score` < 0.5 | Signals conflict heavily. Prefer WAIT over action. |\n| HTTP 500 or timeout | Assume worst case (BLOCK). Retry after 60s. |\n| `cached: true` + `stale_fields` non-empty | Re-request after cache TTL (60s) for fresh data. |\n\n## Security\n\n**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.\n\n**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.\n\n## Example requests\n\n### Minimal (BTC)\n\n```bash\ncurl -X POST https://api.riskstate.ai/v1/risk-state \\\n  -H \"Authorization: Bearer $RISKSTATE_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"asset\": \"BTC\"}'\n```\n\n### Detailed (with scoring breakdown)\n\n```bash\ncurl -X POST https://api.riskstate.ai/v1/risk-state \\\n  -H \"Authorization: Bearer $RISKSTATE_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"asset\": \"BTC\", \"include_details\": true}'\n```\n\n### DeFi monitoring (with wallet)\n\n```bash\ncurl -X POST https://api.riskstate.ai/v1/risk-state \\\n  -H \"Authorization: Bearer $RISKSTATE_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"asset\": \"ETH\", \"wallet\": \"0xYOUR_WALLET_ADDRESS\", \"include_details\": true}'\n```\n\n## Example response (minimal)\n\n```json\n{\n  \"exposure_policy\": {\n    \"max_size_fraction\": 0.42,\n    \"leverage_allowed\": false,\n    \"max_leverage\": \"1x\",\n    \"direction_bias\": \"LONG_PREFERRED\",\n    \"reduce_recommended\": false,\n    \"allowed_actions\": [\"DCA\", \"WAIT\", \"LIGHT_ACCUMULATION\", \"RR_GT_2\"],\n    \"blocked_actions\": [\"LEVERAGE\", \"AGGRESSIVE_LONG\", \"ALL_IN\"]\n  },\n  \"tactical_state\": \"LEAN BULL\",\n  \"structural_state\": \"MID\",\n  \"macro_state\": \"NEUTRAL\",\n  \"market_regime\": \"TREND\",\n  \"volatility_regime\": \"NORMAL\",\n  \"policy_level\": 3,\n  \"confidence_score\": 0.72,\n  \"data_quality_score\": 85,\n  \"binding_constraint\": {\n    \"source\": \"MACRO\",\n    \"reason\": \"NEUTRAL × NORMAL\",\n    \"reason_codes\": [\"MACRO_NEUTRAL\", \"COUPLING_NORMAL\"],\n    \"cap_value\": 0.70\n  },\n  \"risk_flags\": {\n    \"structural_blockers\": [],\n    \"context_risks\": [\"HIGH_FUNDING\"]\n  },\n  \"defi\": null,\n  \"policy_hash\": \"a1b2c3d4e5f6...\",\n  \"scoring_version\": \"score_v2\",\n  \"version\": \"1.2.2\",\n  \"timestamp\": \"2026-03-13T14:30:00.000Z\",\n  \"asset\": \"BTC\",\n  \"cached\": false,\n  \"ttl_seconds\": 60,\n  \"stale_fields\": []\n}\n```\n\n## Detailed response\n\nPass `\"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`.\n\nSee [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.\n\nFile v1.4.1:README.md\n\n<p align=\"center\">\n  <img src=\"https://riskstate.ai/logo-r-grey.svg\" width=\"48\" alt=\"RiskState\" />\n</p>\n\n<h1 align=\"center\">RiskState</h1>\n\n<p align=\"center\">\n  <strong>Pre-trade risk API for crypto — BTC/USD and ETH/USD exposure governance</strong><br />\n  <sub>For trading agents, open-source systems, and capital desks. Spot and perpetual futures (perps). DeFi borrowing aware.</sub>\n</p>\n\n<p align=\"center\">\n  <a href=\"https://api.riskstate.ai/v1/risk-state\"><img src=\"https://img.shields.io/badge/API-v1.4.0-blue?style=flat-square\" alt=\"API Version\" /></a>\n  <a href=\"https://riskstate.ai\"><img src=\"https://img.shields.io/badge/status-beta-green?style=flat-square\" alt=\"Status\" /></a>\n  <a href=\"#supported-assets\"><img src=\"https://img.shields.io/badge/assets-BTC%2FUSD%20%7C%20ETH%2FUSD-orange?style=flat-square\" alt=\"Assets\" /></a>\n  <a href=\"#markets\"><img src=\"https://img.shields.io/badge/markets-spot%20%7C%20perps%20%7C%20DeFi-purple?style=flat-square\" alt=\"Markets\" /></a>\n  <a href=\"#pricing\"><img src=\"https://img.shields.io/badge/pricing-free%20beta-brightgreen?style=flat-square\" alt=\"Pricing\" /></a>\n</p>\n\n<p align=\"center\">\n  <a href=\"https://riskstate.ai\">Website</a> · <a href=\"docs/api-v1.md\">API Reference</a> · <a href=\"SKILL.md\">SKILL.md</a> · <a href=\"https://x.com/riskstate_ai\">X/Twitter</a>\n</p>\n\n---\n\n## What is RiskState?\n\nA deterministic engine that converts live market state into **dynamic risk permissions** — exposure limits, leverage caps, and allowed actions — before capital is deployed.\n\nOne API call returns position limits, allowed actions, and policy constraints computed from **30+ real-time signals** across macro, on-chain, derivatives, and DeFi health. The assessment is **USD-denominated**: all scoring is based on BTC/USD and ETH/USD price action, derivatives, and macro conditions.\n\n```bash\ncurl -X POST https://api.riskstate.ai/v1/risk-state \\\n  -H \"Authorization: Bearer $RISKSTATE_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"asset\": \"BTC\"}'\n```\n\n```json\n{\n  \"exposure_policy\": {\n    \"max_size_fraction\": 0.42,\n    \"leverage_allowed\": true,\n    \"allowed_actions\": [\"DCA\", \"LONG_SHORT_CONFIRMED\"],\n    \"blocked_actions\": [\"ALL_IN\", \"LEVERAGE_GT_2X\"]\n  },\n  \"policy_level\": 4,\n  \"risk_flags\": {\n    \"structural_blockers\": [],\n    \"context_risks\": [\"HIGH_COUPLING\"]\n  },\n  \"binding_constraint\": {\n    \"source\": \"MACRO\",\n    \"reason_codes\": [\"MACRO_NEUTRAL\", \"COUPLING_NORMAL\"]\n  }\n}\n```\n\nRead `max_size_fraction`, check `structural_blockers`, and act. No parsing. No interpretation.\n\n## Why?\n\nWhether you run an AI trading agent, a systematic trading system, or a manual desk — crypto markets have regime shifts that require adaptive risk governance. Static rules fail. RiskState provides a **pre-trade risk check** that adapts every 60 seconds.\n\n| Without governance | With RiskState |\n|---|---|\n| Position size based on signal confidence alone | Capped at `max_size_fraction` (max notional exposure) |\n| No awareness of macro regime | `RISK-OFF` → `blocked_actions: [\"AGGRESSIVE_LONG\"]` |\n| DeFi health factor ignored | Wallet health feeds directly into position limit |\n| Leverage unbounded | Policy-level constraints enforced |\n| No circuit breaker | `structural_blockers` non-empty → halt |\n\n## Quick Start\n\n### 1. Get an API key\n\nSign up at [riskstate.ai](https://riskstate.ai) — email only, free during beta.\n\n### 2. Query the API\n\n```bash\ncurl -X POST https://api.riskstate.ai/v1/risk-state \\\n  -H \"Authorization: Bearer $RISKSTATE_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"asset\": \"BTC\"}'\n```\n\n### 3. Enforce before execution\n\n**In an AI trading agent (Python):**\n\n```python\nimport requests\n\npolicy = requests.post(\n    \"https://api.riskstate.ai/v1/risk-state\",\n    headers={\"Authorization\": f\"Bearer {API_KEY}\"},\n    json={\"asset\": \"BTC\"}\n).json()\n\n# Hard stop: structural blockers\nif policy[\"risk_flags\"][\"structural_blockers\"]:\n    return  # Do not trade\n\n# Size cap — max notional exposure as fraction of portfolio\nmax_size = policy[\"exposure_policy\"][\"max_size_fraction\"]\nposition_size = min(desired_size, portfolio_value * max_size)\n\n# Action filter\nif \"LEVERAGE\" in policy[\"exposure_policy\"][\"blocked_actions\"]:\n    leverage = 1.0\n```\n\n**In a trading system (pre-trade check):**\n\n```python\n# Before placing a spot or perps order\npolicy = fetch_riskstate(\"ETH\")\n\nif policy[\"risk_flags\"][\"structural_blockers\"]:\n    log(\"BLOCKED: structural risk — skipping order\")\n    return\n\nmax_notional = portfolio_value * policy[\"exposure_policy\"][\"max_size_fraction\"]\n# Spot: max_notional is the $ amount to deploy\n# Perps: max_notional is the notional exposure cap\n#   e.g., at 10x leverage → margin = max_notional / 10\n```\n\n**Manual pre-trade check (curl):**\n\n```bash\n# Quick check before placing an order on Binance/Hyperliquid/Aave\ncurl -s -X POST https://api.riskstate.ai/v1/risk-state \\\n  -H \"Authorization: Bearer $RISKSTATE_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"asset\": \"BTC\"}' | jq '{\n    policy_level, \n    max_size: .exposure_policy.max_size_fraction,\n    blocked: .exposure_policy.blocked_actions,\n    blockers: .risk_flags.structural_blockers\n  }'\n```\n\n## Policy Levels\n\n| Level | Label | Max Size | What your agent can do |\n|-------|-------|----------|----------------------|\n| 1 | BLOCK Survival | <15% | Reduce exposure, hedge only |\n| 2 | BLOCK Defensive | <35% | Wait, hedge, small scalps |\n| 3 | CAUTIOUS | <60% | DCA, R:R >2:1 only |\n| 4 | GREEN Selective | <80% | Trade with confirmation |\n| 5 | GREEN Expansion | ≥80% | Full operations, leverage up to 2x |\n\n## Supported Assets\n\n- **BTC/USD** — Full signal coverage (30+ indicators). Scoring based on BTC/USDT price, derivatives, and macro conditions.\n- **ETH/USD** — Full coverage including ETH structural score, ETH/BTC ratio analysis, staking dynamics, ETH/NASDAQ correlation.\n\n> **Note:** The assessment is USD-denominated. If you trade non-USD pairs (e.g., BTC/EUR, ETH/BTC), additional cross-rate risk is not covered.\n\n## Markets\n\nRiskState evaluates the same underlying market conditions regardless of where you trade. The risk assessment applies to:\n\n| Market | How to use the output |\n|--------|----------------------|\n| **Spot** | `max_size_fraction` = % of portfolio to deploy. Leverage fields are not applicable. |\n| **Perpetual futures (perps)** | `max_size_fraction` = max notional exposure as % of portfolio. At 10x leverage, your margin is `max_size_fraction / 10`. Derivatives signals (funding rate, basis, OI, squeeze risk) are especially relevant. |\n| **DeFi borrowing** | Pass your `wallet` address for health factor and liquidation-aware risk caps. `max_leverage` reflects borrowing ratio (LTV). |\n\nThe API returns the same response for all markets — the difference is how you **interpret** the output. See [API Reference → How to Use by Context](docs/api-v1.md#how-to-use-by-context) for detailed workflows.\n\n## Integration Paths\n\n### REST API\nDirect HTTP calls. Any language, any framework.\n\n### SKILL.md\nDrop [`SKILL.md`](SKILL.md) into your agent's repo. Compatible with Claude Code, Copilot, Cursor, and Gemini via [skills.sh](https://skills.sh).\n\n### MCP Server\n\n```bash\nnpm install @riskstate/mcp-server\n```\n\nOr run directly with `npx @riskstate/mcp-server`. Docker: `ghcr.io/riskstate/mcp`.\n\nOne tool: `get_risk_policy` — same parameters as the REST API. Compatible with Claude Desktop, Claude Code, Cursor, and any MCP-compatible client. See [MCP README](https://riskstate.ai/docs/mcp) for full setup.\n\n## Listed On\n\n- [awesome-mcp-servers](https://github.com/punkpeye/awesome-mcp-servers) — Finance & Fintech category\n- [LobeHub MCP](https://lobehub.com) — Auto-discovered\n- [ClawHub.ai](https://clawhub.ai) — Skill marketplace\n- [skills.sh](https://skills.sh) — Vercel skills registry\n- [Glama.ai](https://glama.ai) — AAA score\n\n## Binding Precedence\n\nWhen consuming the response, agents **must** evaluate fields in this order:\n\n1. `risk_flags.structural_blockers` — if non-empty, **abort** new entries\n2. `exposure_policy.blocked_actions` — actions the agent must not take\n3. `exposure_policy.reduce_recommended` — reduce exposure if `true`\n4. `exposure_policy.max_size_fraction` — maximum position size (0.0–1.0)\n5. `exposure_policy.max_leverage` — maximum leverage allowed\n\n## Data Sources\n\nRiskState ingests 30+ real-time signals from:\n\n- **Price & Derivatives** — Binance, OKX, Bybit (funding, OI, basis, L/S ratio)\n- **On-chain** — MVRV, NUPL, exchange netflow, supply metrics (CoinGlass)\n- **Macro** — DXY, US yields, S&P 500, Gold, Fed balance sheet (FRED, Yahoo Finance)\n- **DeFi** — Spark Protocol, Aave V3 health factor and liquidation thresholds\n- **Sentiment** — Fear & Greed, ETF flows, institutional treasuries\n- **ETH-specific** — Staking ratio, burn rate, DEX volume, fees, stablecoin TVL\n\n## Pricing\n\n**Free during beta.** Rate limit: 60 requests/minute.\n\n| Tier | Calls/month | Price |\n|------|------------|-------|\n| Free | 100 | $0 |\n| Builder | 5,000 | $49/mo |\n| Growth | 25,000 | $149/mo |\n| Scale | 100,000 | $399/mo |\n\nPaid tiers coming after beta. [Sign up now](https://riskstate.ai) to lock in early access.\n\n## Documentation\n\n- [**API Reference**](docs/api-v1.md) — Full endpoint documentation, field types, error codes\n- [**SKILL.md**](SKILL.md) — Agent discovery file with decision rules and failure modes\n- [**Changelog**](CHANGELOG.md) — Version history and release notes\n- [**Website**](https://riskstate.ai) — Landing page with interactive examples\n\n## Links\n\n- Website: [riskstate.ai](https://riskstate.ai)\n- X/Twitter: [@riskstate_ai](https://x.com/riskstate_ai)\n- API: `POST https://api.riskstate.ai/v1/risk-state`\n\n---\n\n<p align=\"center\">\n  <sub>Built by <a href=\"https://riskstate.ai\">RiskState</a> · © 2026 Digital Venture Asset LLC</sub>\n</p>\n\nFile v1.4.1:_meta.json\n\n{\n  \"ownerId\": \"kn7djkxqyactdmda78e52x792h83c54v\",\n  \"slug\": \"riskstate\",\n  \"version\": \"1.4.1\",\n  \"publishedAt\": 1789038662413\n}\n\nFile v1.4.1:CHANGELOG.md\n\n# Changelog\n\nAll notable changes to the RiskState API will be documented in this file.\n\n## [1.4.0] - 2026-04-22\n\n### Added\n- **Policy combiner refinements (PR3)** — Five additive refinements to `policy_permissions`, all surfaced in the response and the audit `policy_hash`:\n  - **TREND / RANGE weight split** — `TREND` blends 0.65 structural / 0.35 tactical (continuation-led); `RANGE` 0.55 / 0.45 (tactical has more voice). PANIC, EUPHORIA, and SQUEEZE weights unchanged.\n  - **DQ-gated structural veto** — structural veto is skipped when `structural_score.data_quality < 60`, emitting `STRUCTURAL_VETO_SKIPPED_LOW_DQ`. Prevents low-confidence structural reads from overriding clean tactical signals.\n  - **PANIC SHORT override** — PANIC regime exempts SHORT positions from the strong-structural veto (`STRUCTURAL_VETO_SKIPPED_PANIC`), so dead-cat-bounce / fake-breakout setups are not blocked.\n  - **Bucket codes in `reason_codes`** — typed tokens (e.g. `TACTICAL_STRONG_BULL_72`, `STRUCTURAL_WEAK_22`) replace raw scores for downstream classification.\n  - **`shadow_max_size_fraction`** — read-only preview of a candidate combiner-driven sizing rule. Does not bind today; surfaced for offline comparison.\n\n### Changed\n- Policy hash inputs widened to cover the new bucket codes and shadow size — cached hashes from v1.3.0 will not match (one-time invalidation).\n\n## [1.3.0] - 2026-04-21\n\n### Added\n- **Decoupled Structural + Tactical scores + policy combiner (PR2)** — Splits the single composite into two layers that each drive the appropriate decision:\n  - `structural_score` — slow horizon (weeks-months): cycle, supply, demand, macro. `{overall, label, subfamilies, data_quality, source}`.\n  - `tactical_score` — fast horizon (24-72h): positioning pressure, momentum, volume/CVD, derivatives extremity, L/S velocity, whale pressure. `{overall, label, components, signals}`.\n  - `policy_permissions` — context-aware combiner producing `risk_permission_score`, regime-dependent weights, `direction_bias`, `direction_layer` (audit), and `reason_codes`.\n\n### Changed\n- **`exposure_policy.direction_bias` now comes from the combiner** (was composite-tilt). Breaking semantics.\n- `exposure_policy.direction_layer` added — audit field showing which layer drove direction.\n- Existing `composite` retained for backwards compatibility; `max_size_fraction` still driven by the legacy 4-cap engine.\n\n## [1.2.1] - 2026-04-21\n\n### Added\n- **Positioning Pressure Score (PR1)** — continuous 0-100 tactical signal derived from the squeeze scorer (50 = neutral, >50 short-squeeze setup). Wired into BTC and ETH composite as a 9% subscore. Response gains `positioning.positioning_pressure_score` and `positioning.positioning_pressure_net`.\n\n### Changed\n- **ETH issuance recalibration** — asymmetric bands + 7d/30d blend. Mild post-Merge inflation (+0.82%/yr) now scores ~53 (was ~30); hard-downgrade threshold raised to >+2.0%/yr.\n\n## [1.2.0] - 2026-03-19\n\n### Added\n- **Usage tracking** — Monthly and total API call counts per key, visible in admin panel\n- **Bybit V5 + OKX V5 fallback chain** — Funding rate and OI now have 4-level fallback: Binance → OKX → Bybit → CoinGlass → default. 98%+ uptime for positioning data\n- **DXY in API** — Frankfurter EUR/USD proxy added to API (was missing, affected regime classification)\n- **Aave V3 support** — DeFi position monitoring now supports both Spark Protocol and Aave V3 with per-collateral liquidation thresholds\n\n### Fixed\n- **BTC cycle phase alignment** — API now replicates exact dashboard 9-branch priority order (was simplified 6-branch, causing POST-PEAK vs CORRECTION divergence)\n- **Regime classification fix** — Missing DXY caused false BEAR regime in API (DXY defaulted to 100 → extra bearSignal)\n- **ETH structural score** — Now fetches real data (was hardcoded null → default 50). Lido staking, burn rate, DEX volume, fees, stablecoin TVL all live\n- **Macro regime alignment** — API now calls macro.js as single source of truth (was divergent inline computation)\n\n## [1.1.1] - 2026-03-16\n\n### Added\n- **English standardization** — All API responses in English (was mixed Spanish/English)\n- **ETH Structural Score v2.2** — Widened issuance bands, lending heat directional scoring, hard/soft downgrade reclassification\n- **Weighted warnings in rules cap** — Structural warnings (slow-moving) penalize 0.5x vs tactical 1.0x\n\n### Fixed\n- **False BLOCK prevention** — Mild ETH inflation (+0.3%/yr) no longer triggers defensive policy\n- **CoinGlass fallback fixes** — OI, L/S ratio, MVRV fallback chains corrected (wrong field names, unused data)\n\n## [1.1.0] - 2026-03-13\n\n### Added\n- **Deterministic API contract** — `allowed_actions` and `blocked_actions` use uppercase enum tokens (DCA, WAIT, LEVERAGE_GT_2X) instead of free-text\n- **`reason_codes`** — Machine-parseable tokens in `binding_constraint` (e.g., MACRO_RISK_OFF, COUPLING_NORMAL)\n- **`ttl_seconds`** — Cache TTL in response (60s) for agent scheduling\n- **`binding_constraint.source` uppercased** — RULES, DEFI, MACRO, CYCLE (consistent enum style)\n\n### Changed\n- **SKILL.md rewritten** — Binding precedence section, decision rules table, failure modes table, updated example response\n\n## [1.0.0] - 2026-03-12\n\n### Added\n- **Initial release** — `POST /v1/risk-state` endpoint\n- **5-level policy engine** — BLOCK (1-2) → CAUTIOUS (3) → GREEN (4-5)\n- **Multi-asset support** — BTC and ETH with asset-specific scoring\n- **4-cap system** — Rules, DeFi, Macro, Cycle caps × quality × volatility adjustment\n- **30+ real-time signals** — Macro, on-chain, derivatives, DeFi health, sentiment\n- **DeFi-aware** — Optional wallet parameter for Spark/Aave V3 health factor integration\n- **SHA-256 policy hash** — Deterministic audit trail for non-repudiation\n- **Hierarchical risk flags** — `structural_blockers` (hard stop) vs `context_risks` (reduce conviction)\n- **60s Blob cache** — Skip cache when wallet parameter provided\n- **Bearer auth** — Fail-closed authentication\n- **SKILL.md** — Agent discovery file for skills.sh and agentskills.io ecosystems\n- **Full API documentation** — docs/api-v1.md with field types, error codes, interpretation guide\n\nFile v1.4.1:docs/api-v1.md\n\n# RiskState API v1 Documentation\n\nPre-trade risk permissions for BTC/USD and ETH/USD. Spot, perpetual futures (perps), and DeFi borrowing aware.\n\n> **USD-denominated:** All scoring is based on BTC/USD and ETH/USD price action, derivatives, and macro conditions. If you trade non-USD pairs (e.g., BTC/EUR, ETH/BTC), additional cross-rate risk is not covered by this API.\n\n## Endpoint\n\n```\nPOST /v1/risk-state\n```\n\n## Authentication\n\nAll requests require a Bearer token in the `Authorization` header.\n\n```\nAuthorization: Bearer <your_api_key>\n```\n\n### Key types\n\n| Type | Format | Rate limit | Access |\n|------|--------|------------|--------|\n| **Owner** | `RISKSTATE_API_KEY` env var | Unlimited | All endpoints |\n| **External** | `rs_live_` + 64 hex chars | 60 req/min | `/v1/risk-state` + read-only endpoints |\n\n### Getting an API key\n\nRequest API access at [https://riskstate.ai](https://riskstate.ai) — only an email is required. You'll receive an `rs_live_` key via email within minutes.\n\nKeys are managed through the `/api/api-keys` admin endpoint (owner-only).\n\nThe endpoint **fails closed**: if the server secret is not configured, all requests are denied (401). Rate-limited requests return 429 with `retry_after_seconds: 60`.\n\n## Request\n\n### Headers\n\n| Header | Required | Value |\n|--------|----------|-------|\n| `Authorization` | Yes | `Bearer <token>` |\n| `Content-Type` | Yes | `application/json` |\n\n### Body (JSON)\n\n| Field | Type | Default | Description |\n|-------|------|---------|-------------|\n| `asset` | string | `\"BTC\"` | Asset to evaluate. `\"BTC\"` or `\"ETH\"`. |\n| `wallet` | string | `null` | Ethereum wallet address (0x...) for DeFi position data. Optional. |\n| `protocol` | string | `\"spark\"` | DeFi lending protocol. `\"spark\"` or `\"aave\"`. Only used when `wallet` is provided. |\n| `include_details` | boolean | `false` | Include expanded scoring details in response. |\n| `reference_time` | number | `now` | Unix seconds. Pins `daysSinceHalving` and the policy hash to a single timestamp, enabling bit-exact reproducibility. Must be in `[halving, now+1d]`. |\n| `allow_degraded` | boolean | `false` | If `false` (default), the endpoint returns **503 Core data unavailable** when any of `price`, `rsi`, `funding` are missing upstream. Set to `true` to receive a degraded policy (with `data_integrity` capped). |\n\n### Example requests\n\n**Minimal (BTC):**\n\n```bash\ncurl -X POST https://api.riskstate.ai/v1/risk-state \\\n  -H \"Authorization: Bearer $RISKSTATE_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"asset\": \"BTC\"}'\n```\n\n**Detailed (with scoring breakdown):**\n\n```bash\ncurl -X POST https://api.riskstate.ai/v1/risk-state \\\n  -H \"Authorization: Bearer $RISKSTATE_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"asset\": \"BTC\", \"include_details\": true}'\n```\n\n**DeFi monitoring (with wallet + Aave):**\n\n```bash\ncurl -X POST https://api.riskstate.ai/v1/risk-state \\\n  -H \"Authorization: Bearer $RISKSTATE_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"asset\": \"ETH\", \"wallet\": \"0xYOUR_WALLET_ADDRESS\", \"protocol\": \"aave\", \"include_details\": true}'\n```\n\n> **Note:** All parameters go inside the `-d` JSON string. The `\\` at the end of each line is a shell line continuation — the entire command is one curl call.\n\n### Validation\n\n- `asset` must be `\"BTC\"` or `\"ETH\"` (case-insensitive) → 400 otherwise\n- `wallet` must match `^0x[a-fA-F0-9]{40}$` if provided → 400 otherwise\n- `protocol` must be `\"spark\"` or `\"aave\"` (case-insensitive) → 400 otherwise\n- `reference_time` must be a finite number in `[new Date('2024-04-20').getTime()/1000, now+86400]` if provided → 400 otherwise\n- Invalid JSON body → 400\n- Core data missing (and `allow_degraded` not set) → **503** with `Retry-After: 30` and body `{ error, missing, sources, retry_after_seconds, hint }`\n\n### Determinism contract (v1.2.0)\n\nThe policy hash now includes `api_version`, `scoring_version`, `ts` (from `reference_time`), prices, indicators, **positioning** (funding percentile, OI z-score, squeeze direction), **macro** (regime, coupling, DXY), **volatility** (regime + score), **cycle** (phase, MVRV percentile, boost flag), composite, and policy binding. Given identical inputs and the same `reference_time`, the hash is bit-for-bit identical across requests.\n\n## Response — Minimal (default)\n\nThree blocks: **Permissioning**, **Classification**, **Auditability**.\n\n### Permissioning\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `exposure_policy.max_size_fraction` | float (0–1) | Maximum position size as fraction of portfolio |\n| `exposure_policy.leverage_allowed` | boolean | Whether leverage is permitted |\n| `exposure_policy.max_leverage` | string | Maximum leverage for DeFi borrowing (`\"0x\"`, `\"1x\"`, `\"1.5x\"`, `\"2x\"`). For perps, use `max_size_fraction` as notional cap instead. |\n| `exposure_policy.direction_bias` | string | `\"LONG_PREFERRED\"`, `\"SHORT_PREFERRED\"`, or `\"NEUTRAL\"` |\n| `exposure_policy.reduce_recommended` | boolean | Agent should reduce exposure |\n| `exposure_policy.allowed_actions` | string[] | Actions the agent MAY take (enum tokens, see reference below) |\n| `exposure_policy.blocked_actions` | string[] | Actions the agent MUST NOT take (enum tokens, see reference below) |\n\n### Classification\n\n| Field | Type | Range | Description |\n|-------|------|-------|-------------|\n| `tactical_state` | string | BULLISH, LEAN BULL, NEUTRAL, LEAN BEAR, BEARISH | 24-72h directional tilt from composite |\n| `structural_state` | string | Cycle phase | BTC: BOTTOM/EARLY/MID/LATE/EUPHORIA/CORRECTION/POST-PEAK. ETH: DEPRESSED/VALUE_ZONE/RECOVERY/EXTENDED/DISTRIBUTION |\n| `macro_state` | string | RISK-ON, NEUTRAL, RISK-OFF | Macro regime from FRED data |\n| `market_regime` | string | PANIC, EUPHORIA, SQUEEZE, TREND, RANGE | 5-state unified market regime |\n| `volatility_regime` | string | LOW, NORMAL, HIGH, EXTREME | Volatility classification |\n| `policy_level` | int | 1–5 | Informational classification. The `exposure_policy` fields are the binding constraints. 1=BLOCK Survival, 2=BLOCK Defensive, 3=CAUTIOUS, 4=GREEN Selective, 5=GREEN Expansion |\n| `confidence_score` | float (0–1) | Signal agreement × data quality | Measures subscore agreement and data integrity. NOT a probability of market prediction accuracy. Higher = signals agree more and data is fresher. |\n| `data_quality_score` | int (0–100) | % of data sources live | Percentage of data sources reporting live data. Different scale from `confidence_score` (0–1 factor). <70 = degraded, <50 = unreliable |\n\n### Constraints & Flags\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `binding_constraint.source` | string | Which cap is limiting: `\"RULES\"`, `\"DEFI\"`, `\"MACRO\"`, `\"CYCLE\"` |\n| `binding_constraint.reason` | string | Human-readable explanation (e.g., `\"RISK-OFF × NORMAL\"`) |\n| `binding_constraint.reason_codes` | string[] | Machine-parseable reason tokens (e.g., `[\"MACRO_RISK_OFF\", \"COUPLING_NORMAL\"]`) |\n| `binding_constraint.cap_value` | float | The binding cap's value (0–1) |\n| `risk_flags.structural_blockers` | string[] | Hard blockers — agent MUST pause new entries |\n| `risk_flags.context_risks` | string[] | Soft risks — agent should reduce conviction |\n| `defi` | object\\|null | DeFi position data if wallet provided, else `null`. See fields below. |\n| `defi.health_factor` | float | Current health factor (>1 = safe, <1.1 = danger) |\n| `defi.ltv` | float | Current loan-to-value ratio % (debt / collateral × 100). E.g., 35.4 means 35.4% utilized. |\n| `defi.max_ltv` | float | Protocol's maximum LTV threshold % (e.g., 82.99). Borrowing above this is blocked. |\n| `defi.liquidation_threshold` | float | Liquidation threshold % (e.g., 82.5). Position liquidatable above this. |\n| `defi.protocol` | string | `\"spark\"` or `\"aave\"` |\n\n### Auditability\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `policy_hash` | string | SHA-256 hash of policy inputs for non-repudiation |\n| `scoring_version` | string | `\"score_v2\"` — scoring algorithm version |\n| `version` | string | `\"1.2.2\"` — API version |\n| `timestamp` | string | ISO 8601 timestamp |\n| `asset` | string | Asset evaluated |\n| `cached` | boolean | Whether response was served from cache |\n| `ttl_seconds` | int | Cache TTL in seconds (60). Agent should re-request after this interval for fresh data. |\n| `key_type` | string | `\"owner\"` or `\"external\"` — identifies which auth tier was used |\n| `stale_fields` | string[] | Core signals that are missing or stale |\n\n## Response — Detailed (`include_details=true`)\n\nAll minimal fields plus:\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `caps.rules` | float | Rules cap (0–1) |\n| `caps.defi` | float | DeFi health cap (0–1) |\n| `caps.macro` | float | Macro regime cap (0–1) |\n| `caps.cycle` | float | Cycle phase cap (0–1) |\n| `caps.quality` | float | Quality factor (conflict × integrity) |\n| `caps.data_integrity` | float | Data freshness score |\n| `positioning.squeeze_direction` | string | UPSIDE, DOWNSIDE, TWO-SIDED, NONE |\n| `positioning.squeeze_confidence` | int | 0–100 |\n| `positioning.ls_crowding` | string | LONG_CROWDED, SHORT_CROWDED, BALANCED, etc. |\n| `positioning.ls_crowding_score` | int | 0–100 |\n| `positioning.funding_percentile` | int | Funding rate percentile vs 30d (0–100) |\n| `positioning.oi_zscore` | float | OI z-score vs 30d |\n| `positioning.basis_pct` | float | Perp-spot basis % |\n| `volatility.regime` | string | LOW, NORMAL, HIGH, EXTREME |\n| `volatility.score` | int | 0–100 |\n| `whale_pressure.score` | int | 0–100 (9 proxy signals) |\n| `whale_pressure.direction` | string | STRONG_BUY, BUY, NEUTRAL, SELL, STRONG_SELL |\n| `trend_strength.score` | int | 0–100 |\n| `trend_strength.direction` | string | STRONG_TREND, TREND, NEUTRAL, COUNTER_TREND, STRONG_COUNTER |\n| `trend_strength.components` | object | `{ ma_cluster, expansion, flow_alignment }` (each 0–100) |\n| `composite.overall` | int | 0–100 weighted composite score |\n| `composite.subscores` | array | `[{ name, score, weight }]` — 7-8 subscores |\n| `extreme_scores.panic` | int | 0–100 panic percentile |\n| `extreme_scores.euphoria` | int | 0–100 euphoria percentile |\n| `eth_structural` | object\\|null | ETH structural score (ETH only): `{ overall, label, dataQuality, subfamilies: { network, supply, relative, demand } }` |\n| `eth_downgrade` | object\\|null | ETH structural downgrade (ETH only): `{ active, count, hardCount, softCount, severity, signals, capReduction }` |\n| `macro_detail` | object | Full macro data for diagnostics: `{ regime, coupling, realRate10y, liquidityRegime, yield10y, yield10yChg, spxChangePct, fedBsDelta3m, spread10y2y, riskOffSignals, riskOnSignals, dxy }` |\n| `data_sources` | object | Per-field source status (LIVE/MOCK/CG_FALLBACK/CC_FALLBACK/DEFAULT) |\n| `core_missing` | string[] | Missing core signals |\n\n## Error Responses\n\n| Status | Body | Cause |\n|--------|------|-------|\n| 400 | `{ \"error\": \"Invalid JSON body\" }` | Malformed JSON |\n| 400 | `{ \"error\": \"Invalid asset. Must be BTC or ETH.\" }` | Unknown asset |\n| 400 | `{ \"error\": \"Invalid wallet address format.\" }` | Bad wallet format |\n| 401 | `{ \"error\": \"Unauthorized\" }` | Missing or invalid Bearer token |\n| 429 | `{ \"error\": \"Rate limit exceeded\", \"retry_after_seconds\": 60 }` | External key exceeded 60 req/min |\n| 500 | `{ \"error\": \"Internal server error\" }` | Server-side failure |\n\n## Data Sources & Fallback Chain\n\nThe endpoint fetches from 15+ external APIs in parallel waves. Binance returns HTTP 451 from Netlify servers, so all Binance data has fallbacks:\n\n| Data | Primary | Fallback | Last Resort |\n|------|---------|----------|-------------|\n| RSI (4h) | Binance klines | CryptoCompare `histohour` | Default 50 |\n| Funding rate | Binance `fundingRate` | OKX V5 → Bybit V5 → CoinGlass | Default 0 |\n| Daily klines (200d) | Binance klines | CryptoCompare `histoday` | `null` (trend strength unavailable) |\n| MVRV | blockchain.info | CoinGlass `/indicator/market/mvrv` | Default 1.8 |\n| Real Rate | FRED T10YIE (breakeven) | — | `null` |\n| Liquidity Regime | FRED WALCL (13-week delta) | — | `NEUTRAL` |\n| Gold | Yahoo Finance | — | `null` |\n| Macro regime + coupling | `/api/macro` (single source of truth) | — | `NEUTRAL` / `NORMAL` |\n| ETH Structural | Lido + Ultrasound + DefiLlama (6 APIs) | — | Score defaults to 50 |\n| SPX | Yahoo Finance (^GSPC) via macro.js | FRED SP500 (T-1 lag) | `null` |\n| Staking APR | Lido `/apr/last` | Lido `/apr/sma` | Default 2.8% |\n\nThe `data_sources` field (in detailed response) shows per-field source: `LIVE`, `CC_FALLBACK` (CryptoCompare), `CG_FALLBACK` (CoinGlass), `ESTIMATED` (price-based), `DEFAULT_ZERO`, `DEFAULT`, or `MOCK`.\n\n### Known Data Limitations (v1.2.0)\n\nBinance returns HTTP 451 from Netlify servers. Current CoinGlass tier lacks certain endpoints. These cause permanent fallback states for some fields:\n\n| Field | Server Status | Impact | Dashboard Comparison |\n|-------|--------------|--------|---------------------|\n| Funding | OKX or BYBIT fallback | Live data via cascading fallback chain. Neutral default (0) only if all fallbacks fail | Dashboard gets real data from browser-side Binance |\n| Open Interest | OKX or BYBIT fallback | Live data via cascading fallback chain. Affects squeeze detection and OI z-score | Dashboard gets real data from browser-side Binance |\n| MVRV | ESTIMATED (~price/$53K realized, env-overridable) | Accurate to ±5%. Affects cycle phase near thresholds | Dashboard gets real MVRV from blockchain.info |\n| DXY | LIVE (Frankfurter EUR/USD proxy) | Same formula as dashboard. Affects detectRegime + macro scoring | Dashboard uses same Frankfurter proxy via market-data.js |\n\n### Known Scoring Divergence (disclosed 2026-06-11)\n\n**CVD acceleration (server-side) uses a signed-mean denominator that can overstate \"extreme acceleration\" in choppy markets.** The dashboard and visualizer were fixed in `score_v3.2` (2026-05-19) to use a magnitude (absolute-mean) denominator; the server-side mirror of this signal — feeding the API's whale-pressure score, the tactical volume component, and Telegram whale alerts — deliberately retains the previous formula until `score_v4`, because changing it alters scoring output and the scoring freeze (until 2026-11-19) prohibits that outside the escape-valve protocol.\n\nPractical impact: in range-bound/alternating-flow conditions the API's whale and tactical-volume readings can register a false \"extreme\" that the dashboard does not. Snapshot telemetry (v6.5 `shadow_v4.cvd_accel`, June 2026) measures the live divergence per 4h snapshot; the fix ships as part of `score_v4` (V4-6 in `specs/institutional-roadmap-2026H2.md`). Composite, policy level, and `max_size_fraction` are affected only through the whale/volume contributions (≤10% weight each within their layers).\n\n### API vs Dashboard Classification Alignment (v1.2.0, Mar 19 2026)\n\nAll classification fields now match between API and dashboard for the same market conditions:\n\n| Field | Status | Notes |\n|-------|--------|-------|\n| cycle_phase | Aligned | Full 9-branch BTC classification (was simplified 6-branch) |\n| market_regime | Aligned | DXY fix resolved false BEAR → TREND (was missing Frankfurter call) |\n| macro_state | Aligned | Same macro.js as single source of truth |\n| composite | Aligned | Same scoring-core.js functions |\n| policy_level | Aligned | Same cap computation; DeFi cap differs when API called without wallet |\n\n**Expected deltas** (not bugs — different data availability):\n- **DeFi cap**: API=100% (no wallet) vs dashboard=84% (wallet connected) — pass `wallet` param to API for parity\n- **Whale score**: ~9pt gap — browser computes 9 signals with real-time data; server has fewer\n- **Trend strength**: ~3pt gap — minor data timing/source differences\n- **Quality factor**: ~8pt gap — DeFi cap + subscore spread differences affect conflict_penalty\n\nAll other fields (RSI, daily klines, L/S ratio, CVD, ETF, exchange flow, macro, correlations, ETH structural) have working fallback chains.\n\n## Caching Behavior\n\n- **60-second TTL** via Netlify Blobs\n- First call: 5–12 seconds (fetches from 15+ external APIs in 5 parallel waves)\n- Subsequent calls within 60s: <1 second\n- `cached: true` in response indicates cache hit\n- **Wallet parameter bypasses cache** (DeFi data is personalized)\n\n## Action Enums Reference\n\n### `allowed_actions` values\n\n| Token | Meaning | Policy Levels |\n|-------|---------|---------------|\n| `REDUCE` | Reduce existing exposure | 1 |\n| `ADD_COLLATERAL` | Add collateral to DeFi position | 1 |\n| `HEDGE` | Hedge existing positions | 1, 2 |\n| `WAIT` | Wait for better conditions | 2, 3 |\n| `REDUCE_LEVERAGE` | Reduce leverage on existing positions | 2 |\n| `SCALP_SMALL` | Small scalp trades only | 2 |\n| `RR_GT_2` | Trades with R:R > 2:1 only | 2, 3 |\n| `DCA` | Dollar-cost averaging | 3, 4 |\n| `LIGHT_ACCUMULATION` | Light spot accumulation | 3 |\n| `LONG_SHORT_CONFIRMED` | Long or short with confirmation signals | 4 |\n| `LEVERAGE_MODERATE` | Moderate leverage (up to 1.5x) | 4 |\n| `TREND_FOLLOW` | Trend following strategies | 5 |\n| `ADD_ON_PULLBACK` | Add to winners on pullbacks | 5 |\n| `LEVERAGE_2X` | Leverage up to 2x | 5 |\n| `AGGRESSIVE_ACCUMULATION` | Aggressive spot accumulation | 5 |\n\n### `blocked_actions` values\n\n| Token | Meaning | Policy Levels |\n|-------|---------|---------------|\n| `NEW_TRADES` | All new position entries blocked | 1 |\n| `LEVERAGE` | Any leverage blocked | 1, 3 |\n| `INCREASE_POSITION` | Increasing existing positions blocked | 1 |\n| `LEVERAGE_GT_1X` | Leverage above 1x blocked | 2 |\n| `AGGRESSIVE_LONG` | Aggressive long entries blocked | 2, 3 |\n| `FOMO_ENTRY` | FOMO-driven entries blocked | 2 |\n| `ALL_IN` | Full portfolio allocation blocked | 3, 4 |\n| `LEVERAGE_GT_2X` | Leverage above 2x blocked | 4 |\n| `COUNTER_TREND_SHORT` | Shorting against confirmed trend blocked | 5 |\n\n### `binding_constraint.reason_codes` values\n\n| Source | Possible codes | Example |\n|--------|---------------|---------|\n| RULES | `RULES_CRITICAL_{n}`, `RULES_WARNING_{n}` | `[\"RULES_CRITICAL_2\", \"RULES_WARNING_5\"]` |\n| DEFI | `DEFI_HF_LOW` | `[\"DEFI_HF_LOW\"]` |\n| MACRO | `MACRO_{regime}`, `COUPLING_{level}` | `[\"MACRO_RISK_OFF\", \"COUPLING_HIGH_COUPLING\"]` |\n| CYCLE | `CYCLE_{phase}` | `[\"CYCLE_MID\"]`, `[\"CYCLE_EUPHORIA\"]` |\n\n## Risk Flags Reference\n\n### Structural Blockers (agent MUST pause)\n\n| Flag | Meaning |\n|------|---------|\n| `DEFI_LIQUIDATION_RISK` | Health Factor critically low |\n| `SQUEEZE_RISK` | High-confidence directional squeeze |\n| `MACRO_CONTAGION` | SPX/QQQ selloff >1.5% with normal or high coupling |\n| `MACRO_RISK_OFF` | Macro regime risk-off with multiple signals |\n| `ONCHAIN_EUPHORIA` | MVRV + NUPL at historical extremes |\n| `EXTREME_FEAR` | F&G ≤ 10 (panic conditions) |\n| `FUNDING_EXTREME` | Funding + RSI both extreme |\n| `LIQUIDATION_CASCADE` | >$100M liquidations with asymmetry |\n\n### Context Risks (agent should reduce conviction)\n\n| Flag | Meaning |\n|------|---------|\n| `HIGH_FUNDING` | Funding rate elevated |\n| `RSI_OVERBOUGHT` | RSI > 70 |\n| `RSI_OVERSOLD` | RSI < 25 |\n| `DXY_HEADWIND` | DXY > 104 |\n| `YIELD_PRESSURE` | 10Y yield elevated or spiking |\n| `HIGH_OI` | OI z-score > 2.0 (30d) |\n| `BASIS_EXTREME` | Perp-spot basis > 0.15% |\n| `WHALE_ACTIVITY` | Whale score ≥ 50 |\n| `ETH_STRUCTURAL_WEAK` | ETH structural downgrade active |\n| `ETH_SUPPLY_INFLATIONARY` | ETH supply strongly inflationary |\n| `TREND_NOT_CONFIRMED` | Trend strength ≤ 45 with directional tilt |\n| `NO_TREND` | Trend strength ≤ 20 |\n| `HIGH_COUPLING` | High macro correlation |\n| `SIGNAL_CONFLICT` | Subscore dispersion high |\n| `LS_CROWDED` | L/S ratio extreme |\n| `YIELD_SPIKE` | 10Y yield change > 0.08% in session |\n| `CURVE_INVERTED` | 10Y-2Y spread < -0.2% |\n| `REAL_RATE_HEADWIND` | Real rate > 1.5% |\n| `LIQUIDITY_TIGHTENING` | Fed balance sheet shrinking (3m delta < -1%) |\n| `STAKING_HEADWIND` | Real rate > ETH staking APR (ETH only) |\n| `LIQUIDATION_ASYMMETRY` | >75% of liquidations on one side |\n\n## How to Use by Context\n\nThe API returns the same response regardless of how you trade. The **market conditions assessment** (composite score, regime, policy level) is identical. What changes is how you **interpret the risk permissions** for your specific context.\n\n### Spot Trading (BTC/USD or ETH/USD)\n\nYou are buying or selling the asset on a spot exchange (Coinbase, Binance Spot, Kraken, Uniswap, CoW Swap).\n\n**Key fields:**\n- `max_size_fraction` → **% of portfolio to deploy.** If 0.33, allocate up to 33% of your portfolio to this position.\n- `direction_bias` → `LONG_PREFERRED` means \"buy signal.\" `SHORT_PREFERRED` means \"don't buy / consider selling.\" `NEUTRAL` means \"no directional edge.\"\n- `structural_blockers` → If non-empty, do not buy.\n- `allowed_actions` / `blocked_actions` → Filter for relevant actions (DCA, WAIT, LIGHT_ACCUMULATION).\n\n**Ignore for spot:** `max_leverage`, `leverage_allowed`, and leverage-related blocked actions (`LEVERAGE_GT_1X`, `LEVERAGE_GT_2X`). These apply to leveraged markets and DeFi borrowing.\n\n**Pre-trade workflow:**\n1. Call the API with `{\"asset\": \"BTC\"}`\n2. Check `structural_blockers` — if non-empty, do not enter\n3. Read `max_size_fraction` — this is your max allocation\n4. Check `direction_bias` — respect the directional guidance\n5. Proceed to your exchange and place the spot order\n\n### Perpetual Futures (Perps)\n\nYou are trading BTC/USDT or ETH/USDT perpetuals on Binance Futures, Hyperliquid, dYdX, Bybit, or similar venues.\n\n**Key fields:**\n- `max_size_fraction` → **Max notional exposure as % of portfolio.** If 0.33 and your portfolio is $100K, your max notional is $33K. At 10x leverage, that means max $3.3K margin.\n- `direction_bias` → Directly actionable: `LONG_PREFERRED` favors longs, `SHORT_PREFERRED` favors shorts.\n- `structural_blockers` → If `SQUEEZE_RISK` is present, **do not open leveraged positions** — liquidation risk is elevated.\n\n**Especially relevant for perps (in detailed response):**\n- `positioning.funding_percentile` → How extreme the current funding rate is vs. 30 days. P>85 = paying heavy carry on longs. P<15 = shorts are crowded.\n- `positioning.basis_pct` → Perp-spot premium. Positive = longs dominant, negative = discount.\n- `positioning.squeeze_direction` → UPSIDE (short squeeze probable) or DOWNSIDE (long squeeze probable).\n- `positioning.oi_zscore` → OI z-score vs. 30 days. >2.0 = excessive leverage in the market.\n\n**Margin guide (from `max_size_fraction`):**\n\n| Your leverage | Max margin (% of portfolio) | Example ($100K portfolio, max_size=0.33) |\n|---------------|----------------------------|------------------------------------------|\n| 3x | max_size / 3 = 11.0% | $11,000 margin |\n| 5x | max_size / 5 = 6.6% | $6,600 margin |\n| 10x | max_size / 10 = 3.3% | $3,300 margin |\n| 25x | max_size / 25 = 1.3% | $1,300 margin |\n\n> **Note:** RiskState does not impose a leverage cap for perpetual futures. The `max_leverage` field reflects DeFi borrowing constraints (see below). For perps, the binding constraint is `max_size_fraction` as max notional exposure — you choose your own leverage within that cap.\n\n**Pre-trade workflow (e.g., Hyperliquid):**\n1. Call the API with `{\"asset\": \"BTC\", \"include_details\": true}`\n2. Check `structural_blockers` — if `SQUEEZE_RISK` present, do not open leveraged positions\n3. Read `max_size_fraction` — this is your max notional as % of portfolio\n4. Divide by your intended leverage to get max margin\n5. Check `positioning.funding_percentile` — if P>85, longs are paying heavy carry\n6. Check `positioning.squeeze_direction` — if DOWNSIDE, longs are at risk\n7. Respect `direction_bias` for trade direction\n8. Place your order on the venue\n\n### DeFi Borrowing (Aave, Spark, Morpho)\n\nYou borrow stablecoins against BTC or ETH collateral on-chain.\n\n**Key fields:**\n- `max_size_fraction` → **% of collateral to deploy.** Accounts for your current health factor.\n- `max_leverage` → Borrowing ratio cap: `\"0x\"` (don't borrow), `\"1x\"`, `\"1.5x\"`, `\"2x\"`.\n- `defi.health_factor` → Current health factor (>1 safe, <1.1 danger).\n- `defi.ltv` → Current loan-to-value ratio.\n- `binding_constraint.source` → If `\"DEFI\"`, your on-chain position is the limiting factor.\n\n**Pre-trade workflow:**\n1. Call the API with `{\"asset\": \"ETH\", \"wallet\": \"0xYOUR_WALLET\", \"protocol\": \"aave\"}`\n2. Check `defi.health_factor` — if <1.5, prioritize adding collateral\n3. If `binding_constraint.source === \"DEFI\"`, do not increase debt\n4. Respect `max_leverage` for borrowing ratio\n5. If `structural_blockers` contains `DEFI_LIQUIDATION_RISK`, reduce position immediately\n\n### AI Trading Agent Integration\n\nYou are building an autonomous trading agent (Hermes, ElizaOS, OpenClaw, AgentKit, custom) that calls the API programmatically.\n\n**See [SKILL.md](SKILL.md) for the complete agent integration guide**, including:\n- Binding precedence (evaluation order for response fields)\n- Decision rules by policy level\n- Failure modes and conservative fallback behavior\n- Example requests\n\n**Key principle:** Call the API **between decision and execution**. Your agent decides what to trade (intelligence layer). RiskState tells it **how much** it can risk (governance layer). Then the agent executes within those bounds.\n\n## Interpretation Guide\n\n### Position Sizing\n\n**Spot:**\n```\nposition_size = portfolio_value × max_size_fraction × conviction\n```\n\n**Perps:**\n```\nmax_notional = portfolio_value × max_size_fraction × conviction\nmargin = max_notional / leverage\n```\n\nWhere `conviction` is your own confidence factor (0–1), whether human or algorithmic.\n\n### Re-consultation Frequency\n\n| Use case | Recommended interval |\n|----------|---------------------|\n| Active trading (scalps, day trades) | Every 5 minutes |\n| Swing trading (24h–72h holds) | Every 15 minutes |\n| Holding / DCA | Every 4 hours |\n| After significant move (>3% 1h) | Immediate |\n\n### When to Force-Check\n\n- Before any new position entry\n- When `policy_level` was previously ≤ 2 (check if conditions improved)\n- After external events (ETF announcements, Fed meetings, major hacks)\n\n## Examples\n\n### Pre-trade check (agent workflow)\n\n```\n1. curl -X POST https://api.riskstate.ai/v1/risk-state \\\n     -H \"Authorization: Bearer $RISKSTATE_API_KEY\" \\\n     -H \"Content-Type: application/json\" \\\n     -d '{\"asset\": \"BTC\"}'\n2. If structural_blockers non-empty → ABORT new entries\n3. If blocked_actions contains NEW_TRADES → ABORT new entries\n4. If reduce_recommended → reduce exposure (not necessarily close all)\n5. Size position: max_size_fraction × agent_conviction\n6. Respect max_leverage limit\n7. Respect direction_bias for trade direction\n8. Check allowed_actions before executing\n9. If stale_fields non-empty or data_quality_score < 70 → halve size or abstain\n10. policy_level is summary only — do not use for enforcement\n```\n\n### DeFi monitoring\n\n```bash\ncurl -X POST https://api.riskstate.ai/v1/risk-state \\\n  -H \"Authorization: Bearer $RISKSTATE_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"asset\": \"ETH\", \"wallet\": \"0xYOUR_WALLET_ADDRESS_HERE\", \"include_details\": true}'\n```\n\nThe `defi` field will contain `health_factor` and `ltv` from Spark Protocol or Aave V3.\nIf `binding_constraint.source === \"DEFI\"`, the DeFi position is the limiting factor.\n\nFile v1.4.1:skill-card.md\n\n## Description:\n\nPre-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.\n\nThis skill is ready for commercial/non-commercial use.\n\n## Publisher:\n\n[riskstate](https://clawhub.ai/user/riskstate)\n\n### License/Terms of Use:\n\nMIT-0\n\n## Use Case:\n\nExternal developers, trading-agent builders, systematic trading teams, and capital desks use this skill to query RiskState before opening, sizing, or monitoring BTC/USD and ETH/USD spot, perpetual futures, or DeFi borrowing positions.\n\n### Deployment Geography for Use:\n\nGlobal\n\n## Known Risks and Mitigations:\n\nRisk: The skill can influence automated crypto-trading decisions.\n\nMitigation: Treat outputs as third-party risk inputs, require human review or independent exposure limits for material trades, and do not execute solely from the policy response.\n\nRisk: Optional DeFi checks may send wallet addresses to a third-party API.\n\nMitigation: Avoid operational wallet addresses unless DeFi-specific checks are necessary, and confirm the publisher's wallet-data logging and retention practices.\n\nRisk: The artifact documents an unpinned MCP server install path.\n\nMitigation: Pin package or container versions and run the MCP server in a sandbox before connecting it to trading workflows.\n\nRisk: The API documentation discloses a known scoring divergence affecting whale and tactical-volume readings until a corrected scoring version is deployed.\n\nMitigation: Use human review or independent limits for material trades until the corrected scoring version is released and verified.\n\nRisk: Stale, degraded, or low-confidence market data can reduce policy reliability.\n\nMitigation: Follow the artifact's failure guidance: downgrade conviction, halve or avoid position sizing when data quality is degraded, and fail closed on timeouts or core data errors.\n\n## Reference(s):\n\n- [ClawHub skill listing](https://clawhub.ai/riskstate/skills/riskstate)\n- [RiskState website](https://riskstate.ai)\n- [RiskState API documentation](https://riskstate.ai/docs/api)\n- [Local API reference](docs/api-v1.md)\n\n## Skill Output:\n\n**Output Type(s):** [guidance, shell commands, code, configuration]\n\n**Output Format:** [Markdown guidance with JSON and shell command examples]\n\n**Output Parameters:** [1D]\n\n**Other Properties Related to Output:** [Uses bearer-token authentication through RISKSTATE_API_KEY and returns risk-policy fields from a third-party API.]\n\n## Skill Version(s):\n\n1.4.1 (source: server release metadata and frontmatter)\n\n## Ethical Considerations:\n\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment.\n\nArchive v1.4.0: 6 files, 22826 bytes\n\nFiles: CHANGELOG.md (6257b), docs/api-v1.md (26262b), README.md (9886b), skill-card.md (2670b), SKILL.md (7314b), _meta.json (128b)\n\nFile v1.4.0:SKILL.md\n\n---\nname: riskstate\nversion: 1.4.0\ndescription: 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.\ncategory: risk-management\nauth: bearer-token\nenv: RISKSTATE_API_KEY\nendpoint: POST https://api.riskstate.ai/v1/risk-state\nassets: [BTC, ETH]\nrefresh: 60s cache, recommend 5min polling\nhomepage: https://riskstate.ai\ndocs: https://riskstate.ai/docs/api\nrepository: https://github.com/likidodefi/riskstate-docs\ntags: [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]\npricing: free-beta\nauthor: RiskState\nlicense: proprietary\n---\n\n# RiskState — Pre-Trade Risk Layer for Crypto\n\n## What it does\n\nReturns **dynamic risk permissions** for BTC/USD and ETH/USD before capital is deployed.\nA 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**.\n\nThe response tells you:\n- **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).\n- **allowed_actions / blocked_actions**: What MAY and MUST NOT be done (enum tokens)\n- **risk_flags**: Structural blockers (hard stop) vs contextual risks (reduce conviction)\n- **binding_constraint**: Which cap is limiting and why\n- **policy_level**: 1–5 summary label (informational — use `exposure_policy` for enforcement)\n\n## What it does NOT do\n\n- No trade signals, no entry/exit prices, no predictions\n- No portfolio allocation advice\n- No order execution or routing\n- No historical data or backtesting\n\nThis is a **risk governor**, not a trading oracle. The assessment is USD-denominated.\n\n## When to call\n\n- **Before opening or sizing positions** — check permissions first\n- **Periodically during holds** — every 5 min for active trading, every 4h for holding\n- **After significant market moves** — cache invalidates after 60s (`ttl_seconds` in response)\n\n## Authentication\n\nRequest 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:\n\n```\nAuthorization: Bearer $RISKSTATE_API_KEY\n```\n\n## Binding precedence\n\nWhen consuming the response, agents MUST evaluate fields in this order:\n\n1. `risk_flags.structural_blockers` — if non-empty, ABORT new entries\n2. `exposure_policy.blocked_actions` — actions the agent MUST NOT take\n3. `exposure_policy.reduce_recommended` — reduce exposure if true\n4. `exposure_policy.max_size_fraction` — maximum position size\n5. `exposure_policy.max_leverage` — maximum leverage allowed\n6. `exposure_policy.direction_bias` — preferred trade direction\n7. `policy_level` — informational summary only, do not use for enforcement\n\n## Decision rules by policy level\n\n| `policy_level` | Summary | Key constraints |\n|----------------|---------|-----------------|\n| 1 (BLOCK Survival) | No new positions | `blocked_actions: [NEW_TRADES, ...]`, `max_leverage: \"0x\"` |\n| 2 (BLOCK Defensive) | Wait or hedge only | `blocked_actions: [AGGRESSIVE_LONG, ...]`, `max_leverage: \"1x\"` |\n| 3 (CAUTIOUS) | DCA with R:R >2:1 | `blocked_actions: [LEVERAGE, ALL_IN, ...]`, `max_leverage: \"1x\"` |\n| 4 (GREEN Selective) | Trade with confirmation | `max_leverage: \"1.5x\"` |\n| 5 (GREEN Expansion) | Full operations | `max_leverage: \"2x\"` |\n\n`policy_level` is a convenience label. Always check `exposure_policy` fields for actual constraints.\n\n## Failure modes\n\n| Condition | Agent behavior |\n|-----------|----------------|\n| `stale_fields` contains core indicators (price, funding, rsi) | Downgrade conviction. Data integrity compromised. |\n| `data_quality_score` < 70 | Treat as degraded. Reduce position sizes by 50%. |\n| `data_quality_score` < 50 | Treat as unreliable. Do not open new positions. |\n| `confidence_score` < 0.5 | Signals conflict heavily. Prefer WAIT over action. |\n| HTTP 500 or timeout | Assume worst case (BLOCK). Retry after 60s. |\n| `cached: true` + `stale_fields` non-empty | Re-request after cache TTL (60s) for fresh data. |\n\n## Security\n\n**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.\n\n**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.\n\n## Example requests\n\n### Minimal (BTC)\n\n```bash\ncurl -X POST https://api.riskstate.ai/v1/risk-state \\\n  -H \"Authorization: Bearer $RISKSTATE_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"asset\": \"BTC\"}'\n```\n\n### Detailed (with scoring breakdown)\n\n```bash\ncurl -X POST https://api.riskstate.ai/v1/risk-state \\\n  -H \"Authorization: Bearer $RISKSTATE_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"asset\": \"BTC\", \"include_details\": true}'\n```\n\n### DeFi monitoring (with wallet)\n\n```bash\ncurl -X POST https://api.riskstate.ai/v1/risk-state \\\n  -H \"Authorization: Bearer $RISKSTATE_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"asset\": \"ETH\", \"wallet\": \"0xYOUR_WALLET_ADDRESS\", \"include_details\": true}'\n```\n\n## Example response (minimal)\n\n```json\n{\n  \"exposure_policy\": {\n    \"max_size_fraction\": 0.42,\n    \"leverage_allowed\": false,\n    \"max_leverage\": \"1x\",\n    \"direction_bias\": \"LONG_PREFERRED\",\n    \"reduce_recommended\": false,\n    \"allowed_actions\": [\"DCA\", \"WAIT\", \"LIGHT_ACCUMULATION\", \"RR_GT_2\"],\n    \"blocked_actions\": [\"LEVERAGE\", \"AGGRESSIVE_LONG\", \"ALL_IN\"]\n  },\n  \"tactical_state\": \"LEAN BULL\",\n  \"structural_state\": \"MID\",\n  \"macro_state\": \"NEUTRAL\",\n  \"market_regime\": \"TREND\",\n  \"volatility_regime\": \"NORMAL\",\n  \"policy_level\": 3,\n  \"confidence_score\": 0.72,\n  \"data_quality_score\": 85,\n  \"binding_constraint\": {\n    \"source\": \"MACRO\",\n    \"reason\": \"NEUTRAL × NORMAL\",\n    \"reason_codes\": [\"MACRO_NEUTRAL\", \"COUPLING_NORMAL\"],\n    \"cap_value\": 0.70\n  },\n  \"risk_flags\": {\n    \"structural_blockers\": [],\n    \"context_risks\": [\"HIGH_FUNDING\"]\n  },\n  \"defi\": null,\n  \"policy_hash\": \"a1b2c3d4e5f6...\",\n  \"scoring_version\": \"score_v2\",\n  \"version\": \"1.2.2\",\n  \"timestamp\": \"2026-03-13T14:30:00.000Z\",\n  \"asset\": \"BTC\",\n  \"cached\": false,\n  \"ttl_seconds\": 60,\n  \"stale_fields\": []\n}\n```\n\n## Detailed response\n\nPass `\"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`.\n\nSee [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.\n\nFile v1.4.0:README.md\n\n<p align=\"center\">\n  <img src=\"https://riskstate.ai/logo-r-grey.svg\" width=\"48\" alt=\"RiskState\" />\n</p>\n\n<h1 align=\"center\">RiskState</h1>\n\n<p align=\"center\">\n  <strong>Pre-trade risk API for crypto — BTC/USD and ETH/USD exposure governance</strong><br />\n  <sub>For trading agents, open-source systems, and capital desks. Spot and perpetual futures (perps). DeFi borrowing aware.</sub>\n</p>\n\n<p align=\"center\">\n  <a href=\"https://api.riskstate.ai/v1/risk-state\"><img src=\"https://img.shields.io/badge/API-v1.4.0-blue?style=flat-square\" alt=\"API Version\" /></a>\n  <a href=\"https://riskstate.ai\"><img src=\"https://img.shields.io/badge/status-beta-green?style=flat-square\" alt=\"Status\" /></a>\n  <a href=\"#supported-assets\"><img src=\"https://img.shields.io/badge/assets-BTC%2FUSD%20%7C%20ETH%2FUSD-orange?style=flat-square\" alt=\"Assets\" /></a>\n  <a href=\"#markets\"><img src=\"https://img.shields.io/badge/markets-spot%20%7C%20perps%20%7C%20DeFi-purple?style=flat-square\" alt=\"Markets\" /></a>\n  <a href=\"#pricing\"><img src=\"https://img.shields.io/badge/pricing-free%20beta-brightgreen?style=flat-square\" alt=\"Pricing\" /></a>\n</p>\n\n<p align=\"center\">\n  <a href=\"https://riskstate.ai\">Website</a> · <a href=\"docs/api-v1.md\">API Reference</a> · <a href=\"SKILL.md\">SKILL.md</a> · <a href=\"https://x.com/riskstate_ai\">X/Twitter</a>\n</p>\n\n---\n\n## What is RiskState?\n\nA deterministic engine that converts live market state into **dynamic risk permissions** — exposure limits, leverage caps, and allowed actions — before capital is deployed.\n\nOne API call returns position limits, allowed actions, and policy constraints computed from **30+ real-time signals** across macro, on-chain, derivatives, and DeFi health. The assessment is **USD-denominated**: all scoring is based on BTC/USD and ETH/USD price action, derivatives, and macro conditions.\n\n```bash\ncurl -X POST https://api.riskstate.ai/v1/risk-state \\\n  -H \"Authorization: Bearer $RISKSTATE_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"asset\": \"BTC\"}'\n```\n\n```json\n{\n  \"exposure_policy\": {\n    \"max_size_fraction\": 0.42,\n    \"leverage_allowed\": true,\n    \"allowed_actions\": [\"DCA\", \"LONG_SHORT_CONFIRMED\"],\n    \"blocked_actions\": [\"ALL_IN\", \"LEVERAGE_GT_2X\"]\n  },\n  \"policy_level\": 4,\n  \"risk_flags\": {\n    \"structural_blockers\": [],\n    \"context_risks\": [\"HIGH_COUPLING\"]\n  },\n  \"binding_constraint\": {\n    \"source\": \"MACRO\",\n    \"reason_codes\": [\"MACRO_NEUTRAL\", \"COUPLING_NORMAL\"]\n  }\n}\n```\n\nRead `max_size_fraction`, check `structural_blockers`, and act. No parsing. No interpretation.\n\n## Why?\n\nWhether you run an AI trading agent, a systematic trading system, or a manual desk — crypto markets have regime shifts that require adaptive risk governance. Static rules fail. RiskState provides a **pre-trade risk check** that adapts every 60 seconds.\n\n| Without governance | With RiskState |\n|---|---|\n| Position size based on signal confidence alone | Capped at `max_size_fraction` (max notional exposure) |\n| No awareness of macro regime | `RISK-OFF` → `blocked_actions: [\"AGGRESSIVE_LONG\"]` |\n| DeFi health factor ignored | Wallet health feeds directly into position limit |\n| Leverage unbounded | Policy-level constraints enforced |\n| No circuit breaker | `structural_blockers` non-empty → halt |\n\n## Quick Start\n\n### 1. Get an API key\n\nSign up at [riskstate.ai](https://riskstate.ai) — email only, free during beta.\n\n### 2. Query the API\n\n```bash\ncurl -X POST https://api.riskstate.ai/v1/risk-state \\\n  -H \"Authorization: Bearer $RISKSTATE_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"asset\": \"BTC\"}'\n```\n\n### 3. Enforce before execution\n\n**In an AI trading agent (Python):**\n\n```python\nimport requests\n\npolicy = requests.post(\n    \"https://api.riskstate.ai/v1/risk-state\",\n    headers={\"Authorization\": f\"Bearer {API_KEY}\"},\n    json={\"asset\": \"BTC\"}\n).json()\n\n# Hard stop: structural blockers\nif policy[\"risk_flags\"][\"structural_blockers\"]:\n    return  # Do not trade\n\n# Size cap — max notional exposure as fraction of portfolio\nmax_size = policy[\"exposure_policy\"][\"max_size_fraction\"]\nposition_size = min(desired_size, portfolio_value * max_size)\n\n# Action filter\nif \"LEVERAGE\" in policy[\"exposure_policy\"][\"blocked_actions\"]:\n    leverage = 1.0\n```\n\n**In a trading system (pre-trade check):**\n\n```python\n# Before placing a spot or perps order\npolicy = fetch_riskstate(\"ETH\")\n\nif policy[\"risk_flags\"][\"structural_blockers\"]:\n    log(\"BLOCKED: structural risk — skipping order\")\n    return\n\nmax_notional = portfolio_value * policy[\"exposure_policy\"][\"max_size_fraction\"]\n# Spot: max_notional is the $ amount to deploy\n# Perps: max_notional is the notional exposure cap\n#   e.g., at 10x leverage → margin = max_notional / 10\n```\n\n**Manual pre-trade check (curl):**\n\n```bash\n# Quick check before placing an order on Binance/Hyperliquid/Aave\ncurl -s -X POST https://api.riskstate.ai/v1/risk-state \\\n  -H \"Authorization: Bearer $RISKSTATE_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"asset\": \"BTC\"}' | jq '{\n    policy_level, \n    max_size: .exposure_policy.max_size_fraction,\n    blocked: .exposure_policy.blocked_actions,\n    blockers: .risk_flags.structural_blockers\n  }'\n```\n\n## Policy Levels\n\n| Level | Label | Max Size | What your agent can do |\n|-------|-------|----------|----------------------|\n| 1 | BLOCK Survival | <15% | Reduce exposure, hedge only |\n| 2 | BLOCK Defensive | <35% | Wait, hedge, small scalps |\n| 3 | CAUTIOUS | <60% | DCA, R:R >2:1 only |\n| 4 | GREEN Selective | <80% | Trade with confirmation |\n| 5 | GREEN Expansion | ≥80% | Full operations, leverage up to 2x |\n\n## Supported Assets\n\n- **BTC/USD** — Full signal coverage (30+ indicators). Scoring based on BTC/USDT price, derivatives, and macro conditions.\n- **ETH/USD** — Full coverage including ETH structural score, ETH/BTC ratio analysis, staking dynamics, ETH/NASDAQ correlation.\n\n> **Note:** The assessment is USD-denominated. If you trade non-USD pairs (e.g., BTC/EUR, ETH/BTC), additional cross-rate risk is not covered.\n\n## Markets\n\nRiskState evaluates the same underlying market conditions regardless of where you trade. The risk assessment applies to:\n\n| Market | How to use the output |\n|--------|----------------------|\n| **Spot** | `max_size_fraction` = % of portfolio to deploy. Leverage fields are not applicable. |\n| **Perpetual futures (perps)** | `max_size_fraction` = max notional exposure as % of portfolio. At 10x leverage, your margin is `max_size_fraction / 10`. Derivatives signals (funding rate, basis, OI, squeeze risk) are especially relevant. |\n| **DeFi borrowing** | Pass your `wallet` address for health factor and liquidation-aware risk caps. `max_leverage` reflects borrowing ratio (LTV). |\n\nThe API returns the same response for all markets — the difference is how you **interpret** the output. See [API Reference → How to Use by Context](docs/api-v1.md#how-to-use-by-context) for detailed workflows.\n\n## Integration Paths\n\n### REST API\nDirect HTTP calls. Any language, any framework.\n\n### SKILL.md\nDrop [`SKILL.md`](SKILL.md) into your agent's repo. Compatible with Claude Code, Copilot, Cursor, and Gemini via [skills.sh](https://skills.sh).\n\n### MCP Server\n\n```bash\nnpm install @riskstate/mcp-server\n```\n\nOr run directly with `npx @riskstate/mcp-server`. Docker: `ghcr.io/likidodefi/riskstate-mcp`.\n\nOne tool: `get_risk_policy` — same parameters as the REST API. Compatible with Claude Desktop, Claude Code, Cursor, and any MCP-compatible client. See [MCP README](https://riskstate.ai/docs/mcp) for full setup.\n\n## Listed On\n\n- [awesome-mcp-servers](https://github.com/punkpeye/awesome-mcp-servers) — Finance & Fintech category\n- [LobeHub MCP](https://lobehub.com) — Auto-discovered\n- [ClawHub.ai](https://clawhub.ai) — Skill marketplace\n- [skills.sh](https://skills.sh) — Vercel skills registry\n- [Glama.ai](https://glama.ai) — AAA score\n\n## Binding Precedence\n\nWhen consuming the response, agents **must** evaluate fields in this order:\n\n1. `risk_flags.structural_blockers` — if non-empty, **abort** new entries\n2. `exposure_policy.blocked_actions` — actions the agent must not take\n3. `exposure_policy.reduce_recommended` — reduce exposure if `true`\n4. `exposure_policy.max_size_fraction` — maximum position size (0.0–1.0)\n5. `exposure_policy.max_leverage` — maximum leverage allowed\n\n## Data Sources\n\nRiskState ingests 30+ real-time signals from:\n\n- **Price & Derivatives** — Binance, OKX, Bybit (funding, OI, basis, L/S ratio)\n- **On-chain** — MVRV, NUPL, exchange netflow, supply metrics (CoinGlass)\n- **Macro** — DXY, US yields, S&P 500, Gold, Fed balance sheet (FRED, Yahoo Finance)\n- **DeFi** — Spark Protocol, Aave V3 health factor and liquidation thresholds\n- **Sentiment** — Fear & Greed, ETF flows, institutional treasuries\n- **ETH-specific** — Staking ratio, burn rate, DEX volume, fees, stablecoin TVL\n\n## Pricing\n\n**Free during beta.** Rate limit: 60 requests/minute.\n\n| Tier | Calls/month | Price |\n|------|------------|-------|\n| Free | 100 | $0 |\n| Builder | 5,000 | $49/mo |\n| Growth | 25,000 | $149/mo |\n| Scale | 100,000 | $399/mo |\n\nPaid tiers coming after beta. [Sign up now](https://riskstate.ai) to lock in early access.\n\n## Documentation\n\n- [**API Reference**](docs/api-v1.md) — Full endpoint documentation, field types, error codes\n- [**SKILL.md**](SKILL.md) — Agent discovery file with decision rules and failure modes\n- [**Changelog**](CHANGELOG.md) — Version history and release notes\n- [**Website**](https://riskstate.ai) — Landing page with interactive examples\n\n## Links\n\n- Website: [riskstate.ai](https://riskstate.ai)\n- X/Twitter: [@riskstate_ai](https://x.com/riskstate_ai)\n- API: `POST https://api.riskstate.ai/v1/risk-state`\n\n---\n\n<p align=\"center\">\n  <sub>Built by <a href=\"https://riskstate.ai\">RiskState</a> · © 2026 Digital Venture Asset LLC</sub>\n</p>\n\nFile v1.4.0:_meta.json\n\n{\n  \"ownerId\": \"kn7djkxqyactdmda78e52x792h83c54v\",\n  \"slug\": \"riskstate\",\n  \"version\": \"1.4.0\",\n  \"publishedAt\": 1780923560290\n}\n\nFile v1.4.0:CHANGELOG.md\n\n# Changelog\n\nAll notable changes to the RiskState API will be documented in this file.\n\n## [1.4.0] - 2026-04-22\n\n### Added\n- **Policy combiner refinements (PR3)** — Five additive refinements to `policy_permissions`, all surfaced in the response and the audit `policy_hash`:\n  - **TREND / RANGE weight split** — `TREND` blends 0.65 structural / 0.35 tactical (continuation-led); `RANGE` 0.55 / 0.45 (tactical has more voice). PANIC, EUPHORIA, and SQUEEZE weights unchanged.\n  - **DQ-gated structural veto** — structural veto is skipped when `structural_score.data_quality < 60`, emitting `STRUCTURAL_VETO_SKIPPED_LOW_DQ`. Prevents low-confidence structural reads from overriding clean tactical signals.\n  - **PANIC SHORT override** — PANIC regime exempts SHORT positions from the strong-structural veto (`STRUCTURAL_VETO_SKIPPED_PANIC`), so dead-cat-bounce / fake-breakout setups are not blocked.\n  - **Bucket codes in `reason_codes`** — typed tokens (e.g. `TACTICAL_STRONG_BULL_72`, `STRUCTURAL_WEAK_22`) replace raw scores for downstream classification.\n  - **`shadow_max_size_fraction`** — read-only preview of a candidate combiner-driven sizing rule. Does not bind today; surfaced for offline comparison.\n\n### Changed\n- Policy hash inputs widened to cover the new bucket codes and shadow size — cached hashes from v1.3.0 will not match (one-time invalidation).\n\n## [1.3.0] - 2026-04-21\n\n### Added\n- **Decoupled Structural + Tactical scores + policy combiner (PR2)** — Splits the single composite into two layers that each drive the appropriate decision:\n  - `structural_score` — slow horizon (weeks-months): cycle, supply, demand, macro. `{overall, label, subfamilies, data_quality, source}`.\n  - `tactical_score` — fast horizon (24-72h): positioning pressure, momentum, volume/CVD, derivatives extremity, L/S velocity, whale pressure. `{overall, label, components, signals}`.\n  - `policy_permissions` — context-aware combiner producing `risk_permission_score`, regime-dependent weights, `direction_bias`, `direction_layer` (audit), and `reason_codes`.\n\n### Changed\n- **`exposure_policy.direction_bias` now comes from the combiner** (was composite-tilt). Breaking semantics.\n- `exposure_policy.direction_layer` added — audit field showing which layer drove direction.\n- Existing `composite` retained for backwards compatibility; `max_size_fraction` still driven by the legacy 4-cap engine.\n\n## [1.2.1] - 2026-04-21\n\n### Added\n- **Positioning Pressure Score (PR1)** — continuous 0-100 tactical signal derived from the squeeze scorer (50 = neutral, >50 short-squeeze setup). Wired into BTC and ETH composite as a 9% subscore. Response gains `positioning.positioning_pressure_score` and `positioning.positioning_pressure_net`.\n\n### Changed\n- **ETH issuance recalibration** — asymmetric bands + 7d/30d blend. Mild post-Merge inflation (+0.82%/yr) now scores ~53 (was ~30); hard-downgrade threshold raised to >+2.0%/yr.\n\n## [1.2.0] - 2026-03-19\n\n### Added\n- **Usage tracking** — Monthly and total API call counts per key, visible in admin panel\n- **Bybit V5 + OKX V5 fallback chain** — Funding rate and OI now have 4-level fallback: Binance → OKX → Bybit → CoinGlass → default. 98%+ uptime for positioning data\n- **DXY in API** — Frankfurter EUR/USD proxy added to API (was missing, affected regime classification)\n- **Aave V3 support** — DeFi position monitoring now supports both Spark Protocol and Aave V3 with per-collateral liquidation thresholds\n\n### Fixed\n- **BTC cycle phase alignment** — API now replicates exact dashboard 9-branch priority order (was simplified 6-branch, causing POST-PEAK vs CORRECTION divergence)\n- **Regime classification fix** — Missing DXY caused false BEAR regime in API (DXY defaulted to 100 → extra bearSignal)\n- **ETH structural score** — Now fetches real data (was hardcoded null → default 50). Lido staking, burn rate, DEX volume, fees, stablecoin TVL all live\n- **Macro regime alignment** — API now calls macro.js as single source of truth (was divergent inline computation)\n\n## [1.1.1] - 2026-03-16\n\n### Added\n- **English standardization** — All API responses in English (was mixed Spanish/English)\n- **ETH Structural Score v2.2** — Widened issuance bands, lending heat directional scoring, hard/soft downgrade reclassification\n- **Weighted warnings in rules cap** — Structural warnings (slow-moving) penalize 0.5x vs tactical 1.0x\n\n### Fixed\n- **False BLOCK prevention** — Mild ETH inflation (+0.3%/yr) no longer triggers defensive policy\n- **CoinGlass fallback fixes** — OI, L/S ratio, MVRV fallback chains corrected (wrong field names, unused data)\n\n## [1.1.0] - 2026-03-13\n\n### Added\n- **Deterministic API contract** — `allowed_actions` and `blocked_actions` use uppercase enum tokens (DCA, WAIT, LEVERAGE_GT_2X) instead of free-text\n- **`reason_codes`** — Machine-parseable tokens in `binding_constraint` (e.g., MACRO_RISK_OFF, COUPLING_NORMAL)\n- **`ttl_seconds`** — Cache TTL in response (60s) for agent scheduling\n- **`binding_constraint.source` uppercased** — RULES, DEFI, MACRO, CYCLE (consistent enum style)\n\n### Changed\n- **SKILL.md rewritten** — Binding precedence section, decision rules table, failure modes table, updated example response\n\n## [1.0.0] - 2026-03-12\n\n### Added\n- **Initial release** — `POST /v1/risk-state` endpoint\n- **5-level policy engine** — BLOCK (1-2) → CAUTIOUS (3) → GREEN (4-5)\n- **Multi-asset support** — BTC and ETH with asset-specific scoring\n- **4-cap system** — Rules, DeFi, Macro, Cycle caps × quality × volatility adjustment\n- **30+ real-time signals** — Macro, on-chain, derivatives, DeFi health, sentiment\n- **DeFi-aware** — Optional wallet parameter for Spark/Aave V3 health factor integration\n- **SHA-256 policy hash** — Deterministic audit trail for non-repudiation\n- **Hierarchical risk flags** — `structural_blockers` (hard stop) vs `context_risks` (reduce conviction)\n- **60s Blob cache** — Skip cache when wallet parameter provided\n- **Bearer auth** — Fail-closed authentication\n- **SKILL.md** — Agent discovery file for skills.sh and agentskills.io ecosystems\n- **Full API documentation** — docs/api-v1.md with field types, error codes, interpretation guide\n\nFile v1.4.0:docs/api-v1.md\n\n# RiskState API v1 Documentation\n\nPre-trade risk permissions for BTC/USD and ETH/USD. Spot, perpetual futures (perps), and DeFi borrowing aware.\n\n> **USD-denominated:** All scoring is based on BTC/USD and ETH/USD price action, derivatives, and macro conditions. If you trade non-USD pairs (e.g., BTC/EUR, ETH/BTC), additional cross-rate risk is not covered by this API.\n\n## Endpoint\n\n```\nPOST /v1/risk-state\n```\n\n## Authentication\n\nAll requests require a Bearer token in the `Authorization` header.\n\n```\nAuthorization: Bearer <your_api_key>\n```\n\n### Key types\n\n| Type | Format | Rate limit | Access |\n|------|--------|------------|--------|\n| **Owner** | `RISKSTATE_API_KEY` env var | Unlimited | All endpoints |\n| **External** | `rs_live_` + 64 hex chars | 60 req/min | `/v1/risk-state` + read-only endpoints |\n\n### Getting an API key\n\nRequest API access at [https://riskstate.ai](https://riskstate.ai) — only an email is required. You'll receive an `rs_live_` key via email within minutes.\n\nKeys are managed through the `/api/api-keys` admin endpoint (owner-only).\n\nThe endpoint **fails closed**: if the server secret is not configured, all requests are denied (401). Rate-limited requests return 429 with `retry_after_seconds: 60`.\n\n## Request\n\n### Headers\n\n| Header | Required | Value |\n|--------|----------|-------|\n| `Authorization` | Yes | `Bearer <token>` |\n| `Content-Type` | Yes | `application/json` |\n\n### Body (JSON)\n\n| Field | Type | Default | Description |\n|-------|------|---------|-------------|\n| `asset` | string | `\"BTC\"` | Asset to evaluate. `\"BTC\"` or `\"ETH\"`. |\n| `wallet` | string | `null` | Ethereum wallet address (0x...) for DeFi position data. Optional. |\n| `protocol` | string | `\"spark\"` | DeFi lending protocol. `\"spark\"` or `\"aave\"`. Only used when `wallet` is provided. |\n| `include_details` | boolean | `false` | Include expanded scoring details in response. |\n| `reference_time` | number | `now` | Unix seconds. Pins `daysSinceHalving` and the policy hash to a single timestamp, enabling bit-exact reproducibility. Must be in `[halving, now+1d]`. |\n| `allow_degraded` | boolean | `false` | If `false` (default), the endpoint returns **503 Core data unavailable** when any of `price`, `rsi`, `funding` are missing upstream. Set to `true` to receive a degraded policy (with `data_integrity` capped). |\n\n### Example requests\n\n**Minimal (BTC):**\n\n```bash\ncurl -X POST https://api.riskstate.ai/v1/risk-state \\\n  -H \"Authorization: Bearer $RISKSTATE_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"asset\": \"BTC\"}'\n```\n\n**Detailed (with scoring breakdown):**\n\n```bash\ncurl -X POST https://api.riskstate.ai/v1/risk-state \\\n  -H \"Authorization: Bearer $RISKSTATE_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"asset\": \"BTC\", \"include_details\": true}'\n```\n\n**DeFi monitoring (with wallet + Aave):**\n\n```bash\ncurl -X POST https://api.riskstate.ai/v1/risk-state \\\n  -H \"Authorization: Bearer $RISKSTATE_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"asset\": \"ETH\", \"wallet\": \"0xYOUR_WALLET_ADDRESS\", \"protocol\": \"aave\", \"include_details\": true}'\n```\n\n> **Note:** All parameters go inside the `-d` JSON string. The `\\` at the end of each line is a shell line continuation — the entire command is one curl call.\n\n### Validation\n\n- `asset` must be `\"BTC\"` or `\"ETH\"` (case-insensitive) → 400 otherwise\n- `wallet` must match `^0x[a-fA-F0-9]{40}$` if provided → 400 otherwise\n- `protocol` must be `\"spark\"` or `\"aave\"` (case-insensitive) → 400 otherwise\n- `reference_time` must be a finite number in `[new Date('2024-04-20').getTime()/1000, now+86400]` if provided → 400 otherwise\n- Invalid JSON body → 400\n- Core data missing (and `allow_degraded` not set) → **503** with `Retry-After: 30` and body `{ error, missing, sources, retry_after_seconds, hint }`\n\n### Determinism contract (v1.2.0)\n\nThe policy hash now includes `api_version`, `scoring_version`, `ts` (from `reference_time`), prices, indicators, **positioning** (funding percentile, OI z-score, squeeze direction), **macro** (regime, coupling, DXY), **volatility** (regime + score), **cycle** (phase, MVRV percentile, boost flag), composite, and policy binding. Given identical inputs and the same `reference_time`, the hash is bit-for-bit identical across requests.\n\n## Response — Minimal (default)\n\nThree blocks: **Permissioning**, **Classification**, **Auditability**.\n\n### Permissioning\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `exposure_policy.max_size_fraction` | float (0–1) | Maximum position size as fraction of portfolio |\n| `exposure_policy.leverage_allowed` | boolean | Whether leverage is permitted |\n| `exposure_policy.max_leverage` | string | Maximum leverage for DeFi borrowing (`\"0x\"`, `\"1x\"`, `\"1.5x\"`, `\"2x\"`). For perps, use `max_size_fraction` as notional cap instead. |\n| `exposure_policy.direction_bias` | string | `\"LONG_PREFERRED\"`, `\"SHORT_PREFERRED\"`, or `\"NEUTRAL\"` |\n| `exposure_policy.reduce_recommended` | boolean | Agent should reduce exposure |\n| `exposure_policy.allowed_actions` | string[] | Actions the agent MAY take (enum tokens, see reference below) |\n| `exposure_policy.blocked_actions` | string[] | Actions the agent MUST NOT take (enum tokens, see reference below) |\n\n### Classification\n\n| Field | Type | Range | Description |\n|-------|------|-------|-------------|\n| `tactical_state` | string | BULLISH, LEAN BULL, NEUTRAL, LEAN BEAR, BEARISH | 24-72h directional tilt from composite |\n| `structural_state` | string | Cycle phase | BTC: BOTTOM/EARLY/MID/LATE/EUPHORIA/CORRECTION/POST-PEAK. ETH: DEPRESSED/VALUE_ZONE/RECOVERY/EXTENDED/DISTRIBUTION |\n| `macro_state` | string | RISK-ON, NEUTRAL, RISK-OFF | Macro regime from FRED data |\n| `market_regime` | string | PANIC, EUPHORIA, SQUEEZE, TREND, RANGE | 5-state unified market regime |\n| `volatility_regime` | string | LOW, NORMAL, HIGH, EXTREME | Volatility classification |\n| `policy_level` | int | 1–5 | Informational classification. The `exposure_policy` fields are the binding constraints. 1=BLOCK Survival, 2=BLOCK Defensive, 3=CAUTIOUS, 4=GREEN Selective, 5=GREEN Expansion |\n| `confidence_score` | float (0–1) | Signal agreement × data quality | Measures subscore agreement and data integrity. NOT a probability of market prediction accuracy. Higher = signals agree more and data is fresher. |\n| `data_quality_score` | int (0–100) | % of data sources live | Percentage of data sources reporting live data. Different scale from `confidence_score` (0–1 factor). <70 = degraded, <50 = unreliable |\n\n### Constraints & Flags\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `binding_constraint.source` | string | Which cap is limiting: `\"RULES\"`, `\"DEFI\"`, `\"MACRO\"`, `\"CYCLE\"` |\n| `binding_constraint.reason` | string | Human-readable explanation (e.g., `\"RISK-OFF × NORMAL\"`) |\n| `binding_constraint.reason_codes` | string[] | Machine-parseable reason tokens (e.g., `[\"MACRO_RISK_OFF\", \"COUPLING_NORMAL\"]`) |\n| `binding_constraint.cap_value` | float | The binding cap's value (0–1) |\n| `risk_flags.structural_blockers` | string[] | Hard blockers — agent MUST pause new entries |\n| `risk_flags.context_risks` | string[] | Soft risks — agent should reduce conviction |\n| `defi` | object\\|null | DeFi position data if wallet provided, else `null`. See fields below. |\n| `defi.health_factor` | float | Current health factor (>1 = safe, <1.1 = danger) |\n| `defi.ltv` | float | Current loan-to-value ratio % (debt / collateral × 100). E.g., 35.4 means 35.4% utilized. |\n| `defi.max_ltv` | float | Protocol's maximum LTV threshold % (e.g., 82.99). Borrowing above this is blocked. |\n| `defi.liquidation_threshold` | float | Liquidation threshold % (e.g., 82.5). Position liquidatable above this. |\n| `defi.protocol` | string | `\"spark\"` or `\"aave\"` |\n\n### Auditability\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `policy_hash` | string | SHA-256 hash of policy inputs for non-repudiation |\n| `scoring_version` | string | `\"score_v2\"` — scoring algorithm version |\n| `version` | string | `\"1.2.2\"` — API version |\n| `timestamp` | string | ISO 8601 timestamp |\n| `asset` | string | Asset evaluated |\n| `cached` | boolean | Whether response was served from cache |\n| `ttl_seconds` | int | Cache TTL in seconds (60). Agent should re-request after this interval for fresh data. |\n| `key_type` | string | `\"owner\"` or `\"external\"` — identifies which auth tier was used |\n| `stale_fields` | string[] | Core signals that are missing or stale |\n\n## Response — Detailed (`include_details=true`)\n\nAll minimal fields plus:\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `caps.rules` | float | Rules cap (0–1) |\n| `caps.defi` | float | DeFi health cap (0–1) |\n| `caps.macro` | float | Macro regime cap (0–1) |\n| `caps.cycle` | float | Cycle phase cap (0–1) |\n| `caps.quality` | float | Quality factor (conflict × integrity) |\n| `caps.data_integrity` | float | Data freshness score |\n| `positioning.squeeze_direction` | string | UPSIDE, DOWNSIDE, TWO-SIDED, NONE |\n| `positioning.squeeze_confidence` | int | 0–100 |\n| `positioning.ls_crowding` | string | LONG_CROWDED, SHORT_CROWDED, BALANCED, etc. |\n| `positioning.ls_crowding_score` | int | 0–100 |\n| `positioning.funding_percentile` | int | Funding rate percentile vs 30d (0–100) |\n| `positioning.oi_zscore` | float | OI z-score vs 30d |\n| `positioning.basis_pct` | float | Perp-spot basis % |\n| `volatility.regime` | string | LOW, NORMAL, HIGH, EXTREME |\n| `volatility.score` | int | 0–100 |\n| `whale_pressure.score` | int | 0–100 (9 proxy signals) |\n| `whale_pressure.direction` | string | STRONG_BUY, BUY, NEUTRAL, SELL, STRONG_SELL |\n| `trend_strength.score` | int | 0–100 |\n| `trend_strength.direction` | string | STRONG_TREND, TREND, NEUTRAL, COUNTER_TREND, STRONG_COUNTER |\n| `trend_strength.components` | object | `{ ma_cluster, expansion, flow_alignment }` (each 0–100) |\n| `composite.overall` | int | 0–100 weighted composite score |\n| `composite.subscores` | array | `[{ name, score, weight }]` — 7-8 subscores |\n| `extreme_scores.panic` | int | 0–100 panic percentile |\n| `extreme_scores.euphoria` | int | 0–100 euphoria percentile |\n| `eth_structural` | object\\|null | ETH structural score (ETH only): `{ overall, label, dataQuality, subfamilies: { network, supply, relative, demand } }` |\n| `eth_downgrade` | object\\|null | ETH structural downgrade (ETH only): `{ active, count, hardCount, softCount, severity, signals, capReduction }` |\n| `macro_detail` | object | Full macro data for diagnostics: `{ regime, coupling, realRate10y, liquidityRegime, yield10y, yield10yChg, spxChangePct, fedBsDelta3m, spread10y2y, riskOffSignals, riskOnSignals, dxy }` |\n| `data_sources` | object | Per-field source status (LIVE/MOCK/CG_FALLBACK/CC_FALLBACK/DEFAULT) |\n| `core_missing` | string[] | Missing core signals |\n\n## Error Responses\n\n| Status | Body | Cause |\n|--------|------|-------|\n| 400 | `{ \"error\": \"Invalid JSON body\" }` | Malformed JSON |\n| 400 | `{ \"error\": \"Invalid asset. Must be BTC or ETH.\" }` | Unknown asset |\n| 400 | `{ \"error\": \"Invalid wallet address format.\" }` | Bad wallet format |\n| 401 | `{ \"error\": \"Unauthorized\" }` | Missing or invalid Bearer token |\n| 429 | `{ \"error\": \"Rate limit exceeded\", \"retry_after_seconds\": 60 }` | External key exceeded 60 req/min |\n| 500 | `{ \"error\": \"Internal server error\" }` | Server-side failure |\n\n## Data Sources & Fallback Chain\n\nThe endpoint fetches from 15+ external APIs in parallel waves. Binance returns HTTP 451 from Netlify servers, so all Binance data has fallbacks:\n\n| Data | Primary | Fallback | Last Resort |\n|------|---------|----------|-------------|\n| RSI (4h) | Binance klines | CryptoCompare `histohour` | Default 50 |\n| Funding rate | Binance `fundingRate` | OKX V5 → Bybit V5 → CoinGlass | Default 0 |\n| Daily klines (200d) | Binance klines | CryptoCompare `histoday` | `null` (trend strength unavailable) |\n| MVRV | blockchain.info | CoinGlass `/indicator/market/mvrv` | Default 1.8 |\n| Real Rate | FRED T10YIE (breakeven) | — | `null` |\n| Liquidity Regime | FRED WALCL (13-week delta) | — | `NEUTRAL` |\n| Gold | Yahoo Finance | — | `null` |\n| Macro regime + coupling | `/api/macro` (single source of truth) | — | `NEUTRAL` / `NORMAL` |\n| ETH Structural | Lido + Ultrasound + DefiLlama (6 APIs) | — | Score defaults to 50 |\n| SPX | Yahoo Finance (^GSPC) via macro.js | FRED SP500 (T-1 lag) | `null` |\n| Staking APR | Lido `/apr/last` | Lido `/apr/sma` | Default 2.8% |\n\nThe `data_sources` field (in detailed response) shows per-field source: `LIVE`, `CC_FALLBACK` (CryptoCompare), `CG_FALLBACK` (CoinGlass), `ESTIMATED` (price-based), `DEFAULT_ZERO`, `DEFAULT`, or `MOCK`.\n\n### Known Data Limitations (v1.2.0)\n\nBinance returns HTTP 451 from Netlify servers. Current CoinGlass tier lacks certain endpoints. These cause permanent fallback states for some fields:\n\n| Field | Server Status | Impact | Dashboard Comparison |\n|-------|--------------|--------|---------------------|\n| Funding | OKX or BYBIT fallback | Live data via cascading fallback chain. Neutral default (0) only if all fallbacks fail | Dashboard gets real data from browser-side Binance |\n| Open Interest | OKX or BYBIT fallback | Live data via cascading fallback chain. Affects squeeze detection and OI z-score | Dashboard gets real data from browser-side Binance |\n| MVRV | ESTIMATED (~price/$36K) | Accurate to ±5%. Affects cycle phase near thresholds | Dashboard gets real MVRV from blockchain.info |\n| DXY | LIVE (Frankfurter EUR/USD proxy) | Same formula as dashboard. Affects detectRegime + macro scoring | Dashboard uses same Frankfurter proxy via market-data.js |\n\n### API vs Dashboard Classification Alignment (v1.2.0, Mar 19 2026)\n\nAll classification fields now match between API and dashboard for the same market conditions:\n\n| Field | Status | Notes |\n|-------|--------|-------|\n| cycle_phase | Aligned | Full 9-branch BTC classification (was simplified 6-branch) |\n| market_regime | Aligned | DXY fix resolved false BEAR → TREND (was missing Frankfurter call) |\n| macro_state | Aligned | Same macro.js as single source of truth |\n| composite | Aligned | Same scoring-core.js functions |\n| policy_level | Aligned | Same cap computation; DeFi cap differs when API called without wallet |\n\n**Expected deltas** (not bugs — different data availability):\n- **DeFi cap**: API=100% (no wallet) vs dashboard=84% (wallet connected) — pass `wallet` param to API for parity\n- **Whale score**: ~9pt gap — browser computes 9 signals with real-time data; server has fewer\n- **Trend strength**: ~3pt gap — minor data timing/source differences\n- **Quality factor**: ~8pt gap — DeFi cap + subscore spread differences affect conflict_penalty\n\nAll other fields (RSI, daily klines, L/S ratio, CVD, ETF, exchange flow, macro, correlations, ETH structural) have working fallback chains.\n\n## Caching Behavior\n\n- **60-second TTL** via Netlify Blobs\n- First call: 5–12 seconds (fetches from 15+ external APIs in 5 parallel waves)\n- Subsequent calls within 60s: <1 second\n- `cached: true` in response indicates cache hit\n- **Wallet parameter bypasses cache** (DeFi data is personalized)\n\n## Action Enums Reference\n\n### `allowed_actions` values\n\n| Token | Meaning | Policy Levels |\n|-------|---------|---------------|\n| `REDUCE` | Reduce existing exposure | 1 |\n| `ADD_COLLATERAL` | Add collateral to DeFi position | 1 |\n| `HEDGE` | Hedge existing positions | 1, 2 |\n| `WAIT` | Wait for better conditions | 2, 3 |\n| `REDUCE_LEVERAGE` | Reduce leverage on existing positions | 2 |\n| `SCALP_SMALL` | Small scalp trades only | 2 |\n| `RR_GT_2` | Trades with R:R > 2:1 only | 2, 3 |\n| `DCA` | Dollar-cost averaging | 3, 4 |\n| `LIGHT_ACCUMULATION` | Light spot accumulation | 3 |\n| `LONG_SHORT_CONFIRMED` | Long or short with confirmation signals | 4 |\n| `LEVERAGE_MODERATE` | Moderate leverage (up to 1.5x) | 4 |\n| `TREND_FOLLOW` | Trend following strategies | 5 |\n| `ADD_ON_PULLBACK` | Add to winners on pullbacks | 5 |\n| `LEVERAGE_2X` | Leverage up to 2x | 5 |\n| `AGGRESSIVE_ACCUMULATION` | Aggressive spot accumulation | 5 |\n\n### `blocked_actions` values\n\n| Token | Meaning | Policy Levels |\n|-------|---------|---------------|\n| `NEW_TRADES` | All new position entries blocked | 1 |\n| `LEVERAGE` | Any leverage blocked | 1, 3 |\n| `INCREASE_POSITION` | Increasing existing positions blocked | 1 |\n| `LEVERAGE_GT_1X` | Leverage above 1x blocked | 2 |\n| `AGGRESSIVE_LONG` | Aggressive long entries blocked | 2, 3 |\n| `FOMO_ENTRY` | FOMO-driven entries blocked | 2 |\n| `ALL_IN` | Full portfolio allocation blocked | 3, 4 |\n| `LEVERAGE_GT_2X` | Leverage above 2x blocked | 4 |\n| `COUNTER_TREND_SHORT` | Shorting against confirmed trend blocked | 5 |\n\n### `binding_constraint.reason_codes` values\n\n| Source | Possible codes | Example |\n|--------|---------------|---------|\n| RULES | `RULES_CRITICAL_{n}`, `RULES_WARNING_{n}` | `[\"RULES_CRITICAL_2\", \"RULES_WARNING_5\"]` |\n| DEFI | `DEFI_HF_LOW` | `[\"DEFI_HF_LOW\"]` |\n| MACRO | `MACRO_{regime}`, `COUPLING_{level}` | `[\"MACRO_RISK_OFF\", \"COUPLING_HIGH_COUPLING\"]` |\n| CYCLE | `CYCLE_{phase}` | `[\"CYCLE_MID\"]`, `[\"CYCLE_EUPHORIA\"]` |\n\n## Risk Flags Reference\n\n### Structural Blockers (agent MUST pause)\n\n| Flag | Meaning |\n|------|---------|\n| `DEFI_LIQUIDATION_RISK` | Health Factor critically low |\n| `SQUEEZE_RISK` | High-confidence directional squeeze |\n| `MACRO_CONTAGION` | SPX/QQQ selloff >1.5% with normal or high coupling |\n| `MACRO_RISK_OFF` | Macro regime risk-off with multiple signals |\n| `ONCHAIN_EUPHORIA` | MVRV + NUPL at historical extremes |\n| `EXTREME_FEAR` | F&G ≤ 10 (panic conditions) |\n| `FUNDING_EXTREME` | Funding + RSI both extreme |\n| `LIQUIDATION_CASCADE` | >$100M liquidations with asymmetry |\n\n### Context Risks (agent should reduce conviction)\n\n| Flag | Meaning |\n|------|---------|\n| `HIGH_FUNDING` | Funding rate elevated |\n| `RSI_OVERBOUGHT` | RSI > 70 |\n| `RSI_OVERSOLD` | RSI < 25 |\n| `DXY_HEADWIND` | DXY > 104 |\n| `YIELD_PRESSURE` | 10Y yield elevated or spiking |\n| `HIGH_OI` | OI z-score > 2.0 (30d) |\n| `BASIS_EXTREME` | Perp-spot basis > 0.15% |\n| `WHALE_ACTIVITY` | Whale score ≥ 50 |\n| `ETH_STRUCTURAL_WEAK` | ETH structural downgrade active |\n| `ETH_SUPPLY_INFLATIONARY` | ETH supply strongly inflationary |\n| `TREND_NOT_CONFIRMED` | Trend strength ≤ 45 with directional tilt |\n| `NO_TREND` | Trend strength ≤ 20 |\n| `HIGH_COUPLING` | High macro correlation |\n| `SIGNAL_CONFLICT` | Subscore dispersion high |\n| `LS_CROWDED` | L/S ratio extreme |\n| `YIELD_SPIKE` | 10Y yield change > 0.08% in session |\n| `CURVE_INVERTED` | 10Y-2Y spread < -0.2% |\n| `REAL_RATE_HEADWIND` | Real rate > 1.5% |\n| `LIQUIDITY_TIGHTENING` | Fed balance sheet shrinking (3m delta < -1%) |\n| `STAKING_HEADWIND` | Real rate > ETH staking APR (ETH only) |\n| `LIQUIDATION_ASYMMETRY` | >75% of liquidations on one side |\n\n## How to Use by Context\n\nThe API returns the same response regardless of how you trade. The **market conditions assessment** (composite score, regime, policy level) is identical. What changes is how you **interpret the risk permissions** for your specific context.\n\n### Spot Trading (BTC/USD or ETH/USD)\n\nYou are buying or selling the asset on a spot exchange (Coinbase, Binance Spot, Kraken, Uniswap, CoW Swap).\n\n**Key fields:**\n- `max_size_fraction` → **% of portfolio to deploy.** If 0.33, allocate up to 33% of your portfolio to this position.\n- `direction_bias` → `LONG_PREFERRED` means \"buy signal.\" `SHORT_PREFERRED` means \"don't buy / consider selling.\" `NEUTRAL` means \"no directional edge.\"\n- `structural_blockers` → If non-empty, do not buy.\n- `allowed_actions` / `blocked_actions` → Filter for relevant actions (DCA, WAIT, LIGHT_ACCUMULATION).\n\n**Ignore for spot:** `max_leverage`, `leverage_allowed`, and leverage-related blocked actions (`LEVERAGE_GT_1X`, `LEVERAGE_GT_2X`). These apply to leveraged markets and DeFi borrowing.\n\n**Pre-trade workflow:**\n1. Call the API with `{\"asset\": \"BTC\"}`\n2. Check `structural_blockers` — if non-empty, do not enter\n3. Read `max_size_fraction` — this is your max allocation\n4. Check `direction_bias` — respect the directional guidance\n5. Proceed to your exchange and place the spot order\n\n### Perpetual Futures (Perps)\n\nYou are trading BTC/USDT or ETH/USDT perpetuals on Binance Futures, Hyperliquid, dYdX, Bybit, or similar venues.\n\n**Key fields:**\n- `max_size_fraction` → **Max notional exposure as % of portfolio.** If 0.33 and your portfolio is $100K, your max notional is $33K. At 10x leverage, that means max $3.3K margin.\n- `direction_bias` → Directly actionable: `LONG_PREFERRED` favors longs, `SHORT_PREFERRED` favors shorts.\n- `structural_blockers` → If `SQUEEZE_RISK` is present, **do not open leveraged positions** — liquidation risk is elevated.\n\n**Especially relevant for perps (in detailed response):**\n- `positioning.funding_percentile` → How extreme the current funding rate is vs. 30 days. P>85 = paying heavy carry on longs. P<15 = shorts are crowded.\n- `positioning.basis_pct` → Perp-spot premium. Positive = longs dominant, negative = discount.\n- `positioning.squeeze_direction` → UPSIDE (short squeeze probable) or DOWNSIDE (long squeeze probable).\n- `positioning.oi_zscore` → OI z-score vs. 30 days. >2.0 = excessive leverage in the market.\n\n**Margin guide (from `max_size_fraction`):**\n\n| Your leverage | Max margin (% of portfolio) | Example ($100K portfolio, max_size=0.33) |\n|---------------|----------------------------|------------------------------------------|\n| 3x | max_size / 3 = 11.0% | $11,000 margin |\n| 5x | max_size / 5 = 6.6% | $6,600 margin |\n| 10x | max_size / 10 = 3.3% | $3,300 margin |\n| 25x | max_size / 25 = 1.3% | $1,300 margin |\n\n> **Note:** RiskState does not impose a leverage cap for perpetual futures. The `max_leverage` field reflects DeFi borrowing constraints (see below). For perps, the binding constraint is `max_size_fraction` as max notional exposure — you choose your own leverage within that cap.\n\n**Pre-trade workflow (e.g., Hyperliquid):**\n1. Call the API with `{\"asset\": \"BTC\", \"include_details\": true}`\n2. Check `structural_blockers` — if `SQUEEZE_RISK` present, do not open leveraged positions\n3. Read `max_size_fraction` — this is your max notional as % of portfolio\n4. Divide by your intended leverage to get max margin\n5. Check `positioning.funding_percentile` — if P>85, longs are paying heavy carry\n6. Check `positioning.squeeze_direction` — if DOWNSIDE, longs are at risk\n7. Respect `direction_bias` for trade direction\n8. Place your order on the venue\n\n### DeFi Borrowing (Aave, Spark, Morpho)\n\nYou borrow stablecoins against BTC or ETH collateral on-chain.\n\n**Key fields:**\n- `max_size_fraction` → **% of collateral to deploy.** Accounts for your current health factor.\n- `max_leverage` → Borrowing ratio cap: `\"0x\"` (don't borrow), `\"1x\"`, `\"1.5x\"`, `\"2x\"`.\n- `defi.health_factor` → Current health factor (>1 safe, <1.1 danger).\n- `defi.ltv` → Current loan-to-value ratio.\n- `binding_constraint.source` → If `\"DEFI\"`, your on-chain position is the limiting factor.\n\n**Pre-trade workflow:**\n1. Call the API with `{\"asset\": \"ETH\", \"wallet\": \"0xYOUR_WALLET\", \"protocol\": \"aave\"}`\n2. Check `defi.health_factor` — if <1.5, prioritize adding collateral\n3. If `binding_constraint.source === \"DEFI\"`, do not increase debt\n4. Respect `max_leverage` for borrowing ratio\n5. If `structural_blockers` contains `DEFI_LIQUIDATION_RISK`, reduce position immediately\n\n### AI Trading Agent Integration\n\nYou are building an autonomous trading agent (Hermes, ElizaOS, OpenClaw, AgentKit, custom) that calls the API programmatically.\n\n**See [SKILL.md](SKILL.md) for the complete agent integration guide**, including:\n- Binding precedence (evaluation order for response fields)\n- Decision rules by policy level\n- Failure modes and conservative fallback behavior\n- Example requests\n\n**Key principle:** Call the API **between decision and execution**. Your agent decides what to trade (intelligence layer). RiskState tells it **how much** it can risk (governance layer). Then the agent executes within those bounds.\n\n## Interpretation Guide\n\n### Position Sizing\n\n**Spot:**\n```\nposition_size = portfolio_value × max_size_fraction × conviction\n```\n\n**Perps:**\n```\nmax_notional = portfolio_value × max_size_fraction × conviction\nmargin = max_notional / leverage\n```\n\nWhere `conviction` is your own confidence factor (0–1), whether human or algorithmic.\n\n### Re-consultation Frequency\n\n| Use case | Recommended interval |\n|----------|---------------------|\n| Active trading (scalps, day trades) | Every 5 minutes |\n| Swing trading (24h–72h holds) | Every 15 minutes |\n| Holding / DCA | Every 4 hours |\n| After significant move (>3% 1h) | Immediate |\n\n### When to Force-Check\n\n- Before any new position entry\n- When `policy_level` was previously ≤ 2 (check if conditions improved)\n- After external events (ETF announcements, Fed meetings, major hacks)\n\n## Examples\n\n### Pre-trade check (agent workflow)\n\n```\n1. curl -X POST https://api.riskstate.ai/v1/risk-state \\\n     -H \"Authorization: Bearer $RISKSTATE_API_KEY\" \\\n     -H \"Content-Type: application/json\" \\\n     -d '{\"asset\": \"BTC\"}'\n2. If structural_blockers non-empty → ABORT new entries\n3. If blocked_actions contains NEW_TRADES → ABORT new entries\n4. If reduce_recommended → reduce exposure (not necessarily close all)\n5. Size position: max_size_fraction × agent_conviction\n6. Respect max_leverage limit\n7. Respect direction_bias for trade direction\n8. Check allowed_actions before executing\n9. If stale_fields non-empty or data_quality_score < 70 → halve size or abstain\n10. policy_level is summary only — do not use for enforcement\n```\n\n### DeFi monitoring\n\n```bash\ncurl -X POST https://api.riskstate.ai/v1/risk-state \\\n  -H \"Authorization: Bearer $RISKSTATE_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"asset\": \"ETH\", \"wallet\": \"0xYOUR_WALLET_ADDRESS_HERE\", \"include_details\": true}'\n```\n\nThe `defi` field will contain `health_factor` and `ltv` from Spark Protocol or Aave V3.\nIf `binding_constraint.source === \"DEFI\"`, the DeFi position is the limiting factor.\n\nFile v1.4.0:skill-card.md\n\n## Description: <br>\nPre-trade risk API for crypto trading agents that returns exposure limits, allowed actions, and policy constraints for BTC/USD and ETH/USD from 30+ real-time signals across spot, perpetual futures, and DeFi borrowing. <br>\n\nThis skill is ready for commercial/non-commercial use. <br>\n\n## Publisher: <br>\n[likidodefi](https://clawhub.ai/user/likidodefi) <br>\n\n### License/Terms of Use: <br>\nMIT-0 <br>\n\n\n## Use Case: <br>\nExternal developers, trading-system operators, and capital desks use this skill to query RiskState before opening, sizing, or maintaining BTC/USD and ETH/USD exposure. Agents use the returned policy fields to enforce position limits, leverage caps, blocked actions, and DeFi health constraints before execution. <br>\n\n### Deployment Geography for Use: <br>\nGlobal <br>\n\n## Known Risks and Mitigations: <br>\nRisk: The skill sends RiskState API keys, requested assets, and optional wallet addresses to RiskState's external service. <br>\nMitigation: Use a scoped API key stored in environment variables or a secret manager, and provide a wallet address only when DeFi analysis is needed. <br>\nRisk: Risk output depends on live external market and DeFi data, which may be stale, degraded, unavailable, or rate-limited. <br>\nMitigation: Follow the documented failure-mode behavior: treat stale or low-quality data as degraded, abstain when data quality is unreliable, and fail closed on timeouts or server errors. <br>\nRisk: The optional MCP server is a separate integration path from the skill files reviewed here. <br>\nMitigation: Review and scan the optional MCP server independently before installing it. <br>\n\n\n## Reference(s): <br>\n- [ClawHub skill page](https://clawhub.ai/likidodefi/riskstate) <br>\n- [RiskState homepage](https://riskstate.ai) <br>\n- [RiskState API documentation](https://riskstate.ai/docs/api) <br>\n- [RiskState API v1 reference](docs/api-v1.md) <br>\n\n\n## Skill Output: <br>\n**Output Type(s):** [guidance, shell commands, code, configuration, JSON] <br>\n**Output Format:** [Markdown guidance with curl examples, integration snippets, and JSON API responses] <br>\n**Output Parameters:** [1D] <br>\n**Other Properties Related to Output:** [Requires a RiskState bearer token; optional wallet address enables DeFi position analysis.] <br>\n\n## Skill Version(s): <br>\n1.4.0 (source: server release metadata and SKILL.md frontmatter) <br>\n\n## Ethical Considerations: <br>\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment. <br>\n\nArchive v1.2.2: 6 files, 17855 bytes\n\nFiles: CHANGELOG.md (3398b), docs/api-v1.md (19270b), README.md (7088b), skill-card.md (2814b), SKILL.md (6958b), _meta.json (128b)\n\nFile v1.2.2:SKILL.md\n\n---\nname: riskstate\nversion: 1.2.2\ndescription: Deterministic risk governance API for autonomous crypto trading agents. Returns position limits, allowed actions, and policy constraints from 30+ real-time signals.\ncategory: risk-management\nauth: bearer-token\nenv: RISKSTATE_API_KEY\nendpoint: POST https://riskstate.netlify.app/v1/risk-state\nassets: [BTC, ETH]\nrefresh: 60s cache, recommend 5min polling\nhomepage: https://riskstate.ai\ndocs: https://github.com/likidodefi/riskstate-docs\ntags: [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]\npricing: free-beta\nauthor: RiskState\nlicense: proprietary\n---\n\n# RiskState — Risk Governor for Crypto Trading Agents\n\n## What it does\n\nReturns **operational risk permissions** for crypto trading.\nA deterministic policy engine computes how much exposure is allowed based on 30+ real-time signals across macro, on-chain, derivatives, and DeFi health.\n\nThe response tells you:\n- **max_size_fraction**: Maximum position size as fraction of portfolio (0.0–1.0)\n- **allowed_actions / blocked_actions**: What the agent MAY and MUST NOT do (enum tokens)\n- **risk_flags**: Structural blockers (hard stop) vs contextual risks (reduce conviction)\n- **binding_constraint**: Which cap is limiting and why\n- **policy_level**: 1–5 summary label (informational — use `exposure_policy` for enforcement)\n\n## What it does NOT do\n\n- No trade signals, no entry/exit prices, no predictions\n- No portfolio allocation advice\n- No order execution or routing\n- No historical data or backtesting\n\nThis is a **risk governor**, not a trading oracle.\n\n## When to call\n\n- **Before opening or sizing positions** — check permissions first\n- **Periodically during holds** — every 5 min for active trading, every 4h for holding\n- **After significant market moves** — cache invalidates after 60s (`ttl_seconds` in response)\n\n## Authentication\n\nRequest 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:\n\n```\nAuthorization: Bearer $RISKSTATE_API_KEY\n```\n\n## Binding precedence\n\nWhen consuming the response, agents MUST evaluate fields in this order:\n\n1. `risk_flags.structural_blockers` — if non-empty, ABORT new entries\n2. `exposure_policy.blocked_actions` — actions the agent MUST NOT take\n3. `exposure_policy.reduce_recommended` — reduce exposure if true\n4. `exposure_policy.max_size_fraction` — maximum position size\n5. `exposure_policy.max_leverage` — maximum leverage allowed\n6. `exposure_policy.direction_bias` — preferred trade direction\n7. `policy_level` — informational summary only, do not use for enforcement\n\n## Decision rules by policy level\n\n| `policy_level` | Summary | Key constraints |\n|----------------|---------|-----------------|\n| 1 (BLOCK Survival) | No new positions | `blocked_actions: [NEW_TRADES, ...]`, `max_leverage: \"0x\"` |\n| 2 (BLOCK Defensive) | Wait or hedge only | `blocked_actions: [AGGRESSIVE_LONG, ...]`, `max_leverage: \"1x\"` |\n| 3 (CAUTIOUS) | DCA with R:R >2:1 | `blocked_actions: [LEVERAGE, ALL_IN, ...]`, `max_leverage: \"1x\"` |\n| 4 (GREEN Selective) | Trade with confirmation | `max_leverage: \"1.5x\"` |\n| 5 (GREEN Expansion) | Full operations | `max_leverage: \"2x\"` |\n\n`policy_level` is a convenience label. Always check `exposure_policy` fields for actual constraints.\n\n## Failure modes\n\n| Condition | Agent behavior |\n|-----------|----------------|\n| `stale_fields` contains core indicators (price, funding, rsi) | Downgrade conviction. Data integrity compromised. |\n| `data_quality_score` < 70 | Treat as degraded. Reduce position sizes by 50%. |\n| `data_quality_score` < 50 | Treat as unreliable. Do not open new positions. |\n| `confidence_score` < 0.5 | Signals conflict heavily. Prefer WAIT over action. |\n| HTTP 500 or timeout | Assume worst case (BLOCK). Retry after 60s. |\n| `cached: true` + `stale_fields` non-empty | Re-request after cache TTL (60s) for fresh data. |\n\n## Security\n\n**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.\n\n**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.\n\n## Example requests\n\n### Minimal (BTC)\n\n```bash\ncurl -X POST https://riskstate.netlify.app/v1/risk-state \\\n  -H \"Authorization: Bearer $RISKSTATE_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"asset\": \"BTC\"}'\n```\n\n### Detailed (with scoring breakdown)\n\n```bash\ncurl -X POST https://riskstate.netlify.app/v1/risk-state \\\n  -H \"Authorization: Bearer $RISKSTATE_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"asset\": \"BTC\", \"include_details\": true}'\n```\n\n### DeFi monitoring (with wallet)\n\n```bash\ncurl -X POST https://riskstate.netlify.app/v1/risk-state \\\n  -H \"Authorization: Bearer $RISKSTATE_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"asset\": \"ETH\", \"wallet\": \"0xYOUR_WALLET_ADDRESS\", \"include_details\": true}'\n```\n\n## Example response (minimal)\n\n```json\n{\n  \"exposure_policy\": {\n    \"max_size_fraction\": 0.42,\n    \"leverage_allowed\": false,\n    \"max_leverage\": \"1x\",\n    \"direction_bias\": \"LONG_PREFERRED\",\n    \"reduce_recommended\": false,\n    \"allowed_actions\": [\"DCA\", \"WAIT\", \"LIGHT_ACCUMULATION\", \"RR_GT_2\"],\n    \"blocked_actions\": [\"LEVERAGE\", \"AGGRESSIVE_LONG\", \"ALL_IN\"]\n  },\n  \"tactical_state\": \"LEAN BULL\",\n  \"structural_state\": \"MID\",\n  \"macro_state\": \"NEUTRAL\",\n  \"market_regime\": \"TREND\",\n  \"volatility_regime\": \"NORMAL\",\n  \"policy_level\": 3,\n  \"confidence_score\": 0.72,\n  \"data_quality_score\": 85,\n  \"binding_constraint\": {\n    \"source\": \"MACRO\",\n    \"reason\": \"NEUTRAL × NORMAL\",\n    \"reason_codes\": [\"MACRO_NEUTRAL\", \"COUPLING_NORMAL\"],\n    \"cap_value\": 0.70\n  },\n  \"risk_flags\": {\n    \"structural_blockers\": [],\n    \"context_risks\": [\"HIGH_FUNDING\"]\n  },\n  \"defi\": null,\n  \"policy_hash\": \"a1b2c3d4e5f6...\",\n  \"scoring_version\": \"score_v2\",\n  \"version\": \"1.2.2\",\n  \"timestamp\": \"2026-03-13T14:30:00.000Z\",\n  \"asset\": \"BTC\",\n  \"cached\": false,\n  \"ttl_seconds\": 60,\n  \"stale_fields\": []\n}\n```\n\n## Detailed response\n\nPass `\"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`.\n\nSee [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.\n\nFile v1.2.2:README.md\n\n<p align=\"center\">\n  <img src=\"https://riskstate.ai/logo-r-grey.svg\" width=\"48\" alt=\"RiskState\" />\n</p>\n\n<h1 align=\"center\">RiskState</h1>\n\n<p align=\"center\">\n  <strong>Risk governance API for autonomous crypto trading agents</strong>\n</p>\n\n<p align=\"center\">\n  <a href=\"https://riskstate.netlify.app/v1/risk-state\"><img src=\"https://img.shields.io/badge/API-v1.2.0-blue?style=flat-square\" alt=\"API Version\" /></a>\n  <a href=\"https://riskstate.ai\"><img src=\"https://img.shields.io/badge/status-beta-green?style=flat-square\" alt=\"Status\" /></a>\n  <a href=\"#supported-assets\"><img src=\"https://img.shields.io/badge/assets-BTC%20%7C%20ETH-orange?style=flat-square\" alt=\"Assets\" /></a>\n  <a href=\"#pricing\"><img src=\"https://img.shields.io/badge/pricing-free%20beta-brightgreen?style=flat-square\" alt=\"Pricing\" /></a>\n</p>\n\n<p align=\"center\">\n  <a href=\"https://riskstate.ai\">Website</a> · <a href=\"docs/api-v1.md\">API Reference</a> · <a href=\"SKILL.md\">SKILL.md</a> · <a href=\"https://x.com/riskstate_ai\">X/Twitter</a>\n</p>\n\n---\n\n## What is RiskState?\n\nA deterministic policy engine that tells AI trading agents **how much risk is allowed** — not what to trade.\n\nOne API call returns position limits, allowed actions, and policy constraints computed from **30+ real-time signals** across macro, on-chain, derivatives, and DeFi health.\n\n```bash\ncurl -X POST https://riskstate.netlify.app/v1/risk-state \\\n  -H \"Authorization: Bearer $RISKSTATE_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"asset\": \"BTC\"}'\n```\n\n```json\n{\n  \"exposure_policy\": {\n    \"max_size_fraction\": 0.42,\n    \"leverage_allowed\": true,\n    \"allowed_actions\": [\"DCA\", \"LONG_SHORT_CONFIRMED\"],\n    \"blocked_actions\": [\"ALL_IN\", \"LEVERAGE_GT_2X\"]\n  },\n  \"policy_level\": 4,\n  \"risk_flags\": {\n    \"structural_blockers\": [],\n    \"context_risks\": [\"HIGH_COUPLING\"]\n  },\n  \"binding_constraint\": {\n    \"source\": \"MACRO\",\n    \"reason_codes\": [\"MACRO_NEUTRAL\", \"COUPLING_NORMAL\"]\n  }\n}\n```\n\nYour agent reads `max_size_fraction`, checks `structural_blockers`, and acts. No parsing. No interpretation.\n\n## Why?\n\nAutonomous trading agents can execute trades. None of them know when to **stop**.\n\n| Without governance | With RiskState |\n|---|---|\n| Agent sizes position based on signal confidence | Agent caps position at `max_size_fraction` |\n| No awareness of macro regime | `RISK-OFF` → `blocked_actions: [\"AGGRESSIVE_LONG\"]` |\n| DeFi health factor ignored | Wallet health feeds directly into position limit |\n| Leverage unbounded | `max_leverage: \"1x\"` enforced per policy level |\n| No circuit breaker | `structural_blockers` non-empty → halt |\n\n## Quick Start\n\n### 1. Get an API key\n\nSign up at [riskstate.ai](https://riskstate.ai) — email only, free during beta.\n\n### 2. Query the API\n\n```bash\ncurl -X POST https://riskstate.netlify.app/v1/risk-state \\\n  -H \"Authorization: Bearer $RISKSTATE_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"asset\": \"BTC\"}'\n```\n\n### 3. Enforce in your agent\n\n```python\nimport requests\n\npolicy = requests.post(\n    \"https://riskstate.netlify.app/v1/risk-state\",\n    headers={\"Authorization\": f\"Bearer {API_KEY}\"},\n    json={\"asset\": \"BTC\"}\n).json()\n\n# Hard stop: structural blockers\nif policy[\"risk_flags\"][\"structural_blockers\"]:\n    return  # Do not trade\n\n# Size cap\nmax_size = policy[\"exposure_policy\"][\"max_size_fraction\"]\nposition_size = min(desired_size, portfolio_value * max_size)\n\n# Action filter\nif \"LEVERAGE\" in policy[\"exposure_policy\"][\"blocked_actions\"]:\n    leverage = 1.0\n```\n\n## Policy Levels\n\n| Level | Label | Max Size | What your agent can do |\n|-------|-------|----------|----------------------|\n| 1 | BLOCK Survival | <15% | Reduce exposure, hedge only |\n| 2 | BLOCK Defensive | <35% | Wait, hedge, small scalps |\n| 3 | CAUTIOUS | <60% | DCA, R:R >2:1 only |\n| 4 | GREEN Selective | <80% | Trade with confirmation |\n| 5 | GREEN Expansion | ≥80% | Full operations, leverage up to 2x |\n\n## Supported Assets\n\n- **BTC** — Full signal coverage (30+ indicators)\n- **ETH** — Full coverage including ETH structural score, ETH/BTC ratio analysis, staking dynamics\n\n## Integration Paths\n\n### REST API\nDirect HTTP calls. Any language, any framework.\n\n### SKILL.md\nDrop [`SKILL.md`](SKILL.md) into your agent's repo. Compatible with Claude Code, Copilot, Cursor, and Gemini via [skills.sh](https://skills.sh).\n\n### MCP Server\n\n```bash\nnpm install @riskstate/mcp-server\n```\n\nOr run directly with `npx @riskstate/mcp-server`. Docker: `ghcr.io/likidodefi/riskstate-mcp`.\n\nOne tool: `get_risk_policy` — same parameters as the REST API. Compatible with Claude Desktop, Claude Code, Cursor, and any MCP-compatible client. See [MCP README](https://github.com/likidodefi/RiskState/tree/main/mcp) for full setup.\n\n## Listed On\n\n- [awesome-mcp-servers](https://github.com/punkpeye/awesome-mcp-servers) — Finance & Fintech category\n- [LobeHub MCP](https://lobehub.com) — Auto-discovered\n- [ClawHub.ai](https://clawhub.ai) — Skill marketplace\n- [skills.sh](https://skills.sh) — Vercel skills registry\n- [Glama.ai](https://glama.ai) — AAA score\n\n## Binding Precedence\n\nWhen consuming the response, agents **must** evaluate fields in this order:\n\n1. `risk_flags.structural_blockers` — if non-empty, **abort** new entries\n2. `exposure_policy.blocked_actions` — actions the agent must not take\n3. `exposure_policy.reduce_recommended` — reduce exposure if `true`\n4. `exposure_policy.max_size_fraction` — maximum position size (0.0–1.0)\n5. `exposure_policy.max_leverage` — maximum leverage allowed\n\n## Data Sources\n\nRiskState ingests 30+ real-time signals from:\n\n- **Price & Derivatives** — Binance, OKX, Bybit (funding, OI, basis, L/S ratio)\n- **On-chain** — MVRV, NUPL, exchange netflow, supply metrics (CoinGlass)\n- **Macro** — DXY, US yields, S&P 500, Gold, Fed balance sheet (FRED, Yahoo Finance)\n- **DeFi** — Spark Protocol, Aave V3 health factor and liquidation thresholds\n- **Sentiment** — Fear & Greed, ETF flows, institutional treasuries\n- **ETH-specific** — Staking ratio, burn rate, DEX volume, fees, stablecoin TVL\n\n## Pricing\n\n**Free during beta.** Rate limit: 60 requests/minute.\n\n| Tier | Calls/month | Price |\n|------|------------|-------|\n| Free | 100 | $0 |\n| Builder | 5,000 | $49/mo |\n| Growth | 25,000 | $149/mo |\n| Scale | 100,000 | $399/mo |\n\nPaid tiers coming after beta. [Sign up now](https://riskstate.ai) to lock in early access.\n\n## Documentation\n\n- [**API Reference**](docs/api-v1.md) — Full endpoint documentation, field types, error codes\n- [**SKILL.md**](SKILL.md) — Agent discovery file with decision rules and failure modes\n- [**Changelog**](CHANGELOG.md) — Version history and release notes\n- [**Website**](https://riskstate.ai) — Landing page with interactive examples\n\n## Links\n\n- Website: [riskstate.ai](https://riskstate.ai)\n- X/Twitter: [@riskstate_ai](https://x.com/riskstate_ai)\n- API: `POST https://riskstate.netlify.app/v1/risk-state`\n\n---\n\n<p align=\"center\">\n  <sub>Built by <a href=\"https://github.com/likidodefi\">likidodefi</a> · © 2026 Digital Venture Asset LLC</sub>\n</p>\n\nFile v1.2.2:_meta.json\n\n{\n  \"ownerId\": \"kn7djkxqyactdmda78e52x792h83c54v\",\n  \"slug\": \"riskstate\",\n  \"version\": \"1.2.2\",\n  \"publishedAt\": 1774480873900\n}\n\nFile v1.2.2:CHANGELOG.md\n\n# Changelog\n\nAll notable changes to the RiskState API will be documented in this file.\n\n## [1.2.0] - 2026-03-19\n\n### Added\n- **Usage tracking** — Monthly and total API call counts per key, visible in admin panel\n- **Bybit V5 + OKX V5 fallback chain** — Funding rate and OI now have 4-level fallback: Binance → OKX → Bybit → CoinGlass → default. 98%+ uptime for positioning data\n- **DXY in API** — Frankfurter EUR/USD proxy added to API (was missing, affected regime classification)\n- **Aave V3 support** — DeFi position monitoring now supports both Spark Protocol and Aave V3 with per-collateral liquidation thresholds\n\n### Fixed\n- **BTC cycle phase alignment** — API now replicates exact dashboard 9-branch priority order (was simplified 6-branch, causing POST-PEAK vs CORRECTION divergence)\n- **Regime classification fix** — Missing DXY caused false BEAR regime in API (DXY defaulted to 100 → extra bearSignal)\n- **ETH structural score** — Now fetches real data (was hardcoded null → default 50). Lido staking, burn rate, DEX volume, fees, stablecoin TVL all live\n- **Macro regime alignment** — API now calls macro.js as single source of truth (was divergent inline computation)\n\n## [1.1.1] - 2026-03-16\n\n### Added\n- **English standardization** — All API responses in English (was mixed Spanish/English)\n- **ETH Structural Score v2.2** — Widened issuance bands, lending heat directional scoring, hard/soft downgrade reclassification\n- **Weighted warnings in rules cap** — Structural warnings (slow-moving) penalize 0.5x vs tactical 1.0x\n\n### Fixed\n- **False BLOCK prevention** — Mild ETH inflation (+0.3%/yr) no longer triggers defensive policy\n- **CoinGlass fallback fixes** — OI, L/S ratio, MVRV fallback chains corrected (wrong field names, unused data)\n\n## [1.1.0] - 2026-03-13\n\n### Added\n- **Deterministic API contract** — `allowed_actions` and `blocked_actions` use uppercase enum tokens (DCA, WAIT, LEVERAGE_GT_2X) instead of free-text\n- **`reason_codes`** — Machine-parseable tokens in `binding_constraint` (e.g., MACRO_RISK_OFF, COUPLING_NORMAL)\n- **`ttl_seconds`** — Cache TTL in response (60s) for agent scheduling\n- **`binding_constraint.source` uppercased** — RULES, DEFI, MACRO, CYCLE (consistent enum style)\n\n### Changed\n- **SKILL.md rewritten** — Binding precedence section, decision rules table, failure modes table, updated example response\n\n## [1.0.0] - 2026-03-12\n\n### Added\n- **Initial release** — `POST /v1/risk-state` endpoint\n- **5-level policy engine** — BLOCK (1-2) → CAUTIOUS (3) → GREEN (4-5)\n- **Multi-asset support** — BTC and ETH with asset-specific scoring\n- **4-cap system** — Rules, DeFi, Macro, Cycle caps × quality × volatility adjustment\n- **30+ real-time signals** — Macro, on-chain, derivatives, DeFi health, sentiment\n- **DeFi-aware** — Optional wallet parameter for Spark/Aave V3 health factor integration\n- **SHA-256 policy hash** — Deterministic audit trail for non-repudiation\n- **Hierarchical risk flags** — `structural_blockers` (hard stop) vs `context_risks` (reduce conviction)\n- **60s Blob cache** — Skip cache when wallet parameter provided\n- **Bearer auth** — Fail-closed authentication\n- **SKILL.md** — Agent discovery file for skills.sh and agentskills.io ecosystems\n- **Full API documentation** — docs/api-v1.md with field types, error codes, interpretation guide\n\nFile v1.2.2:docs/api-v1.md\n\n# RiskState API v1 Documentation\n\n## Endpoint\n\n```\nPOST /v1/risk-state\n```\n\n## Authentication\n\nAll requests require a Bearer token in the `Authorization` header.\n\n```\nAuthorization: Bearer <your_api_key>\n```\n\n### Key types\n\n| Type | Format | Rate limit | Access |\n|------|--------|------------|--------|\n| **Owner** | `RISKSTATE_API_KEY` env var | Unlimited | All endpoints |\n| **External** | `rs_live_` + 64 hex chars | 60 req/min | `/v1/risk-state` + read-only endpoints |\n\n### Getting an API key\n\nRequest API access at [https://riskstate.ai](https://riskstate.ai) — only an email is required. You'll receive an `rs_live_` key via email within minutes.\n\nKeys are managed through the `/api/api-keys` admin endpoint (owner-only).\n\nThe endpoint **fails closed**: if the server secret is not configured, all requests are denied (401). Rate-limited requests return 429 with `retry_after_seconds: 60`.\n\n## Request\n\n### Headers\n\n| Header | Required | Value |\n|--------|----------|-------|\n| `Authorization` | Yes | `Bearer <token>` |\n| `Content-Type` | Yes | `application/json` |\n\n### Body (JSON)\n\n| Field | Type | Default | Description |\n|-------|------|---------|-------------|\n| `asset` | string | `\"BTC\"` | Asset to evaluate. `\"BTC\"` or `\"ETH\"`. |\n| `wallet` | string | `null` | Ethereum wallet address (0x...) for DeFi position data. Optional. |\n| `protocol` | string | `\"spark\"` | DeFi lending protocol. `\"spark\"` or `\"aave\"`. Only used when `wallet` is provided. |\n| `include_details` | boolean | `false` | Include expanded scoring details in response. |\n\n### Example requests\n\n**Minimal (BTC):**\n\n```bash\ncurl -X POST https://riskstate.netlify.app/v1/risk-state \\\n  -H \"Authorization: Bearer $RISKSTATE_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"asset\": \"BTC\"}'\n```\n\n**Detailed (with scoring breakdown):**\n\n```bash\ncurl -X POST https://riskstate.netlify.app/v1/risk-state \\\n  -H \"Authorization: Bearer $RISKSTATE_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"asset\": \"BTC\", \"include_details\": true}'\n```\n\n**DeFi monitoring (with wallet + Aave):**\n\n```bash\ncurl -X POST https://riskstate.netlify.app/v1/risk-state \\\n  -H \"Authorization: Bearer $RISKSTATE_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"asset\": \"ETH\", \"wallet\": \"0xYOUR_WALLET_ADDRESS\", \"protocol\": \"aave\", \"include_details\": true}'\n```\n\n> **Note:** All parameters go inside the `-d` JSON string. The `\\` at the end of each line is a shell line continuation — the entire command is one curl call.\n\n### Validation\n\n- `asset` must be `\"BTC\"` or `\"ETH\"` (case-insensitive) → 400 otherwise\n- `wallet` must match `^0x[a-fA-F0-9]{40}$` if provided → 400 otherwise\n- `protocol` must be `\"spark\"` or `\"aave\"` (case-insensitive) → 400 otherwise\n- Invalid JSON body → 400\n\n## Response — Minimal (default)\n\nThree blocks: **Permissioning**, **Classification**, **Auditability**.\n\n### Permissioning\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `exposure_policy.max_size_fraction` | float (0–1) | Maximum position size as fraction of portfolio |\n| `exposure_policy.leverage_allowed` | boolean | Whether leverage is permitted |\n| `exposure_policy.max_leverage` | string | Maximum leverage (`\"0x\"`, `\"1x\"`, `\"1.5x\"`, `\"2x\"`) |\n| `exposure_policy.direction_bias` | string | `\"LONG_PREFERRED\"`, `\"SHORT_PREFERRED\"`, or `\"NEUTRAL\"` |\n| `exposure_policy.reduce_recommended` | boolean | Agent should reduce exposure |\n| `exposure_policy.allowed_actions` | string[] | Actions the agent MAY take (enum tokens, see reference below) |\n| `exposure_policy.blocked_actions` | string[] | Actions the agent MUST NOT take (enum tokens, see reference below) |\n\n### Classification\n\n| Field | Type | Range | Description |\n|-------|------|-------|-------------|\n| `tactical_state` | string | BULLISH, LEAN BULL, NEUTRAL, LEAN BEAR, BEARISH | 24-72h directional tilt from composite |\n| `structural_state` | string | Cycle phase | BTC: BOTTOM/EARLY/MID/LATE/EUPHORIA/CORRECTION/POST-PEAK. ETH: DEPRESSED/VALUE_ZONE/RECOVERY/EXTENDED/DISTRIBUTION |\n| `macro_state` | string | RISK-ON, NEUTRAL, RISK-OFF | Macro regime from FRED data |\n| `market_regime` | string | PANIC, EUPHORIA, SQUEEZE, TREND, RANGE | 5-state unified market regime |\n| `volatility_regime` | string | LOW, NORMAL, HIGH, EXTREME | Volatility classification |\n| `policy_level` | int | 1–5 | Informational classification. The `exposure_policy` fields are the binding constraints. 1=BLOCK Survival, 2=BLOCK Defensive, 3=CAUTIOUS, 4=GREEN Selective, 5=GREEN Expansion |\n| `confidence_score` | float (0–1) | Signal agreement × data quality | Measures subscore agreement and data integrity. NOT a probability of market prediction accuracy. Higher = signals agree more and data is fresher. |\n| `data_quality_score` | int (0–100) | % of data sources live | Percentage of data sources reporting live data. Different scale from `confidence_score` (0–1 factor). <70 = degraded, <50 = unreliable |\n\n### Constraints & Flags\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `binding_constraint.source` | string | Which cap is limiting: `\"RULES\"`, `\"DEFI\"`, `\"MACRO\"`, `\"CYCLE\"` |\n| `binding_constraint.reason` | string | Human-readable explanation (e.g., `\"RISK-OFF × NORMAL\"`) |\n| `binding_constraint.reason_codes` | string[] | Machine-parseable reason tokens (e.g., `[\"MACRO_RISK_OFF\", \"COUPLING_NORMAL\"]`) |\n| `binding_constraint.cap_value` | float | The binding cap's value (0–1) |\n| `risk_flags.structural_blockers` | string[] | Hard blockers — agent MUST pause new entries |\n| `risk_flags.context_risks` | string[] | Soft risks — agent should reduce conviction |\n| `defi` | object\\|null | DeFi position data if wallet provided, else `null`. See fields below. |\n| `defi.health_factor` | float | Current health factor (>1 = safe, <1.1 = danger) |\n| `defi.ltv` | float | Current loan-to-value ratio % (debt / collateral × 100). E.g., 35.4 means 35.4% utilized. |\n| `defi.max_ltv` | float | Protocol's maximum LTV threshold % (e.g., 82.99). Borrowing above this is blocked. |\n| `defi.liquidation_threshold` | float | Liquidation threshold % (e.g., 82.5). Position liquidatable above this. |\n| `defi.protocol` | string | `\"spark\"` or `\"aave\"` |\n\n### Auditability\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `policy_hash` | string | SHA-256 hash of policy inputs for non-repudiation |\n| `scoring_version` | string | `\"score_v2\"` — scoring algorithm version |\n| `version` | string | `\"1.2.2\"` — API version |\n| `timestamp` | string | ISO 8601 timestamp |\n| `asset` | string | Asset evaluated |\n| `cached` | boolean | Whether response was served from cache |\n| `ttl_seconds` | int | Cache TTL in seconds (60). Agent should re-request after this interval for fresh data. |\n| `key_type` | string | `\"owner\"` or `\"external\"` — identifies which auth tier was used |\n| `stale_fields` | string[] | Core signals that are missing or stale |\n\n## Response — Detailed (`include_details=true`)\n\nAll minimal fields plus:\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `caps.rules` | float | Rules cap (0–1) |\n| `caps.defi` | float | DeFi health cap (0–1) |\n| `caps.macro` | float | Macro regime cap (0–1) |\n| `caps.cycle` | float | Cycle phase cap (0–1) |\n| `caps.quality` | float | Quality factor (conflict × integrity) |\n| `caps.data_integrity` | float | Data freshness score |\n| `positioning.squeeze_direction` | string | UPSIDE, DOWNSIDE, TWO-SIDED, NONE |\n| `positioning.squeeze_confidence` | int | 0–100 |\n| `positioning.ls_crowding` | string | LONG_CROWDED, SHORT_CROWDED, BALANCED, etc. |\n| `positioning.ls_crowding_score` | int | 0–100 |\n| `positioning.funding_percentile` | int | Funding rate percentile vs 30d (0–100) |\n| `positioning.oi_zscore` | float | OI z-score vs 30d |\n| `positioning.basis_pct` | float | Perp-spot basis % |\n| `volatility.regime` | string | LOW, NORMAL, HIGH, EXTREME |\n| `volatility.score` | int | 0–100 |\n| `whale_pressure.score` | int | 0–100 (9 proxy signals) |\n| `whale_pressure.direction` | string | STRONG_BUY, BUY, NEUTRAL, SELL, STRONG_SELL |\n| `trend_strength.score` | int | 0–100 |\n| `trend_strength.direction` | string | STRONG_TREND, TREND, NEUTRAL, COUNTER_TREND, STRONG_COUNTER |\n| `trend_strength.components` | object | `{ ma_cluster, expansion, flow_alignment }` (each 0–100) |\n| `composite.overall` | int | 0–100 weighted composite score |\n| `composite.subscores` | array | `[{ name, score, weight }]` — 7-8 subscores |\n| `extreme_scores.panic` | int | 0–100 panic percentile |\n| `extreme_scores.euphoria` | int | 0–100 euphoria percentile |\n| `eth_structural` | object\\|null | ETH structural score (ETH only): `{ overall, label, dataQuality, subfamilies: { network, supply, relative, demand } }` |\n| `eth_downgrade` | object\\|null | ETH structural downgrade (ETH only): `{ active, count, hardCount, softCount, severity, signals, capReduction }` |\n| `macro_detail` | object | Full macro data for diagnostics: `{ regime, coupling, realRate10y, liquidityRegime, yield10y, yield10yChg, spxChangePct, fedBsDelta3m, spread10y2y, riskOffSignals, riskOnSignals, dxy }` |\n| `data_sources` | object | Per-field source status (LIVE/MOCK/CG_FALLBACK/CC_FALLBACK/DEFAULT) |\n| `core_missing` | string[] | Missing core signals |\n\n## Error Responses\n\n| Status | Body | Cause |\n|--------|------|-------|\n| 400 | `{ \"error\": \"Invalid JSON body\" }` | Malformed JSON |\n| 400 | `{ \"error\": \"Invalid asset. Must be BTC or ETH.\" }` | Unknown asset |\n| 400 | `{ \"error\": \"Invalid wallet address format.\" }` | Bad wallet format |\n| 401 | `{ \"error\": \"Unauthorized\" }` | Missing or invalid Bearer token |\n| 429 | `{ \"error\": \"Rate limit exceeded\", \"retry_after_seconds\": 60 }` | External key exceeded 60 req/min |\n| 500 | `{ \"error\": \"Internal server error\" }` | Server-side failure |\n\n## Data Sources & Fallback Chain\n\nThe endpoint fetches from 15+ external APIs in parallel waves. Binance returns HTTP 451 from Netlify servers, so all Binance data has fallbacks:\n\n| Data | Primary | Fallback | Last Resort |\n|------|---------|----------|-------------|\n| RSI (4h) | Binance klines | CryptoCompare `histohour` | Default 50 |\n| Funding rate | Binance `fundingRate` | OKX V5 → Bybit V5 → CoinGlass | Default 0 |\n| Daily klines (200d) | Binance klines | CryptoCompare `histoday` | `null` (trend strength unavailable) |\n| MVRV | blockchain.info | CoinGlass `/indicator/market/mvrv` | Default 1.8 |\n| Real Rate | FRED T10YIE (breakeven) | — | `null` |\n| Liquidity Regime | FRED WALCL (13-week delta) | — | `NEUTRAL` |\n| Gold | Yahoo Finance | — | `null` |\n| Macro regime + coupling | `/api/macro` (single source of truth) | — | `NEUTRAL` / `NORMAL` |\n| ETH Structural | Lido + Ultrasound + DefiLlama (6 APIs) | — | Score defaults to 50 |\n| SPX | Yahoo Finance (^GSPC) via macro.js | FRED SP500 (T-1 lag) | `null` |\n| Staking APR | Lido `/apr/last` | Lido `/apr/sma` | Default 2.8% |\n\nThe `data_sources` field (in detailed response) shows per-field source: `LIVE`, `CC_FALLBACK` (CryptoCompare), `CG_FALLBACK` (CoinGlass), `ESTIMATED` (price-based), `DEFAULT_ZERO`, `DEFAULT`, or `MOCK`.\n\n### Known Data Limitations (v1.2.0)\n\nBinance returns HTTP 451 from Netlify servers. Current CoinGlass tier lacks certain endpoints. These cause permanent fallback states for some fields:\n\n| Field | Server Status | Impact | Dashboard Comparison |\n|-------|--------------|--------|---------------------|\n| Funding | OKX or BYBIT fallback | Live data via cascading fallback chain. Neutral default (0) only if all fallbacks fail | Dashboard gets real data from browser-side Binance |\n| Open Interest | OKX or BYBIT fallback | Live data via cascading fallback chain. Affects squeeze detection and OI z-score | Dashboard gets real data from browser-side Binance |\n| MVRV | ESTIMATED (~price/$36K) | Accurate to ±5%. Affects cycle phase near thresholds | Dashboard gets real MVRV from blockchain.info |\n| DXY | LIVE (Frankfurter EUR/USD proxy) | Same formula as dashboard. Affects detectRegime + macro scoring | Dashboard uses same Frankfurter proxy via market-data.js |\n\n### API vs Dashboard Classification Alignment (v1.2.0, Mar 19 2026)\n\nAll classification fields now match between API and dashboard for the same market conditions:\n\n| Field | Status | Notes |\n|-------|--------|-------|\n| cycle_phase | Aligned | Full 9-branch BTC classification (was simplified 6-branch) |\n| market_regime | Aligned | DXY fix resolved false BEAR → TREND (was missing Frankfurter call) |\n| macro_state | Aligned | Same macro.js as single source of truth |\n| composite | Aligned | Same scoring-core.js functions |\n| policy_level | Aligned | Same cap computation; DeFi cap differs when API called without wallet |\n\n**Expected deltas** (not bugs — different data availability):\n- **DeFi cap**: API=100% (no wallet) vs dashboard=84% (wallet connected) — pass `wallet` param to API for parity\n- **Whale score**: ~9pt gap — browser computes 9 signals with real-time data; server has fewer\n- **Trend strength**: ~3pt gap — minor data timing/source differences\n- **Quality factor**: ~8pt gap — DeFi cap + subscore spread differences affect conflict_penalty\n\nAll other fields (RSI, daily klines, L/S ratio, CVD, ETF, exchange flow, macro, correlations, ETH structural) have working fallback chains.\n\n## Caching Behavior\n\n- **60-second TTL** via Netlify Blobs\n- First call: 5–12 seconds (fetches from 15+ external APIs in 5 parallel waves)\n- Subsequent calls within 60s: <1 second\n- `cached: true` in response indicates cache hit\n- **Wallet parameter bypasses cache** (DeFi data is personalized)\n\n## Action Enums Reference\n\n### `allowed_actions` values\n\n| Token | Meaning | Policy Levels |\n|-------|---------|---------------|\n| `REDUCE` | Reduce existing exposure | 1 |\n| `ADD_COLLATERAL` | Add collateral to DeFi position | 1 |\n| `HEDGE` | Hedge existing positions | 1, 2 |\n| `WAIT` | Wait for better conditions | 2, 3 |\n| `REDUCE_LEVERAGE` | Reduce leverage on existing positions | 2 |\n| `SCALP_SMALL` | Small scalp trades only | 2 |\n| `RR_GT_2` | Trades with R:R > 2:1 only | 2, 3 |\n| `DCA` | Dollar-cost averaging | 3, 4 |\n| `LIGHT_ACCUMULATION` | Light spot accumulation | 3 |\n| `LONG_SHORT_CONFIRMED` | Long or short with confirmation signals | 4 |\n| `LEVERAGE_MODERATE` | Moderate leverage (up to 1.5x) | 4 |\n| `TREND_FOLLOW` | Trend following strategies | 5 |\n| `ADD_ON_PULLBACK` | Add to winners on pullbacks | 5 |\n| `LEVERAGE_2X` | Leverage up to 2x | 5 |\n| `AGGRESSIVE_ACCUMULATION` | Aggressive spot accumulation | 5 |\n\n### `blocked_actions` values\n\n| Token | Meaning | Policy Levels |\n|-------|---------|---------------|\n| `NEW_TRADES` | All new position entries blocked | 1 |\n| `LEVERAGE` | Any leverage blocked | 1, 3 |\n| `INCREASE_POSITION` | Increasing existing positions blocked | 1 |\n| `LEVERAGE_GT_1X` | Leverage above 1x blocked | 2 |\n| `AGGRESSIVE_LONG` | Aggressive long entries blocked | 2, 3 |\n| `FOMO_ENTRY` | FOMO-driven entries blocked | 2 |\n| `ALL_IN` | Full portfolio allocation blocked | 3, 4 |\n| `LEVERAGE_GT_2X` | Leverage above 2x blocked | 4 |\n| `COUNTER_TREND_SHORT` | Shorting against confirmed trend blocked | 5 |\n\n### `binding_constraint.reason_codes` values\n\n| Source | Possible codes | Example |\n|--------|---------------|---------|\n| RULES | `RULES_CRITICAL_{n}`, `RULES_WARNING_{n}` | `[\"RULES_CRITICAL_2\", \"RULES_WARNING_5\"]` |\n| DEFI | `DEFI_HF_LOW` | `[\"DEFI_HF_LOW\"]` |\n| MACRO | `MACRO_{regime}`, `COUPLING_{level}` | `[\"MACRO_RISK_OFF\", \"COUPLING_HIGH_COUPLING\"]` |\n| CYCLE | `CYCLE_{phase}` | `[\"CYCLE_MID\"]`, `[\"CYCLE_EUPHORIA\"]` |\n\n## Risk Flags Reference\n\n### Structural Blockers (agent MUST pause)\n\n| Flag | Meaning |\n|------|---------|\n| `DEFI_LIQUIDATION_RISK` | Health Factor critically low |\n| `SQUEEZE_RISK` | High-confidence directional squeeze |\n| `MACRO_CONTAGION` | SPX/QQQ selloff >1.5% with normal or high coupling |\n| `MACRO_RISK_OFF` | Macro regime risk-off with multiple signals |\n| `ONCHAIN_EUPHORIA` | MVRV + NUPL at historical extremes |\n| `EXTREME_FEAR` | F&G ≤ 10 (panic conditions) |\n| `FUNDING_EXTREME` | Funding + RSI both extreme |\n| `LIQUIDATION_CASCADE` | >$100M liquidations with asymmetry |\n\n### Context Risks (agent should reduce conviction)\n\n| Flag | Meaning |\n|------|---------|\n| `HIGH_FUNDING` | Funding rate elevated |\n| `RSI_OVERBOUGHT` | RSI > 70 |\n| `RSI_OVERSOLD` | RSI < 25 |\n| `DXY_HEADWIND` | DXY > 104 |\n| `YIELD_PRESSURE` | 10Y yield elevated or spiking |\n| `HIGH_OI` | OI z-score > 2.0 (30d) |\n| `BASIS_EXTREME` | Perp-spot basis > 0.15% |\n| `WHALE_ACTIVITY` | Whale score ≥ 50 |\n| `ETH_STRUCTURAL_WEAK` | ETH structural downgrade active |\n| `ETH_SUPPLY_INFLATIONARY` | ETH supply strongly inflationary |\n| `TREND_NOT_CONFIRMED` | Trend strength ≤ 45 with directional tilt |\n| `NO_TREND` | Trend strength ≤ 20 |\n| `HIGH_COUPLING` | High macro correlation |\n| `SIGNAL_CONFLICT` | Subscore dispersion high |\n| `LS_CROWDED` | L/S ratio extreme |\n| `YIELD_SPIKE` | 10Y yield change > 0.08% in session |\n| `CURVE_INVERTED` | 10Y-2Y spread < -0.2% |\n| `RE\n\nArchive v1.2.1: 5 files, 16491 bytes\n\nFiles: CHANGELOG.md (3398b), docs/api-v1.md (19270b), README.md (7088b), SKILL.md (6997b), _meta.json (128b)\n\nArchive v1.2.0: 5 files, 16477 bytes\n\nFiles: CHANGELOG.md (3398b), docs/api-v1.md (19210b), README.md (7088b), SKILL.md (6909b), _meta.json (128b)\n\nArchive v1.1.1: 5 files, 15821 bytes\n\nFiles: CHANGELOG.md (3398b), docs/api-v1.md (19210b), README.md (6268b), SKILL.md (6273b), _meta.json (128b)","readmeExcerpt":"Skill: Clawhub Owner: riskstate Summary: 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. Tags: agent-skills:1.2.1, agents:1.2.1, ai:1.2.1, ai-agents:1.2.1, ai-trading:1.2.1, bitcoin:1.2.1, btc:1.1.1, crypto:1.2.1, decentralized-finance:1.2.1, def","codeSnippets":[],"executableExamples":[{"language":"text","snippet":"Authorization: Bearer $RISKSTATE_API_KEY"},{"language":"bash","snippet":"curl -X POST https://api.riskstate.ai/v1/risk-state \\\n  -H \"Authorization: Bearer $RISKSTATE_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"asset\": \"BTC\"}'"},{"language":"bash","snippet":"curl -X POST https://api.riskstate.ai/v1/risk-state \\\n  -H \"Authorization: Bearer $RISKSTATE_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"asset\": \"BTC\"}'"},{"language":"bash","snippet":"curl -X POST https://api.riskstate.ai/v1/risk-state \\\n  -H \"Authorization: Bearer $RISKSTATE_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"asset\": \"BTC\", \"include_details\": true}'"},{"language":"bash","snippet":"curl -X POST https://api.riskstate.ai/v1/risk-state \\\n  -H \"Authorization: Bearer $RISKSTATE_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"asset\": \"BTC\", \"include_details\": true}'"},{"language":"bash","snippet":"curl -X POST https://api.riskstate.ai/v1/risk-state \\\n  -H \"Authorization: Bearer $RISKSTATE_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"asset\": \"ETH\", \"wallet\": \"0xYOUR_WALLET_ADDRESS\", \"include_details\": true}'"}],"parameters":null,"dependencies":[],"permissions":[],"extractedFiles":[{"path":"SKILL.md","content":"---\nname: riskstate\nversion: 1.4.1\ndescription: 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.\ncategory: risk-management\nauth: bearer-token\nenv: RISKSTATE_API_KEY\nendpoint: POST https://api.riskstate.ai/v1/risk-state\nassets: [BTC, ETH]\nrefresh: 60s cache, recommend 5min polling\nhomepage: https://riskstate.ai\ndocs: https://riskstate.ai/docs/api\nrepository: https://github.com/Riskstate/risk-engine\ntags: [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]\npricing: free-beta\nauthor: RiskState\nlicense: proprietary\n---\n\n# RiskState — Pre-Trade Risk Layer for Crypto\n\n## What it does\n\nReturns **dynamic risk permissions** for BTC/USD and ETH/USD before capital is deployed.\nA 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**.\n\nThe response tells you:\n- **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).\n- **allowed_actions / blocked_actions**: What MAY and MUST NOT be done (enum tokens)\n- **risk_flags**: Structural blockers (hard stop) vs contextual risks (reduce conviction)\n- **binding_constraint**: Which cap is limiting and why\n- **policy_level**: 1–5 summary label (informational — use `exposure_policy` for enforcement)\n\n## What it does NOT do\n\n- No trade signals, no entry/exit prices, no predictions\n- No portfolio allocation advice\n- No order execution or routing\n- No historical data or backtesting\n\nThis is a **risk governor**, not a trading oracle. The assessment is USD-denominated.\n\n## When to call\n\n- **Before opening or sizing positions** — check permissions first\n- **Periodically during holds** — every 5 min for active trading, every 4h for holding\n- **After significant market moves** — cache invalidates after 60s (`ttl_seconds` in response)\n\n## Authentication\n\nRequest 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:\n\n```\nAuthorization: Bearer $RISKSTATE_API_KEY\n```\n\n## Binding precedence\n\nWhen consuming the response, agents MUST evaluate fields in this order:\n\n1. `risk_flags.structural_blockers` — if non-empty, ABORT new entries\n2. `exposure_policy.blocked_actions` — actions the agent MUST NOT take\n3. `exposure_policy.reduce_recommended` — reduce exposure if true\n4. `exposure_policy.max_size_fraction` — maximum position siz"},{"path":"README.md","content":"<p align=\"center\">\n  <img src=\"https://riskstate.ai/logo-r-grey.svg\" width=\"48\" alt=\"RiskState\" />\n</p>\n\n<h1 align=\"center\">RiskState</h1>\n\n<p align=\"center\">\n  <strong>Pre-trade risk API for crypto — BTC/USD and ETH/USD exposure governance</strong><br />\n  <sub>For trading agents, open-source systems, and capital desks. Spot and perpetual futures (perps). DeFi borrowing aware.</sub>\n</p>\n\n<p align=\"center\">\n  <a href=\"https://api.riskstate.ai/v1/risk-state\"><img src=\"https://img.shields.io/badge/API-v1.4.0-blue?style=flat-square\" alt=\"API Version\" /></a>\n  <a href=\"https://riskstate.ai\"><img src=\"https://img.shields.io/badge/status-beta-green?style=flat-square\" alt=\"Status\" /></a>\n  <a href=\"#supported-assets\"><img src=\"https://img.shields.io/badge/assets-BTC%2FUSD%20%7C%20ETH%2FUSD-orange?style=flat-square\" alt=\"Assets\" /></a>\n  <a href=\"#markets\"><img src=\"https://img.shields.io/badge/markets-spot%20%7C%20perps%20%7C%20DeFi-purple?style=flat-square\" alt=\"Markets\" /></a>\n  <a href=\"#pricing\"><img src=\"https://img.shields.io/badge/pricing-free%20beta-brightgreen?style=flat-square\" alt=\"Pricing\" /></a>\n</p>\n\n<p align=\"center\">\n  <a href=\"https://riskstate.ai\">Website</a> · <a href=\"docs/api-v1.md\">API Reference</a> · <a href=\"SKILL.md\">SKILL.md</a> · <a href=\"https://x.com/riskstate_ai\">X/Twitter</a>\n</p>\n\n---\n\n## What is RiskState?\n\nA deterministic engine that converts live market state into **dynamic risk permissions** — exposure limits, leverage caps, and allowed actions — before capital is deployed.\n\nOne API call returns position limits, allowed actions, and policy constraints computed from **30+ real-time signals** across macro, on-chain, derivatives, and DeFi health. The assessment is **USD-denominated**: all scoring is based on BTC/USD and ETH/USD price action, derivatives, and macro conditions.\n\n```bash\ncurl -X POST https://api.riskstate.ai/v1/risk-state \\\n  -H \"Authorization: Bearer $RISKSTATE_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"asset\": \"BTC\"}'\n```\n\n```json\n{\n  \"exposure_policy\": {\n    \"max_size_fraction\": 0.42,\n    \"leverage_allowed\": true,\n    \"allowed_actions\": [\"DCA\", \"LONG_SHORT_CONFIRMED\"],\n    \"blocked_actions\": [\"ALL_IN\", \"LEVERAGE_GT_2X\"]\n  },\n  \"policy_level\": 4,\n  \"risk_flags\": {\n    \"structural_blockers\": [],\n    \"context_risks\": [\"HIGH_COUPLING\"]\n  },\n  \"binding_constraint\": {\n    \"source\": \"MACRO\",\n    \"reason_codes\": [\"MACRO_NEUTRAL\", \"COUPLING_NORMAL\"]\n  }\n}\n```\n\nRead `max_size_fraction`, check `structural_blockers`, and act. No parsing. No interpretation.\n\n## Why?\n\nWhether you run an AI trading agent, a systematic trading system, or a manual desk — crypto markets have regime shifts that require adaptive risk governance. Static rules fail. RiskState provides a **pre-trade risk check** that adapts every 60 seconds.\n\n| Without governance | With RiskState |\n|---|---|\n| Position size based on signal confidence alone | Capped at `max_size_fraction` (max notional exposure) |\n| No awareness of macro regime"},{"path":"_meta.json","content":"{\n  \"ownerId\": \"kn7djkxqyactdmda78e52x792h83c54v\",\n  \"slug\": \"riskstate\",\n  \"version\": \"1.4.1\",\n  \"publishedAt\": 1789038662413\n}"},{"path":"CHANGELOG.md","content":"# Changelog\n\nAll notable changes to the RiskState API will be documented in this file.\n\n## [1.4.0] - 2026-04-22\n\n### Added\n- **Policy combiner refinements (PR3)** — Five additive refinements to `policy_permissions`, all surfaced in the response and the audit `policy_hash`:\n  - **TREND / RANGE weight split** — `TREND` blends 0.65 structural / 0.35 tactical (continuation-led); `RANGE` 0.55 / 0.45 (tactical has more voice). PANIC, EUPHORIA, and SQUEEZE weights unchanged.\n  - **DQ-gated structural veto** — structural veto is skipped when `structural_score.data_quality < 60`, emitting `STRUCTURAL_VETO_SKIPPED_LOW_DQ`. Prevents low-confidence structural reads from overriding clean tactical signals.\n  - **PANIC SHORT override** — PANIC regime exempts SHORT positions from the strong-structural veto (`STRUCTURAL_VETO_SKIPPED_PANIC`), so dead-cat-bounce / fake-breakout setups are not blocked.\n  - **Bucket codes in `reason_codes`** — typed tokens (e.g. `TACTICAL_STRONG_BULL_72`, `STRUCTURAL_WEAK_22`) replace raw scores for downstream classification.\n  - **`shadow_max_size_fraction`** — read-only preview of a candidate combiner-driven sizing rule. Does not bind today; surfaced for offline comparison.\n\n### Changed\n- Policy hash inputs widened to cover the new bucket codes and shadow size — cached hashes from v1.3.0 will not match (one-time invalidation).\n\n## [1.3.0] - 2026-04-21\n\n### Added\n- **Decoupled Structural + Tactical scores + policy combiner (PR2)** — Splits the single composite into two layers that each drive the appropriate decision:\n  - `structural_score` — slow horizon (weeks-months): cycle, supply, demand, macro. `{overall, label, subfamilies, data_quality, source}`.\n  - `tactical_score` — fast horizon (24-72h): positioning pressure, momentum, volume/CVD, derivatives extremity, L/S velocity, whale pressure. `{overall, label, components, signals}`.\n  - `policy_permissions` — context-aware combiner producing `risk_permission_score`, regime-dependent weights, `direction_bias`, `direction_layer` (audit), and `reason_codes`.\n\n### Changed\n- **`exposure_policy.direction_bias` now comes from the combiner** (was composite-tilt). Breaking semantics.\n- `exposure_policy.direction_layer` added — audit field showing which layer drove direction.\n- Existing `composite` retained for backwards compatibility; `max_size_fraction` still driven by the legacy 4-cap engine.\n\n## [1.2.1] - 2026-04-21\n\n### Added\n- **Positioning Pressure Score (PR1)** — continuous 0-100 tactical signal derived from the squeeze scorer (50 = neutral, >50 short-squeeze setup). Wired into BTC and ETH composite as a 9% subscore. Response gains `positioning.positioning_pressure_score` and `positioning.positioning_pressure_net`.\n\n### Changed\n- **ETH issuance recalibration** — asymmetric bands + 7d/30d blend. Mild post-Merge inflation (+0.82%/yr) now scores ~53 (was ~30); hard-downgrade threshold raised to >+2.0%/yr.\n\n## [1.2.0] - 2026-03-19\n\n### Added\n- **Usage tracking** — Monthly and total API c"},{"path":"docs/api-v1.md","content":"# RiskState API v1 Documentation\n\nPre-trade risk permissions for BTC/USD and ETH/USD. Spot, perpetual futures (perps), and DeFi borrowing aware.\n\n> **USD-denominated:** All scoring is based on BTC/USD and ETH/USD price action, derivatives, and macro conditions. If you trade non-USD pairs (e.g., BTC/EUR, ETH/BTC), additional cross-rate risk is not covered by this API.\n\n## Endpoint\n\n```\nPOST /v1/risk-state\n```\n\n## Authentication\n\nAll requests require a Bearer token in the `Authorization` header.\n\n```\nAuthorization: Bearer <your_api_key>\n```\n\n### Key types\n\n| Type | Format | Rate limit | Access |\n|------|--------|------------|--------|\n| **Owner** | `RISKSTATE_API_KEY` env var | Unlimited | All endpoints |\n| **External** | `rs_live_` + 64 hex chars | 60 req/min | `/v1/risk-state` + read-only endpoints |\n\n### Getting an API key\n\nRequest API access at [https://riskstate.ai](https://riskstate.ai) — only an email is required. You'll receive an `rs_live_` key via email within minutes.\n\nKeys are managed through the `/api/api-keys` admin endpoint (owner-only).\n\nThe endpoint **fails closed**: if the server secret is not configured, all requests are denied (401). Rate-limited requests return 429 with `retry_after_seconds: 60`.\n\n## Request\n\n### Headers\n\n| Header | Required | Value |\n|--------|----------|-------|\n| `Authorization` | Yes | `Bearer <token>` |\n| `Content-Type` | Yes | `application/json` |\n\n### Body (JSON)\n\n| Field | Type | Default | Description |\n|-------|------|---------|-------------|\n| `asset` | string | `\"BTC\"` | Asset to evaluate. `\"BTC\"` or `\"ETH\"`. |\n| `wallet` | string | `null` | Ethereum wallet address (0x...) for DeFi position data. Optional. |\n| `protocol` | string | `\"spark\"` | DeFi lending protocol. `\"spark\"` or `\"aave\"`. Only used when `wallet` is provided. |\n| `include_details` | boolean | `false` | Include expanded scoring details in response. |\n| `reference_time` | number | `now` | Unix seconds. Pins `daysSinceHalving` and the policy hash to a single timestamp, enabling bit-exact reproducibility. Must be in `[halving, now+1d]`. |\n| `allow_degraded` | boolean | `false` | If `false` (default), the endpoint returns **503 Core data unavailable** when any of `price`, `rsi`, `funding` are missing upstream. Set to `true` to receive a degraded policy (with `data_integrity` capped). |\n\n### Example requests\n\n**Minimal (BTC):**\n\n```bash\ncurl -X POST https://api.riskstate.ai/v1/risk-state \\\n  -H \"Authorization: Bearer $RISKSTATE_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"asset\": \"BTC\"}'\n```\n\n**Detailed (with scoring breakdown):**\n\n```bash\ncurl -X POST https://api.riskstate.ai/v1/risk-state \\\n  -H \"Authorization: Bearer $RISKSTATE_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"asset\": \"BTC\", \"include_details\": true}'\n```\n\n**DeFi monitoring (with wallet + Aave):**\n\n```bash\ncurl -X POST https://api.riskstate.ai/v1/risk-state \\\n  -H \"Authorization: Bearer $RISKSTATE_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n "}],"languages":[],"docsSourceLabel":"CLAWHUB","editorialOverview":null,"editorialQuality":{"score":100,"threshold":65,"status":"thin","wordCount":2167,"uniquenessScore":43,"reasons":["uniqueness-below-45"]}},"media":{"evidence":{"source":"no-media","verified":false,"confidence":"low","updatedAt":"2026-10-10T18:49:59.527Z","emptyReason":"No screenshots, media assets, or demo links are available."},"primaryImageUrl":null,"mediaAssetCount":0,"assets":[],"demoUrl":null},"ownerResources":{"evidence":{"source":"unclaimed","verified":false,"confidence":"low","updatedAt":"2026-10-10T18:49:59.527Z","emptyReason":"This page has not been claimed by the agent owner."},"hasCustomPage":false,"customPageUpdatedAt":null,"customLinks":[],"structuredLinks":{"docsUrl":null,"demoUrl":null,"supportUrl":null,"pricingUrl":null,"statusUrl":null},"customPage":null},"relatedAgents":{"evidence":{"source":"protocol-neighbors","verified":false,"confidence":"medium","updatedAt":"2026-10-10T21:43:10.136Z","emptyReason":null},"items":[{"id":"8ebccd8e-3863-4187-8355-c3f14e1f9edf","entityType":"agent","canonicalPath":"/agent/iofficeai-aionui","slug":"iofficeai-aionui","name":"AionUi","description":"Free, local, open-source 24/7 Cowork app and OpenClaw for Gemini CLI, Claude Code, Codex, OpenCode, Qwen Code, Goose CLI, Auggie, and more | 🌟 Star if you like it!","url":"https://github.com/iOfficeAI/AionUi","homepage":"https://www.aionui.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-10-09T19:11:12.944Z","createdAt":"2026-02-25T03:38:16.584Z","downloads":null},{"id":"b917f68a-ebff-438e-84f8-3f4b2494c0bc","entityType":"agent","canonicalPath":"/agent/activepieces-activepieces","slug":"activepieces-activepieces","name":"activepieces","description":"AI Agents & MCPs & AI Workflow Automation • (~400 MCP servers for AI agents) • AI Automation / AI Agent with MCPs • AI Workflows & AI Agents • MCPs for AI Agents","url":"https://github.com/activepieces/activepieces","homepage":"https://www.activepieces.com","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-15T02:22:12.426Z","createdAt":"2026-02-25T03:38:12.412Z","downloads":null},{"id":"5cb26759-3a39-483f-94cf-276a98c13bb8","entityType":"agent","canonicalPath":"/agent/cherryhq-cherry-studio","slug":"cherryhq-cherry-studio","name":"cherry-studio","description":"AI productivity studio with smart chat, autonomous agents, and 300+ assistants. Unified access to frontier LLMs","url":"https://github.com/CherryHQ/cherry-studio","homepage":"https://cherry-ai.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-11T14:38:40.986Z","createdAt":"2026-02-25T03:38:19.379Z","downloads":null},{"id":"6f6582d0-5d76-4f0f-b81d-86520247950b","entityType":"agent","canonicalPath":"/agent/copilotkit-copilotkit","slug":"copilotkit-copilotkit","name":"CopilotKit","description":"The Frontend for Agents & Generative UI. React + Angular","url":"https://github.com/CopilotKit/CopilotKit","homepage":"https://docs.copilotkit.ai","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-03-25T09:50:57.846Z","createdAt":"2026-02-25T03:39:14.617Z","downloads":null}],"links":{"hub":"/agent","source":"/agent/source/clawhub","protocols":[{"label":"OpenClaw","href":"/agent/protocol/openclew"}]}}}