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
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
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
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
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)
{
"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
{
"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_calibrated: false is exposed in responses to let agents detect this placeholder.
06
Chain coverage
| Chain | Type | Regime | Status |
|---|---|---|---|
| Ethereum | L1 | S1D1 · S1D2 · S2D1 · S2D2 | Live |
| Polygon | L1 | S1D1 · S1D2 · S2D1 · S2D2 | Live |
| Solana | L1 | S1D1 · S1D2 · S2D1 · S2D2 | Live: π confidence LOW |
| Avalanche | L1 | S1D1 · S1D2 · S2D1 · S2D2 | Live: backtest pending |
| Arbitrum | L2 | Execution profile | Live |
| Base | L2 | Execution profile | Live: baseline stabilizing ~April 2026 |
| Optimism | L2 | Execution profile | Live: baseline stabilizing ~April 2026 |
L1 and L2 signals vary by chain architecture. Signal methodology is not publicly documented.
07
Key fields
| Field | Description |
|---|---|
regime | Certified regime: S1D1 / S1D2 / S2D1 / S2D2 |
oracle_status | Signal freshness: OK / STALE / OFFLINE |
data_age_seconds | Seconds since last data ingestion: always validate before acting |
structural.rhythm_ratio | Normalized structural index. ≈1.0 nominal: feeds S1/S2 classification |
structural.continuity_ratio | Normalized structural index: feeds S1/S2 classification |
execution_profile.index_a | Normalized infrastructure metric |
execution_profile.index_b | Normalized infrastructure metric |
execution_profile.index_c | Normalized infrastructure metric: feeds D1/D2 classification |
divergence_index | Continuous divergence index: complement to SxDx classification |
l2_verified | Ed25519 chain continuity verified. If false, do not use the signal. |
beacon.participation | ETH only: beacon chain participation rate. Low = network health alert |
signature | HMAC-SHA256 attestation signature: verifiable via /verify |
08
Agent integration pattern
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
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. |
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.
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
| Code | Meaning |
|---|---|
401 | Invalid or missing API key |
403 | Key does not have access to this chain |
404 | No signal available for this chain |
429 | Rate limit exceeded |
500 | Internal error: retry after 60s |