Signal API Documentation

Full reference for the Quark signal feed. Endpoint list, response schemas, rate limits, and — most importantly — how to translate the regime score / crash probability / defensive blend into trades in your own portfolio.

Authentication, versioning & rate limits

Per-tier monthly quotas

Sandbox trial — evaluate without payment

Before subscribing, you can issue a no-payment 7-day Automated-tier key and exercise the full API surface. Useful for backtest integration, load-shape testing, or just confirming the data lines up with your existing stack.

Issue a trial key and immediately call the signal endpoint:

curl -sS -X POST https://api.quarkresearch.cc/api/trial/start \
     -H "content-type: application/json" \
     -d '{"email":"[email protected]"}'

# {"api_key":"qk_trial_abc...","trial_expires_at":"...","sample_curl":"..."}

curl -sS https://api.quarkresearch.cc/api/v1/signals/current \
     -H "x-api-key: qk_trial_abc..."

Quickstart — curl, Python, JS, SDK

Three ways to pull the current regime read. All examples authenticate with a key you get from the dashboard.

1 · curl (one-liner)

curl -sS https://api.quarkresearch.cc/api/signals/current \
  -H "x-api-key: $QUARK_API_KEY" | jq .regime

2 · Python (requests — raw HTTP)

import os, requests

r = requests.get(
    "https://api.quarkresearch.cc/api/signals/current",
    headers={"x-api-key": os.environ["QUARK_API_KEY"]},
    timeout=10,
)
r.raise_for_status()
sig = r.json()
print(f"regime: {sig['regime']['regime_label']} "
      f"(score={sig['regime']['regime_score']:.2f}); "
      f"crash 21d: {sig['tail_risk']['crash_prob_21d']:.1%}; "
      f"asof: {sig['freshness']['asof']} "
      f"({sig['freshness']['staleness_seconds']}s stale)")

3 · JavaScript (fetch)

const res = await fetch('https://api.quarkresearch.cc/api/signals/current', {
  headers: { 'x-api-key': process.env.QUARK_API_KEY }
});
if (!res.ok) throw new Error(`HTTP ${res.status}`);
const sig = await res.json();
console.log(`${sig.regime.regime_label} (${sig.regime.regime_score.toFixed(2)})`);
console.log(`crash 21d: ${(sig.tail_risk.crash_prob_21d * 100).toFixed(1)}%`);
console.log(`asof: ${sig.freshness.asof}, ${sig.freshness.staleness_seconds}s old`);

4 · Signal history straight into pandas

import os, io, pandas as pd, requests

r = requests.get(
    "https://api.quarkresearch.cc/api/signals/history.csv",
    params={"days": 365},
    headers={"x-api-key": os.environ["QUARK_API_KEY"]},
    timeout=30,
)
r.raise_for_status()
df = pd.read_csv(io.StringIO(r.text), parse_dates=["timestamp_utc"])
df = df.set_index("timestamp_utc").sort_index()
print(df[["regime", "regime_score", "crash_prob_21d"]].tail())

The CSV endpoint is the authoritative point-in-time-stamped export — every row carries a UTC timestamp at the moment the signal was computed, not when you pulled it. Intended for reproducibility and audit of what the signal said at a specific moment.

5 · Register a webhook for state changes

curl -sS -X POST https://api.quarkresearch.cc/api/webhook/register \
  -H "x-api-key: $QUARK_API_KEY" \
  -H "content-type: application/json" \
  -d '{"url": "https://your-server.example/quark-webhook"}'

# then fire a test payload to your endpoint:
curl -sS -X POST https://api.quarkresearch.cc/api/webhook/test \
  -H "x-api-key: $QUARK_API_KEY"

6 · Verify a webhook signature (Python)

import hmac, hashlib, os

def verify(payload_bytes: bytes, header_sig: str) -> bool:
    secret = os.environ["QUARK_WEBHOOK_SECRET"].encode()
    mac = hmac.new(secret, payload_bytes, hashlib.sha256).hexdigest()
    return hmac.compare_digest(mac, header_sig)

# In your webhook handler:
# raw = request.body  (bytes, not the parsed JSON)
# sig = request.headers["X-Quark-Signature"]
# if not verify(raw, sig): abort(401)

7 · Python SDK (pip install quarkresearch)

For Python users, the official client wraps authentication, v1 routing, deprecation-header parsing, quota introspection, and typed exceptions. Single runtime dependency (requests); Python 3.9+. Published to PyPI as quarkresearch and versioned lockstep with the /api/v1 surface.

