Skip to content

cryptYP/ActuaryOS

BranchesTags

Repository files navigation

ActuaryOS

AI-native actuarial infrastructure for programmable insurance pools, reserve analytics, and automated stablecoin payouts.

"Instead of building another crypto dashboard, we built a modern operating system for pooled risk, reserve management, and automated payouts."

The Problem

Insurance underwriting is slow. Reserve management is opaque. Claims and payouts are operationally heavy. Microinsurance and parametric products are underbuilt. Pooled capital is hard to track. Small insurers, MGAs, mutual aid systems, and experimental risk pools lack modern programmable infrastructure.

Traditional insurance software is monolithic, closed-source, and designed for enterprise incumbents. There is no open, composable stack for building programmable insurance products on modern rails.

The Solution

ActuaryOS turns programmable finance rails into real-world actuarial infrastructure. By combining AI underwriting, XRPL settlement, and a Liquid-powered reserve terminal, ActuaryOS gives insurers and experimental risk pools a programmable back office.

Every decision is explainable. Every transaction is auditable. Every payout is on-chain.

MVP: Flight Delay Parametric Insurance

The MVP demonstrates the full lifecycle of a parametric insurance product using flight delay as the trigger:

  1. Pool Creation -- An operator creates a named insurance pool with coverage type, reserve targets, and payout rules. A reserve account is automatically provisioned.

  2. Capital Deposit -- Capital providers deposit RLUSD into the pool's reserve account. Each deposit is tracked on-chain via XRPL and recorded in the audit log.

  3. Quote Generation -- A policyholder submits flight details (flight number, route, departure date, requested payout, trigger threshold). The actuarial engine runs a 6-step pipeline: historical delay rate lookup, weather risk assessment, flight risk scoring (seasonal/airline/weather factors), premium calculation (expected loss + risk load + expense load + buffer), reserve impact analysis, and concentration scoring. Gemini extracts structured features; Anthropic generates a human-readable underwriting memo. The system returns a priced quote with recommendation (approve/review/decline), confidence band, risk drivers, and warnings.

  4. Policy Purchase -- The policyholder accepts the quote. A premium payment intent is created on XRPL. Reserves are earmarked (moved from available to locked). The policy is issued and the quote is bound.

  5. Trigger Event -- A flight delay event is ingested (or simulated). The trigger service matches the event against all active policies for that flight and departure date.

  6. Claim Evaluation -- For each matched policy, the claim service checks whether the actual delay meets the trigger threshold. If the trigger is met, the claim is auto-approved and a payout intent is created. Anthropic generates a claims decision memo for the audit trail.

  7. RLUSD Payout -- The settlement service executes the payout via XRPL, records the chain transaction, creates a settlement event, releases locked reserves, and updates the claim status to "paid".

  8. Reserve Rebalancing -- The reserve terminal (powered by the Liquid adapter) allows operators to quote and execute deployment of surplus capital or unwind positions, with post-action solvency projections.

Architecture

+---------------------------------------------------+
|              Next.js 15 Frontend                   |
|  Dashboard | Underwrite | Terminal | Claims        |
+------------------------+--------------------------+
                         |
                    API Routes
                  (thin handlers)
                         |
+------------------------v--------------------------+
|              Service Layer (14 services)            |
|  Pool | Quote | Policy | Claim | Payout | Reserve  |
|  Trigger | Settlement | LiquidReserve | Dashboard  |
|  Underwriting | AiOrchestration | Audit | Events   |
+----+------------+---------------+-----------------+
     |            |               |
+----v----+ +----v----+   +------v-------+
|Actuarial| |   AI    |   |   Adapters   |
| Engine  | |Gemini + |   | XRPL |Liquid |
| 6 mods  | |Anthropic|   | Flight Data  |
+---------+ +---------+   +--------------+
     |            |               |
     +------------+---------------+
                  |
           +------v------+
           |  PostgreSQL  |
           |  (Drizzle)   |
           |  23 tables   |
           +-------------+

Monorepo Structure

ActuaryOS/
  apps/
    web/              Next.js 15 app (frontend + API routes)
  packages/
    types/            Domain entities, enums, API schemas (Zod), adapter interfaces
    actuarial/        Pure actuarial engine (pricing, reserve, solvency, concentration, flight-risk, underwriting)
    adapters/         XRPL (mock + live), Liquid (mock), Flight Data (mock)
    ai/               Gemini provider, Anthropic provider, Mock provider, prompt templates
    config/           Zod-validated env config, AdapterRegistry factory
    core/             14 service modules, EventBus, error types, ServiceContext DI
    data/             Drizzle ORM schema (23 tables), repositories, seed script, migrations

