RiskState

Motor determinista de gobernanza de riesgos y políticas para agentes de trading de criptomonedas. Política de 5 niveles con dimensionamiento de posiciones, límites de apalancamiento y bloqueo de operaciones. BTC + ETH. Más de 9 fuentes de datos en tiempo real.

GitHub

Prueba este MCPPatrocinado

Documentación

Servidor MCP de RiskState

Servidor MCP para RiskState — permisos de riesgo pre-trade para BTC/USD y ETH/USD. Compatible con spot, futuros perpetuos (perps) y préstamos DeFi.

Tu sistema pregunta: "¿Cuánto puedo arriesgar ahora mismo?" RiskState responde con: nivel de política, exposición máxima, límites de apalancamiento, acciones bloqueadas — calculados a partir de más de 30 señales en tiempo real.

Dos formas de usar RiskState a través de MCP

1. Conector remoto — sin instalación, sin clave API. RiskState ejecuta un servidor MCP alojado (HTTP Streamable) con un nivel gratuito público:

https://api.riskstate.ai/mcp

Agrégalo como conector personalizado en Claude o ChatGPT, y simplemente pregunta cuál es el estado de riesgo de BTC. Expone tres herramientas de solo lectura — get_risk_state, get_market_structure, get_playbook_status — que cubren los tres motores, y está listado en el registro oficial de MCP como ai.riskstate/mcp.

Las respuestas son el resumen público gratuito: la misma altitud que el visualizador público. policy_hash, subpuntuaciones compuestas, detalle de posicionamiento y macro requieren una clave.

2. Este paquete — stdio, con clave, respuesta completa. Úsalo cuando quieras el payload auditado completo en un agente local, o para fijar una versión en tu propio flujo de herramientas. Requiere una RISKSTATE_API_KEY y devuelve todo a lo que tu clave tiene derecho. Eso es lo que cubre el resto de este README.

Herramientas

Cuatro herramientas de solo lectura, una por cada pregunta que podrías hacer antes de una operación:

Herramienta	Responde	Endpoint	Clave
`get_risk_policy`	¿Cuánta exposición está permitida?	`POST /v1/risk-state`	sí
`get_market_structure`	¿Estamos cerca de una inflexión estructural?	`POST /v1/market-structure`	sí
`get_playbook_status`	¿Es una configuración accionable ahora mismo?	`GET /api/playbook-data`	no
`check_trade`	¿Se permitiría ESTA posición?	`POST /v2/portfolio-risk-state`	sí

get_risk_policy devuelve:

Campo	Descripción
`policy_level`	5 niveles: BLOCK_SURVIVAL, BLOCK_DEFENSIVE, CAUTIOUS, GREEN_SELECTIVE, GREEN_EXPANSION
`max_size_pct`	Tamaño máximo de posición como % del portafolio (0-100)
`leverage_max`	Multiplicador máximo de apalancamiento permitido
`allowed_actions`	Lo que el agente PUEDE hacer en este nivel de política
`blocked_actions`	Lo que el agente NO PUEDE hacer
`confidence_score`	Acuerdo de señales x calidad de datos (0-1)

check_trade evalúa un libro hipotético — envía la posición que estás considerando más cualquier cosa que ya tengas, ya que los límites son conscientes del portafolio. Devuelve por posición si está permitida, el límite de tamaño en porcentaje y dólares, y reason_codes cuando no lo está. Esos son bloqueantes; advisories son informativos y no afectan a allowed. No coloca órdenes.

get_playbook_status reporta una configuración como accionable solo cuando sus condiciones coinciden, ningún motor la vetó, y no está en período de enfriamiento de alertas. Las configuraciones que coinciden pero ya alertaron se cuentan por separado, para que un agente que consulta esta herramienta no actúe sobre la misma señal dos veces.

Por qué no hay herramientas de escritura

No hay update_policy, no hay set_limit, no hay gestión de excepciones — y no las habrá. La premisa de RiskState es que el sistema gobernado no puede mover sus propios límites. Cada decisión se hashea (policy_hash) para que pueda auditarse posteriormente contra los insumos que la produjeron; una herramienta que permitiera al llamante reescribir la política haría que ese hash perdiera sentido y que la pista de auditoría fuera decorativa.