pip install quarkresearch

from quarkresearch import Client, QuotaExceededError, RateLimitError

client = Client(api_key="qk_live_...")           # or env QUARK_API_KEY

# Current signal — typed dict with the same schema as /api/v1/signals/current
snap = client.signals_current()
print(snap["regime"]["regime_label"], snap["regime"]["regime_score"])

# Every call stamps client.last_meta (ResponseMeta dataclass)
meta = client.last_meta
print(meta.api_version)          # "v1"
print(meta.quota_limit,
      meta.quota_used,
      meta.quota_reset_epoch)    # Stripe-cycle-aligned Unix epoch
if meta.deprecation:
    print(f"Migrate to {meta.successor_url} by {meta.sunset}")

# Reproducibility — what was the signal at 14:30 UTC on 2026-03-14?
historical = client.signals_at("2026-03-14T14:30:00Z")
if historical["available"]:
    # Response is flat: same field layout as signals_current, plus snapshot_timestamp
    print(historical["snapshot_timestamp"],
          historical["regime"]["regime_label"])

# History straight into pandas — no manual CSV parsing
import io, pandas as pd
df = pd.read_csv(io.StringIO(client.signals_history_csv(days=365)),
                 parse_dates=["timestamp_utc"]).set_index("timestamp_utc")
print(df[["regime", "regime_score", "crash_prob_21d"]].tail())

The SDK maps HTTP status codes to a typed exception hierarchy — catch at whatever granularity you want:

import time

try:
    snap = client.signals_current()
except QuotaExceededError:
    # Server has already told us when the quota resets — the SDK reads
    # client.last_meta.quota_reset_epoch and sleeps until then.
    client.wait_for_quota_reset()
    snap = client.signals_current()
except RateLimitError as e:
    time.sleep(e.retry_after or 60)
    snap = client.signals_current()
# AuthenticationError (401), PermissionDeniedError (403), NotFoundError (404),
# ValidationError (400), ServerError (500+ with .error_id) are also raised
# from QuarkError — catch that as the root for defensive loops.

Response shape — the fields you'll actually use

{
  "regime": {
    "regime_label": "NEUTRAL",        // RISK_ON | NEUTRAL | RISK_OFF | CRISIS
    "regime_score": 0.48,              // 0.0 RISK_ON → 1.0 CRISIS
    "barrier_depletion": 0.22          // 0.0 stable → 1.0 transition imminent
  },
  "tail_risk": {
    "crash_prob_1d":  0.04,
    "crash_prob_5d":  0.11,
    "crash_prob_21d": 0.19             // workhorse tail-risk number
  },
  "allocation": {
    "equity_pct":    0.65,             // strategy posture (not a personal rec)
    "defensive_pct": 0.25,
    "hedge_pct":     0.10
  },
  "freshness": {
    "asof": "2026-04-21T14:32:00+00:00",
    "staleness_seconds": 42
  },
  "provenance": {
    "sources_agreed": 3,
    "primary_feed": "yahoo",
    "consensus_feeds": ["yahoo", "stooq", "finnhub"],
    "max_disagreement_bps": 5,
    "reference_symbol": "SPY",
    "probed_at": "2026-04-21T14:31:58+00:00"
  }
}

Full schema for every field — including the risk_params and rotation blocks on /full — is in the Full response schema section.

Python SDK (pip install quarkresearch)

Official client for the /api/v1 surface. MIT-licensed, Python 3.9+, a single runtime dependency (requests). Same pipeline that powers our own tooling.

Method surface

ResponseMeta — per-call introspection

Every successful call stamps client.last_meta with a ResponseMeta dataclass so you can log version + quota state without re-parsing headers. Fields:

Exception hierarchy

QuarkError                    # root — catch this in defensive loops
├── AuthenticationError       # 401 — bad/missing API key
├── PermissionDeniedError     # 403 — tier doesn't include this endpoint
├── NotFoundError             # 404 — unknown route or missing resource
├── ValidationError           # 400 — invalid params (also raised client-side on bad inputs)
├── RateLimitError            # 429 — exposes .retry_after (seconds)
├── QuotaExceededError        # 402 — exposes .body (quota_month, calls_month, resets_at)
└── ServerError               # 500+ — exposes .error_id (use in support tickets)

Endpoints

Point-in-time signals (/api/v1/signals/at)

