AEGIS technical documentation

AEGIS is a risk protocol for autonomous transactions. It underwrites the decision an AI agent is about to make, enforces the agent's mandate at the wallet, issues a verifiable proof-of-cover, and settles claims parametrically from escrowed capacity. This document specifies the system end to end: domain model, architecture, API surface, pricing engine, enforcement semantics, attestation format, claims logic, security posture and operational targets.

AEGIS is structured as a managing general agent (MGA): it prices, binds and services the risk under a binding authority, while regulated capacity is provided by partner (re)insurers. AEGIS never carries the risk on its own balance sheet. Premiums flow through safeguarded accounts; claims are paid from insurer-funded escrow.

Design principles

Insure the decision, not the transfer. Settlement rails are deterministic; agent decisions are probabilistic. The covered object is the decision — its mandate, its counterparty, its outcome — never the mechanics of the payment itself.

Reads are free, writes are priced. Verifying an attestation or reading a risk profile costs nothing and requires no account; that is how the standard spreads. Binding cover is where the premium lives.

Prevention before indemnity. Every policy condition that can be enforced mechanically is compiled into the agent's wallet. A blocked transaction is cheaper than a paid claim, for the client and for the loss ratio.

Capital-light by construction. The pricing engine, the data, and the gate are AEGIS assets; the balance sheet is rented. Risk passes through; loss data does not.

System context

Core concepts

Seven objects describe the whole domain. Every API resource, event and ledger row maps to one of them.

Cover scopes

Cover is written at one of two granularities. Transaction scope covers a single identified transfer — appropriate above roughly €50, where a per-decision premium is economically meaningful. Mandate scope covers everything an agent does inside one mandate for its lifetime (typically a session or a budget window) with an aggregate limit and per-event sublimits — the correct construction for micro-payments, where pricing a €0.10 API call individually is nonsense. The two scopes share the same policy object; only scope, the exposure base and the rate differ.

Covered perils

Exclusions. Market or price risk on delivered goods, losses caused by the principal's own instructions, gas and network fees, consequential damages, sanctioned counterparties, and losses on transactions executed while cover was suspended are outside cover. War/systemic-outage exclusions follow the capacity provider's treaty wording.

Policy lifecycle

Architecture

Six core services behind one gateway, an event backbone, and a thin on-chain footprint. Everything on the hot path is stateless and horizontally scaled; state lives in the policy ledger and the event log.

Request path

Service responsibilities & hot-path budgets

Consistency model: the policy ledger (Postgres) is the source of truth, written transactionally with an outbox; the event bus replicates state changes exactly-once to consumers (claims, data platform, webhooks). The attestation status served by the CDN is eventually consistent with a ≤5 s staleness bound — acceptable because attestations are short-lived and the bind path is strongly consistent.

Data platform

The loss ledger is the company. Every quote, bind, breach, settlement and claim is captured as an immutable event and flows into one governed pipeline that feeds pricing.

Events land on the bus under six topics — quotes, policies, enforcement.events, attestations, claims, ledger.anchors — and are materialised into an Iceberg lakehouse. A label pipeline joins policies to outcomes (clean expiry, breach, claim cause, paid amount) with a maturation window per peril, producing the supervised dataset. Features are defined once and served twice: offline for training, online (Redis) for the 60 ms inference budget, with automated online/offline parity checks.

Agent identifiers are pseudonymous keys; principal PII lives in a separate, access-controlled store and never enters the feature space. Model artifacts are versioned and signed in the registry; every quote records the exact model version and feature snapshot that priced it, making any historical price reproducible — an auditability requirement from both the capacity provider and the actuarial function.

Conventions

Base URL https://api.aegis.dev. All requests and responses are JSON, UTF-8. Amounts are integers in minor units (cents). Timestamps are RFC 3339 UTC.

Authentication

Server-to-server API keys: Authorization: Bearer sk_live_… (or sk_test_… against the sandbox). High-volume rails additionally sign each request — X-Aegis-Signature: t=<unix>,v1=HMAC_SHA256(secret, t + "." + body) — and may pin mTLS. Signatures older than 5 minutes are rejected (replay protection). The attestation verify endpoint requires no authentication.

Idempotency

All POST endpoints accept an Idempotency-Key header (UUID, 24 h window). Replays return the original result with Idempotent-Replay: true; a key reused with a different body returns 409 idempotency_conflict.

Environments & versioning

Sandbox is a full simulation including deterministic incident injection (X-Aegis-Simulate: prompt_injection). The API is versioned in the path (/v1); breaking changes ship as a new version with a 12-month overlap.

Endpoints