Así que el ciclo de vida aquí vive deliberadamente en un solo lado: el motor calcula, el agente lee y cumple. check_trade es lo más parecido a una operación dinámica por operación, y sigue siendo de solo lectura — responde "¿se permitiría esto?", nunca "permite esto".

La API agrega 9+ fuentes de datos en tiempo real del lado del servidor. Consulta documentación de API para más detalles.

Qué hace este envoltorio (y qué no)

Este es un envoltorio delgado — traduce llamadas de herramientas MCP en solicitudes REST API y devuelve la respuesta. Todo el cálculo (puntuación, motor de políticas, ingesta de datos) ocurre del lado del servidor.

Este envoltorio añade:

Cumplimiento del protocolo MCP (transporte stdio para Claude Desktop/Code)
Validación de entrada mediante esquemas Zod
Resumen de política legible para humanos antepuesto a las respuestas
Mensajes de error específicos (autenticación, límite de tasa, tiempo de espera) para recuperación del agente

Este envoltorio NO:

Almacena en caché respuestas (la API tiene caché de 60s del lado del servidor)
Realiza puntuación o cálculo localmente
Garantiza estabilidad del esquema de respuesta (sigue el versionado de la API)

Instalación

npm install @riskstate/mcp-server

Configuración

Variables de entorno

Variable	Requerida	Descripción
`RISKSTATE_API_KEY`	Sí	Clave API de riskstate.ai (gratuita durante beta)
`RISKSTATE_API_URL`	No	URL base de API personalizada (predeterminada: `https://api.riskstate.ai`)

Claude Desktop

Añade a ~/.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

Configura la clave API en tu entorno:

export RISKSTATE_API_KEY=your-api-key

Instalación global (alternativa)

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

Uso

Las cuatro herramientas se listan arriba. get_risk_policy toma:

Parámetros

Parámetro	Tipo	Requerido	Descripción
`asset`	`"BTC"` \| `"ETH"`	Sí	Activo a analizar
`wallet_address`	string	No	Billetera DeFi para datos de posición en cadena
`protocol`	`"spark"` \| `"aave"`	No	Protocolo de préstamo (predeterminado: spark)
`include_details`	boolean	No	Incluir desglose completo (subpuntuaciones, macro, banderas de riesgo)

Ejemplo de respuesta

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

Cómo deberían usar esto los agentes

Llama a get_risk_policy antes de cada operación:

Si policy_level comienza con BLOCK → no abrir nuevas posiciones
Usa max_size_pct para limitar el tamaño de la posición
Verifica blocked_actions antes de ejecutar
Vuelve a consultar después de ttl_seconds (caché de 60s)

Para una posición dimensionada, check_trade combina los pasos 2-3 en una sola llamada: envía la posición que pretendes abrir junto con lo que ya tienes, y lee allowed más reason_codes. Prefiérela sobre re-derivar el límite tú mismo, ya que los límites son conscientes del portafolio y una posición que pasa de forma aislada aún puede violar la concentración una vez agregada.

get_market_structure y get_playbook_status son contexto, no permiso. Ninguna de las dos autoriza una operación — solo la política de riesgo lo hace. Úsalas para decidir si vale la pena proponer una operación, luego get_risk_policy / check_trade para saber cuánto de ella te está permitido.

Limitaciones

Alcance v1: solo BTC/USD y ETH/USD (evaluación denominada en USD). Se planean más activos.
Mercados: Spot, futuros perpetuos y préstamos DeFi. Misma respuesta — la interpretación difiere según el mercado (consulta documentación de API).
Protocolos: Solo Spark y Aave V3 para datos de posición DeFi.
Límite de tasa: 60 solicitudes/minuto por clave API.
Latencia: ~1-3s por solicitud (agregación de 9+ fuentes de datos upstream).
Probado con: Claude Desktop, Claude Code. Debería funcionar con cualquier cliente compatible con MCP.

Enlaces

Página de inicio: riskstate.ai
Documentación de API: riskstate.ai/docs/api
SKILL.md: agentskills.io

Licencia

MIT