API Documentation

Comprehensive documentation for all public API endpoints

Beliefs & Oracle

GET/api/beliefs

Fetch belief distributions from prediction markets

Retrieves market-implied probability distributions for yearly low prices from Kalshi and/or Polymarket. Returns Metalog v2 fitted distributions with normalized points.

Query Parameters

Name	Type	Required	Default	Description
`asset`	`string`	No	BTC	Asset symbol (BTC or ETH) Example: `BTC`
`source`	`string`	No	kalshi	Data source: "kalshi", "polymarket", or "both" Example: `both`
`spot`	`number`	No	—	Override spot price (USD). If not provided, fetched from Hyperliquid.
`debug`	`string`	No	—	Enable debug output (set to "1" or "true")

Responses

200Success

{
  "kalshi": {
    "min": {
      "metalog": {
        "aCoefficients": [
          0.867,
          7.285,
          4.844
        ],
        "terms": 7,
        "valid": true,
        "isFit": true,
        "lowerBound": 0,
        "upperBound": 92921.5,
        "minPdf": 0.000366
      },
      "points": [
        {
          "price": 60000,
          "probability": 0.37,
          "volume": 6600,
          "openInterest": 22500
        }
      ],
      "kalshiSeriesTicker": "KXBTCMINY"
    }
  },
  "polymarket": {
    "min": {
      "metalog": {
        "aCoefficients": [
          0.867,
          7.285,
          4.844
        ],
        "terms": 7,
        "valid": true,
        "isFit": true,
        "lowerBound": 0,
        "upperBound": 92921.5,
        "minPdf": 0.000366
      },
      "points": [
        {
          "price": 15000,
          "probability": 0.03,
          "volume": 101000,
          "openInterest": 27100
        }
      ],
      "polymarketSlug": "what-price-will-bitcoin-hit-before-2027"
    }
  },
  "aggregated": {
    "min": {
      "metalog": {
        "aCoefficients": [
          0.867,
          7.285,
          4.844
        ],
        "terms": 7,
        "valid": true,
        "isFit": true,
        "lowerBound": 0,
        "upperBound": 92921.5,
        "minPdf": 0.000366
      },
      "points": [
        {
          "price": 15000,
          "probability": 0.03,
          "volume": 0,
          "openInterest": 0
        }
      ]
    }
  },
  "spotPrice": 92921.5,
  "metadata": {
    "source": "both",
    "spotSource": "hyperliquid",
    "asset": "BTC",
    "priceUnit": "USD",
    "timestamp": "2026-01-06T12:00:00Z"
  }
}

503Service unavailable - failed to fetch from requested sources

Examples

Get BTC beliefs from both sources

/api/beliefs?asset=BTC&source=both

Get ETH beliefs from Polymarket only

/api/beliefs?asset=ETH&source=polymarket

GET/api/beliefs/oracle/query

Query belief oracle (quantile, percentile, tail probability)

Query the belief oracle distribution for quantile (probability → price), percentile (price → probability), or tail probability calculations. Supports SIPmath 3.0 format output.

Query Parameters

Name	Type	Required	Default	Description
`price`	`number`	No	—	Price to query (returns percentile and tail probability). Mutually exclusive with prob. Example: `60000`
`prob`	`number`	No	—	Probability to query (returns quantile). Must be between 0 and 1. Mutually exclusive with price. Example: `0.5`
`asset`	`string`	No	BTC	Asset symbol (BTC or ETH)
`format`	`string`	No	summary	Response format: "summary", "full", or "sipmath"
`entity`	`number`	No	—	RNG entity parameter (defaults to deterministic hash)
`varId`	`number`	No	1	RNG varId parameter
`seed3`	`number`	No	0	RNG seed3 parameter
`seed4`	`number`	No	0	RNG seed4 parameter

Responses

200Success

{
  "query": {
    "type": "probability",
    "value": 0.5
  },
  "result": {
    "quantile": 65000
  },
  "metadata": {
    "summary": {
      "asOf": "2026-01-06T12:00:00Z",
      "asset": "BTC",
      "side": "min",
      "sources": [
        {
          "provider": "polymarket",
          "weight": 1,
          "asset": "BTC",
          "side": "min",
          "rawPointCount": 7,
          "normalizedPointCount": 7
        }
      ],
      "metalog": {
        "terms": 7,
        "monotone": true,
        "minPdf": 0.000366,
        "lowerBound": 0,
        "upperBound": 92921.5
      }
    }
  }
}

