DEVELOPERS

The fastest way to integrate Invarians. Handles authentication, retry, STALE policy, and calibration metadata automatically.

pip install "invarians[requests]>=0.5.0"   # v2.0 client (Attestation + Regime + Drift)

from invarians import InvariansClient

client = InvariansClient(api_key="inv_your_key_here")

# v2.0 panel with full diagnostic (regime + Delta per metric)
panel = client.get_panel_v2(
    chains=["ethereum", "arbitrum"],
    bridges=["cctp"],
    include="diagnostic",    # core | diagnostic | full
)

eth = panel.l1_by_chain("ethereum")
arb = panel.l2_by_chain("arbitrum")
br  = panel.bridge_by_id("arbitrum-ethereum/cctp")

# Primitive 2: regime classification (12 codes per chain)
if eth.regime.startswith("S2") or arb.regime.startswith("S2"):
    pause_agent_execution()    # structural stress detected

# Primitive 3: Delta (per-chain calibrated precursors, v3 preview)
for p in arb.precursors:
    if p.is_firing and p.baseline_lift >= 1.5:
        defer_action()        # calibrated precursor fired, defer for p.lead_hours

# Per-metric inspection (only available in diagnostic mode)
print(eth.demand.tx.shift)                  # current deviation vs 30d baseline
print(eth.demand.tx.is_drifting_away)       # True if deviation amplifying
print(eth.demand.tx.is_reverting)           # True if returning to nominal

# Primitive 1: HMAC integrity
ok = client.verify_panel_v2(
    panel_dict, panel.signed_execution_context.signature
)

For raw HTTP access (JavaScript, curl, other languages), see sections below.

# Python — raw HTTP, v2.0 panel with diagnostic mode
import requests

API_KEY = "inv_your_api_key"
BASE_URL = "https://api.invarians.com"

def get_panel(chains=None, bridges=None, include="core") -> dict:
    params = {"include": include}
    if chains:  params["chains"]  = ",".join(chains)
    if bridges: params["bridges"] = ",".join(bridges)
    r = requests.get(
        f"{BASE_URL}/v2/panel",
        headers={"Authorization": f"Bearer {API_KEY}"},
        params=params,
    )
    r.raise_for_status()
    return r.json()

panel = get_panel(chains=["ethereum"], bridges=["cctp"], include="diagnostic")

print(panel["version"])                                    # "2.0.0"
print(panel["oracle_status"])                              # "OK" | "DEGRADED"
print(panel["panel"]["l1"][0]["regime"])                      # 12 possible codes per chain
for p in panel["panel"]["l2"][0].get("precursors", []):
    print(p["axis"], p["fires"], p["baseline_lift"])    # v3 per-chain calibrated precursors
print(panel["signed_execution_context"]["signature"])      # "hmac-sha256:..."

// JavaScript / Node — v2.0 panel
const getPanel = async (params = {}) => {
  const qs = new URLSearchParams(params).toString();
  const res = await fetch(
    `https://api.invarians.com/v2/panel?${qs}`,
    { headers: { Authorization: `Bearer ${API_KEY}` } }
  );
  return res.json();
};

const panel = await getPanel({
  chains: "ethereum,arbitrum",
  bridges: "cctp",
  include: "diagnostic",
});

console.log(panel.version);                                    // "2.0.0"
console.log(panel.panel.l1[0].regime);                         // "S1D1" | "S1D2+" | ... (12 codes)
console.log(panel.panel.l1[0].demand.tx.shift);                // per-metric deviation magnitude
console.log(panel.panel.l1[0].demand.tx.shift_magnitude_delta); // per-metric trend
console.log(panel.panel.bridges[0].state);                     // "BS1" | "BS2" | null

# Python — compose a route from the v2.0 panel (agent-side)
panel = get_panel(chains=["ethereum", "arbitrum"], bridges=["cctp"], include="diagnostic")

l1 = next(e for e in panel["panel"]["l1"] if e["chain"] == "ethereum")
l2 = next(e for e in panel["panel"]["l2"] if e["chain"] == "arbitrum")
br = next(b for b in panel["panel"]["bridges"] if b["id"] == "arbitrum-ethereum/cctp")

