API Reference

Pre-trade risk permissions for BTC/USD and ETH/USD. Spot, perpetual futures (perps), and DeFi borrowing aware.

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.

Endpoint

POST https://riskstate.netlify.app/v1/risk-state

Authentication

All requests require a Bearer token in the Authorization header.

Authorization: Bearer <your_api_key>

Key types

Getting an API key

Request API access from the home page — only an email is required. You'll receive an rs_live_ key via email within minutes. Free during beta.

The 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.

Request

Headers

Body (JSON)

Example requests

Minimal (BTC):

curl -X POST https://riskstate.netlify.app/v1/risk-state \
  -H "Authorization: Bearer $RISKSTATE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"asset": "BTC"}'

Detailed (with scoring breakdown):

curl -X POST https://riskstate.netlify.app/v1/risk-state \
  -H "Authorization: Bearer $RISKSTATE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"asset": "BTC", "include_details": true}'

DeFi monitoring (with wallet + Aave):

curl -X POST https://riskstate.netlify.app/v1/risk-state \
  -H "Authorization: Bearer $RISKSTATE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"asset": "ETH", "wallet": "0xYOUR_WALLET_ADDRESS", "protocol": "aave", "include_details": true}'

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.

Validation

• asset must be "BTC" or "ETH" (case-insensitive) → 400 otherwise
• wallet must match ^0x[a-fA-F0-9]{40}$ if provided → 400 otherwise
• protocol must be "spark" or "aave" (case-insensitive) → 400 otherwise
• reference_time must be a finite number in [new Date('2024-04-20').getTime()/1000, now+86400] if provided → 400 otherwise
• Invalid JSON body → 400
• Core data missing (and allow_degraded not set) → 503 with Retry-After: 30 and body { error, missing, sources, retry_after_seconds, hint }

Determinism contract (v1.2.0+)

The 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.

Response — Minimal (default)

Three blocks: Permissioning, Classification, Auditability.

Permissioning

Classification

Constraints & Flags

Auditability

Response — Detailed (include_details=true)

All minimal fields plus:

Error Responses

Data Sources & Fallback Chain

The endpoint fetches from 15+ external APIs in parallel waves. Binance returns HTTP 451 from Netlify servers, so all Binance data has fallbacks:

The 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.

Known Data Limitations

Binance returns HTTP 451 from Netlify servers. Current CoinGlass tier lacks certain endpoints. These cause permanent fallback states for some fields:

Caching Behavior

• 60-second TTL via Netlify Blobs
• First call: 5–12 seconds (fetches from 15+ external APIs in 5 parallel waves)
• Subsequent calls within 60s: <1 second
• cached: true in response indicates cache hit
• Wallet parameter bypasses cache (DeFi data is personalized)

Action Enums Reference

allowed_actions values

blocked_actions values

binding_constraint.reason_codes values

Risk Flags Reference

Structural Blockers (agent MUST pause)

Context Risks (agent should reduce conviction)

How to Use by Context

The 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.

Spot Trading (BTC/USD or ETH/USD)

You are buying or selling the asset on a spot exchange (Coinbase, Binance Spot, Kraken, Uniswap, CoW Swap).

Key fields:

• max_size_fraction → % of portfolio to deploy. If 0.33, allocate up to 33% of your portfolio to this position.
• direction_bias → LONG_PREFERRED means "buy signal." SHORT_PREFERRED means "don't buy / consider selling." NEUTRAL means "no directional edge."
• structural_blockers → If non-empty, do not buy.
• allowed_actions / blocked_actions → Filter for relevant actions (DCA, WAIT, LIGHT_ACCUMULATION).

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.

Pre-trade workflow:

1. Call the API with {"asset": "BTC"}
2. Check structural_blockers — if non-empty, do not enter
3. Read max_size_fraction — this is your max allocation
4. Check direction_bias — respect the directional guidance
5. Proceed to your exchange and place the spot order

Perpetual Futures (Perps)

You are trading BTC/USDT or ETH/USDT perpetuals on Binance Futures, Hyperliquid, dYdX, Bybit, or similar venues.

Key fields:

• 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.
• direction_bias → Directly actionable: LONG_PREFERRED favors longs, SHORT_PREFERRED favors shorts.
• structural_blockers → If SQUEEZE_RISK is present, do not open leveraged positions — liquidation risk is elevated.

Especially relevant for perps (in detailed response):

• 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.
• positioning.basis_pct → Perp-spot premium. Positive = longs dominant, negative = discount.
• positioning.squeeze_direction → UPSIDE (short squeeze probable) or DOWNSIDE (long squeeze probable).
• positioning.oi_zscore → OI z-score vs. 30 days. >2.0 = excessive leverage in the market.

Margin guide (from max_size_fraction):

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.

Pre-trade workflow (e.g. Hyperliquid):

1. Call the API with {"asset": "BTC", "include_details": true}
2. Check structural_blockers — if SQUEEZE_RISK present, do not open leveraged positions
3. Read max_size_fraction — this is your max notional as % of portfolio
4. Divide by your intended leverage to get max margin
5. Check positioning.funding_percentile — if P>85, longs are paying heavy carry
6. Check positioning.squeeze_direction — if DOWNSIDE, longs are at risk
7. Respect direction_bias for trade direction
8. Place your order on the venue

DeFi Borrowing (Aave, Spark, Morpho)

You borrow stablecoins against BTC or ETH collateral on-chain.

Key fields:

• max_size_fraction → % of collateral to deploy. Accounts for your current health factor.
• max_leverage → Borrowing ratio cap: "0x" (don't borrow), "1x", "1.5x", "2x".
• defi.health_factor → Current health factor (>1 safe, <1.1 danger).
• defi.ltv → Current loan-to-value ratio.
• binding_constraint.source → If "DEFI", your on-chain position is the limiting factor.

Pre-trade workflow:

1. Call the API with {"asset": "ETH", "wallet": "0xYOUR_WALLET", "protocol": "aave"}
2. Check defi.health_factor — if <1.5, prioritize adding collateral
3. If binding_constraint.source === "DEFI", do not increase debt
4. Respect max_leverage for borrowing ratio
5. If structural_blockers contains DEFI_LIQUIDATION_RISK, reduce position immediately

AI Trading Agent Integration

You are building an autonomous trading agent (Hermes, ElizaOS, OpenClaw, AgentKit, custom) that calls the API programmatically.

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.

Binding precedence (evaluation order):

1. risk_flags.structural_blockers — if non-empty, abort new entries
2. exposure_policy.blocked_actions contains NEW_TRADES — abort new entries
3. exposure_policy.reduce_recommended — reduce exposure (not necessarily close all)
4. Size position: max_size_fraction × agent_conviction
5. Respect max_leverage and direction_bias
6. Filter trades through allowed_actions
7. If stale_fields non-empty or data_quality_score < 70 → halve size or abstain
8. policy_level is summary only — do not use for enforcement

Interpretation Guide

Position Sizing

Spot:

position_size = portfolio_value × max_size_fraction × conviction

Perps:

max_notional = portfolio_value × max_size_fraction × conviction
margin = max_notional / leverage

Where conviction is your own confidence factor (0–1), whether human or algorithmic.

Re-consultation Frequency

When to Force-Check

• Before any new position entry
• When policy_level was previously ≤ 2 (check if conditions improved)
• After external events (ETF announcements, Fed meetings, major hacks)