Sponsor Integrations

Ripple / XRPL

  • RLUSD premium payments: Every policy purchase creates an XRPL payment intent for the premium amount in RLUSD
  • Claim payouts: Approved claims are settled on-chain via XRPL with full transaction recording
  • Escrow-based reserve locking: XrplAdapter interface includes createEscrow and releaseEscrow for conditional reserve locking
  • Auditable transaction timeline: Every XRPL transaction is recorded in chain_transactions with txHash, ledger index, explorer URL, and memo
  • Live adapter: XrplLiveAdapter connects to XRPL testnet via WebSocket, uses the official xrpl SDK (v4.4.0), supports Payment and EscrowCreate transaction types
  • Account queries: getAccountInfo and getAccountTransactions for balance and history lookups

Liquid Network (Blockstream)

  • Reserve Terminal: Trading-adjacent capital allocation interface for deploying idle reserves
  • Quote/deploy/unwind workflow: Operators can quote a reserve deployment (with estimated cost, slippage, and yield), execute it, or unwind positions
  • Strategy selection: Conservative (3.5% yield), balanced (6.2%), aggressive (11.8%) deployment strategies
  • Post-action projections: Every reserve action shows projected reserve ratio and solvency buffer after execution
  • Market snapshots: Real-time liquidity, utilization rate, yield, and volatility data from the Liquid adapter

Anthropic (Claude)

  • Underwriting memos: Formal actuarial reasoning memos generated for every quote, covering risk drivers, premium adequacy, reserve impact, concentration risk, scenario sensitivity, and recommendation rationale
  • Claims decision memos: Structured claims evaluation documents explaining trigger evaluation, payout determination, financial impact, and decision rationale
  • Reserve health memos: Pool-level reserve adequacy analysis with stress test commentary and risk flags
  • Audit trail: Every AI-generated memo is stored as an AiArtifact linked to an AiRun record with provider, model, token usage, and duration

Google (Gemini)

  • Structured feature extraction: Parses raw application text into typed underwriting features (flight number, airline, origin, destination, departure date, trigger threshold, requested payout, coverage type)
  • Event data normalization: Extracts structured fields from unstructured flight delay data
  • Dual-AI pipeline: Gemini handles extraction (fast, structured), Anthropic handles reasoning (deep, narrative)

How This Maps to Hackathon Tracks

Best Overall

  • Real-world actuarial platform solving genuine insurance infrastructure gaps
  • Clean TypeScript monorepo with typed services, adapter patterns, and domain-driven design
  • 120+ unit tests across actuarial engine, adapter conformance, and AI provider mocks
  • AI explainability at every decision point -- every underwriting, claims, and reserve decision includes a human-readable memo
  • Full audit trail with 16 domain event types, automatic EventBus-to-audit-log bridging, and correlation IDs for traceability
  • 23-table relational schema with Drizzle ORM, proper foreign keys, indexes, and relations

Ripple Track

  • XRPL as the settlement ledger for RLUSD premiums and payouts
  • Multiple XRPL primitives: Payment, EscrowCreate, EscrowFinish, account_info, account_tx
  • Live adapter with testnet support (XrplLiveAdapter using xrpl v4.4.0)
  • Every transaction generates an audit log entry, chain_transactions record, and UI timeline event
  • Mock adapter with deterministic behavior for reliable demo and testing

Liquid Track

  • Reserve Terminal: novel trading-adjacent interface for capital allocation
  • Quote -> execute deployment/unwind workflow with slippage and cost estimation
  • Strategy-based reserve optimization (conservative/balanced/aggressive)
  • Post-action solvency projections ensure reserve floor is never breached
  • Market snapshot API for liquidity and yield monitoring

Tech Stack

Layer Technology Why
Frontend Next.js 15, React 19, Tailwind, shadcn/ui App Router, dark mode, institutional feel
State Zustand, React Query Minimal boilerplate, server state management
Charts Recharts Composable, React-native charts
Backend Next.js Route Handlers Zero CORS, single deployable, Vercel-ready
Database PostgreSQL + Drizzle ORM Relational, migration-safe, type-safe queries
Blockchain xrpl 4.4.0 Official XRPL SDK, testnet support
AI @google/genai, @anthropic-ai/sdk Dual AI: extraction + reasoning
Testing Vitest Fast, native ESM support
Monorepo pnpm workspaces Lightweight, reliable