# Primitive 2: regime per chain (12 codes)
print(l1["regime"], l1["status"])               # e.g. "S1D2+" "OK"
print(l2["regime"], l2["status"])               # e.g. "S1D1" "OK"

# Primitive 3: Delta (v3 per-chain precursors + raw shift inputs)
for p in l2.get("precursors", []):
    print(p["axis"], p["fires"],
          p["lead_hours"], p["baseline_lift"])  # calibrated per-chain precursor
print(l1["demand"]["sigma"]["shift"])           # per-metric current deviation (raw)
print(l1["demand"]["sigma"]["shift_magnitude_delta"])  # per-metric trend (raw)

# Bridge state
print(br["state"], br["calibrated"], br["status"])  # e.g. "BS1" True "OK"

The default panel returns every tracked chain and bridge (~25 entries, ~30 KB JSON in diagnostic mode). Most agents only need a small subset. Always filter your queries.

# Minimal panel for a single L1+L2 pair, CCTP route only
GET /v2/panel?chains=ethereum,arbitrum&bridges=cctp&include=core
# → ~2 KB, regime + status + precursors[] per chain

# Diagnostic mode adds per-metric raw shift fields
GET /v2/panel?chains=ethereum&bridges=cctp&include=diagnostic
# → ~3 KB, with shift + shift_delta + shift_magnitude_delta per metric

# Research / debugging (raw EMA baselines included)
GET /v2/panel?chains=ethereum&include=full
# → ~5 KB, with baseline_short + baseline_long

# Multi-bridge route comparison (CCIP + CCTP)
GET /v2/panel?chains=ethereum,arbitrum&bridges=ccip,cctp&include=core
# → ~6 KB

Full response for GET /v2/panel. One signed payload with every tracked L1, L2, and bridge, axis-grouped by chain. The agent picks the entries relevant to its planned action.