The single-endpoint answer to "what signal would I have seen if my strategy ran at 14:30 UTC on March 14, 2026?" Shipped 2026-04-22 so licensees can audit and reproduce what the live feed said at any historical moment.

Signal snapshots are persisted every cycle. /api/v1/signals/at resolves the most recent snapshot at or before the as_of timestamp — so there is exactly one answer for any given historical moment, no interpolation, no forward contamination.

Request

GET /api/v1/signals/at?as_of=2026-03-14T14:30:00Z
x-api-key: qk_live_...

Response

Fields are flat (same layout as /api/v1/signals/current) with three extra fields: as_of (echo of the request), snapshot_timestamp (the snapshot actually returned), and source: "point_in_time". Drop-in compatible with code that already handles /api/v1/signals/current responses.

{
  "as_of":              "2026-03-14T14:30:00Z",        // echoed from request
  "snapshot_timestamp": "2026-03-14T14:29:12+00:00",   // snapshot actually returned (≤ as_of)
  "source":             "point_in_time",
  "available":          true,
  "regime":         { "regime_label": "...", "regime_score": ..., ... },
  "tail_risk":      { "crash_prob_1d": ..., "crash_prob_5d": ..., "crash_prob_21d": ..., ... },
  "signal_quality": { "avg_snr": ... },
  "allocation":     { "equity_pct": ..., "defensive_pct": ... }
}

When no snapshot exists at or before the requested time (request before retention window, or no data yet persisted):

{
  "as_of":              "2015-01-01T00:00:00Z",
  "snapshot_timestamp": null,
  "source":             "point_in_time",
  "available":          false,
  "note":               "No signal snapshot persisted at or before the requested time."
}

Invalid as_of values fail fast with HTTP 400:

Resolution semantics

Retention

Snapshots are retained back to platform inception (2026-02 for current production data). History before the retention boundary returns available: false, reason: "before_retention_window". The available: false response still succeeds with HTTP 200 — callers branch on available, not on status code.

Audit / reproducibility pattern (SDK)

from quarkresearch import Client
import pandas as pd

client = Client(api_key="qk_live_...")

# Reconstruct exactly what the live feed said every Monday 14:30 UTC in 2025:
dates = pd.date_range("2025-01-06", "2025-12-29", freq="W-MON", tz="UTC")
rows = []
for dt in dates:
    resp = client.signals_at(dt.strftime("%Y-%m-%dT14:30:00Z"))
    if not resp["available"]:
        continue
    rows.append({
        "date":                 dt,
        "snapshot_timestamp":   resp["snapshot_timestamp"],
        "regime":               resp["regime"]["regime_label"],
        "regime_score":         resp["regime"]["regime_score"],
        "crash_prob_21d":       resp["tail_risk"]["crash_prob_21d"],
        "equity_pct":           resp["allocation"]["equity_pct"],
    })

df = pd.DataFrame(rows).set_index("date")
# ... df now contains the exact snapshot the live feed emitted at each timestamp

Platform health (/api/health)

Public deep-check endpoint. No API key required. Designed to be poll-safe from uptime monitors (UptimeRobot, Better Uptime, Pingdom), status-page integrations, and client-side ops dashboards.

Every response is HTTP 200 with a structured JSON body. The top-level status field drives caller behavior; per-check detail under checks helps diagnose what is degraded when something's off.

Response shape

{
  "status":         "ok",                              // ok | degraded | down
  "checked_at":     "2026-04-21T14:32:00+00:00",
  "version":        "3.0.0",
  "uptime_seconds": 847293,
  "boot_at":        "2026-04-11T18:50:27+00:00",
  "checks": {
    "db.connectivity": {
      "status": "ok",
      "path":   "/app/data/subscribers.db"
    },
    "db.signal_log.fresh": {
      "status":             "ok",
      "staleness_seconds":  412,
      "last_signal_at":     "2026-04-21T14:25:08+00:00",
      "threshold_seconds":  7200
    },
    "feeds.consensus": {
      "status":                "ok",
      "sources_agreed":        3,
      "feeds_up":              ["yahoo", "stooq", "finnhub"],
      "max_disagreement_bps":  5,
      "median_price":          542.1,
      "reference_symbol":      "SPY"
    },
    "arena.initialized": {
      "status":       "ok",
      "cycle_count":  12847,
      "n_portfolios": 7
    }
  }
}

Status levels

Check reference

Full response schema