400Bad request - missing or invalid parameters

{
  "error": "Must provide either price or prob parameter"
}

Examples

Query quantile at 50% probability

/api/beliefs/oracle/query?prob=0.5&asset=BTC&format=sipmath

Query percentile and tail probability for price

/api/beliefs/oracle/query?price=60000&asset=BTC&format=full

Regime Detection

POST/api/regime/detect

Classify market regime

Stateless regime classification endpoint that maps SignalDetector outputs to canonical 4-regime set (CALM, TRENDING, CROWDED, DISLOCATION). Returns raw classification without stabilization.

Request Body

Regime detection request with current sample and optional trail data

{
  "asOf": "2026-01-06T12:00:00Z",
  "asset": "HYPE",
  "sample": {
    "close": 1.5,
    "sigma": 0.5,
    "delta": 0.001,
    "fragilityScore": 50,
    "responseEfficiency": 50,
    "crowdSide": "LONG",
    "warmRatio": 0.9
  },
  "detectorState": "NEUTRAL",
  "trail": [
    {
      "ts": 1704547200000,
      "sigma": 0.4,
      "delta": 0.0008
    },
    {
      "ts": 1704547260000,
      "sigma": 0.5,
      "delta": 0.001
    }
  ]
}

Responses

200Success

{
  "asOf": "2026-01-06T12:00:00Z",
  "asset": "HYPE",
  "regimeRaw": "CALM",
  "confidenceRaw": 0.85,
  "scores": {
    "CALM": 0.7,
    "TRENDING": 0.2,
    "CROWDED": 0.08,
    "DISLOCATION": 0.02
  },
  "signals": {
    "volatility": "LOW",
    "directionality": "FLAT",
    "crowding": "MED",
    "efficiency": "MED"
  },
  "metadata": {
    "shockTriggered": false,
    "detectorState": "NEUTRAL",
    "fragilityScore": 50,
    "responseEfficiency": 50,
    "crowdSide": "LONG",
    "warmRatio": 0.9
  },
  "diagnostics": {
    "pointsUsed": 2,
    "notes": [
      "Classification based on detector state mapping"
    ]
  }
}

400Bad request - missing required fields

{
  "error": "Missing required fields: asOf, asset, sample.close"
}

Help Documentation

Stateless regime classification endpoint that maps SignalDetector outputs to canonical 4-regime set.

endpoint

/api/regime/detect

method

POST

regimes

C A L M

Low volatility, low crowding, mean reversion works. "Nothing is happening."

detector States

CALM
NO_TRADE
NEUTRAL
POST_CLEAR
RESET

characteristics

volatility

LOW

directionality

FLAT or MIXED

crowding

LOW

efficiency

MED to HIGH

T R E N D I N G

Directional movement, vol rising slowly, breakouts persist. "Winners keep winning."

detector States

INITIATION
MOMENTUM

characteristics

volatility

MED to HIGH

directionality

UP or DOWN

crowding

LOW to MED

efficiency

MED to HIGH

C R O W D E D

Positioning heavy, volatility elevated, small moves cause big reactions. "Everyone's on the same side."

detector States

CROWD_BUILD
CROWD_FRAGILE
CROWDING_EXHAUSTION

characteristics

volatility

HIGH

directionality

UP, DOWN, or MIXED

crowding

HIGH

efficiency

LOW to MED

D I S L O C A T I O N

Vol spikes, correlations jump, liquidations dominate. "Risk-off / panic."

detector States

FAILURE_BREAK
TRAP_FORMING

characteristics

volatility

HIGH

directionality

MIXED or extreme UP/DOWN

crowding

HIGH

efficiency

LOW

shock Override

Shock detection (large σ spike + large |Δ| change) immediately overrides to DISLOCATION

classification

primary

Maps SignalDetector state to base regime using state mapping rules

refinement

metrics

Uses fragility score, response efficiency, crowd side to refine classification

signals

Computes volatility, directionality, crowding, efficiency from trail data

shock

Detects shocks: σ change > 1.5 AND |Δ| change > 0.002 → forces DISLOCATION

confidence

base

warmRatio (detector calibration progress)

adjustments

Penalized if detector state is CALIBRATING
Adjusted for trail length (needs at least 5 points)
Clamped to [0, 1]

signals

volatility

computation

Standard deviation of recent σ (positioning pressure) values