{
  "version":       "2.0.0",
  "oracle_status": "OK",                       // "OK" | "DEGRADED"
  "issued_at":    "2026-04-30T12:30:00Z",

  "panel": {
    // L1 chains, axis-grouped (structural / demand) per chain
    "l1": [
      {
        "chain":       "ethereum",
        "regime":      "S1D1",                   // 12 codes possible: S1, S2+, S2- × D1, D2+, D2-, D2±
        "status":      "OK",                     // "OK" | "STALE" | "UNAVAILABLE" | "UNCALIBRATED"
        "computed_at": "2026-04-30T12:25:00Z",

        // Structural axis (S): rhythm, continuity, plus beacon_participation on Ethereum only
        "structural": {
          "rhythm": {
            "ratio":                 1.0013,    // short EMA (~10h) vs short baseline
            "ratio_long":            0.9996,    // long EMA (~30d) vs long baseline (diagnostic+)
            "shift":                 0.0017,    // = ratio - ratio_long, current deviation
            "shift_delta":           0.0008,    // = shift - shift_prev, direction of value movement
            "shift_magnitude_delta": 0.0008     // = |shift| - |shift_prev|, deviation grows or shrinks
          },
          "continuity": {
            "ratio": 1.0, "ratio_long": 1.0, "shift": 0.0, "shift_delta": 0.0, "shift_magnitude_delta": 0.0
          },
          "beacon_participation": {                  // Ethereum only (Beacon Chain validators)
            "ratio":           0.998,
            "epoch":           312547,
            "shift_available": false                // slow EMA stabilizing, ~30d post-launch
          }
        },

        // Demand axis (D): sigma, size, tx (echo of activity on confirmed blocks)
        "demand": {
          "sigma": { "ratio": 1.003,  "ratio_long": 0.99, "shift":  0.013, "shift_delta":  0.005, "shift_magnitude_delta":  0.005 },
          "size":  { "ratio": 1.0095, "ratio_long": 1.05, "shift": -0.04,  "shift_delta": -0.012, "shift_magnitude_delta":  0.012 },
          "tx":    { "ratio": 1.2037, "ratio_long": 1.18, "shift":  0.024, "shift_delta":  0.018, "shift_magnitude_delta":  0.018 }
        },

        // Precursors per chain (v3 design preview; empty on ethereum, calibration registry is per-chain)
        "precursors": []
      }
    ],

    // L2 rollups, axis-grouped. structural also includes sequencer_publish_latency.
    // demand has 5 observables on L2 (sigma + size + tx + complexity + gas_complexity).
    "l2": [
      {
        "chain":       "arbitrum",
        "regime":      "S1D1",
        "status":      "OK",
        "computed_at": "2026-04-30T12:25:00Z",

        "structural": {
          "rhythm":     { "ratio": 1.001, "ratio_long": 0.992, "shift": 0.009, "shift_delta": 0.001, "shift_magnitude_delta": 0.001 },
          "continuity": { "ratio": 1.0,   "ratio_long": 1.006, "shift": -0.006, "shift_delta": 0.0, "shift_magnitude_delta": 0.0 },
          "sequencer_publish_latency": {              // L2 third structural observable
            "ratio":           null,
            "seconds":         11.4,                // raw delay between L2 batches inscribed on L1
            "shift_available": false                // slow EMA pending
          }
        },

        "demand": {
          "sigma":          { "ratio": 1.0,   "ratio_long": 1.0, "shift": 0.0, "shift_delta": 0.0, "shift_magnitude_delta": 0.0 },
          "size":           { "ratio": 0.94,  "ratio_long": 0.97, "shift": -0.03, "shift_delta": -0.005, "shift_magnitude_delta": 0.005 },
          "tx":             { "ratio": 0.91,  "ratio_long": 1.01, "shift": -0.10, "shift_delta": -0.02, "shift_magnitude_delta": 0.02 },
          "complexity":     { "ratio": 1.02,  "ratio_long": 1.0, "shift": 0.02, "shift_delta": 0.005, "shift_magnitude_delta": 0.005 },
          "gas_complexity": { "ratio": 1.01,  "ratio_long": 1.0, "shift": 0.01, "shift_delta": 0.002, "shift_magnitude_delta": 0.002 }
        },

        // Precursors per chain (v3 design preview; 6 calibrated configurations on arbitrum from ETH-ARB-CCTP 2025)
        "precursors": [
          {
            "axis":                 "arb_struct_seq_publish_latency_shift",
            "fires":                false,
            "current_smd":          0.080,
            "smd_threshold_value":  0.2258,
            "k_consecutive_hours":  2,
            "pctl_threshold":       0.90,
            "lead_hours":           6,
            "outcome_category":     "latency_high_only",
            "bridge_corridor":      "ETH-ARB-CCTP",
            "baseline_lift":        1.913,
            "baseline_p_adj":       0.023,
            "baseline_precision":   0.439,
            "baseline_alert_rate":  0.0057,
            "cross_chain_status":   "FAIL_on_optimism",
            "calibrated_at":        "2026-05-19T00:00:00Z"
          }
          // + 5 other arbitrum precursors (seq_publish_latency at lead 3h/12h, demand_tx, demand_size, eth_demand_tx cross-substrate)
        ]
      }
      // + base, optimism (same shape, each with its own per-chain precursors[])
    ],

    // Bridges. Unified state codes BS1/BS2 across all protocols (CCIP, CCTP, future fast bridges); type field distinguishes the protocol.
    "bridges": [
      {
        "id":                     "arbitrum-ethereum/cctp",
        "endpoints":              ["ethereum", "arbitrum"],
        "type":                   "cctp",
        "state":                  "BS1",
        "calibrated":             true,
        "status":                 "OK",
        "observed_at":            "2026-05-04T12:28:00Z",
        "window":                 "1h",
        "circle_api_status":      "OK"
      }
      // + base-ethereum/cctp, optimism-ethereum/cctp, plus CCIP entries with calibrated:false (raw observability until throughput sustained)
    ]
  },

  "coverage": {
    "l1_chains":       ["ethereum"],
    "l2_chains":       ["arbitrum", "base", "optimism"],
    "bridges_ccip":    10,
    "bridges_ccip":    10,
    "bridges_cctp":    10,
    "include_mode":    "diagnostic",                       // echoes the ?include= query param
    "methodology_url": "https://invarians.com/methodology"
  },

  // HMAC-SHA256 over canonical JSON of everything above. anchor populated in v2.x with the on-chain Merkle anchor.
  "signed_execution_context": {
    "payload_hash": "0x84f549ab8c50cdf609a2a84bae3d23d37fc1496de23acddaebe4d78c6080b268",
    "signature":    "hmac-sha256:8ad60a8c399a1f779056fca4005841aa9257b9cf721da49a4a68c7173ac76a06",
    "key_id":       "invarians-v1",
    "anchor":       null
  }
}

