RiskState — Crypto Risk Engine

RiskState MCP Server

适用于 RiskState 的 MCP 服务——为 BTC/USD 和 ETH/USD 提供交易前风险权限。支持现货、永续期货（perps）和 DeFi 借贷。

你的系统会询问：“我现在可以承担多大风险？” RiskState 会给出：策略级别、最大敞口、杠杆限制、受阻操作——这些结果基于 30 多项实时信号计算得出。

通过 MCP 使用 RiskState 的两种方式

1. 远程连接器——无需安装，无需 API 密钥。 RiskState 运行着一个托管的 MCP 服务（Streamable HTTP），并提供免费的公共层级：

https://api.riskstate.ai/mcp

将其添加为 Claude 或 ChatGPT 中的自定义连接器，然后直接询问 BTC 的风险 状态。它提供三个只读工具——get_risk_state、 get_market_structure、get_playbook_status——涵盖全部三个引擎，并且 已作为 ai.riskstate/mcp 列入官方 MCP 注册表。

响应是免费的公共摘要：与公共可视化工具展示的详细程度相同。要获取 policy_hash、综合子评分、持仓和宏观细节，则需要密钥。

2. 此软件包——stdio、有密钥、完整响应。 如果你想在本地 Agent 中获取 完整的审计数据，或在自己的工具链中固定版本，请使用此方式。它需要 RISKSTATE_API_KEY，并会返回你的密钥有权访问的全部数据。本 README 的其余部分 介绍的就是这种用法。

工具

四个只读工具，分别回答你在交易前可能会提出的一个问题：

工具	回答的问题	端点	需要密钥
get_risk_policy	允许多少敞口？	POST /v1/risk-state	是
get_market_structure	我们是否接近结构性拐点？	POST /v1/market-structure	是
get_playbook_status	当前有可执行的交易设置吗？	GET /api/playbook-data	否
check_trade	这笔持仓会获准吗？	POST /v2/portfolio-risk-state	是

get_risk_policy 返回：

字段	说明
policy_level	5 个级别：BLOCK_SURVIVAL、BLOCK_DEFENSIVE、CAUTIOUS、GREEN_SELECTIVE、GREEN_EXPANSION
max_size_pct	最大持仓规模，占投资组合的百分比（0-100）
leverage_max	允许的最大杠杆倍数
allowed_actions	在此策略级别下，Agent 可以执行的操作
blocked_actions	Agent 不能执行的操作
confidence_score	信号一致性 x 数据质量（0-1）

check_trade 会评估假设投资组合——请发送你正在考虑的持仓，以及你 已经持有的任何仓位，因为限额会考虑整个投资组合。它会逐个持仓返回该仓位是否获准、以 百分比和美元计的规模上限，以及不获准时的 reason_codes。这些代码表示阻止原因； advisories 仅供参考，不影响 allowed。它不会下单。

只有当交易设置的条件匹配、未被任何引擎否决，并且不处于提醒冷却期时， get_playbook_status 才会将其报告为可执行。 匹配但已经提醒过的设置会单独计数，因此轮询此工具的 Agent 不会对同一信号重复采取行动。

为什么没有写入工具

这里没有 update_policy、没有 set_limit、没有例外管理——而且以后也 不会有。RiskState 的前提是，受其约束的系统不能自行更改限制。每项决策都会经过哈希处理（policy_hash），以便之后根据生成该决策的输入进行 审计；如果有工具允许调用方重写策略，那么这个哈希就失去了意义，审计轨迹也会沦为装饰。

因此，这里的生命周期有意限定在一侧：引擎负责计算，Agent 负责读取并遵守。 check_trade 是最接近动态逐笔交易操作的功能，但它仍然是只读的——它回答“这会获准吗”，而不是“批准这笔交易”。

API 会在服务器端汇总 9 个以上的实时数据源。详情请参阅 API 文档。

此封装器的功能与不提供的功能

这是一个轻量封装器——它将 MCP 工具调用转换为 REST API 请求，并返回响应。所有计算（评分、策略引擎、数据摄取）都在服务端进行。

此封装器提供：

