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 + drift signal 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: drift signal (is the regime persisting or reverting?)
if eth.drift.demand > 0.05 and eth.drift.demand_magnitude_delta > 0:
    defer_action()            # transition imminent, deviation amplifying

# 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
print(panel["panel"]["l1"][0]["drift"]["demand"])              # composite drift magnitude
print(panel["panel"]["l1"][0]["drift"]["demand_magnitude_delta"])  # > 0 deviation amplifies, < 0 reverts
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: drift signal (axis-grouped, per-metric blocks)
print(l1["drift"]["structural"],
      l1["drift"]["demand"])                # composite drift magnitudes per axis
print(l1["demand"]["sigma"]["shift"])           # per-metric current deviation
print(l1["demand"]["sigma"]["shift_magnitude_delta"])  # trend: amplifying or reverting

# 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, just regime + status + drift composite

# Drift-aware decision (full trend signal)
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 }
        },

        // Composite drift per axis (max |shift| over classifying observables, with delta + magnitude_delta)
        "drift": {
          "structural":                 0.0017,
          "structural_delta":           0.0008,
          "structural_magnitude_delta": 0.0008,
          "demand":                     0.04,
          "demand_delta":              -0.012,
          "demand_magnitude_delta":     0.018
        }
      }
    ],

    // 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 }
        },

        "drift": {
          "structural": 0.009, "structural_delta": 0.001, "structural_magnitude_delta": 0.001,
          "demand":     0.10,  "demand_delta":     -0.02,  "demand_magnitude_delta":     0.02
        }
      }
      // + base, optimism (same shape)
    ],

    // 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 Drift Signal answers is it safe to act in the next 30 minutes. 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:

"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
}

# 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.

Drift Signal (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")
print(eth.regime, eth.structural.rhythm.shift)
print(eth.drift.demand)                          # NEW: composite drift magnitude
print(eth.demand.tx.is_drifting_away)            # NEW: trend helper

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)