The four base codes below classify chains against an upper threshold on each axis. On chains with calibrated lower bounds (since 2026-04-29: ETH, POL on L1; ARB, BASE, OP on L2), the API also emits signed regime codes with explicit direction suffixes (+, -, ±). The four base codes remain valid as aliases for chains without lower bounds yet calibrated. See foundations §03b for the full extended grid.

The Regime classification answers what is the substrate doing now. The Delta answers is the deviation amplifying or reverting. Each classifying observable is exposed as a self-contained MetricBlock with the current ratio, the long-term reference, the deviation magnitude, and two trend signals.

{
  "ratio":                 1.094,    // short EMA (~10h) vs short baseline
  "ratio_long":            0.991,    // long EMA (~30d) vs long baseline
  "shift":                 0.103,    // = ratio - ratio_long, deviation magnitude (signed)
  "shift_delta":           0.016,    // = shift_now - shift_prev, raw direction of value movement
  "shift_magnitude_delta": 0.016     // = |shift_now| - |shift_prev|, deviation growing or shrinking
}

Reading rules

Each chain entry exposes a composite drift summary computed server-side. The block below is what the API returns today on /v2/panel. The empirical reading below the table is an initial heuristic that did not pass independent validation on the 2025 corpora (see the research note). The v3 design that replaces this block with calibrated precursors per chain is documented in the next subsection.

"drift": {
  "structural":                 0.0017,   // max |shift| over structural observables
  "structural_delta":           0.0008,
  "structural_magnitude_delta": 0.0008,
  "demand":                     0.103,    // max |shift| over demand observables
  "demand_delta":               0.016,
  "demand_magnitude_delta":     0.016
}

In v3 the composite drift block is replaced by a precursors[] array on each L1 and L2 entry. Each element is a single calibrated configuration that survived a 648-configuration Benjamini-Hochberg FDR exploration on its discovery corpus. The element carries everything the agent needs to act: the boolean fire flag, the current value of the signal, the calibration metadata (axis, threshold, lead, outcome, lift, precision), and the cross-chain test status. There is no composite Delta score and no aggregation across chains: an agent reads the precursors that belong to the chain it is acting on, applies its own decision policy, and routes accordingly.

"l2": [
  {
    "chain": "arbitrum",
    "regime": "S1D1",
    "structural": { ... },
    "demand":     { ... },
    "precursors": [
      {
        "axis":                 "arb_struct_seq_publish_latency_shift",
        "fires":                false,
        "current_smd":          0.080,
        "smd_threshold_value":  0.2258,
        "k_consecutive_hours":  2,
        "pctl_threshold":       0.90,
        "lead_hours":           6,
        "outcome_category":     "latency_high_only",
        "bridge_corridor":      "ETH-ARB-CCTP",
        "baseline_lift":        1.913,
        "baseline_p_adj":       0.023,
        "baseline_precision":   0.439,
        "baseline_alert_rate":  0.0057,
        "cross_chain_status":   "FAIL_on_optimism",
        "cross_chain_lift":     0.000,
        "cross_chain_placebo_p": 1.000,
        "calibrated_at":        "2026-05-19T00:00:00Z"
      },
      // 5 other precursors on arbitrum, one per calibrated configuration
    ]
  }
]

The user does not configure thresholds. The calibration values (smd_threshold_value, k_consecutive_hours, pctl_threshold, lead_hours) are derived by Invarians from the discovery corpus and seeded server-side. The agent only chooses its own decision policy on top of fires and the metadata.

The same payload supports several decision policies. The choice is the agent's, not Invarians'. Below are three reference policies in increasing order of permissiveness.

# Suitable for RWA settlement with low alert tolerance.
# Defer only on precursors whose calibration also held on another chain.
# With the 2025 ETH-ARB-CCTP and ETH-OP-CCTP corpora, no precursor
# currently passes this filter (all carry FAIL_on_X). Policy A is
# aspirational: it documents the bar a future precursor must clear
# to be acted on in this mode.

