Skip to content

Architecture

Jump to bottom
Clo edited this page Mar 29, 2026 · 1 revision

Architecture

Overview

OmniClaw is structured as a layered SDK that separates concerns between payment execution, trust evaluation, and operator policy enforcement.

+--------------------------------------------------+
|                   Applications                    |
|         (AI Agents, Payment Apps, CLIs)           |
+--------------------------------------------------+
|                  OmniClaw SDK                     |
|  +--------+  +---------+  +------------------+   |
|  | Pay    |  | Sell    |  | Trust            |   |
|  | Layer  |  | Layer   |  | Layer            |   |
|  +--------+  +---------+  +------------------+   |
|  +--------+  +---------+  +------------------+   |
|  | Policy |  | Nano    |  | x402             |   |
|  | Engine |  | Payment |  | Protocol         |   |
|  +--------+  +---------+  +------------------+   |
+--------------------------------------------------+
|              Circle Programmable Wallets           |
|              Base / Ethereum Networks              |
+--------------------------------------------------+

Module Structure

Core Modules

Module Path Description
OmniClaw src/omniclaw/core.py Main SDK client — wallet creation, pay(), simulate()
Seller src/omniclaw/seller.py Seller SDK — accept payments, sell() decorator
Trust src/omniclaw/trust/ ERC-8004 trust evaluation engine
Policy src/omniclaw/policy.py Operator policy enforcement — limits, velocity, circuit breakers
NanoPayment src/omniclaw/nanopayment/ Gas-free EIP-3009 USDC transfers via Circle Gateway

Infrastructure

Module Path Description
CLI src/omniclaw/cli.py Command-line interface — omniclaw doctor, omniclaw env
Agent src/omniclaw/agent/ MCP agent server with FastAPI routes
Onboarding src/omniclaw/onboarding.py First-run setup and credential configuration
Config src/omniclaw/config.py Environment and configuration management

Payment Flow

  1. Agent calls pay() with wallet ID, recipient, and amount
  2. Policy engine checks spending limits, velocity, and trust score
  3. simulate() runs to verify the transaction will succeed
  4. Trust layer evaluates the recipient using ERC-8004 signals
  5. Payment executes via Circle Programmable Wallets or x402 protocol
  6. Transaction is logged for audit and operator visibility

Network Support

  • Base Sepolia (testnet) — for development and testing
  • Base Mainnet — for production USDC payments
  • Ethereum Mainnet — for cross-chain scenarios

Key Design Decisions

  • Simulation before execution: Every payment can be simulated first to catch errors before funds move
  • Separation of roles: Agents execute, operators set policy, compliance layer enforces
  • Trust as a first-class concept: ERC-8004 trust evaluation is built into the payment flow, not bolted on
  • Gas-free nanopayments: EIP-3009 enables USDC transfers without gas costs for micro-transactions

Clone this wiki locally