Is BTC/USD or ETH/USD near a structural inflection? A read-only HTTP engine that emits structural events — cycle bottoms/tops, extreme-fear reversals, funding resets, failed-breakout fades — plus a live structural map (breakout / breakdown triggers, nearest major top and support) and a governed playbook.
This repository is the open integration kit: a typed client (TypeScript + Python), the full response types, runnable examples, and a sample fixture so you can build offline before you have a key. The engine itself runs server-side.
Part of RiskState — composable, pre-trade infrastructure for crypto (BTC/USD, ETH/USD). RiskState is three independent engines, each usable on its own:
Engine Role Answers Repo Risk Engine Governor how much is allowed? docs · MCP ▸ Market Structure Engine (this repo) Navigator are we near an inflection? you are here Trading Playbook Engine Strategist is there a setup I trade? trading-playbook-engine Compose them and you get a complete pre-trade question — what is the setup, is the terrain right, and how much is permitted — but each stands alone.
Live viewer: https://api.riskstate.ai/structure · Docs: https://riskstate.ai/docs/structure-engine
- Structural events — each with a direction, tier, confidence, a regime gate
(
PASS/FAIL/WEAK/EXEMPT), evidence, and an honest caveat. - Structural map — live price in context: breakout/breakdown triggers, nearest all-time-high and 200-week-MA, drawdown from ATH.
- Governed playbook — an action (
ACCUMULATE/BUY/FADE/REDUCE/STAND_ASIDE/WAIT), a deployment ladder, stop reference, and invalidations — sized as a fraction of the RiskState governor's cap, never a dollar amount. - Audit trail — a
structure_hash(per-response integrity) and astate_hash(discrete-state dedup), so identical inputs reproduce identical output.
The engine is honest by construction: every event carries its in-sample caveat. It is probabilistic asymmetry, not a price oracle.
/v1/market-structure is authenticated. Request a key from the home page
— email only, free during beta. The endpoint is server-side only (keys must
never ship in a browser); call it from your backend, agent, or job.
# TypeScript / Node
npm install @riskstate/market-structure-engine
# Python
pip install riskstate-market-structureimport { MarketStructureClient } from "@riskstate/market-structure-engine";
const client = new MarketStructureClient({ apiKey: process.env.RISKSTATE_API_KEY! });
const s = await client.get("BTC");
console.log(s.headline); // e.g. "BUYABLE FEAR"
console.log(s.asymmetry.label); // e.g. "POSITIVE"
for (const e of s.events) {
console.log(`${e.event} [${e.regime_gate}] conf=${e.confidence} validated=${e.validated}`);
}from riskstate_market_structure import MarketStructureClient
import os
client = MarketStructureClient(api_key=os.environ["RISKSTATE_API_KEY"])
s = client.get("BTC")
print(s["headline"]) # e.g. "BUYABLE FEAR"
print(s["asymmetry"]["label"]) # e.g. "POSITIVE"
for e in s["events"]:
print(f'{e["event"]} [{e["regime_gate"]}] conf={e["confidence"]} validated={e.get("validated")}')fixtures/sample-btc.json is a complete, illustrative response. Point the client
at it (TS) or load it directly to build your rendering / alerting before you have a
key:
import sample from "@riskstate/market-structure-engine/fixtures/sample-btc.json";| Example | What it shows |
|---|---|
examples/ts/01-quickstart.ts / python/01_quickstart.py |
Pull the state, print headline + events |
examples/ts/02-breakout-alert.ts / python/02_breakout_alert.py |
Watch the structural map; alert when price approaches the breakout/breakdown trigger |
examples/ts/03-log-transitions-csv.ts / python/03_log_transitions_csv.py |
Log structural-state transitions (keyed by state_hash) to CSV for your own track record |
Full, exact types in src/types.ts.
Both dormant and friction_levels are typed optional, so a response from an
older deployment still type-checks — null-check before reading them. Neither is
included in state_hash: proximity to a trigger moves with price, while the
discrete structural state does not. And friction_levels is derived price
structure, not validated events — no win-rate claim attaches to it.
- On-chain fields are BTC-only. For
"ETH",mvrv/nupl/exchange-netflow arenulland the read leans on price structure, regime, and macro. - Errors:
400invalid asset/body ·401bad key ·429rate limit (retry afterretry_after_seconds) ·503upstream momentarily unavailable (retry afterRetry-After; the engine already retries once internally). - Not advice. This is risk/structure information, USD-denominated. You own the trade.
MIT — the client and examples are free to use and modify. The engine (scoring, structure logic, track record) runs server-side and is not included.
{ "asset": "BTC", "headline": "BUYABLE FEAR", "subhead": "Fear dislocation, regime gate clear · expected asymmetry: positive", "watch": { "breakout": 71200, "breakdown": 58400 }, "events": [ /* StructureEvent[] — each with `validated` true/false — see src/types.ts */ ], "structural_map": { /* price in context, 40d triggers, 180d range, ATH + 200W MA */ }, "asymmetry": { "label": "POSITIVE", "rationale": "..." }, "risk_overlay": { "market_regime": "RANGE", "sustained_bear": false, "...": "..." }, // api_version 0.2.0+ — roster events NOT firing, and what each would need "dormant": [ { "event": "Cycle Bottom Candidate", "condition": "MVRV < 1.0", "current": "MVRV 1.4703", "distance": "0.4703 above" } ], // api_version 0.3.0+ — confluence-scored price walls between spot and the triggers "friction_levels": { "spot": 77949, "battling": { /* zone containing spot, if any */ }, "above": [ { "zone_low": 78720.66, "zone_high": 79488, "distance_pct": 1.6, "strength": "medium", "score": 3, "components": [ { "label": "20D MA", "level": 78720.66 } ] } ], "below": [ /* … */ ], "summary": "2 walls to the 40d-high trigger · heaviest 81,500–82,842" }, "structure_hash": "…", "state_hash": "…", "structure_version": "…", "api_version": "…", "timestamp": "…", "data_sources": { "onchain": "coinmetrics (…)", "...": "…" } }