for p in panel.l2_by_chain("arbitrum").precursors:
    if p.is_firing and p.baseline_lift >= 2.0 and p.cross_chain_held:
        agent.defer(
            reason=f"strict precursor {p.axis} fired",
            horizon_hours=p.lead_hours,
        )

# Defer when any precursor on the relevant chain fires with lift >= 1.5.
# No cross-chain gating: the configuration is valid on the chain
# the agent is acting on, which is what matters operationally.
# This is the recommended default for most agent designs in 2025.

for p in panel.l2_by_chain("arbitrum").precursors:
    if p.is_firing and p.baseline_lift >= 1.5:
        agent.defer(
            reason=f"{p.axis} expects {p.outcome_category} in {p.lead_hours}h",
            expected_precision=p.baseline_precision,
            corridor_scope=p.bridge_corridor,
        )

# Flag any precursor with lift above unconditional baseline (lift > 1).
# Higher alert volume, lower precision per alert.
# Suitable for monitoring or human-in-the-loop scenarios where false
# positives are cheap and missed signals are expensive.

for p in panel.l2_by_chain("arbitrum").precursors:
    if p.is_firing and p.baseline_lift > 1.0:
        agent.flag(p)  # surface to operator, do not auto-defer

The payload exposes a single-hour fire check. If the calibration says k_consecutive_hours: 2, an agent that wants the full K-consecutive condition reads two consecutive panel responses (or polls at 1h intervals) and treats the configuration as fully engaged only when both reports return fires=true. The agent can implement this with a small state buffer:

from collections import deque

fire_history = deque(maxlen=2)  # for K=2; widen for larger K

def on_panel_response(panel):
    p = next(
        (p for p in panel.l2_by_chain("arbitrum").precursors
         if p.axis == "arb_struct_seq_publish_latency_shift"
         and p.lead_hours == 6),
        None,
    )
    if p is None:
        return
    fire_history.append(p.is_firing)
    if len(fire_history) == p.k_consecutive_hours and all(fire_history):
        agent.defer(reason="K-consecutive condition met", horizon_hours=p.lead_hours)

v3 removes the drift.* composite block from each entry. Per-metric shift, shift_delta, shift_magnitude_delta remain exposed on every MetricBlock as raw inputs. v3 is announced one release cycle in advance with the v2 drift block flagged deprecated_unvalidated: true on each entry root. Integrations relying on drift.demand_magnitude_delta > threshold migrate to iterating on precursors[] with one of the three policies above.

# Python, single-chain evaluation from the panel
def evaluate_chain(panel: dict, chain: str) -> str:
    # First: global panel freshness
    if panel["oracle_status"] != "OK":
        return "PANEL_DEGRADED"

    l1 = next((e for e in panel["panel"]["l1"] if e["chain"] == chain), None)
    l2 = next((e for e in panel["panel"]["l2"] if e["chain"] == chain), None)
    entry = l1 or l2

    if entry is None or entry["status"] != "OK":
        return "CHAIN_UNAVAILABLE"

    return entry["regime"]   # "S1D1" | "S1D2" | "S2D2" | "S2D1" | signed code (S1D2+, S1D2-, S1D2±, S2+D1, S2-D2±, ...)

import re
SIGNED_PATTERN = re.compile(r"^(S1|S2[+-])(D1|D2[+\-±])$")

def parse_regime(code):
    # Returns (structure_axis, demand_axis) where each is the prefix-stripped direction.
    # Legacy 4-state codes are mapped to their topological equivalent.
    legacy = {"S1D1": ("S1",  "D1"),
              "S1D2": ("S1",  "D2+"),
              "S2D1": ("S2+", "D1"),
              "S2D2": ("S2+", "D2+")}
    if code in legacy: return legacy[code]
    m = SIGNED_PATTERN.match(code)
    return (m.group(1), m.group(2)) if m else (None, None)

# Your agent decides, Invarians only reads the substrate
panel = client.get_panel_v2(chains=["ethereum"], include="core")
state_code = evaluate_chain(panel, "ethereum")
struct, demand = parse_regime(state_code)

