API Reference

Execution Context API

Signed structural attestations covering L1 regime, L2 execution profile and bridge state, delivered to autonomous agents at the moment of execution.

01

Quick start

Base URL

https://sdpilypwumxsyyipceew.supabase.co/functions/v1/attestation
Python: minimum integration Python
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" | "S2D1" | "S2D2"
print(state["oracle_status"])     # "OK" | "STALE" | "OFFLINE"
print(state["data_age_seconds"])  # seconds since last data ingestion
JavaScript: minimum integration JavaScript
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" | "S2D1" | "S2D2"
console.log(state.oracle_status)   // "OK" | "STALE" | "OFFLINE"

02

Endpoints

GET /attestation/{chain} L1 regime: ethereum · polygon · solana · avalanche
GET /attestation/l2/{chain} L2 execution profile: arbitrum · base · optimism
GET /attestation/execution-context?from={l1}&to={l2} Cross-chain: L1 + L2 + bridge in one call
POST /attestation/verify Verify HMAC-SHA256 signature

Valid cross-chain pairs: ethereum → arbitrum · ethereum → base · ethereum → optimism

03

Authentication

Pass your API key as a Bearer token in every request.

Authorization: Bearer inv_your_api_key
For CRE workflows: use runtime.getSecret("inVariansApiKey") to inject the key at runtime rather than embedding it in config. See CRE Integration for the full pattern.

04

Response format

L1 response (Ethereum)

GET /attestation/ethereum JSON
{
  "chain":              "ethereum",
  "oracle_status":      "OK",          // "OK" | "STALE" | "OFFLINE"
  "regime":             "S1D2",        // S1D1 | S1D2 | S2D1 | S2D2
  "version":            "v2",

  "structural": {
    "rhythm_ratio":     1.002,         // normalized structural index
    "continuity_ratio": 1.000          // normalized structural index
  },

  "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":   -0.032,        // cross-layer divergence
  "data_age_seconds":   340,           // seconds since last ingestion: always check
  "l2_verified":        true,          // Ed25519 chain continuity verified

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

  "issued_at":          "2026-03-03T10:00:00.000Z",
  "expires_at":         "2026-03-03T11:00:00.000Z",
  "signature":          "inv_sig_..."
}

Cross-chain execution context