levels

L O W

|σ| < 0.5

M E D

0.5 ≤ |σ| < 1.5

H I G H

|σ| ≥ 1.5

directionality

computation

Mean and variance of recent Δ (price response) values

levels

F L A T

|Δ| < 0.0005

U P

Δ > 0.0005

D O W N

Δ < -0.0005

M I X E D

High variance in Δ values

crowding

computation

Derived from fragility score

levels

L O W

fragilityScore < 40

M E D

40 ≤ fragilityScore < 70

H I G H

fragilityScore ≥ 70

efficiency

computation

Response efficiency metric from SignalDetector

levels

L O W

responseEfficiency < 40

M E D

40 ≤ responseEfficiency < 60

H I G H

responseEfficiency ≥ 60

request Format

required

asOf
asset
sample.close

optional

sample.sigma (σ - positioning pressure)
sample.delta (Δ - price response)
sample.fragilityScore
sample.responseEfficiency
sample.crowdSide
sample.warmRatio
trail (array of {ts, sigma, delta})
detectorState
market.fundingRate
market.openInterest

response Format

regime Raw

Raw classification (no stabilization) - one of: CALM, TRENDING, CROWDED, DISLOCATION

confidence Raw

Confidence score [0, 1]

scores

Probability scores for all 4 regimes (sum to 1.0)

signals

Signal breakdown (volatility, directionality, crowding, efficiency)

metadata

shock Triggered

Whether shock was detected

detector State

Original SignalDetector state

fragility Score

Fragility score [0, 100]

response Efficiency

Response efficiency [0, 100]

crowd Side

Crowd positioning (LONG, SHORT, MIXED, UNKNOWN)

warm Ratio

Detector calibration progress [0, 1]

diagnostics

points Used

Number of trail points used for computation

notes

Array of diagnostic notes about classification process

interpretation

usage

Use raw classification for immediate state, but apply stabilization (k-of-n, dwell time) before acting

stabilization

k Of N

Require regime to appear k times in last n samples before switching (e.g., 3 of 5)

dwell Time

Don't switch more than once per dwell period (e.g., 5 minutes) unless shock

shock Override

Shocks immediately switch to DISLOCATION regardless of stabilization

actions

C A L M

Normal trading conditions, mean reversion strategies work

T R E N D I N G

Breakout strategies favored, trends persist

C R O W D E D

Reduce position size, tighten stops, watch for reversals

D I S L O C A T I O N

Risk-off mode, reduce exposure, wait for stabilization

View live help endpoint

SIPmath

GET/api/sipmath/joint

Build SIPmath 3.0 joint distribution model

Builds a SIPmath 3.0 sipModel JSON from historical series (FRED + Hyperliquid) with a Gaussian copula for coherence. Supports multiple assets and transformations.

Query Parameters

Name	Type	Required	Default	Description
`assets`*	`string`	Yes	—	Comma-separated list of assets. Prefix sources: HL:<coin> or FRED:<seriesId>. Unprefixed IDs are treated as FRED. Example: `HL:BTC,HL:ETH`
`start`	`YYYY-MM-DD`	No	2020-08-01 if any HL: present, else 2020-01-01	Start date for historical data
`end`	`YYYY-MM-DD`	No	today (UTC)	End date for historical data
`freq`	`"m" \| "d"`	No	m	Frequency: monthly ("m") or daily ("d"). Daily only supported when all assets are HL:<coin>.
`transform`	`"level" \| "pct_change" \| "pch"`	No	pct_change	Transformation: pct_change (multiplicative factors), level (raw levels), or pch (percent points)
`transformMap`	`string`	No	—	Per-series transform overrides. Format: FRED:UNRATE=level,HL:BTC=pct_change
`terms`	`"auto" \| number`	No	auto	Metalog terms. "auto" tries 4..15 terms and selects first valid fit.
`minRows`	`number`	No	24	Minimum number of aligned rows required
`mode`	`"intersection" \| "union"`	No	intersection	Date alignment mode
`name`	`string`	No	—	Top-level sipModel name
`entity`	`number`	No	—	HDR_2_0 entity parameter (defaults to deterministic hash)
`seed3`	`number`	No	0	HDR_2_0 seed3 parameter
`seed4`	`number`	No	0	HDR_2_0 seed4 parameter
`varIdStart`	`number`	No	1	Starting varId for HDR_2_0 (varId will be varIdStart..varIdStart+N-1)