if struct == "S1" and demand == "D1":
    handle_nominal()
elif demand == "D2+":
    handle_demand_high()                   # elevated demand, organic surge or coordinated buying
elif demand == "D2-":
    handle_demand_starvation()             # depressed demand, sequencer slowing or censorship of small transfers
elif demand == "D2±":
    handle_composition_split()             # size/tx asymmetry, agentic concentration signature
elif struct == "S2+":
    handle_structural_slowdown()           # rhythm degraded, sequencer or validator-side
elif struct == "S2-":
    handle_structural_acceleration()       # rhythm faster than baseline, infra change or client optimisation
else:
    fallback_behavior()                    # panel degraded, chain unavailable, or regime not yet calibrated

// JavaScript, multi-chain check from a single panel fetch
const checkAllChains = async () => {
  const panel = await getPanel();
  const all = [...panel.panel.l1, ...panel.panel.l2];

  return all.reduce((acc, entry) => {
    acc[entry.chain] = entry.status === "OK"
      ? { regime: entry.regime, status: entry.status }
      : { regime: null, status: entry.status };   // STALE | UNAVAILABLE | UNCALIBRATED
    return acc;
  }, {});
};

# Python, cross-chain agent pattern, panel API
panel = get_panel()

if panel["oracle_status"] == "DEGRADED":
    fallback()

l1 = next(e for e in panel["panel"]["l1"] if e["chain"] == "ethereum")
br = next(b for b in panel["panel"]["bridges"] if b["id"] == "arbitrum-ethereum/cctp")

# Your agent applies its own policy
if l1["regime"].startswith("S1") and br["state"] == "BS1":
    proceed()
elif br["status"] == "UNCALIBRATED":
    # Bridge classification deferred (CCIP), raw signal available in br["last_sequence_advance_seconds"]
    proceed_with_observation_only()
else:
    defer_execution()

Invarians produces three distinct primitives per query.

Primitive 1, Attestation: every panel response carries a HMAC-SHA256 envelope (payload_hash + signature + key_id + anchor) covering the full payload. Independently verifiable via POST /v2/verify. This is what makes the certified execution state provable, not just observable.

The execution policy is not prescribed. The agent reads the certified state and applies its own thresholds, risk tolerance, and fallback logic. Invarians certifies the infrastructure state, the decision belongs to the agent.

{
  "action": "execution_deferred",
  "reason": "L1 structural stress detected, ethereum regime S2D1",
  "invarians_proof": {
    // Excerpt of the panel entries relevant to the decision
    "l1":     { "chain": "ethereum", "regime": "S2D1", "status": "OK" },
    "l2":     { "chain": "arbitrum", "regime": "S1D1", "status": "OK" },
    "bridge": { "id": "arbitrum-ethereum/cctp", "state": "BS1", "calibrated": true },
    "signed_execution_context": {
      "payload_hash": "0x714b64...",
      "signature":    "hmac-sha256:9b5b1d...",
      "key_id":       "invarians-v1",
      "anchor":       null
    },
    "issued_at": "2026-04-20T10:00:00Z"
  }
}

Invarians tracks blockchain behavior under AI agent load and defines safe execution windows. Current monitoring scope:

Bridge classification scope is variable-latency surfaces only (Chainlink CCIP, Circle CCTP). Institutional RWA settlement moves stablecoins via CCTP and tokens via CCIP, both bidirectional.

Delta (Primitive 3) shift per metric is computed against the long-term EMA (~30-day baseline). For newly added structural observables (beacon_participation on ETH, sequencer_publish_latency on L2), shift_available: false until the slow EMA stabilizes (~30 days post-launch). The regime trigger uses raw ratio or seconds against calibrated bounds during this period.

401  Unauthorized    , invalid or missing API key
403  Forbidden       , key does not have access to this chain
404  Not Found       , no signal available for this chain
429  Too Many Requests, rate limit exceeded
500  Server Error    , internal error, retry after 60s

Use the /verify endpoint, no additional secret required, only your API key.

# POST /v2/verify
# Returns: { "valid": true|false, "key_id": "invarians-v1", "version": "2.0.0" }

import requests

