Documentation

Volatility regime API for crypto. REST + WebSocket. Base URL: https://api.amaneki.com/v1

Quickstart

curl https://api.amaneki.com/v1/regime/btcusdt

No key needed for the free tier (60 req/min per IP). For higher limits, persistent key, and webhook alerts, get a Pro key — pricing.

New to the API? Walk through the 10-minute quickstart (curl → Python SDK → Discord webhook) before scanning this reference.

Prefer a live sandbox? Interactive API reference — Scalar, rendered from the same /openapi.json you'd feed to openapi-generator, Stainless, or Speakeasy to auto-build a typed client.

Clients

Three examples of the same call — pick your language:

curl -H "Authorization: Bearer ak_..." \
  https://api.amaneki.com/v1/regime/btcusdt?timeframe=15m

# Python (pip install amaneki)
from amaneki import Client
c = Client(api_key="ak_...")
print(c.get_regime("btcusdt", timeframe="15m"))

// JavaScript / TypeScript — plain fetch
const r = await fetch(
  "https://api.amaneki.com/v1/regime/btcusdt?timeframe=15m",
  { headers: { Authorization: "Bearer ak_..." } }
);
console.log(await r.json());

// Go
req, _ := http.NewRequest("GET",
  "https://api.amaneki.com/v1/regime/btcusdt?timeframe=15m", nil)
req.Header.Set("Authorization", "Bearer ak_...")
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()
io.Copy(os.Stdout, resp.Body)

Authentication

Send your key as a Bearer token:

curl -H "Authorization: Bearer ak_..." https://api.amaneki.com/v1/regime/btcusdt

Or as a header:

curl -H "X-API-Key: ak_..." https://api.amaneki.com/v1/regime/btcusdt

Endpoints — Regime

GET /v1/regime/{symbol}

Current regime for one (symbol, timeframe).

{
  "symbol": "btcusdt",
  "timeframe": "1m",
  "regime": "normal",
  "z_vol": -0.83,
  "realized_vol": 0.23,
  "baseline_vol": 0.29,
  "close": 74915.42,
  "last_update_ms": 1776324240000,
  "seconds_in_state": 18420,
  "last_transition": null
}

GET /v1/regime/{symbol}/custom

Re-run the FSM against the in-memory feature window with caller-supplied thresholds. Stateless; doesn't affect the broadcast stream or the preset detector.

curl "https://api.amaneki.com/v1/regime/btcusdt/custom?high_enter=2.5&low_enter=-2.0&enter_k=3"

GET /v1/regime/{symbol}/history

Past regime transitions. Without from_ms/to_ms, returns the in-memory ring buffer (~last 1024 transitions since process start). With either, queries Postgres for the full archive.

curl "https://api.amaneki.com/v1/regime/btcusdt/history?timeframe=15m&limit=200"

GET /v1/regime/{symbol}/matrix

3×3 transition probability matrix (rows: from-regime, cols: to-regime) over the archive window. Diagonal reports persistence.

curl "https://api.amaneki.com/v1/regime/btcusdt/matrix?timeframe=15m&lookback_days=30"

GET /v1/regime/{symbol}/durations

Empirical duration distribution per regime (seconds spent before exiting). Returns median/mean/p25/p75/p95 per regime label.

curl "https://api.amaneki.com/v1/regime/btcusdt/durations?timeframe=15m"

GET /v1/regime/{symbol}/state_at

Regime label at an arbitrary millisecond timestamp. Resolves by scanning the transition archive.

curl "https://api.amaneki.com/v1/regime/btcusdt/state_at?timeframe=15m&ts_ms=1776324240000"

GET /v1/regime/{symbol}/explain

Why the FSM is in its current state: which threshold crossed, which counter tripped, how many bars since the last flip. Useful for debugging "why didn't this transition fire?"

curl "https://api.amaneki.com/v1/regime/btcusdt/explain?timeframe=15m"

GET /v1/regime/{symbol}/forecast

Next-bar log-return distribution conditioned on the current regime. Mean, std, and quantiles computed from the history archive.

curl "https://api.amaneki.com/v1/regime/btcusdt/forecast?timeframe=15m"

GET /v1/regime/{symbol}/impact

Realized return distribution following transitions into a target regime, at fixed horizons (1h, 4h, 24h). For each past transition, price at t+h is compared to price at t. Returns sample_size plus horizons with median, mean, std, p05/p25/p75/p95.

Gets more useful over time: every new transition adds a sample. On a fresh symbol or a rare target regime, sample_size can be 0. Always check the field before trusting the stats.

curl "https://api.amaneki.com/v1/regime/btcusdt/impact?to=high&timeframe=15m&lookback_days=60"

GET /v1/regime/lead-lag

