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 & rate limits

Endpoints

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

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

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

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