DEVELOPERS

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

pip install invarians[requests]

from invarians import InvariansClient

client = InvariansClient(api_key="inv_your_key_here")
ctx = client.get_execution_context(l1="ethereum", l2="arbitrum")

# Structural stress — invisible to fee monitors
l2 = ctx.proof.l2_regime or ""
if ctx.proof.l1_regime.startswith("S2") or l2.startswith("S2"):
    pause_agent_execution()

print(ctx.proof.pattern_key)    # "S1D1×S1D2×BS1"
print(ctx.is_actionable())      # True
print(ctx.stale_action)         # "ok" | "caution" | "wait"

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

# Python — minimum integration
import requests

API_KEY = "inv_your_api_key"
BASE_URL = "https://sdpilypwumxsyyipceew.supabase.co/functions/v1/attestation"

def get_state(chain: str) -> dict:
    r = requests.get(
        f"{BASE_URL}/{chain}",
        headers={"Authorization": f"Bearer {API_KEY}"}
    )
    r.raise_for_status()
    return r.json()

state = get_state("ethereum")
print(state["regime"])           # "S1D1" | "S1D2" | "S2D2" | "S2D1"
print(state["oracle_status"])     # "OK" | "STALE"
print(state["data_age_seconds"])   # seconds since last data ingestion

// JavaScript / Node
const getState = async (chain) => {
  const res = await fetch(
    `https://sdpilypwumxsyyipceew.supabase.co/functions/v1/attestation/${chain}`,
    { headers: { Authorization: `Bearer ${API_KEY}` } }
  );
  return res.json();
};

const state = await getState("ethereum");
console.log(state.regime);           // "S1D1" | "S1D2" | "S2D2" | "S2D1"
console.log(state.oracle_status);    // "OK" | "STALE"

# Python — cross-chain execution context
def get_execution_context(from_chain: str, to_chain: str) -> dict:
    r = requests.get(
        f"{BASE_URL}/execution-context",
        params={"from": from_chain, "to": to_chain},
        headers={"Authorization": f"Bearer {API_KEY}"}
    )
    r.raise_for_status()
    return r.json()

ctx = get_execution_context("ethereum", "arbitrum")

# Primitive 1 — Proof of Execution Context
proof = ctx["proof_of_execution_context"]
print(proof["l1_regime"])              # "S1D1" | "S1D2" | "S2D2" | "S2D1" — L1 structural regime
print(proof["l2_regime"])              # "S1D1" | "S1D2" | "S2D2" | "S2D1" — L2 structural regime
print(proof["bridge_state"])          # "BS1" | "BS2"

# L2 — regime + execution profile
l2 = ctx["l2"]
print(l2["regime"])                     # "S1D1" | "S1D2" | "S2D2" | "S2D1"
print(l2["execution_profile"]["index_a"])
print(l2["execution_profile"]["index_b"])
print(l2["execution_profile"]["index_f"])

# Raw states — apply your own policy
l1_regime = proof["l1_regime"]     # "S1D1" | "S1D2" | "S2D1" | "S2D2"
l2_regime = proof["l2_regime"]     # "S1D1" | "S1D2" | "S2D1" | "S2D2"
bridge    = proof["bridge_state"]  # "BS1" | "BS2"
print(l1_regime, l2_regime, bridge)

Full response for Ethereum (ETH, Polygon, Avalanche — 5 dimensions, beacon available on ETH):