// 200 OK
{
  "quote_id": "qt_9fK2a",
  "scope": "transaction",
  "premium": { "amount": 480, "currency": "EUR" },
  "rate": "0.96%",
  "factors": { "base": "1.20%", "behaviour": "-0.42%", "exposure": "+0.18%" },
  "limit": 50000, "deductible": 500,
  "covered_perils": ["hallucination","prompt_injection","mandate_breach","non_delivery"],
  "expires_in": 90
}

// 201 Created
{
  "policy_id": "pol_3xQ7c", "status": "active",
  "enforcement": "wallet_hooks_v1",
  "conditions_hash": "sha256:9f2a…",
  "attestation_id": "att_71bd",
  "valid_until": "2026-07-03T21:04:11Z"
}

// 200 OK
{
  "attestation_id": "att_71bd", "policy_id": "pol_3xQ7c",
  "status": "valid",            // valid | suspended | revoked | expired
  "scope": "transaction", "limit": 50000, "currency": "EUR",
  "conditions_hash": "sha256:9f2a…",
  "valid_to": "2026-07-03T21:04:11Z",
  "jws": "eyJhbGciOiJFZERTQSIsImtpZCI6ImFlZ2lzLTIwMjYtMDcifQ…"
}

// 202 Accepted → webhook claim.paid | claim.denied | claim.review
{ "claim_id": "clm_5t1", "status": "verifying", "sla": "auto: minutes · review: 72h" }

Webhooks

All state changes are pushed. Deliveries are signed with the same HMAC scheme as inbound requests (X-Aegis-Signature), retried with exponential backoff for 24 h, and de-duplicated by event_id.

Errors & limits

Errors follow application/problem+json: {type, title, status, code, detail, request_id}. The code is stable and machine-matchable.

Pricing

A two-stage actuarial model — frequency × severity — served online in <60 ms, wrapped in rule overlays, with an additive factor decomposition returned on every quote.

Feature groups

Model & rate construction

Frequency is a gradient-boosted Poisson model per peril; severity is a Tweedie body with a generalized-Pareto tail fitted above a threshold to respect the fat-tailed loss regime. Expected loss is converted into a rate with a risk load and an expense load, then clamped:

# rate construction (illustrative — mirrors the public simulator)
E_loss   = Σ_peril  freq_p(x) × sev_p(x)
rate     = clamp( E_loss/exposure × (1+risk_load) + expense_load,  0.15%, 3.0% )
mandate  : aggregate rating ≈ 0.6 × per-tx rate, with per-event sublimits
output   : additive factors {base, behaviour, exposure} via grouped SHAP

Cold start & guardrails

With near-zero industry claims history, the engine opens with hierarchical priors by cohort (framework, rail, category) instead of per-agent estimates, and compensates uncertainty with structure rather than price alone: low limits, a 10% minimum deductible, mandatory cosigner_v1 or hooks for new agents, and co-insurance on the high tier. Every policy's outcome then tightens the priors — the cold start is the moat's on-ramp, not a bug.

Monitoring runs cohort loss ratios, calibration curves and PSI drift daily; champion/challenger models retrain weekly with actuarial sign-off, and a kill-switch reverts to a conservative static rate table if calibration degrades. Model versions are pinned per quote for full reproducibility.

Enforcement

The mandate is a small declarative document. Binding compiles it into the strongest control the agent's stack supports — turning pricing assumptions into physical impossibilities.

// mandate — the enforceable conditions object
{
  "max_amount": 50000,
  "currency": "EUR",
  "allowed_counterparties": ["cpy_af9", "cpy_x21"],
  "category_whitelist": ["cloud_compute", "logistics"],
  "velocity": { "window": "1h", "max_total": 200000, "max_count": 25 },
  "expiry": "2026-07-03T21:00:00Z",
  "fail_mode": "closed"
}

Enforcement modes

Semantics. Cover is in force if and only if all conditions held at execution time. A detected breach emits policy.suspended; cover over subsequent actions is void until cure, while the breached action itself becomes a claim under mandate_breach. fail_mode governs the hook's behaviour if the AEGIS status service is unreachable: closed (block, default above €500) or open (allow, cover suspended for that window). Hook modules are open-source, audited, and version-pinned in the policy — the wallet never trusts AEGIS blindly.

Attestation — proof-of-cover

A compact signed token that lets any counterparty answer one question — is this transaction insured, by whom, up to how much, under which conditions? — in one call or fully offline.