Do transitions in leader precede matching transitions in follower? For each leader event into the target regime, scans forward up to max_lag_minutes for a follower event of the same kind. Returns hit_rate plus median/mean/p25/p75 of the matched lags in minutes.

Data-accumulation-based. A 7-day lookback on a quiet pair will match almost nothing. Prefer lookback_days ≥ 60 and read matched before trusting hit_rate.

curl "https://api.amaneki.com/v1/regime/lead-lag?leader=btcusdt&follower=ethusdt&to=high&timeframe=15m&lookback_days=60&max_lag_minutes=60"

Endpoints — Consensus & Market Context

GET /v1/consensus/{symbol}

Majority vote across Binance, Coinbase and Bybit. Each venue computes its own regime from its own klines; consensus reports which venues agreed. Useful for catching single-venue wicks.

curl "https://api.amaneki.com/v1/consensus/btcusdt?timeframe=15m"

GET /v1/consensus/{symbol}/multi-tf

Pro Plus only. Cross-venue consensus evaluated on every supported timeframe in a single call. Use this to check whether a signal is isolated to one TF or confirmed top-down.

curl -H "Authorization: Bearer ak_..." \
  "https://api.amaneki.com/v1/consensus/btcusdt/multi-tf"

GET /v1/correlation/market

Mean pairwise Pearson correlation across every tracked symbol at the given timeframe, over the last window bars. Stateless regime label (tight ≥ 0.8, dispersed ≤ 0.3, mixed in between).

curl "https://api.amaneki.com/v1/correlation/market?timeframe=15m&window=60"

GET /v1/correlation/{symbol}

Beta of the symbol's log-returns against a reference (default BTC) plus correlation to each peer.

curl "https://api.amaneki.com/v1/correlation/ethusdt?timeframe=15m"

GET /v1/iv-gap/{symbol}

Realized vs implied vol for BTC or ETH. RV is our annualized 1-minute vol; IV is the Deribit DVOL (30-day option-implied). Gap = IV − RV. Negative gap means spot is realizing faster than options imply.

curl "https://api.amaneki.com/v1/iv-gap/btcusdt"

GET /v1/funding/{symbol}

Current perpetual funding rate and recent history. Source: the symbol's primary venue.

curl "https://api.amaneki.com/v1/funding/btcusdt"

GET /v1/sizing/{symbol}

Vol-targeted position size helper. Given a target annualized portfolio vol and an equity figure, returns the notional implied by the symbol's current realized vol.

curl "https://api.amaneki.com/v1/sizing/btcusdt?timeframe=15m&target_vol=0.20&equity=100000"

GET /v1/badge/{symbol}.svg

Shields.io-style SVG badge of the current regime. Drop into a README or dashboard.

<img src="https://api.amaneki.com/v1/badge/btcusdt.svg?timeframe=15m" />

POST /v1/backtest

Replay a simple rule against the in-memory feature ring (~1024 bars per series). Returns per-trade detail + summary stats. Requires an API key.

curl -X POST https://api.amaneki.com/v1/backtest \
  -H "Authorization: Bearer ak_..." \
  -H "Content-Type: application/json" \
  -d '{"symbol":"btcusdt","timeframe":"15m","rule":"long_low_exit_normal"}'

Rules: long_low_exit_normal, short_high_exit_normal, avoid_high. Optional thresholds overrides the preset.

GET /v1/symbols, /v1/timeframes, /v1/presets

Lists. Public, no key needed.

curl https://api.amaneki.com/v1/symbols

WS /v1/stream

Push every regime transition. Browsers can pass the key via query string (no custom headers): wss://api.amaneki.com/v1/stream?api_key=ak_...

{
  "type": "regime_transition",
  "symbol": "BTCUSDT",
  "timeframe": "5m",
  "ts_ms": 1776324300000,
  "from": "normal",
  "to": "high",
  "z_vol": 3.21,
  "close": 74900.12
}

Endpoints — Account

POST /v1/feedback

Submit a verdict on a past transition. Used to surface false-positive patterns back into calibration.

curl -X POST https://api.amaneki.com/v1/feedback \
  -H "Authorization: Bearer ak_..." \
  -H "Content-Type: application/json" \
  -d '{"symbol":"btcusdt","timeframe":"15m","ts_ms":1776324300000,"verdict":"false_positive","note":"wick"}'

GET /v1/feedback

List feedback submitted by this key.

curl -H "Authorization: Bearer ak_..." https://api.amaneki.com/v1/feedback

POST /v1/me/rotate-key

Issue a new key and invalidate the current one. The response is the only place the new secret is shown.

curl -X POST -H "Authorization: Bearer ak_..." \
  https://api.amaneki.com/v1/me/rotate-key

GET /v1/me/events

Audit events scoped to this key: issued, rotated, rate-limit hits, webhook deliveries.