• 符合 MCP 协议（为 Claude Desktop/Code 提供 stdio 传输）
• 通过 Zod 架构验证输入
• 在响应前附加易于阅读的策略摘要
• 提供具体的错误消息（身份验证、速率限制、超时），以便 Agent 恢复

此封装器不提供：

• 缓存响应（API 在服务端缓存 60s）
• 在本地执行任何评分或计算
• 保证响应架构的稳定性（遵循 API 版本管理）

安装

npm install @riskstate/mcp-server

配置

环境变量

变量	必需	说明
RISKSTATE_API_KEY	是	来自 riskstate.ai 的 API 密钥（Beta 期间免费）
RISKSTATE_API_URL	否	自定义 API 基础 URL（默认值：https://api.riskstate.ai）

Claude Desktop

添加到 ~/.config/Claude/claude_desktop_config.json：

{
  "mcpServers": {
    "riskstate": {
      "command": "npx",
      "args": ["-p", "@riskstate/mcp-server", "riskstate-mcp"],
      "env": {
        "RISKSTATE_API_KEY": "your-api-key"
      }
    }
  }
}

Claude Code

claude mcp add riskstate -- npx -p @riskstate/mcp-server riskstate-mcp

在环境中设置 API 密钥：

export RISKSTATE_API_KEY=your-api-key

全局安装（替代方案）

npm install -g @riskstate/mcp-server
riskstate-mcp  # starts MCP server on stdio

使用方法

上方列出了四个工具。get_risk_policy 接受以下参数：

参数

参数	类型	必需	说明
asset	"BTC" | "ETH"	是	要分析的资产
wallet_address	string	否	用于获取链上持仓数据的 DeFi 钱包
protocol	"spark" | "aave"	否	借贷协议（默认值：spark）
include_details	boolean	否	包含完整明细（子评分、宏观指标、风险标记）

响应示例

{
  "exposure_policy": {
    "policy_level": "CAUTIOUS",
    "max_size_pct": 35,
    "leverage_max": 1.5,
    "allowed_actions": ["DCA", "WAIT", "SPOT_LONG_CONFIRMED"],
    "blocked_actions": ["LEVERAGE_GT_2X", "NEW_POSITIONS_UNCONFIRMED"]
  },
  "classification": {
    "cycle_phase": "MID",
    "market_regime": "RANGE",
    "macro_regime": "NEUTRAL",
    "direction": "SIDEWAYS"
  },
  "auditability": {
    "composite_score": 52,
    "confidence_score": 0.72,
    "policy_hash": "a3f8c2...",
    "ttl_seconds": 60
  }
}

Agent 应如何使用此工具

在每次交易前调用 get_risk_policy：

1. 如果 policy_level 以 BLOCK 开头 → 不要开立新仓位
2. 使用 max_size_pct 限制仓位规模
3. 执行前检查 blocked_actions
4. 在 ttl_seconds 之后（60s 缓存）重新查询

对于需要确定规模的仓位，check_trade 可将步骤 2-3 合并为一次调用：发送你打算开立的仓位以及当前已有的持仓，并查看 allowed 和 reason_codes。建议优先使用它，而不是自行重新推算上限，因为这些上限会考虑整个投资组合，单独看似乎合规的仓位，在汇总后仍可能突破集中度限制。

get_market_structure 和 get_playbook_status 提供的是背景信息，不代表许可。这两者都不能授权交易——只有风险策略可以。使用它们判断是否值得提出交易，然后调用 get_risk_policy / check_trade 了解允许交易的规模。

限制

• v1 范围： 仅支持 BTC/USD 和 ETH/USD（以 USD 计价的评估）。计划支持更多资产。
• 市场： 现货、永续期货和 DeFi 借贷。响应格式相同，但不同市场的解读方式有所区别（参见 API 文档）。
• 协议： DeFi 持仓数据仅支持 Spark 和 Aave V3。
• 速率限制： 每个 API 密钥每分钟 60 个请求。
• 延迟： 每次请求约 1-3s（聚合 9 个以上的上游数据源）。
• 测试环境： Claude Desktop、Claude Code。应可与任何兼容 MCP 的客户端配合使用。

链接

• 主页： riskstate.ai
• API 文档： riskstate.ai/docs/api
• SKILL.md： agentskills.io

许可证

MIT