Responses

200Success - returns SIPmath 3.0 sipModel JSON

400Bad request - invalid parameters

Examples

Hyperliquid BTC + ETH (monthly, multiplicative factors)

/api/sipmath/joint?assets=HL:BTC,HL:ETH&transform=pct_change

FRED CPI + Hyperliquid BTC

/api/sipmath/joint?assets=FRED:CPIAUCSL,HL:BTC&start=2020-08-01&transform=pct_change

GET/api/sipmath/help

SIPmath API help documentation

Returns comprehensive documentation for the SIPmath API endpoints, including query parameters, examples, and available FRED series and Hyperliquid assets.

Responses

200Success - returns help documentation JSON

Examples

Get help documentation

/api/sipmath/help

Other Endpoints

GET/api/polymarket/strip

Fetch raw Polymarket strip data

Returns raw strip data from Polymarket for a given asset and side (min/max).

Query Parameters

Name	Type	Required	Default	Description
`asset`	`string`	No	BTC	Asset symbol (BTC or ETH)
`side`	`string`	No	min	Side: "min" or "max"

Responses

200Success - returns array of RawStripRow objects

[
  {
    "x": 60000,
    "p": 0.37,
    "volume24h": 6600,
    "openInterest": 22500
  }
]

Examples

Get BTC min strip data

/api/polymarket/strip?asset=BTC&side=min

GET/api/machine/state

Get economic machine state

Returns the current state of the economic machine, including regime classification, stability scores, and Metalog fits for Lift, Weight, Thrust, and Drag.

Query Parameters

Name	Type	Required	Default	Description
`observation_start`	`YYYY-MM-DD`	No	2006-01-01	Start date for observation window

Responses

200Success

Examples

Get current machine state

/api/machine/state

GET/api/fred/observations

Fetch FRED economic data

Retrieves economic observations from the Federal Reserve Economic Data (FRED) API for a given series.

Query Parameters

Name	Type	Required	Default	Description
`seriesId`*	`string`	Yes	—	FRED series ID (e.g., CPIAUCSL, UNRATE) Example: `CPIAUCSL`
`observation_start`	`YYYY-MM-DD`	No	—	Start date for observations
`observation_end`	`YYYY-MM-DD`	No	—	End date for observations
`targetFrequency`	`"q" \| "m" \| "d"`	No	—	Target frequency for aggregation (q=quarterly, m=monthly, d=daily)

Responses

200Success

400Bad request - seriesId required or series not found

Examples

Get CPI data

/api/fred/observations?seriesId=CPIAUCSL&observation_start=2020-01-01

POST/api/current-price

Get current asset prices

Returns current prices, market cap, and 24h change for specified tickers.

Request Body

Array of ticker symbols

{
  "tickers": [
    "BTC",
    "ETH",
    "SOL"
  ]
}

Responses

200Success

{
  "BTC": {
    "price": 92921.5,
    "symbol": "BTC",
    "name": "Bitcoin",
    "change24h": 2.5,
    "marketCap": 1800000000000,
    "lastUpdated": "2026-01-06T12:00:00Z"
  }
}

400Bad request - tickers array required

Examples

Get prices for BTC and ETH

Request Body:

{
  "tickers": [
    "BTC",
    "ETH"
  ]
}

For questions or issues, please refer to the GitHub repository.

API Documentation

Table of Contents

Beliefs & Oracle

Fetch belief distributions from prediction markets

Get BTC beliefs from both sources

Get ETH beliefs from Polymarket only

Query belief oracle (quantile, percentile, tail probability)

Query quantile at 50% probability

Query percentile and tail probability for price

Regime Detection

Classify market regime

endpoint

method

regimes

C A L M

detector States

characteristics

volatility

directionality

crowding

efficiency

T R E N D I N G

detector States

characteristics

volatility

directionality

crowding

efficiency

C R O W D E D

detector States

characteristics

volatility

directionality

crowding

efficiency

D I S L O C A T I O N

detector States

characteristics

volatility

directionality

crowding

efficiency

shock Override

classification

primary

refinement

metrics

signals

shock

confidence

base

adjustments

signals

volatility

computation

levels

L O W

M E D

H I G H

directionality

computation

levels

F L A T

U P

D O W N

M I X E D

crowding

computation

levels

L O W

M E D

H I G H

efficiency

computation

levels

L O W

M E D

H I G H

request Format

required