// JWS payload (header: {"alg":"EdDSA","kid":"aegis-2026-07"})
{
  "iss": "https://api.aegis.dev",
  "att": "att_71bd",  "sub": "pol_3xQ7c",  "agt": "agt_b12",
  "scope": "transaction",  "limit": 50000,  "cur": "EUR",
  "cnd": "sha256:9f2a…",
  "nbf": 1782847451,  "exp": 1782847751
}

Keys are Ed25519, held in KMS/HSM, published at /.well-known/aegis-jwks.json, and rotated monthly with overlapping validity. Tokens are deliberately short-lived (minutes to hours by scope); revocation therefore has a bounded blast radius, and the online status endpoint covers the residual window (status: suspended | revoked propagates to the CDN in ≤5 s).

Every issued attestation is appended to a Merkle transparency log whose root is anchored on-chain hourly. Anyone can request an inclusion proof (GET /v1/transparency/proof?att=…), which makes silent back-dating or selective denial of issuance cryptographically detectable — the property that lets competitors' counterparties trust the padlock without trusting the company.

Claims & settlement

Claims are parametric first: each peril has a mechanical trigger evaluated against the mandate, the hook logs and the on-chain trail. What verifies automatically pays in minutes from escrow; what doesn't goes to bounded human review.

Settlement. Auto-verified claims are paid from a per-cohort escrow pre-funded by the capacity provider (stablecoin for on-chain rails, trust account for fiat), median target 4–5 minutes. Payouts go to the counterparty through the original rail — never to a fresh address — which removes the incentive to fabricate incidents. Deductibles (default 10%, min €5) and high-tier co-insurance keep the principal exposed to a slice of every loss; per-agent aggregate limits cap tail exposure; paid claims feed experience rating immediately (trust_score ↓).

Fraud & disputes. A collusion graph screens agent↔counterparty pairs (shared funding sources, circular flows, synchronized creation); flagged claims route to review. Sanctions screening runs pre-payout. Denials carry a documented reason and a 30-day dispute window with an independent-arbitration fallback; AEGIS holds subrogation rights against recoverable third parties, exercised by the capacity provider.

Security & threat model

The interesting attacker here is economic, not just technical: the system must price adversaries who are themselves agents.

Baseline hygiene: least-privilege service IAM, secrets in KMS, encrypted at rest and in transit, dependency and container scanning in CI, external penetration test before GA, audited open-source hook modules, and a public vulnerability-disclosure policy.

Compliance

The regulatory position is deliberate: AEGIS is an insurance intermediary with delegated underwriting authority, not a carrier — the capital and the solvency obligations sit with regulated partners.

Insurance. AEGIS operates as an MGA/coverholder under a binding authority with an EU carrier (Solvency II), registered as an insurance intermediary under IDD (ORIAS in France) with EU passporting. Premium flows use safeguarded accounts with risk-transfer clauses in the binder; claims funds come from insurer escrow. Bordereaux and loss reporting follow the binder's schedule via the capacity gateway.

Financial crime. KYB on principals and platforms at onboarding; sanctions screening (EU/OFAC/UN) on counterparties before any payout; AEGIS holds no client funds outside safeguarded flows, keeping it outside e-money licensing at MVP.

Data. GDPR: agents are pseudonymous, principal PII is minimised and segregated, EU data residency, DPIA maintained, processors under DPAs. Retention follows insurance-record obligations (typically 5–10 years for policy and claim records).

EU AI Act. AEGIS is oversight tooling for deployers, who retain their Article 26 obligations; the pricing model is documented, monitored and human-supervised internally (model risk-management file, versioning, sign-off). For financial-sector clients, operational-resilience posture aligns with DORA (incident reporting, third-party register, tested continuity). Roadmap certifications: SOC 2 Type II, then ISO 27001.

Reliability & SLOs

Deployment: active in eu-west, warm standby in eu-central; RPO 5 min, RTO 30 min; game-days quarterly. The bias is explicit — fail conservative on writes, never fail on verification — because the padlock must be checkable even when the shop is closed.

Integrations

For rails & platforms (segment C)

Open a mandate-scope policy at session start, roll the premium into your existing fee line like interchange, and gate acceptance on the attestation. One middleware:

// accept-if-insured middleware (Node)
const ok = await aegis.verify(tx.attestation);
if (ok.status !== "valid" || ok.limit < tx.amount) return reject(tx, "uninsured");

For wallet & agent-framework vendors

Ship the audited hook module and expose aegis.quote()/bind() in the transaction path. Smart accounts get wallet_hooks_v1; anything else falls back to cosigner_v1 with no interface change.

For counterparties

No account needed: verify the attestation (one GET or offline JWS check against the published JWKS) and set your own acceptance floor — for example, require limit ≥ amount and scope = transaction above €1,000.

Glossary