Market Structure Engine

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

What it gives you

• 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 a state_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.

Getting a key

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

Install

# TypeScript / Node
npm install @riskstate/market-structure-engine

# Python
pip install riskstate-market-structure

Quickstart — TypeScript

import { 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}`);
}

Quickstart — Python

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")}')

Develop offline (no key)

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";

Examples

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

Response shape (summary)

{
  "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, "...": "..." },
  "structure_hash": "…", "state_hash": "…",
  "structure_version": "…", "api_version": "…", "timestamp": "…",
  "data_sources": { "onchain": "coinmetrics (…)", "...": "…" }
}

Full, exact types in src/types.ts.

Notes & limits

• On-chain fields are BTC-only. For "ETH", mvrv/nupl/exchange-netflow are null and the read leans on price structure, regime, and macro.
• Errors: 400 invalid asset/body · 401 bad key · 429 rate limit (retry after retry_after_seconds) · 503 upstream momentarily unavailable (retry after Retry-After; the engine already retries once internally).
• Not advice. This is risk/structure information, USD-denominated. You own the trade.

License

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.