{
  "chain":              "ethereum",
  "oracle_status":     "OK",          // "OK" | "STALE" | "OFFLINE"
  "version":           "v2",

  // Layer 1 — Structural (slow, inertial)
  "structural": {
    "rhythm_ratio":      1.002,   // block timing / calibrated baseline
    "continuity_ratio":  1.000    // chain continuity / calibrated baseline
  },

  // Execution profile (reactive)
  "execution_profile": {
    "index_a":           1.225,   // normalized infrastructure metric
    "index_b":           1.083,   // normalized infrastructure metric
    "index_c":           1.051    // normalized infrastructure metric
  },

  // Divergence index
  "divergence_index":  -0.032,

  "regime":             "S1D2",   // S1D1 | S1D2 | S2D2 | S2D1

  // Calibration metadata
  "calibration": {
    "version":           "v2"
  },

  // ETH only: beacon chain participation
  "beacon": {
    "participation":     0.9987,
    "epoch":             318540,
    "age_seconds":       312
  },

  "data_age_seconds":   340,     // seconds since last data ingestion
  "l2_verified":       true,    // Ed25519 chain continuity verified
  "issued_at":          "2026-03-03T10:00:00.000Z",
  "expires_at":         "2026-03-03T11:00:00.000Z",
  "signature":          "inv_sig_..."
}

Solana differences (no beacon, per-chain calibration applied):

{
  "chain": "solana",
  // structural: same
  "execution_profile": {
    "index_b":  1.04,
    "index_c":  1.02
  },
  "calibration": {
    "version": "v2"
  }
  // beacon: absent on Solana
}

Response for GET /attestation/execution-context?from=ethereum&to=arbitrum:

{
  "oracle_status":  "OK",

  // Primitive 1 — Proof of Execution Context (certified, signed)
  "proof_of_execution_context": {
    "l1_regime":    "S1D2",   // L1 structural regime: S1D1 | S1D2 | S2D1 | S2D2
    "l2_regime":    "S1D1",   // L2 structural regime: S1D1 | S1D2 | S2D1 | S2D2
    "bridge_state": "BS1"    // Bridge state (BS1=nominal, BS2=congested) — collector live, oracle integration Q3 2026
  },

  // Detail — L1 layer
  "l1": {
    "chain":   "ethereum",
    "regime":  "S1D2",
    "structural": { "rhythm_ratio": 1.0001, "continuity_ratio": 1.000 },
    "execution_profile": { "index_a": 0.960, "index_b": 1.193, "index_c": 1.276 },
    "divergence_index": -0.032,
    "data_age_seconds": 1178
  },

  // Detail — L2 rollup (regime + structural + execution profile)
  "l2": {
    "chain":   "arbitrum",
    "regime":  "S1D1",   // L2 structural regime: S1D1 | S1D2 | S2D1 | S2D2
    "structural": {
      "rhythm_ratio":     1.000,
      "continuity_ratio": 1.000
    },
    "execution_profile": {
      "index_a":  1.000,   // normalized infrastructure metric
      "index_b":  1.002,   // normalized infrastructure metric
      "index_c":  1.008,   // normalized infrastructure metric
      "index_d":  1.023,   // normalized infrastructure metric
      "index_e":  1.041,   // normalized infrastructure metric
      "index_f":  4830,    // normalized infrastructure metric (raw)
      "index_g":  0.833,   // normalized infrastructure metric — BASE/OP
      "index_h":  312.4    // normalized infrastructure metric (raw)
    },
    "data_age_seconds": 2050
  },

  // Bridge (operational signal — Phase 2C ~April 2026)
  "bridge": {
    "state":      "BS1",
    "calibrated": false   // bridge calibration active Phase 2C
  },
  "bridge_calibrated": false,

  "data_age_seconds": 2050,
  "issued_at":       "2026-03-15T15:47:37Z",
  "expires_at":      "2026-03-15T16:47:37Z",
  "signature":       "inv_sig_..."
}

# Python — agent pattern
def evaluate_state(chain: str) -> str:
    state = get_state(chain)

    # First: always validate data freshness
    if state["oracle_status"] != "OK":
        return "DATA_UNAVAILABLE"

    if state.get("data_age_seconds", 9999) > 600:
        return "DATA_STALE"

    if not state.get("l2_verified", False):
        return "CHAIN_NOT_VERIFIED"

    return state["regime"]   # "S1D1" | "S1D2" | "S2D2" | "S2D1"

# Your agent decides — Invarians only reads the substrate
state_code = evaluate_state("ethereum")

if state_code == "S1D1":
    handle_nominal()
elif state_code == "S1D2":
    handle_charge()
elif state_code == "S2D2":
    handle_risk()