curl -H "Authorization: Bearer ak_..." https://api.amaneki.com/v1/me/events

GET /v1/me/usage

Per-endpoint request counts for the current billing period.

curl -H "Authorization: Bearer ak_..." https://api.amaneki.com/v1/me/usage

GET /v1/me/allowlist, PUT /v1/me/allowlist

Pro Plus. Restrict this key to a subset of symbols. PUT with {"symbols": ["btcusdt","ethusdt"]}; empty list means "all tracked symbols".

curl -X PUT https://api.amaneki.com/v1/me/allowlist \
  -H "Authorization: Bearer ak_..." \
  -H "Content-Type: application/json" \
  -d '{"symbols":["btcusdt","ethusdt"]}'

GET/PUT/DELETE /v1/presets/custom

Save named threshold presets on your account. PUT body: {"name":"tight","high_enter":2.0,"low_enter":-1.8,"enter_k":3,...}. GET returns your saved presets; DELETE with ?name=tight removes one.

curl -X PUT https://api.amaneki.com/v1/presets/custom \
  -H "Authorization: Bearer ak_..." \
  -H "Content-Type: application/json" \
  -d '{"name":"tight","high_enter":2.0,"low_enter":-1.8,"enter_k":3}'

Endpoints — Webhooks (Pro Plus)

POST /v1/webhooks

Register an outbound webhook. Optional filters: symbols, timeframes, to_regimes.

curl -X POST https://api.amaneki.com/v1/webhooks \
  -H "Authorization: Bearer ak_..." \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your.app/regime",
    "symbols": ["btcusdt", "ethusdt"],
    "timeframes": ["5m", "15m"],
    "to_regimes": ["high"],
    "batch_window_seconds": 0,
    "format": "json"
  }'

Response includes a one-time signing_secret. Each delivery carries an HMAC-SHA256 signature in X-Amaneki-Signature: t=<unix>,v1=<hex> over {t}.{body} — same scheme as Stripe.

GET /v1/webhooks

List subscriptions registered by this key.

curl -H "Authorization: Bearer ak_..." https://api.amaneki.com/v1/webhooks

DELETE /v1/webhooks/{id}

Remove a subscription. Returns 204 on success.

curl -X DELETE -H "Authorization: Bearer ak_..." \
  https://api.amaneki.com/v1/webhooks/wh_01HXYZ...

Endpoints — Billing

POST /v1/billing/checkout

Create a Stripe Checkout session. Response includes url; redirect the user there.

curl -X POST https://api.amaneki.com/v1/billing/checkout \
  -H "Content-Type: application/json" \
  -d '{"tier":"pro","billing_cycle":"monthly","trial_days":7,"email":"[email protected]"}'

GET /v1/billing/key?session_id=...

Retrieve the provisioned API key for a completed Checkout session. One-shot: the key is only returned on first fetch. Call this from your success page.

curl "https://api.amaneki.com/v1/billing/key?session_id=cs_live_..."

POST /v1/billing/webhook

Stripe → Amaneki events. Not for customer use.

Endpoints — Infra

GET /v1/health

Liveness. Returns 200 if the process is up.

curl https://api.amaneki.com/v1/health

GET /v1/health/deep

Readiness. Pings the database, the Binance feed, and confirms at least one series has ticked in the last 60 seconds.

curl https://api.amaneki.com/v1/health/deep

GET /v1/metrics

Prometheus text format. Token-gated; for operators, not customers.

Errors

Python SDK

pip install amaneki

Source at github.com/Nakammura/pqesd1, on PyPI as amaneki.

from amaneki import Client

c = Client(api_key="ak_...")
snap = c.get_regime("btcusdt", timeframe="5m")
print(snap.regime, snap.z_vol, snap.seconds_in_state)

cs = c.get_consensus("btcusdt", timeframe="15m")
print(cs.consensus, f"{cs.agreed}/{cs.available}")

r = c.run_backtest("btcusdt", timeframe="15m", rule="long_low_exit_normal")
print(r.n_trades, r.total_return)

for t in c.get_history("btcusdt", from_ms=1776000000000):
    print(t.ts_ms, t.from_regime, "→", t.to_regime)

Calibration

Each symbol is calibrated independently against 180 days of its own 1-minute klines — 2,304 threshold combinations, Pareto-front selection on the (F1, alerts/day) plane. Detection lag median ~20 minutes regardless of symbol.

Macro-F1 against the smoothed percentile ground truth, by symbol and preset:

Honest caveats: regime detection against a smoothed percentile ground truth is a noisy problem. Every symbol lands in the 0.37-0.45 band at the balanced preset. Anyone advertising F1 > 0.9 for a regime task is leaking future information into the labels.

Status

amaneki.com/status shows live health.