Dependency Manifest

Package Version Purpose Sponsor-Critical
xrpl 4.4.0 XRPL blockchain interaction Yes (Ripple)
@google/genai 1.5.0 Gemini AI provider Yes (Google)
@anthropic-ai/sdk 0.39.0 Claude AI provider Yes (Anthropic)
next 15.1.6 Full-stack framework No
drizzle-orm 0.38.4 Database ORM No
zod 3.24.2 Schema validation No
recharts 2.15.1 Data visualization No
zustand 5.0.3 Client state No
@tanstack/react-query 5.66.0 Server state No
framer-motion 12.4.7 Animations No
react-hook-form 7.54.2 Form handling No

Setup

Prerequisites

  • Node.js 20+
  • pnpm 9+
  • Docker (for PostgreSQL)

Quick Start

git clone <repo>
cd ActuaryOS
cp .env.example .env
docker compose up -d
pnpm install
pnpm db:generate
pnpm db:migrate
pnpm db:seed
pnpm dev

Open http://localhost:3000

Environment Variables

Variable Default Description
DATABASE_URL postgresql://actuaryos:actuaryos@localhost:5432/actuaryos PostgreSQL connection string
XRPL_ADAPTER mock mock or live -- controls XRPL adapter selection
LIQUID_ADAPTER mock mock or live -- controls Liquid adapter selection
AI_PROVIDER mock mock or live -- controls AI provider selection
FLIGHT_DATA_ADAPTER mock mock or live -- controls flight data adapter
XRPL_NETWORK testnet mainnet, testnet, or devnet
XRPL_WSS_URL wss://s.altnet.rippletest.net:51233 XRPL WebSocket endpoint
XRPL_OPERATOR_SEED -- XRPL wallet seed for the operator account (required for live)
XRPL_RLUSD_ISSUER -- RLUSD issuer address on XRPL (required for live RLUSD payments)
GEMINI_API_KEY -- Google Gemini API key (required when AI_PROVIDER=live)
ANTHROPIC_API_KEY -- Anthropic API key (required when AI_PROVIDER=live)
ANTHROPIC_MODEL claude-sonnet-4-20250514 Anthropic model ID
GEMINI_MODEL gemini-2.5-flash Gemini model ID
NEXT_PUBLIC_APP_URL http://localhost:3000 Public URL of the application
NODE_ENV development Runtime environment

Running Tests

pnpm test          # All tests (actuarial, adapters, AI)
pnpm test:unit     # Unit tests only
pnpm smoke         # End-to-end smoke test against running API

What's Mocked vs Live

Integration Status Notes
XRPL Payments Live (testnet) when XRPL_ADAPTER=live MockXrplAdapter for dev with deterministic tx hashes
XRPL Escrow Interface defined, mock implemented Live calls via EscrowCreate/EscrowFinish ready
Liquid Mocked MockLiquidAdapter with realistic cost/slippage/yield fixtures
Gemini Live when AI_PROVIDER=live Feature extraction and parsing
Anthropic Live when AI_PROVIDER=live Reasoning memos (underwriting, claims, reserve)
Flight Data Mocked Deterministic fixtures by airline code (UA, DL, AA, SW)

Limitations

  • Flight data uses mock fixtures with airline-specific delay profiles (no live API in MVP)
  • Liquid SDK integration uses mock adapter with realistic but simulated market data
  • XRPL escrow primitives are architected and mocked but not yet connected to live reserve locking
  • Single-tenant in MVP (one organization, demo users)
  • No real wallet signing UX (demo wallet mode -- premium and payout transactions are operator-signed)
  • AI memos are best-effort -- quote generation and claim evaluation succeed even if AI providers fail

Future Work

  • Live flight data provider integration (FlightAware, AviationStack, or Cirium)
  • Multi-coverage product support (weather, shipping, event cancellation)
  • XRPL credentials-based pool permissions for permissioned capital pools
  • Portfolio exposure heatmaps with geographic and temporal visualization
  • Multi-tenant organization support with role-based access control
  • Exportable regulator/auditor reports in PDF format
  • Live Liquid Network integration for real reserve deployment
  • Tiered payout structures (30-60 min = 50%, 60-120 min = 75%, 120+ min = 100%)
  • WebSocket-based real-time dashboard updates via EventBus

About

AI-native actuarial infrastructure for programmable insurance pools, reserve analytics, and automated stablecoin payouts

Resources

Readme
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

2 tags

Packages

 
 
 

Contributors

Languages