# 1. Fetch a panel
r = requests.get(
    "https://api.invarians.com/v2/panel",
    headers={"Authorization": "Bearer YOUR_API_KEY"}
)
panel = r.json()
sig   = panel["signed_execution_context"]["signature"]

# 2. Verify the signature independently
#    Send the panel with signed_execution_context stripped + the signature.
payload = {k: v for k, v in panel.items() if k != "signed_execution_context"}

verify = requests.post(
    "https://api.invarians.com/v2/verify",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={"payload": payload, "signature": sig}
)
print(verify.json())
# → { "valid": true, "key_id": "invarians-v1", "version": "2.0.0" }

# Complete STALE handling, Python, panel API

from datetime import datetime, timezone

import requests

r = requests.get(
    "https://api.invarians.com/v2/panel",
    headers={"Authorization": "Bearer YOUR_API_KEY"}
)
panel = r.json()

def age_seconds(iso: str) -> float:
    return (datetime.now(timezone.utc) - datetime.fromisoformat(iso.replace("Z", "+00:00"))).total_seconds()

l1 = next(e for e in panel["panel"]["l1"] if e["chain"] == "ethereum")
br = next(b for b in panel["panel"]["bridges"] if b["id"] == "arbitrum-ethereum/cctp")

l1_age     = age_seconds(l1["computed_at"])
bridge_age = age_seconds(br["observed_at"]) if br["observed_at"] else 9999

if l1["status"] == "OK" and br["status"] in ("OK", "UNCALIBRATED"):
    # Fresh. Apply your own policy.
    if l1["regime"].startswith("S1") and br["state"] == "BS1":
        proceed()
    elif br["status"] == "UNCALIBRATED":
        proceed_with_observation_only()
    else:
        defer_execution()

elif l1["status"] == "STALE" and l1_age <= 7200:
    log_warning(f"L1 stale ({int(l1_age)}s), regime likely unchanged: {l1['regime']}")

else:
    log_warning(f"Infrastructure state unknown, deferring, global: {panel['oracle_status']}")

# Always log the full item state in the decision record
decision_log = {
    "oracle_status": panel["oracle_status"],
    "l1":            {"chain": l1["chain"], "regime": l1["regime"], "status": l1["status"], "computed_at": l1["computed_at"]},
    "bridge":        {"id": br["id"], "state": br["state"], "calibrated": br["calibrated"], "status": br["status"]},
    "issued_at":     panel["issued_at"],
    "payload_hash":  panel["signed_execution_context"]["payload_hash"],
}

# v1.1.0 client (deprecated)
from invarians import InvariansClient
client = InvariansClient(api_key="inv_...")
panel = client.get_panel()
eth = panel.l1_by_chain("ethereum")
print(eth.regime, eth.shifts.rhythm_shift)

# v2.0 client (recommended)
panel = client.get_panel_v2(
    chains=["ethereum"],
    bridges=["cctp"],
    include="diagnostic",
)
eth = panel.l1_by_chain("ethereum")
arb = panel.l2_by_chain("arbitrum")
print(eth.regime, eth.structural.rhythm.shift)
for p in arb.precursors:                       # v3 per-chain calibrated precursors
    print(p.axis, p.is_firing, p.baseline_lift)
print(eth.demand.tx.is_drifting_away)            # trend helper on raw shift

1. Upgrade SDK : pip install --upgrade "invarians>=0.5.0"
2. Replace client.get_panel(...) with client.get_panel_v2(chains=..., bridges=..., include=...)
3. Update field accessors : eth.structural.rhythm_ratio → eth.structural.rhythm.ratio, eth.shifts.rhythm_shift → eth.structural.rhythm.shift
4. If your agent uses execution_profile.index_a/b/c, switch to demand.sigma.ratio / demand.size.ratio / demand.tx.ratio
5. If your agent uses long-term EMA: structural_slow.rhythm_ratio_slow → structural.rhythm.ratio_long
6. Always specify chains= and bridges= filters (see Filters & Best Practices) — default behavior is to return all entries
7. Replace verify_panel() with verify_panel_v2()
8. Optional: consume the new drift composite and shift_magnitude_delta per-metric trends to make fitness-for-action decisions (see Primitive 3)