RiskState — Crypto Risk Engine

ai.riskstatePublished by riskstate.aiOfficial publisherv1.0.1Updated Oct 24, 2026

Live BTC/ETH risk state: risk policy, market structure and trading playbooks. Keyless free tier.

VerifiedStreamable HTTPWeb executableFinanceData & Analytics

Overview

AI-generated overview

RiskState exposes read-only BTC/ETH risk policy, market structure and trading playbook data so an assistant can check how much exposure a trade would be allowed

What you can do
Read the current risk policy for BTC or ETH: policy level, maximum position size, leverage limit, allowed and blocked actions, and composite scores with a policy hash for auditing. Inspect market structure: firing structural events, expected asymmetry, distance to next triggers and key structural levels. Check trading playbook status: which rule-based setups are firing, structure-gate verdicts, cooldown state and why other setups do not match. Evaluate a hypothetical position against portfolio-aware caps and get allowed status, size caps and reason codes. All tools are read-only and place no orders.
When to use it
Use it when an assistant helps with BTC or ETH trading decisions and should check risk permissions before proposing or sizing a position, or when you want structural and playbook context alongside the risk policy. It suits spot, perpetual futures and DeFi borrowing analysis rather than order execution.
Requirements
Remote use needs no install or API key: connect to the hosted Streamable HTTP endpoint as a custom connector. The keyed stdio package needs Node.js and a RISKSTATE_API_KEY environment variable; RISKSTATE_API_URL is optional. Network access to the RiskState API is required, with a rate limit of 60 requests per minute per key.
Before you install
The server is read-only and places no orders, but its output is trading risk guidance, not financial advice, and it covers only BTC/USD and ETH/USD. The keyed package requires a RISKSTATE_API_KEY secret, which should be kept out of shared configuration. Optional wallet_address and protocol parameters send DeFi position details to the remote API. Free-tier responses are a public summary; fuller fields need a key.

Installation

In SourceWeft

  1. Open RiskState — Crypto Risk Engine in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Web executable via Streamable HTTP. Remote servers run from the web runtime once configured in a workspace.

Use with an agent

Paste this prompt into Claude Code, Codex, Cursor or another agent — or into SourceWeft chat. The agent reads this server's install guide, shows you its publisher, endpoint and sign-in, and adds it to your client once you agree. Keys never go into a command.

Read https://sourceweft.com/mcp/ai.riskstate%2Fmcp/install.md and connect the MCP server it describes to my client. Before changing any config, show me its publisher, endpoint and sign-in method and wait for my OK. Never put an API key in a command or in a file I would commit; ask me where it should come from.

Read the install guide the agent follows

Other MCP clients

Add this to your client's mcpServers config.

{
  "mcpServers": {
    "riskstate-crypto-risk-engine": {
      "type": "http",
      "url": "https://api.riskstate.ai/mcp"
    }
  }
}

README

RiskState MCP Server

MCP server for RiskState — pre-trade risk permissions for BTC/USD and ETH/USD. Spot, perpetual futures (perps), and DeFi borrowing aware.

Your system asks: "How much can I risk right now?" RiskState answers with: policy level, max exposure, leverage limits, blocked actions — computed from 30+ real-time signals.

Two ways to use RiskState over MCP

1. Remote connector — no install, no API key. RiskState runs a hosted MCP server (Streamable HTTP) with a free public tier:

https://api.riskstate.ai/mcp

Add it as a custom connector in Claude or ChatGPT, then just ask what the risk state of BTC is. It exposes three read-only tools — get_risk_state, get_market_structure, get_playbook_status — covering all three engines, and is listed on the official MCP registry as ai.riskstate/mcp.

Responses are the free public summary: the same altitude as the public visualizer. policy_hash, composite subscores, positioning and macro detail need a key.

2. This package — stdio, keyed, full response. Use it when you want the complete audited payload in a local agent, or to pin a version in your own toolchain. It needs a RISKSTATE_API_KEY and returns everything your key is entitled to. That is what the rest of this README covers.

Tools

Four read-only tools, one per question you might ask before a trade:

ToolAnswersEndpointKey
get_risk_policyHow much exposure is allowed?POST /v1/risk-stateyes
get_market_structureAre we near a structural inflection?POST /v1/market-structureyes
get_playbook_statusIs a setup actionable right now?GET /api/playbook-datano
check_tradeWould THIS position be allowed?POST /v2/portfolio-risk-stateyes

get_risk_policy returns:

FieldDescription
policy_level5 levels: BLOCK_SURVIVAL, BLOCK_DEFENSIVE, CAUTIOUS, GREEN_SELECTIVE, GREEN_EXPANSION
max_size_pctMaximum position size as % of portfolio (0-100)
leverage_maxMaximum allowed leverage multiplier
allowed_actionsWhat the agent CAN do at this policy level
blocked_actionsWhat the agent CANNOT do
confidence_scoreSignal agreement x data quality (0-1)

check_trade evaluates a hypothetical book — send the position you are considering plus anything you already hold, since the caps are portfolio-aware. It returns per position whether it is allowed, the size cap in percent and dollars, and reason_codes when it is not. Those are blocking; advisories are informational and do not affect allowed. It places no orders.

