Aomi

Aomi

Aomi is an AI-agent CLI that converts natural-language intents into executable on-chain transactions. The user types aomi chat "swap 1 ETH for USDC on Uniswap", the agent picks the right protocol and contract, stages the approve+swap as a batch, simulates it on a forked chain, and returns a queued wallet request. Signing is a separate, explicit step — the wallet only ever sees calldata that already passed simulation.

The CLI is account-abstraction-first: by default it signs through a zero-config Alchemy proxy (no provider credentials needed), using EIP-7702 on Ethereum mainnet and ERC-4337 on L2s. Each aomi invocation starts, runs, and exits — conversation history lives on the backend; pending and signed transaction state lives locally under ~/.aomi/. The skill is shaped as a procedure for an agent to drive that CLI, not as an SDK to import.

Official docs: aomi.dev · npm: @aomi-labs/client

What You Probably Got Wrong

> LLMs have stale training data. These are the most common mistakes.

• "Aomi is a wallet" — Aomi is an agent + CLI. It composes calldata and queues a wallet request; the user signs. The CLI does not custody funds, never signs without an explicit aomi tx sign, and never broadcasts on its own initiative.
• "aomi chat always queues a transaction" — Often the first response is a quote, route, or clarifying question. The agent only stages calldata when it has enough context. Always run aomi tx list after chat to see what's actually pending — never assume.
• "Approval and swap are one transaction" — Most DeFi flows are two-step: approve then supply/swap/deposit. Aomi stages them as a batch and aomi tx simulate tx-1 tx-2 runs them sequentially on a fork so the second step sees the first's state changes. Sign them as a batch, not individually.
• "Use --rpc-url to switch chains" — --chain controls the wallet/session context (which chain the agent thinks you're on); --rpc-url controls where aomi tx sign estimates and submits. They are independent. For a cross-chain swap, the queued tx has its own chain field — pass --rpc-url matching that chain when signing.
• "AA always sponsors gas on L2s" — The zero-config proxy path on Base/Arbitrum/Optimism does not reliably sponsor in v0.1.30. If the EOA has 0 native gas on the destination chain, signing fails with insufficient funds for transfer. Either fund the EOA with a tiny amount of native gas, or configure a real BYOK Alchemy/Pimlico provider with a sponsorship policy. Do not retry with --eoa — that path also needs gas.
• "--new-session should always be passed" — Pass it on the first command of a new task. Reusing it mid-task starts a fresh conversation and the agent loses context (e.g. the quote it just gave you). For follow-up confirmations like "yes, proceed", omit --new-session.
• "Failed simulation txs disappear" — They don't. aomi tx list shows orphaned tx-N from earlier failed attempts alongside the current passing batch. Check the batch_status line and only sign txs marked Batch [...] passed.
• "7702 and 4337 are interchangeable" — They're not. 7702 is a native EIP-7702 type-4 transaction with EOA delegation; the EOA pays gas. 4337 is a bundler+paymaster UserOperation; the paymaster can sponsor. Use 4337 if you need gasless execution. Default chain modes: 7702 on Ethereum, 4337 on Polygon/Arbitrum/Base/Optimism.
• "Drain vectors are aomi-specific" — They're protocol-specific calldata fields where a malicious prompt could redirect funds (recipient in Uniswap, onBehalfOf in Aave, mintRecipient in CCTP, _to in OP-stack bridges). The agent blocks these at simulation time when they don't equal msg.sender. The skill's job is to surface the block, not bypass it.

Quick Start

Install

Two equivalent paths:

# Global install (recommended for repeated use)
npm install -g @aomi-labs/client

# Or run on demand without installing
npx @aomi-labs/client --help

Throughout the rest of this skill, commands are written as aomi for brevity. If aomi is not on PATH, substitute npx @aomi-labs/client everywhere aomi appears.

Verify version

The skill assumes v0.1.30 or newer (older versions lack --aa-provider/--aa-mode and the simulation gate):

aomi --version 2>/dev/null || npx @aomi-labs/client --version

If older, upgrade with npm install -g @aomi-labs/client@latest.

First chat

aomi --prompt "what is the price of ETH?" --new-session

For a wallet-aware first turn, pass the user's address and chain:

aomi chat "swap 1 USDC for WETH on Uniswap V3" \
  --public-key 0xUserAddress --chain 1 --new-session

The agent responds with a quote, stages the calldata, and queues a wallet request:

⚡ Wallet request queued: tx-1
   to:    0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48
   value: 0
   chain: 1

Lifecycle

Every flow follows the same five steps:

> chat (intent) → list (verify what was queued) → simulate (catch reverts before signing) → sign (wallet pop) → verify (chain-state confirmation)

aomi chat "" --public-key 0xUserAddress --chain 1 --new-session
aomi tx list                      # confirm tx-N exists
aomi tx simulate tx-1 tx-2        # only for multi-step batches
aomi tx sign tx-1 tx-2            # AA-first; falls through to EOA if user has BYOK
aomi tx list                      # confirm signed/broadcast hash

If you only remember one thing: the user gives intent in plain English; the agent composes calldata; simulate is the gate; the wallet only sees what passed simulation.

Core Patterns

Single-tx flow

ETH transfers, native L2 bridges (depositETHTo), Lido staking (submit()) — no approve, no batch.

aomi chat "stake 0.01 ETH with Lido" --public-key 0xUser --chain 1 --new-session
aomi tx list
aomi tx sign tx-1

Simulation is optional for single-tx flows but never wrong to run.

Multi-step batch (approve + action)

Most DeFi flows. The agent stages both steps and the simulator runs them sequentially on a fork.

aomi chat "swap 100 USDC for WETH on Uniswap" --public-key 0xUser --chain 1 --new-session
aomi tx list                      # tx-1 = approve, tx-2 = swap
aomi tx simulate tx-1 tx-2        # MUST simulate; second step depends on first
aomi tx sign tx-1 tx-2            # one hash on AA 7702 atomic-batch path

If simulation fails at step N, read the revert reason. Common causes: insufficient balance, expired quote, missing prior approval. Do not blindly re-sign.

See [examples/multi-step-batch/README.md](examples/multi-step-batch/README.md) for an end-to-end approve+swap with real gas figures.

Agent retry-as-batch

When the agent's first attempt fails simulation (e.g. tries a single-tx supply and gets transfer amount exceeds allowance), it rebuilds as approve+supply automatically. aomi tx list then shows three entries: an orphan tx-1 from the failed attempt and the working tx-2/tx-3 pair. Sign the pair, not the orphan. Match against batch_status — only sign txs marked Batch [...] passed.

Cross-chain

The agent stages txs that target a different chain than the session. Pass --rpc-url matching the queued tx's chain, not the session chain. See [examples/cross-chain-swap/README.md](examples/cross-chain-swap/README.md) for CCTP Ethereum → Base.

Self-healing deadlines

For deadline-bearing routes (Across, Khalani fillers), if simulation reports an expiry, the agent rebuilds the request with fresh deadlines automatically. Don't re-prompt — re-check aomi tx list for the latest passing batch.

Account Abstraction

The CLI signs via AA by default. Most invocations need no AA flags — aomi tx sign tx-1 is enough. The resolution chain is flag > user-side credential > zero-config backend proxy.

| Mode | Flag | Gas | Notes | | ------ | ---------------- | ---------- | ------------------------------------------- | | 7702 | --aa-mode 7702 | EOA pays | EIP-7702 type-4 tx with delegation. Default on Ethereum. No sponsorship. | | 4337 | --aa-mode 4337 | Paymaster | Bundler+paymaster UserOperation. Default on L2s. Supports sponsorship. | | EOA | --eoa | EOA pays | Skip AA. Use for Sepolia, Anvil, or when AA fails. |

Default chain modes:

| Chain | ID | Default | Supported | | -------- | ----- | ------- | ---------- | | Ethereum | 1 | 7702 | 4337, 7702 | | Polygon | 137 | 4337 | 4337, 7702 | | Arbitrum | 42161 | 4337 | 4337, 7702 | | Base | 8453 | 4337 | 4337, 7702 | | Optimism | 10 | 4337 | 4337, 7702 | | Sepolia | 11155111 | — | use --eoa | | Anvil | 31337 | — | use --eoa |

Mode fallback: when AA is selected, the CLI tries the preferred mode, then the alternative, then errors with a --eoa suggestion. There is no silent EOA fallback.

L2 sponsorship caveat (verified v0.1.30): the zero-config proxy on Base does not reliably sponsor — aomi tx sign returns viem's insufficient funds for transfer if the EOA has 0 native gas. Either fund the EOA with ~0.0005 ETH-equivalent on the destination chain, or configure a real BYOK Alchemy/Pimlico provider on the user's side and pass --aa-provider alchemy --aa-mode 4337. Do not retry with --eoa blindly — --eoa also needs gas.

Contract Addresses

> Last verified: April 2026 (v0.1.30 captures, mainnet + L2)

These are the AA-stack and protocol delegation contracts the CLI signs through. The skill itself does not deploy contracts — these are the well-known endpoints the AA path delegates to.

EIP-7702 delegation contract (Alchemy)

| Contract | Ethereum | |----------|----------| | Modular Account v2 (delegation target) | 0x69007702764179f14F51cdce752f4f775d74E139 |

The EOA's code slot points at this address after the first 7702 transaction. Verified onchain via cast code 0x69007702764179f14F51cdce752f4f775d74E139 --rpc-url $ETH_RPC_URL.

ERC-4337 EntryPoint v0.7

| Contract | All EVM chains | |----------|----------------| | EntryPoint v0.7 | 0x0000000071727De22E5E9d8BAf0edAc6f37da032 |

Singleton contract deployed at the same address across Ethereum, Polygon, Arbitrum, Base, Optimism, and most EVM L2s.

Examples of contracts the agent commonly stages calls to

These appear in [examples/](examples/) — included for grep-ability, not as an exhaustive registry.

| Contract | Address | |----------|---------| | Uniswap V3 SwapRouter02 (Ethereum) | 0x68b3465833fb72A70ecDF485E0e4C7bD8665Fc45 | | Aave V3 Pool (Ethereum) | 0x87870Bca3F3fD6335C3F4ce8392D69350B4fA4E2 | | Lido stETH (Ethereum) | 0xae7ab96520DE3A18E5e111B5EaAb095312D7fE84 | | CCTP TokenMessenger (Ethereum) | 0x28b5a0e9c621a5badaa536219b3a228c8168cf5d | | L1StandardBridge for Base | 0x3154cf16ccdb4c6d922629664174b904d80f2c35 |

For per-chain protocol addresses (Aave on Arbitrum, Uniswap on Polygon, etc.), the agent picks them at request time from the active app's registry — aomi app list to see which apps are loaded.

See [resources/contract-addresses.md](resources/contract-addresses.md) for the full table.

Apps

Aomi exposes 25+ apps that bundle protocol-specific tools. Each app is a context the agent loads for the next request.

aomi app list                                              # list installed apps
aomi app current                                           # show active app
aomi chat "" --app khalani --chain 137             # one-turn override

Common categories: DEX (uniswap, cow, oneinch, zerox), lending (aave, morpho), bridges (cctp, across, khalani, lifi), staking (lido, rocket_pool, etherfi), perps (gmx, dydx, hyperliquid), prediction (polymarket, kalshi, manifold), CEX read (binance, bybit, okx), social (x, neynar, kaito), analytics (defillama, dune).

The full catalog with credential requirements is in [resources/supported-apps.md](resources/supported-apps.md).

Sessions

A session is split across two stores. Knowing what lives where prevents wrong-place lookups.

• Backend — full conversation transcript, tool calls, system events. Read via aomi session log, aomi session events, aomi session status.
• Local ($AOMI_STATE_DIR or ~/.aomi/) — sessionId, clientId, pendingTxs[], signedTxs[], secretHandles{}. Read via aomi tx list, aomi wallet current.

aomi session list             # local sessions with topic + pending count
aomi session resume       # set active pointer to an existing session
aomi session delete       # remove a local session (check no pending txs first)
aomi session close            # clear the active pointer; next chat starts fresh

The "No active session" recovery pattern: if aomi tx list reports no active session, run aomi session list to find the right one by topic, then aomi session resume > /dev/null && aomi tx list in the same shell call (the active-session pointer can be lost between subprocess invocations).

See [examples/session-management/README.md](examples/session-management/README.md) for resume/recovery patterns.

Error Handling

| Error / output | Cause | Fix | |----------------|-------|-----| | (no response) from aomi chat | Backend timeout or stale local session pointer | Wait briefly, run aomi session status. If session is gone, retry with --new-session | | No active session from aomi tx list | Active-session pointer lost between shell invocations | aomi session list to find session, then aomi session resume > /dev/null && aomi tx list in same call | | Batch [N] failed: ERC20: transfer amount exceeds allowance | First-attempt single-tx; agent will retry as approve+action batch | Wait for retry, sign the new pair (tx-2 tx-3), ignore the orphan tx-1 | | insufficient funds for transfer (viem) on L2 sign | Zero-config AA proxy did not sponsor; EOA has 0 native gas on destination | Fund EOA with native gas on that chain, OR configure BYOK provider with sponsorship policy | | AA mode error suggesting --eoa | Both AA modes (preferred + alternative) failed | Read console output, address the underlying issue (provider creds, chain support), or use --eoa if user accepts EOA signing | | 401 / 429 on aomi tx sign | RPC rate-limited or auth-failed | Pass --rpc-url . Don't rotate through random RPCs — ask user for a reliable one | | stateful: false in simulation result | Backend could not fork chain; ran each tx via eth_call | Retry; check backend Anvil status. Multi-step batches may show false negatives | | [session] Backend user_state mismatch (non-fatal) log spam | Known v0.1.30 cosmetic noise | Ignore. Look past the JSON dump for the actual response and ⚡ Wallet request queued line |

The full troubleshooting guide is in [docs/troubleshooting.md](docs/troubleshooting.md).

Security

This skill drives an external CLI. It does not install software, read files outside ~/.aomi/, or execute generated code. The hard rules below are non-negotiable.

• Credentials are opaque pass-through. Never invent, guess, or derive a credential value. Values reach the CLI only when the user has handed them over for a specific command in this turn. Never echo a credential value back.
• No unsolicited setup. Don't run aomi wallet set, aomi secret add, or --api-key/--private-key flags on your own initiative to "prepare" or "fix" something. Only run them when the user explicitly asked for that specific setup and provided the value.
• Trust-boundary warning before secret ingestion. aomi secret add NAME=value transmits the credential to the aomi backend and stores a handle locally. Surface this to the user before running it so they can choose to export to the

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: aomi-labs
• Source: aomi-labs/skills
• License: MIT
• Homepage: https://aomi.dev/

Install and usage instructions live in the source repository linked above.