Haima

Agentic finance engine for the Life Agent OS -- the circulatory system that distributes economic resources throughout the organism.

Haima (Greek: blood) implements the x402 protocol for machine-to-machine payments at the HTTP layer, enabling agents to pay for resources and charge for services without human intervention.

Architecture

                          +------------------+
                          |    Arcan (Agent)  |
                          +--------+---------+
                                   |
                    HTTP 402 / Payment Required
                                   |
                          +--------v---------+
                          |   haima-x402     |
                          |  (client/server) |
                          +--------+---------+
                                   |
                 +-----------------+-----------------+
                 |                                   |
        +--------v---------+              +----------v--------+
        |   haima-wallet   |              |    haima-core      |
        | secp256k1 keypair|              | types, policy,     |
        | EVM address      |              | events, receipts   |
        | ChaCha20 encrypt |              +----------+--------+
        +------------------+                         |
                                           +---------v--------+
                                           |   haima-lago     |
                                           | event publishing |
                                           | projection fold  |
                                           +------------------+
                                                     |
                                              +------v------+
                                              |    Lago     |
                                              | (journal)   |
                                              +-------------+

x402 Protocol Flow

Agent as Client (paying for resources)

Agent (Arcan) --> HTTP request --> 402 + PAYMENT-REQUIRED header
  --> Haima parses payment terms
  --> Evaluates against PaymentPolicy (auto-approve / approval / deny)
  --> Signs with agent's secp256k1 wallet
  --> Retries with PAYMENT-SIGNATURE header
  --> Receives 200 + PAYMENT-RESPONSE (settlement confirmation)
  --> Records finance.payment_settled event to Lago

Agent as Server (charging for services)

External client --> HTTP request to agent's paid endpoint
  --> Haima middleware returns 402 + PAYMENT-REQUIRED
  --> Client signs and retries with payment
  --> Facilitator verifies and settles on-chain
  --> Revenue recorded as finance.revenue_received
  --> Per-task billing via finance.task_billed events

Crates

Quick Start

# Standalone mode (in-memory projections, for testing)
cargo run -p haimad -- --bind 127.0.0.1:3003

# With Lago persistence (production -- reads events from journal)
cargo run -p haimad -- --bind 127.0.0.1:3003 --lago-data-dir /path/to/data

API Endpoints

Payment Policy

Every payment is evaluated against a PaymentPolicy:

Session spend cap: 10,000,000 micro-credits ($10.00).

Economic bridge: 1 USDC = 1,000,000 micro-credits.

Build and Test

# Full verification
cargo fmt && cargo clippy --workspace -- -D warnings && cargo test --workspace

# Run tests only
cargo test --workspace

# Build release
cargo build --workspace --release

Dependency Order

aios-protocol (canonical contract)
    |
haima-core (types + traits + events + policy)
    |          \
haima-wallet    haima-lago (+ lago-core, lago-journal)
    |          /
haima-x402 (x402 protocol: client, server, facilitator)
    |
haima-api (axum HTTP)
    |
haimad (binary)

Chain Support

• Primary: Base (EVM, eip155:8453)
• Planned: Solana
• Facilitator: Coinbase CDP default; self-hosted and Stripe abstractions ready

Documentation

Full documentation: docs.broomva.tech/docs/life/haima

License

MIT