get_playbook_status reports a setup as actionable only when its conditions match, no engine vetoed it, and it is not in alert cooldown. Setups that match but already alerted are counted separately, so an agent polling this tool does not act on the same signal twice.

Why there are no write tools

There is no update_policy, no set_limit, no exception management — and there will not be. The premise of RiskState is that the system being governed cannot move its own limits. Every decision is hashed (policy_hash) so it can be audited afterwards against the inputs that produced it; a tool that let the caller rewrite the policy would make that hash meaningless and the audit trail decorative.

So the lifecycle here deliberately lives on one side: the engine computes, the agent reads and complies. check_trade is the closest thing to a dynamic per-trade operation, and it is still read-only — it answers "would this be allowed", never "allow this".

The API aggregates 9+ real-time data sources server-side. See API docs for details.

What this wrapper does (and doesn't)

This is a thin wrapper — it translates MCP tool calls into REST API requests and returns the response. All computation (scoring, policy engine, data ingestion) happens server-side.

This wrapper adds:

  • MCP protocol compliance (stdio transport for Claude Desktop/Code)
  • Input validation via Zod schemas
  • Human-readable policy summary prepended to responses
  • Specific error messages (auth, rate limit, timeout) for agent recovery

This wrapper does NOT:

  • Cache responses (the API has 60s server-side cache)
  • Perform any scoring or computation locally
  • Guarantee response schema stability (follows API versioning)

Installation

bash
npm install @riskstate/mcp-server

Configuration

Environment Variables

VariableRequiredDescription
RISKSTATE_API_KEYYesAPI key from riskstate.ai (free during beta)
RISKSTATE_API_URLNoCustom API base URL (default: https://api.riskstate.ai)

Claude Desktop

Add to ~/.config/Claude/claude_desktop_config.json:

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

Claude Code

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

Set the API key in your environment:

bash
export RISKSTATE_API_KEY=your-api-key

Global install (alternative)

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

Usage

The four tools are listed above. get_risk_policy takes:

Parameters

ParameterTypeRequiredDescription
asset"BTC" | "ETH"YesAsset to analyze
wallet_addressstringNoDeFi wallet for on-chain position data
protocol"spark" | "aave"NoLending protocol (default: spark)
include_detailsbooleanNoInclude full breakdown (subscores, macro, risk flags)

Example Response

json
{  "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  }}

How Agents Should Use This

Call get_risk_policy before every trade:

  1. If policy_level starts with BLOCK → do not open new positions
  2. Use max_size_pct to cap position sizing
  3. Check blocked_actions before executing
  4. Re-query after ttl_seconds (60s cache)

For a sized position, check_trade collapses steps 2-3 into one call: send the position you intend to open along with what you already hold, and read allowed plus reason_codes. Prefer it over re-deriving the cap yourself, since the caps are portfolio-aware and a position that passes in isolation can still breach concentration once aggregated.

get_market_structure and get_playbook_status are context, not permission. Neither one authorises a trade — only the risk policy does. Use them to decide whether a trade is worth proposing, then get_risk_policy / check_trade to learn how much of it you are allowed.

Limitations

  • v1 scope: BTC/USD and ETH/USD only (USD-denominated assessment). More assets planned.
  • Markets: Spot, perpetual futures, and DeFi borrowing. Same response — interpretation differs by market (see API docs).
  • Protocols: Spark and Aave V3 only for DeFi position data.
  • Rate limit: 60 requests/minute per API key.
  • Latency: ~1-3s per request (9+ upstream data source aggregation).
  • Tested with: Claude Desktop, Claude Code. Should work with any MCP-compatible client.

Links

License

MIT

Source: README.md at commit d4773c8

Tools

3

get_risk_state

Get BTC/ETH risk state

Current risk state of Bitcoin (BTC) or Ethereum (ETH): 5-level risk policy (BLOCK to GREEN) with max position size, leverage limit, direction bias and allowed/blocked actions, plus composite score (0-100), structural and tactical scores, market regime (BULL/SIDEWAYS/BEAR), volatility regime, cycle phase and macro state. Computed from 9+ real-time data sources (price, funding, RSI, MVRV, ETF flows, on-chain, macro). Use whenever the user asks how BTC or ETH is doing, whether it is a good time to buy/sell/hold, or how much risk to take.

Parametersasset

get_market_structure

Get BTC/ETH market structure

Market Structure Engine view for BTC or ETH: validated structural events firing now (breakouts, breakdowns, cycle bottom/top, funding resets), expected asymmetry, distance to the next bullish/bearish triggers, key structural levels (ATH, 200W MA, 180d range) and a friction map of confluence-scored support/resistance walls between spot and the triggers. Use for questions about levels, support/resistance, breakouts or what would change the picture.

Parametersasset

get_playbook_status

Get trading playbook status

Trading Playbook Engine status: the registry of rule-based trade setups (playbooks) for BTC and ETH and which ones are firing right now, with structure-gate verdicts, cooldown state and why non-firing setups do not match (failed predicates with live market readings). Strategy-level only — no prices, sizes or portfolio data. Use for questions about active trade setups or what the playbooks are watching.

Takes no parameters.

Version history

1
  1. v1.0.1LatestSep 16, 2026

Score

100% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 daysRequired25 pts
  • Auth declaredRequired10 pts
  • Tools listedRequired15 pts
  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts