Architecture

ouroborai is structured as a Bun + TypeScript monorepo where a Hono API server orchestrates a Claude-backed agent runner, protocol-specific adapters, and ERC-4337 smart account infrastructure. This page explains the data flow, component responsibilities, and design patterns that hold the system together.

High-Level Data Flow

User (Web / Telegram / CLI / MCP)
  |
  |  POST /agent/prompt { prompt, threadId? }
  v
Hono API Server
  |
  |  x402 payment verification ($0.01 USDC)
  |  Nonce uniqueness check (Redis / in-memory)
  v
Agent Runner
  |
  |  Skill detection --> Claude tool-call loop
  |  Thread context loaded from ThreadStore
  v
Protocol Adapters
  |
  |  UniswapV3 | GmxV2 | AaveV3 | RWA | TimeBoost
  |  Build + simulate transactions
  v
ZeroDev Kernel (ERC-4337)
  |
  |  Session key authorization
  |  UserOperation bundling
  v
Arbitrum One / Robinhood Chain (46630)

Request Lifecycle

Every prompt follows this sequence:

Payment gate

The x402 middleware extracts the X-PAYMENT header, verifies the USDC signature, and checks that the nonce has not been used before (stored in Redis with a 24-hour TTL, or in an in-memory set for local development).

Job creation

The API creates an async job in the job queue and returns a jobId + threadId immediately. The caller polls GET /agent/job/:id for results.

Skill detection

The agent runner scans the prompt against registered skill definitions. Each skill declares a set of trigger keywords and maps to one or more adapter tools. Matching skills are loaded into the Claude system prompt as available tools.

Claude agent loop

Claude receives the prompt, the thread history (if threadId was provided), and the matched tool definitions. It reasons about the intent and emits a sequence of tool calls. The runner executes each tool call against the corresponding adapter and feeds results back to Claude until the agent produces a final text response.

Adapter execution

Each tool call dispatches to a protocol adapter. The adapter builds a transaction (or read call), simulates it against the current chain state, and either returns data (quotes, balances, health factors) or submits the transaction through the smart account.

Response

The final agent response and any transaction hashes are written to the thread and stored on the job. The client retrieves the completed job with the full conversation and execution results.

Adapter Pattern

Protocol integrations follow a uniform adapter interface. Each adapter exposes a set of tools — typed functions the agent can call — and handles all protocol-specific encoding, simulation, and error handling internally.

Adapter	Protocol	Tools
`UniswapV3`	Uniswap V3	`swap`, `quote`, `positions`, `pool_info`
`GmxV2`	GMX V2	`open_position`, `close_position`, `positions`
`AaveV3`	Aave V3	`supply`, `borrow`, `repay`, `health_factor`
`RWA`	Robinhood RWA	`rwa_scan`, `rwa_quote`, `rwa_trade`
`TimeBoost`	Arbitrum	`bid_express_lane`, `estimate_mev`

Adding a new protocol means implementing the adapter interface and registering its tools with the skill system. See the Add a Protocol guide.

Skill System

Skills are the bridge between natural language and adapter tools. Each skill is defined in a SKILL.md markdown file with this structure:

# Skill: spot-trading

## Triggers
swap, trade, exchange, buy, sell, convert

## Description
Execute token swaps on Uniswap V3 with automatic route optimization.

## Tools
- swap: Execute a token swap
- quote: Get a price quote without executing

When a prompt matches a skill’s trigger keywords, the runner loads that skill’s tools into the Claude context. Multiple skills can activate for a single prompt (e.g. “Swap USDC for ARB and supply ARB to Aave” activates both spot-trading and lending).

Skills are discovered at startup by scanning the packages/adapters/src/ directory for SKILL.md files. No registration code is required.

State Management

The platform uses a factory pattern for all stateful services. Each service has two implementations — one backed by Redis for production, one using in-memory data structures for local development — selected automatically based on whether REDIS_URL is configured.