elif state_code == "S2D1":
    handle_anomaly()
else:
    fallback_behavior()                    # data unavailable / stale

// JavaScript — multi-chain check
const checkAllChains = async () => {
  const chains = ["ethereum", "polygon", "solana", "avalanche"];
  const results = await Promise.allSettled(chains.map(getState));

  return results.reduce((acc, r, i) => {
    acc[chains[i]] = r.status === "fulfilled"
      ? { regime: r.value.regime, status: r.value.oracle_status }
      : { regime: "OFFLINE", status: "ERROR" };
    return acc;
  }, {});
};

# Python — cross-chain agent pattern with raw states
ctx = get_execution_context("ethereum", "arbitrum")

if ctx["oracle_status"] != "OK":
    fallback()

l1_regime = ctx["proof_of_execution_context"]["l1_regime"]     # S1D1 | S1D2 | S2D1 | S2D2
bridge    = ctx["proof_of_execution_context"]["bridge_state"]  # BS1 | BS2
# Your agent applies its own policy
if l1_regime.startswith("S1") and bridge == "BS1":
    proceed()
else:
    defer_execution()

Invarians produces two distinct primitives per query.

Primitive 1 — Proof of Execution Context: the certified infrastructure state at the moment of query. L1 structural regime · L2 rollup execution profile · Bridge state. HMAC-SHA256 signed, timestamped, independently verifiable via /verify.

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 — l1_regime S2D1",
  "invarians_proof": {
    "proof_of_execution_context": {
      "l1_regime":    "S2D1",   // L1 structural stress
      "l2_regime":    "S1D1",
      "bridge_state": "BS1"
    },
    "issued_at": "2026-03-15T10:00:00Z",
    "signature": "inv_sig_..."
  }
}

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 /attestation/verify
# Returns: { "valid": true|false, "expired": true|false }

import requests

# 1. Fetch an attestation
r = requests.get(
    "https://sdpilypwumxsyyipceew.supabase.co/functions/v1/attestation/ethereum",
    headers={"Authorization": "Bearer YOUR_API_KEY"}
)
data = r.json()
# data = { "regime": "S1D1", "signature": "inv_sig_...", "expires_at": "...", ... }

# 2. Verify the signature independently
verify = requests.post(
    "https://sdpilypwumxsyyipceew.supabase.co/functions/v1/attestation/verify",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={
        "attestation": {k: v for k, v in data.items() if k != "signature"},
        "signature": data["signature"]
    }
)
print(verify.json())
# → { "valid": true, "expired": false }

# Complete STALE handling — Python

import requests

r = requests.get(
    "https://sdpilypwumxsyyipceew.supabase.co/functions/v1/attestation/execution-context",
    params={"from": "ethereum", "to": "arbitrum"},
    headers={"Authorization": "Bearer YOUR_API_KEY"}
)
data = r.json()

oracle_status    = data.get("oracle_status", "STALE")
data_age_seconds = data.get("data_age_seconds", 9999)
proof            = data.get("proof_of_execution_context", {})
l1_regime        = proof.get("l1_regime", "UNKNOWN")    # S1D1 | S1D2 | S2D1 | S2D2
bridge           = proof.get("bridge_state", "UNKNOWN") # BS1 | BS2

if oracle_status == "OK":
    # Fresh signal — full confidence — apply your own policy
    if l1_regime.startswith("S1") and bridge == "BS1":
        proceed()
    else:
        defer_execution()

elif data_age_seconds <= 7200:
    # STALE < 2h — regime likely unchanged, proceed with caution
    log_warning(f"Signal stale ({data_age_seconds}s) — using last known l1_regime {l1_regime}")

else:
    # STALE > 2h — infrastructure state unknown
    log_warning(f"Signal stale ({data_age_seconds}s) — deferring, state unknown")

# Always log staleness in decision record
decision_log = {
    "l1_regime":          l1_regime,
    "bridge_state":       bridge,
    "oracle_status":      oracle_status,
    "data_age_seconds":   data_age_seconds,
    "issued_at":          data.get("issued_at"),
}