Aomi CLI — natural-language to executable on-chain transactions via an agent. Send a prompt like 'swap 1 ETH for USDC' and the agent stages calldata, simulates as a batch, and returns a queued tx for you to sign. Account-abstraction-first signing (EIP-7702 on mainnet, ERC-4337 on L2s) with EOA fallback. Covers swaps, lending, bridging, staking, perps, and CEX read across 25+ apps (Uniswap, Aave, CCTP, Across, Lido, GMX, Polymarket, Binance, etc.) on Ethereum, Polygon, Arbitrum, Base, Optimism...
Scanned 6/9/2026
Install via CLI
Skills Directoryopenskills install aomi-labs/skills---
name: aomi
description: "Aomi CLI — natural-language to executable on-chain transactions via an agent. Send a prompt like 'swap 1 ETH for USDC' and the agent stages calldata, simulates as a batch, and returns a queued tx for you to sign. Account-abstraction-first signing (EIP-7702 on mainnet, ERC-4337 on L2s) with EOA fallback. Covers swaps, lending, bridging, staking, perps, and CEX read across 25+ apps (Uniswap, Aave, CCTP, Across, Lido, GMX, Polymarket, Binance, etc.) on Ethereum, Polygon, Arbitrum, Base, Optimism, and more. Use when an agent should drive on-chain actions through a CLI rather than constructing calldata directly. Triggers: aomi, agent CLI, natural-language transaction, intent execution, simulate-then-sign."
license: MIT
compatibility: Claude Code, Cursor, Windsurf, Cline, Codex
metadata:
author: aomi-labs
version: "1.0"
chain: multichain
category: AI Agents
tags:
- aomi
- ai-agents
- account-abstraction
- intent
- natural-language
- cli
- transactions
- simulation
---
# 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](https://aomi.dev) · npm: [`@aomi-labs/client`](https://www.npmjs.com/package/@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:
```bash
# 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 <command>` 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):
```bash
aomi --version 2>/dev/null || npx @aomi-labs/client --version
```
If older, upgrade with `npm install -g @aomi-labs/client@latest`.
### First chat
```bash
aomi --prompt "what is the price of ETH?" --new-session
```
For a wallet-aware first turn, pass the user's address and chain:
```bash
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)
```bash
aomi chat "<intent>" --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.
```bash
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.
```bash
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.
```bash
aomi app list # list installed apps
aomi app current # show active app
aomi chat "<intent>" --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`.
```bash
aomi session list # local sessions with topic + pending count
aomi session resume <id> # set active pointer to an existing session
aomi session delete <id> # 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 <N> > /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 <N> > /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 <chain-matching-public-rpc>`. 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 their own shell environment instead.
- **Always simulate multi-step batches.** Approve+swap, approve+supply, bridge+attestation — these are state-dependent. The second tx will revert if submitted independently. `aomi tx simulate tx-1 tx-2` runs them sequentially on a fork.
- **Never sign past simulation failure.** If `aomi tx simulate` reports `Batch success: false` or any drain-vector annotation, **do not** attempt `aomi tx sign`. Surface the failure to the user — either rebuild (allowance retry pattern) or stop.
- **Drain vectors are guard-blocked, not bypassed.** When the agent rejects `recipient != msg.sender` (or `onBehalfOf`, `mintRecipient`, `_to`), surface the block to the user. Do not try to construct calldata that bypasses the guard.
- **Read-only by default.** Chat, simulation, session inspection, and app/model/chain introspection do not move funds. Signing is a separate, explicit step the user must request.
- **Match `--rpc-url` to the queued tx's chain.** A single `--rpc-url` cannot serve a mixed-chain multi-sign request. The pending tx already contains its target chain — pass an RPC for that chain.
- **`--aa-provider` and `--aa-mode` cannot combine with `--eoa`.** They force AA. If the user wants EOA, pass only `--eoa`.
## Skill Structure
```
aomi/
├── SKILL.md # This file
├── docs/
│ └── troubleshooting.md # Full troubleshooting guide (chat, signing, RPC, simulation, AA, quirks)
├── examples/
│ ├── chat-and-sign/README.md # Lido stake — single-tx flow
│ ├── multi-step-batch/README.md # Uniswap V3 swap — approve + swap with simulation
│ ├── cross-chain-swap/README.md # CCTP Ethereum → Base — bridge with attestation
│ └── session-management/README.md # Resume, recover, cleanup
├── resources/
│ ├── contract-addresses.md # AA stack + commonly staged protocol contracts
│ ├── error-codes.md # CLI error reference with fixes
│ └── supported-apps.md # 25+ app catalog with credential requirements
└── templates/
└── aomi-workflow.sh # Reusable bash functions for chat → simulate → sign
```
## Guidelines
1. **Default `--new-session` on the first command of a new task; omit it for follow-up confirmations** in the same flow (the agent loses context otherwise).
2. **Never sign before `aomi tx list` confirms a pending `tx-N`.** A chat response does not always queue a transaction immediately.
3. **Always `aomi tx simulate` before signing a multi-step batch.** Single-tx flows are simulation-optional but never wrong to simulate.
4. **Sign only `Batch [...] passed` txs.** Skip orphans from earlier failed attempts (`failed at step N: 0x...`).
5. **Match `--rpc-url` to the queued tx's chain**, not the session chain (`--chain`). They are independent controls.
6. **Don't retry `--eoa` on L2 `insufficient funds for transfer`** — that path also needs gas. Fix the root cause: fund the EOA, or configure BYOK sponsorship.
7. **Surface drain-vector blocks to the user.** Do not attempt to bypass them by reformulating the prompt.
8. **Never echo credential values back to the user** after a setup command. Confirm with handle name or derived address only.
## References
- [aomi-labs/client on npm](https://www.npmjs.com/package/@aomi-labs/client)
- [aomi.dev](https://aomi.dev) — official docs
- [aomi-labs/skills](https://github.com/aomi-labs/skills) — upstream source for this skill, including [aomi-build](https://github.com/aomi-labs/skills/tree/main/aomi-build) for building new apps from API specs
- [EIP-7702](https://eips.ethereum.org/EIPS/eip-7702) — Set EOA account code
- [ERC-4337](https://eips.ethereum.org/EIPS/eip-4337) — Account Abstraction Using Alt Mempool
- [Alchemy AA stack](https://accountkit.alchemy.com/) — provider for the zero-config AA proxy path
No comments yet. Be the first to comment!