Service	Purpose	Redis Key Pattern
Job Queue	Async job creation, polling, results	`arb:job:{jobId}`
Thread Store	Conversation history per session	`arb:thread:{threadId}`
Nonce Tracker	x402 payment replay protection	`arb:nonce:{nonce}` (24h TTL)

Threads are recovered automatically when a threadId is passed with a prompt. The web terminal persists the active threadId in sessionStorage so refreshing the browser resumes the same conversation.

Workspace Structure

The monorepo is organized into packages (shared libraries) and apps (deployable services):

agent/
  packages/
    sdk/            # Chain config, types, contract addresses
    adapters/       # UniswapV3, GmxV2, AaveV3, RWA, TimeBoost adapters
    timeboost/      # Express lane bidder, MEV estimation
    smart-account/  # ZeroDev Kernel wrapper, session key management
  apps/
    api/            # Hono API server (agent runner, x402 middleware)
    web/            # Next.js 15 web terminal
    telegram/       # Grammy Telegram bot
    mcp-server/     # 15-tool MCP server for Claude Code
  contracts/
    agent-registry/       # On-chain agent registry (Stylus/Rust)
    route-optimizer/      # Multi-DEX route comparison (Stylus/Rust)
    liquidation-monitor/  # Multi-protocol health scanner (Stylus/Rust)
    timeboost-vault/      # Bid funding + resale vault (Stylus/Rust)

Build order matters because of workspace dependencies:

packages/sdk — no internal dependencies, built first
packages/adapters, packages/timeboost, packages/smart-account — depend on sdk
apps/* — depend on one or more packages

External packages @zerodev/*, permissionless, and tslib must be marked as externals in the Bun build configuration to avoid bundling issues.

Smart Account Integration

All on-chain transactions are executed through a ZeroDev Kernel smart account (ERC-4337). This provides three key capabilities: Session keys — The agent operates with a scoped session key that has limited permissions (specific token allowances, time bounds, spending caps). The user’s root private key never touches the agent runtime. UserOperation bundling — Multiple actions within a single prompt (e.g. approve + swap + supply) are bundled into a single UserOperation, saving gas and ensuring atomicity. Spending limits — Each session key is configured with per-token and aggregate spending limits. The smart account contract enforces these limits on-chain, so even a compromised session key cannot drain the wallet.

User Wallet (EOA)
  |
  |  Delegates session key with limits
  v
ZeroDev Kernel (Smart Account)
  |
  |  Validates session key permissions
  |  Bundles UserOperations
  v
Bundler --> Arbitrum One

Stylus Contracts

Performance-critical on-chain logic is implemented in Stylus — Rust compiled to WASM and executed natively on the Arbitrum VM. These contracts use dynamic registries (indexed mappings with soft-delete) so new protocols and DEXes can be added without redeployment.

Contract	Purpose	Tests
`agent-registry`	On-chain agent registry with capabilities	7
`route-optimizer`	Multi-DEX route comparison and selection	38
`liquidation-monitor`	Multi-protocol health factor scanning	43
`timeboost-vault`	Express lane bid funding and resale	27

See the Contracts section for detailed documentation.

What’s Next

x402 Payments

How the micropayment protocol gates API access.

Skills & Tools

Deep dive into skill detection and tool registration.

MCP Server

Use the 15-tool MCP server from Claude Code or any MCP client.

Contract Methods

Full reference for all Stylus contract interfaces.

Getting Started

Agent API

Features

Contracts

Bots

Guides

High-Level Data Flow

Request Lifecycle

Adapter Pattern

Skill System

State Management

Workspace Structure

Smart Account Integration

Stylus Contracts

What’s Next

x402 Payments

Skills & Tools

MCP Server

Contract Methods

​High-Level Data Flow

​Request Lifecycle

​Adapter Pattern

​Skill System

​State Management

​Workspace Structure

​Smart Account Integration

​Stylus Contracts

​What’s Next

x402 Payments

Skills & Tools

MCP Server

Contract Methods

High-Level Data Flow

Request Lifecycle

Adapter Pattern

Skill System

State Management

Workspace Structure

Smart Account Integration

Stylus Contracts

What’s Next