Haima

Haima — Agentic Finance Engine

Broomva Stack Layer 6 (Platform) — part of the 24-skill Broomva Stack. Repo: github.com/broomva/haima | Part of: Life Agent OS

Haima (αἷμα, Greek for "blood") is the circulatory system of the Agent OS — it distributes economic resources throughout the organism. Agents can pay for external resources, charge for completed tasks, and maintain sovereign wallets, all through standard HTTP via the x402 protocol.

Core Concept

Every agent has an economic identity backed by a secp256k1 keypair and an on-chain wallet (USDC on Base). The x402 protocol activates HTTP's dormant 402 Payment Required status code: when an agent encounters a 402 response, Haima automatically evaluates payment policy, signs a cryptographic authorization, and retries — settling on-chain in under 2 seconds.

Three Financial Primitives

1. Pay — Agent pays for external resources (API calls, data feeds, compute)
2. Charge — Agent prices completed tasks and collects revenue
3. Account — On-chain balance synced with Autonomic's economic state

Quick Start

For an existing Life/Arcan project

# Haima runs as a companion daemon alongside Arcan and Autonomic
cargo run -p haimad -- --bind 127.0.0.1:3003

# With Lago persistence
cargo run -p haimad -- --bind 127.0.0.1:3003 --lago-data-dir /path/to/data

Adding x402 payments to an agent tool

When Arcan's tool harness encounters an HTTP 402 during tool execution:

1. Parse the PAYMENT-REQUIRED header → PaymentRequest
2. Evaluate against PaymentPolicy:
   • ≤100 micro-credits ($0.0001) → auto-approve
   • 101 to 1,000,000 micro-credits ($1.00) → require human approval (via ApprovalPort)
   • >1,000,000 micro-credits → deny
3. If approved: sign with WalletBackend → retry with PAYMENT-SIGNATURE
4. Record finance.payment_settled event to Lago

Billing for agent services

Agent completes task → finance.task_billed event (price + description)
  → x402 server middleware returns 402 to requesting client
  → Client pays → finance.revenue_received → balance increases

Architecture

Crate Structure

haima/
├── crates/
│   ├── haima-core/     — Types, traits, errors, payment policy, finance events
│   ├── haima-wallet/   — secp256k1 keypair, EVM addresses, encrypted storage
│   ├── haima-x402/     — x402 client/server middleware, facilitator client
│   ├── haima-lago/     — Lago bridge: event publishing, financial projections
│   ├── haima-api/      — axum HTTP: /health, /state, /balance, /transactions
│   └── haimad/         — Daemon binary

Integration with Agent OS

aiOS (kernel contract — PaymentPort trait)
  ├── Arcan → arcan-haima bridge (intercepts 402, signs payments)
  ├── Autonomic ← finance.* events update EconomicState
  └── Lago ← all financial events via EventKind::Custom("finance.*")

Consciousness Stack Integration

Haima builds on the three consciousness substrates:

Control Metalayer (How to behave with money):

• PaymentPolicy acts as a governance gate — amounts above thresholds require escalation
• Economic modes (Sovereign/Conserving/Hustle/Hibernate) from Autonomic gate payment authorization
• Rate limits prevent runaway spending (max transactions per minute)

Knowledge Graph (What is known about finances):

• FinancialState projection = deterministic fold over Lago finance events
• Transaction history searchable via Lago journal queries
• Pending bills tracked as first-class state

Episodic Memory (What financial actions were taken):

• All payments are immutable Lago events: finance.payment_*, finance.revenue_*
• Every transaction links to a session and optional task ID
• Balance sync events detect and log on-chain/internal drift

x402 Protocol

The x402 protocol activates HTTP 402 Payment Required — a status code that waited 30 years for agents to need it.

Flow (Agent as Client)

Agent (Arcan)                Resource Server              Facilitator
  |--- GET /api/data ------->|                                |
  |<-- 402 + PAYMENT-REQUIRED|                                |
  |   (price, chain, token)  |                                |
  |                           |                                |
  | [Haima: evaluate policy]  |                                |
  | [Haima: sign with wallet] |                                |
  |                           |                                |
  |--- GET + PAYMENT-SIGNATURE>|--- POST /verify ------------->|
  |                           |<-- { valid, tx_hash } ---------|
  |<-- 200 + data + receipt   |                                |

Flow (Agent as Server — Per-Task Billing)

Client                    Agent (Arcan + Haima)           Facilitator
  |--- POST /solve ------->|                                |
  |                         | [Agent solves task]            |
  |                         | [Haima: finance.task_billed]   |
  |<-- 402 + PAYMENT-REQUIRED                                |
  |                         |                                |
  |--- POST + PAYMENT-SIGNATURE>                             |
  |                         |--- POST /verify -------------->|
  |                         |<-- { valid, tx_hash } ---------|
  |                         | [Haima: finance.revenue_received]
  |<-- 200 + result         |                                |

Wallet Management

Local Wallet (Default)

• secp256k1 keypair generated via k256 (pure Rust, no OpenSSL)
• Ethereum-compatible address derivation (keccak256 of public key)
• Private key encrypted with ChaCha20-Poly1305
• Encrypted key stored as Lago blob (SHA-256 + zstd, content-addressed)

MPC Wallet (Future)

• WalletBackend trait abstracts local vs MPC implementations
• Coinbase CDP MPC planned — key shares distributed, no single point of failure
• Same signing interface (sign_message, sign_typed_data, sign_transfer_authorization)

Economic Bridge

1 USDC = 1,000,000 micro-credits (μc)
Autonomic default balance (10 credits) = $10 USDC

PaymentPolicy defaults:
  auto_approve_cap:   100 μc    ($0.0001)
  hard_cap_per_tx:    1,000,000 μc ($1.00)
  session_spend_cap:  10,000,000 μc ($10.00)
  max_tx_per_minute:  10

Autonomic's EconomicState.balance_micro_credits maps 1:1 to USDC's smallest unit. Periodic BalanceSynced events reconcile internal and on-chain ledgers.

Finance Events (Lago Namespace)

All events use EventKind::Custom with "finance." prefix:

Chain Support

Facilitator Support

Phase Roadmap

Dependencies

• Required: aios-protocol (canonical contract), lago (event journal)
• Crypto: k256 (secp256k1), sha3 (keccak256), chacha20poly1305 (key encryption)
• HTTP: axum (API server), reqwest (facilitator client)
• Integration: autonomic-core (economic state), vigil (observability)

When NOT to Use This Skill

• For internal cost accounting without real payments → use Autonomic directly
• For human-facing payment UIs → use Stripe/payment processor directly
• For blockchain dApp development → this is specifically for agent-to-agent HTTP payments
• For fiat payments → wait for Phase F6 (MPP with fiat bridge)

Reference Files

• Architecture — Full system design and data flow
• x402 Protocol — x402 specification and implementation guide
• Wallet Security — Key management and encryption details