Every numeric field is a float in [0, 1] unless otherwise noted. All fields carry a fallback: bool flag — when true, the section is showing a classical/default estimate because the quantum pipeline failed to produce a non-fallback value this cycle.

regime section

tail_risk section

signal_quality section

allocation section

risk_params section (full endpoint only)

rotation section (full endpoint only)

fund_summary section

freshness section

Every successful response carries a freshness block so you can tell whether the signal is live or stale. Use staleness_seconds to decide whether to trade on the value or skip this cycle.

provenance section

Cross-vendor price consensus. Every response probes three independent feeds — Yahoo Finance, Stooq, and Finnhub — for a reference symbol (SPY by default) and reports how many agreed within 50 bps of the median. Higher = stronger confidence the signal's price inputs weren't driven by a single-vendor anomaly. The probe is 60-second cached server-side; your per-request latency is not impacted.

How to apply the signal to your portfolio

The signal is deliberately decoupled from any specific trade list — it's a set of continuous knobs you translate into your own allocation logic. Below are the three patterns we see licensees use successfully. Pick one that matches your existing workflow.

Pattern 1 — Defensive overlay on a static allocation

Simplest. You already have a strategic allocation (e.g. 60/40). Use defensive_blend to scale up/down your equity weight when the signal says conditions are deteriorating.

target_equity_pct = base_equity_pct × (1 − signal.allocation.defensive_blend)
target_bond_pct   = 1 − target_equity_pct

# Example:
# base 60/40, defensive_blend = 0.25 →
#   target_equity = 0.60 × 0.75 = 45%
#   target_bond   = 55%

Pattern 2 — Tail-risk gated sizing

For strategies that size positions as Kelly fractions or vol-targeted. Scale each position's size by the complement of the 21-day crash probability, so sizes shrink as crash risk rises.

crash_21 = signal.tail_risk.crash_prob_21d
sizing_multiplier = 1 − min(2 × crash_21, 0.80)   # cap de-risking at 80%

for asset in portfolio:
    target_size[asset] = base_size[asset] × sizing_multiplier

The 2× factor is a convention — we use it internally. It means a 21d crash probability of 0.40 drives sizing to 20% of baseline; anything higher clamps at 20%.

Pattern 3 — Full quant replication

For licensees running their own quant book. Use the /full endpoint and consume the per-asset caps, factor weights, and subspace-rotation state directly.

from scipy.optimize import minimize

def step(signal):
    caps = signal.allocation.per_asset_caps  # ticker → max weight

    # Halflife → covariance EWMA decay
    lam = 0.5 ** (1 / signal.risk_params.quantum_halflife)
    cov = ewma_covariance(returns, lam) × signal.risk_params.quantum_shrinkage_boost

    # Factor tilt from signal-quality weights
    factor_tilt = {
        'momentum':    signal.signal_quality.momentum_weight,
        'quality':     signal.signal_quality.quality_weight,
        'volume':      signal.signal_quality.volume_weight,
        'cyclicality': signal.signal_quality.cyclicality_weight,
    }

    # Solve mean-variance with caps as upper bound on each w_i
    weights = mean_variance_with_caps(
        expected_returns=alpha_from_factors(factor_tilt),
        covariance=cov,
        upper_bounds=caps,
        defensive_blend=signal.allocation.defensive_blend,
    )
    return weights

# Only re-solve on a regime change or rotation flag
if signal.rotation.should_invalidate_cache or regime_changed:
    weights = step(signal)

Field-by-field heuristics

Worked examples

Example A — "Check once a day, adjust 60/40"

import requests, json

KEY = 'qk_live_...'
BASE = 'https://api.quarkresearch.cc'

def daily_allocation(base_equity=0.60):
    sig = requests.get(f'{BASE}/api/signals/current',
                       headers={'x-api-key': KEY}, timeout=10).json()
    defensive = sig['allocation']['defensive_blend']
    crash_21  = sig['tail_risk']['crash_prob_21d']

    eq_pct = base_equity * (1 - defensive)

    # Extra de-risk if crash probability elevated
    if crash_21 > 0.15:
        eq_pct *= 0.75
    if crash_21 > 0.30:
        eq_pct *= 0.50

    bond_pct = 1 - eq_pct
    return {'equity': eq_pct, 'bonds': bond_pct, 'signal': sig}

alloc = daily_allocation()
print(f"Target equity: {alloc['equity']:.1%}, bonds: {alloc['bonds']:.1%}")

Example B — "Push to Google Sheets via webhook"