GET /attestation/execution-context?from=ethereum&to=arbitrum JSON
{
  "oracle_status":  "OK",

  "proof_of_execution_context": {  // certified, signed
    "l1_regime":    "S1D2",          // S1D1 | S1D2 | S2D1 | S2D2
    "bridge_state": "BS1"            // BS1=nominal: BS2 integration Q2 2026
  },

  "l1": {
    "chain":            "ethereum",
    "regime":           "S1D2",
    "data_age_seconds": 1178
  },

  "l2": {
    "chain":              "arbitrum",
    "execution_profile": {
      "index_a": 1.000, "index_b": 1.002, "index_c": 1.008,
      "index_d": 1.023, "index_e": 1.041
    },
    "data_age_seconds":   2050
  },

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

05

Regimes: SxDx framework

Two orthogonal axes: structural (τ) and demand (π): each independently classified. L1 and L2 are classified independently.

State Meaning For an agent
S1D1 Structural + demand within baseline Standard conditions. Nominal execution.
S1D2 Demand elevated, structure intact Congestion pressure. Gas costs higher. No structural risk.
S2D1 Structural stress, demand normal Sequencer degradation: invisible to fee monitors. High-value operations should defer.
S2D2 Structural stress + elevated demand Both axes stressed simultaneously. Maximum caution.
Bridge Meaning
BS1 Bridge nominal: posting latency within baseline
BS2 Bridge degraded: abnormal posting latency or gap detected
Bridge status: BS1 is currently hardcoded. The bridge collector is live and collecting data (deployed 2026-03-22). BS2 emission begins after 30-day calibration: ~Q2 2026. The field bridge_calibrated: false is exposed in responses to let agents detect this placeholder.

06

Chain coverage

Chain Type Regime Status
EthereumL1S1D1 · S1D2 · S2D1 · S2D2Live
PolygonL1S1D1 · S1D2 · S2D1 · S2D2Live
SolanaL1S1D1 · S1D2 · S2D1 · S2D2Live: π confidence LOW
AvalancheL1S1D1 · S1D2 · S2D1 · S2D2Live: backtest pending
ArbitrumL2Execution profileLive
BaseL2Execution profileLive: baseline stabilizing ~April 2026
OptimismL2Execution profileLive: baseline stabilizing ~April 2026

L1 and L2 signals vary by chain architecture. Signal methodology is not publicly documented.

07

Key fields

Field Description
regimeCertified regime: S1D1 / S1D2 / S2D1 / S2D2
oracle_statusSignal freshness: OK / STALE / OFFLINE
data_age_secondsSeconds since last data ingestion: always validate before acting
structural.rhythm_ratioNormalized structural index. ≈1.0 nominal: feeds S1/S2 classification
structural.continuity_ratioNormalized structural index: feeds S1/S2 classification
execution_profile.index_aNormalized infrastructure metric
execution_profile.index_bNormalized infrastructure metric
execution_profile.index_cNormalized infrastructure metric: feeds D1/D2 classification
divergence_indexContinuous divergence index: complement to SxDx classification
l2_verifiedEd25519 chain continuity verified. If false, do not use the signal.
beacon.participationETH only: beacon chain participation rate. Low = network health alert
signatureHMAC-SHA256 attestation signature: verifiable via /verify

08

Agent integration pattern

Principle: Invarians certifies execution state: it does not prescribe actions. Interpretation and execution logic remain entirely with your agent.
Python: single-chain agent pattern Python
def evaluate_state(chain: str) -> str:
    state = get_state(chain)

    # Always validate freshness first
    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" | "S2D1" | "S2D2"

code = evaluate_state("ethereum")

if   code == "S1D1": handle_nominal()
elif code == "S1D2": handle_charge()
elif code == "S2D1": handle_anomaly()   # structural: invisible to fee monitors
elif code == "S2D2": handle_risk()
else:                  fallback()         # data unavailable / stale
Python: cross-chain execution context Python
ctx = get_execution_context("ethereum", "arbitrum")

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

proof     = ctx["proof_of_execution_context"]
l1_regime = proof["l1_regime"]    # S1D1 | S1D2 | S2D1 | S2D2
bridge    = proof["bridge_state"]  # BS1 | BS2

if l1_regime.startswith("S1") and bridge == "BS1":
    proceed()
else:
    defer_execution()

09

Handling stale signals

Every attestation includes oracle_status and data_age_seconds. STALE does not mean the regime has changed: structural regimes take ~3 hours to change. A signal stale for 30 minutes is likely still valid, but carries uncertainty.

data_age_seconds oracle_status Confidence Recommended behavior
< 3600 OK High Execute normally.
3600 – 7200 STALE Medium Use last known regime with caution. Log the staleness. Avoid new high-value positions.
> 7200 STALE Low State unknown. Proceed at agent's discretion with explicit staleness flag in decision log.
Python: complete STALE handling Python
data          = get_state("ethereum")
oracle_status = data.get("oracle_status", "STALE")
data_age_s    = data.get("data_age_seconds", 9999)
regime        = data.get("regime", "UNKNOWN")

if oracle_status == "OK":
    apply_regime_policy(regime)

elif data_age_s <= 7200:
    log_warning(f"Signal stale ({data_age_s}s): using last known regime {regime}")
    apply_regime_policy(regime)  # at agent's discretion

else:
    log_warning(f"Signal stale ({data_age_s}s): deferring, state unknown")
    fallback()

10

Signature verification

Every attestation includes a signature field (HMAC-SHA256, prefixed inv_sig_...). Use the /verify endpoint to confirm the attestation was issued by Invarians and has not been altered.

POST /attestation/verify Python
data = get_state("ethereum")

verify = requests.post(
    "https://sdpilypwumxsyyipceew.supabase.co/functions/v1/attestation/verify",
    headers={"Authorization": f"Bearer {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 }

Note: an expired attestation (expired: true) may still have valid: true. Always check both fields. Valid confirms integrity: not freshness.

11

Errors

CodeMeaning
401Invalid or missing API key
403Key does not have access to this chain
404No signal available for this chain
429Rate limit exceeded
500Internal error: retry after 60s