haima

name

haima

description

Agentic finance engine for the Agent OS — x402 machine-to-machine payments, on-chain settlement, per-task revenue billing, and wallet management. Integrates with Arcan (agent runtime), Autonomic (economic homeostasis), and Lago (event-sourced persistence) to give agents real financial agency. Use when: (1) adding payment capabilities to an agent or agent-controlled API, (2) implementing x402 protocol support for HTTP-native machine payments, (3) wiring per-task billing so agents can charge for completed work, (4) managing agent wallets (secp256k1 keypair, encrypted storage), (5) configuring payment policies (auto-approve, spend caps, rate limits), (6) integrating Coinbase CDP or self-hosted facilitators for on-chain settlement, (7) bridging on-chain USDC with Autonomic's micro-credit state. Triggers on 'agent payments', 'x402', 'machine payments', 'agentic finance', 'haima', 'payment port', 'wallet management', 'per-task billing', 'USDC payments', 'agent revenue', '402 payment required'.

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:

Event	Trigger	State Change
finance.payment_requested	Agent encounters 402	Informational
finance.payment_authorized	Agent signs payment	Informational
finance.payment_settled	On-chain confirmation	expenses + session_spend ↑
finance.payment_failed	Settlement failure	failed_count ↑
finance.revenue_received	Client pays for task	revenue + net_balance ↑
finance.wallet_created	Keypair generated	wallet_address set
finance.balance_synced	Periodic reconciliation	on_chain_balance updated
finance.task_billed	Agent prices a task	pending_bills ↑

Chain Support

Chain	Status	CAIP-2 ID	Notes
Base (Coinbase L2)	Active	eip155:8453	Primary — lowest fees (~$0.0001/tx)
Base Sepolia	Active	eip155:84532	Testnet
Solana	Planned	solana:*	Phase F5
Ethereum	Possible	eip155:1	Higher fees, for large settlements

Facilitator Support

Facilitator	Status	Notes
Coinbase CDP	Default	Free tier 1K tx/month, then $0.001/tx
Self-hosted	Abstracted	Reference impl via x402-rs facilitator crate
Stripe	Abstracted	PaymentIntents API with crypto deposit addresses

Phase Roadmap

Phase	Scope	Status
F0	Core types, wallet, policy, events, API scaffold	COMPLETE
F1	x402-rs integration, header parsing, signing, settlement	PLANNED
F2	Lago EventStorePort wiring, Autonomic CostReason integration	PLANNED
F3	x402 server middleware, task billing, revenue collection	PLANNED
F4	Full daemon with persistence, balance sync, tx history API	PLANNED
F5	Solana chain support	PLANNED
F6	Stripe MPP integration (when Rust SDK ships)	FUTURE

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