# Register webhook (one-time)
curl -X POST -H "x-api-key: $KEY" \
  -H "content-type: application/json" \
  -d '{"url":"https://script.google.com/macros/s/YOUR_DEPLOY/exec"}' \
  https://api.quarkresearch.cc/api/webhook/register

# Test delivery
curl -X POST -H "x-api-key: $KEY" \
  https://api.quarkresearch.cc/api/webhook/test

Your Apps Script receives the same JSON as /api/signals/current. Write it into a sheet, pivot against your broker's positions, done.

Example C — "Size a momentum sleeve with crash gate"

def momentum_sleeve_sizing(base_gross_exposure=1.50):
    sig = requests.get(f'{BASE}/api/signals/current',
                       headers={'x-api-key': KEY}).json()

    # Sizing multiplier from crash probability
    crash_21 = sig['tail_risk']['crash_prob_21d']
    mult = 1 - min(2 * crash_21, 0.80)

    # Adjust momentum weight based on SNR
    mom_w = sig['signal_quality']['momentum_weight']

    target_gross = base_gross_exposure * mult * (mom_w / 0.25)  # 0.25 = long-run avg
    return target_gross

Example D — "Replay 2025 with the SDK + point-in-time endpoint"

Audit replay: reconstruct what the signal said at every Monday 14:30 UTC for all of 2025, against a static 60/40 baseline for reference. The key property — each call to signals_at(t) returns only information observable at time t, so you're reading the live feed as it stood at t, not an ex-post reconstruction.

from quarkresearch import Client, QuotaExceededError
import pandas as pd

client = Client()   # reads QUARK_API_KEY from environment

def target_equity_pct(snap):
    # Start from the strategy's own equity posture and layer a crash-gate on top.
    pct = snap["allocation"]["equity_pct"]
    crash_21 = snap["tail_risk"]["crash_prob_21d"]
    if crash_21 > 0.15: pct *= 0.75
    if crash_21 > 0.30: pct *= 0.50
    return pct

dates = pd.date_range("2025-01-06", "2025-12-29", freq="W-MON", tz="UTC")
rows = []
for dt in dates:
    try:
        resp = client.signals_at(dt.strftime("%Y-%m-%dT14:30:00Z"))
    except QuotaExceededError:
        client.wait_for_quota_reset()
        resp = client.signals_at(dt.strftime("%Y-%m-%dT14:30:00Z"))

    if not resp["available"]:
        continue   # before retention / in future — skip

    # Response is flat (same layout as signals_current)
    rows.append({
        "date":                 dt,
        "snapshot_timestamp":   resp["snapshot_timestamp"],
        "regime":               resp["regime"]["regime_label"],
        "crash_prob_21d":       resp["tail_risk"]["crash_prob_21d"],
        "target_equity":        target_equity_pct(resp),
    })

df = pd.DataFrame(rows).set_index("date")
print(df.describe())
# → plot df["target_equity"] vs a static 0.60 baseline across 2025

Webhook reference

Register a URL to receive push notifications when the regime changes, crash probability crosses 15%, or rotation.should_invalidate_cache fires.

Payload

Identical to /api/signals/current response, with one extra field at the top:

{
  "event": "regime_change" | "crash_threshold_crossed" | "rotation_invalidate" | "test",
  "regime": {...},
  "tail_risk": {...},
  ...
}

Signature verification

Every webhook request carries an X-Quark-Signature header with an HMAC-SHA256 of the raw body, keyed on your API key. Verify in your receiver:

import hmac, hashlib

def verify(raw_body: bytes, signature: str, api_key: str) -> bool:
    expected = hmac.new(
        api_key.encode('utf-8'),
        raw_body,
        hashlib.sha256,
    ).hexdigest()
    return hmac.compare_digest(expected, signature)

Retry policy

Webhooks that return a non-2xx status or time out after 5 seconds will be retried with exponential backoff: 30s, 2m, 10m, 1h, 6h, 24h. After that the delivery is dropped; the signal itself is still available via GET on /api/signals/current.

Errors & status codes

Response body shape

Error responses use one of three JSON shapes depending on status code. Clients should handle both error and detail when parsing — the official Python SDK does this automatically.

Status code reference

fallback: true semantics

When any section returns fallback: true, that section's values are from a classical/default estimator rather than the quantum pipeline. Two options:

• Conservative: skip that section this cycle — use the previous non-fallback value.
• Relaxed: use the fallback value anyway; it's still a reasonable estimate, just not the proprietary one.

Changelog