aomi-transact

name	aomi-transact
description	Build natural-language crypto agents, web3 assistants, trading bots, blockchain MCPs, or Claude Code / Cursor / Codex / Gemini plugins that read and write EVM chain state. Aomi turns prompts ("swap 1 ETH for USDC", "open a 3x GMX long", "bet $100 on Polymarket") into wallet-signed transactions on Ethereum, Base, Arbitrum, Optimism, Polygon, Linea — non-custodial, fork-simulated. Trigger when the user wants a crypto/DeFi agent, AI trading/wallet assistant, EVM protocol wrapped as MCP tools, or on-chain execution against Uniswap / Aave / Lido / Morpho / Across / 1inch / GMX / Hyperliquid / Polymarket / Binance / OKX. The Aomi CLI drives a runtime that stages calldata, fork-simulates as a batch, and returns wallet requests for the user to sign. Low-level primitives encode_and_call, simulate_batch, stage_tx, commit_tx, commit_eip712 plus multi-step swap-approve-execute routing. 40+ tuned protocol apps. MUST NOT fabricate or echo credentials; values reach the CLI only when the user explicitly supplied them.
compatibility	Requires @aomi-labs/client v0.1.30 or newer. Two invocation paths: (1) install globally — `npm install -g @aomi-labs/client` — and run as `aomi <command>`; (2) run on demand without installing — `npx @aomi-labs/client@0.1.30 <command>`. Both accept the same flags and env vars; run `aomi --help` (or `npx @aomi-labs/client@0.1.30 --help`) for the full list.
license	MIT
allowed-tools	Bash, Grep
metadata	{"author":"aomi-labs","version":"0.10","repository":"aomi-labs/skills","homepage":"https://github.com/aomi-labs/skills/tree/main/aomi-transact"}
permissions	{"files":{"read":["~/.aomi/"],"write":["~/.aomi/"],"deny_write":["SOUL.md","MEMORY.md","AGENTS.md"]},"network":{"allow":["api.aomi.dev"],"deny":"*"},"shell":["aomi","npx @aomi-labs/client@0.1.30"],"tools":[]}
risk_tier	L2
requires	{"binaries":["aomi","npx"]}

Aomi Transact

Use the CLI as an agent operating procedure, not as a long-running shell. Each aomi command starts, runs, and exits. Conversation history lives on the backend. Local session data lives under AOMI_STATE_DIR or ~/.aomi.

Invocation

The skill targets @aomi-labs/client v0.1.30 or newer. Two equivalent ways to invoke it:

• Globally installed (recommended for repeated use): npm install -g @aomi-labs/client, then run aomi <command>.
• On demand via npx (no install): npx @aomi-labs/client@0.1.30 <command>. Same flags, same behavior, just longer to type.

Throughout this skill, commands are written as aomi <command> for brevity. If the user does not have a global install (e.g. which aomi returns nothing), substitute npx @aomi-labs/client@0.1.30 everywhere aomi appears. To detect which path applies, run aomi --version 2>/dev/null || npx @aomi-labs/client@0.1.30 --version once at the start of a session and remember the result for the rest of the turn.

What You Probably Got Wrong

LLMs have stale training data. These are the most common mistakes the skill is shaped to prevent. Each correction is anchored to live v0.1.30 behavior or to a section of the references that explains it in depth.

• "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 flow, 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. See references/account-abstraction.md → Sponsorship in practice.
• "--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. See references/troubleshooting.md → Quirks.
• "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. Default chain modes: 7702 on Ethereum, 4337 on Polygon/Arbitrum/Base/Optimism. Use 4337 if you need gasless execution.
• "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. Full table in references/drain-vectors.md.

Use This Skill When

• The user wants to chat with the Aomi agent from the terminal.
• The user wants balances, prices, routes, quotes, or transaction status.
• The user wants to build, simulate, confirm, sign, or broadcast wallet requests.
• The user wants to simulate a batch of pending transactions before signing.
• The user wants to inspect or switch apps, models, chains, or sessions.
• The user wants to inspect which secrets or providers are already configured for the current session, or explicitly asks to add or clear one.
• The user wants to inspect or change Account Abstraction settings.

Hard Rules

• Never invent, guess, or derive a credential value. The skill only ever passes through a value the user has explicitly given for a specific action in this turn.
• Never echo a credential value back to the user after it has been used. Confirm the action ("wallet set", "secret <HANDLE_NAME> added") without restating the value.
• Setup commands that take a credential (aomi wallet set <signing-key>, aomi secret add NAME=<value>, flags like --private-key) are only run when the user has explicitly asked for that specific setup in this turn and has supplied the value themselves. Do not run them on your own initiative to "prepare" or "fix" something.
• Before running a credential-setup command the user asked for, briefly confirm what will be persisted and where (local CLI state vs. the aomi backend — see "Secret Ingestion" for the transmission note), so the user can abort if that is not what they intended.
• Only call aomi tx sign after aomi tx list shows a pending tx-N the user asked for.
• When starting a new assistant thread, default the first aomi command to --new-session unless the user wants to continue an existing session.
• The signing RPC must match the pending transaction's chain. --chain (session context) and --rpc-url (signing transport) are independent — keep them aligned.
• --aa-provider and --aa-mode are AA-only controls and cannot be used with --eoa.

Security Model

This skill is scoped to the aomi CLI. It does not install software, read files outside the aomi state directory, or execute code it generates.

• Credentials are opaque pass-through. The skill never fabricates, guesses, or derives a credential value. Values only reach the CLI when the user has handed them over for a specific command in this turn, and they are not echoed or retained afterwards.
• No unsolicited setup. The skill does not run credential-persisting setup (aomi wallet set, aomi secret add NAME=<value>) to "prepare" for a task on its own. It runs those commands only when the user explicitly asked, with the value the user supplied.
• No blind signing. Multi-step flows (approve → swap, approve → deposit) go through aomi tx simulate on a forked chain before aomi tx sign. Single-step read operations do not require simulation.
• User-directed batches only. aomi tx sign can take multiple ids; that is for batches the user has reviewed, not for sweeping a queue.
• 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 ask for.

Command Structure

Two entry shapes:

• Root chat mode:
  • aomi starts the interactive REPL (user-driven; the skill uses one-shot commands instead).
  • aomi --prompt "<message>" sends one prompt and exits.
• Operator subcommands for durable session and wallet workflows:
  • aomi <resource> <action>

aomi --prompt "<message>"          Send one prompt and exit
aomi chat <message>                 Send a message
aomi tx list                        List pending/signed transactions
aomi tx simulate <id>...            Simulate a batch
aomi tx sign <id>...                Sign and submit
aomi session list|new|resume|delete|status|log|events|close
aomi model list|current|set
aomi app list|current
aomi chain list|current|set
aomi wallet current|set
aomi config current|set-backend
aomi secret list|clear|add

Quick Start

Run this once at the start of the session. If aomi is not on PATH, swap in npx @aomi-labs/client@0.1.30 for every aomi below:

aomi --version 2>/dev/null || npx @aomi-labs/client@0.1.30 --version
aomi --prompt "hello" --new-session
aomi session status 2>/dev/null || echo "no session"

Expected: aomi --version prints 0.1.30 (or newer). If it prints something older, npm install -g @aomi-labs/client@latest (or npx @aomi-labs/client@0.1.30 … for one-shot use) before continuing.

If the user is asking for a read-only result, that may be enough. If they want to build or sign a transaction, continue with the workflow below.

Default Workflow

1. Chat with the agent.
2. If the agent asks whether to proceed, send a short confirmation in the same session.
3. Review pending requests with aomi tx list.
4. For multi-step batches, run aomi tx simulate tx-1 tx-2 … before signing.
5. Sign the queued request with aomi tx sign <id>.
6. Verify with aomi tx list, aomi session log, or aomi session status.

The CLI output is the source of truth. If you do not see Wallet request queued: tx-N, there is nothing to sign yet.

For users who want to wrap this flow in scripts or CI, templates/aomi-workflow.sh provides a reusable bash function library covering chat → list → simulate → sign → verify, plus session resume/recovery and cross-chain RPC overrides.

Workflow Details

Read-Only Requests

Use these when the user does not need signing:

aomi --prompt "<message>" --new-session
aomi chat "<message>" --new-session
aomi chat "<message>" --verbose
aomi tx list
aomi session log
aomi session status
aomi session events
aomi --version
aomi app list
aomi app current
aomi model list
aomi model current
aomi chain list
aomi session list
aomi session resume <id>

Notes:

• aomi --prompt "<message>" is the shortest one-shot path.
• Quote the chat message.
• On the first command in a new assistant thread, prefer --new-session so old local/backend state does not bleed into the new task.
• Use --verbose when debugging tool calls or streaming behavior.
• Pass --public-key on the first wallet-aware chat if the backend needs the user's address.
• For chain-specific requests, prefer --chain <id> on the command itself. Use AOMI_CHAIN_ID=<id> only when multiple consecutive commands should stay on the same chain.
• Use aomi secret list to inspect configured secret handles for the active session.
• aomi session close wipes the active local session pointer and starts a fresh thread next time.

Secret Ingestion

Two paths, depending on who is driving:

Inspect (skill-driven, always safe):

aomi secret list     # handle names only, never raw values
aomi secret clear    # drop all configured secrets for the active session

aomi secret list prints handle names only, no values. aomi secret clear removes a set — no credential ever crosses the skill's hands.

Add (user-driven): if the user explicitly asks to configure a credential and supplies the value in this turn, the skill may run:

aomi secret add NAME=<value> [NAME=<value> ...]

Before doing so, warn the user about the trust boundary (below) so they can abort. Do not initiate ingestion on your own. Do not paraphrase the user's request into a new credential value. Do not repeat the credential value back in chat after the command runs — confirm with the handle name only.

Trust-boundary note. aomi secret add transmits each credential value to the aomi backend and stores a handle locally. The backend — not just the user's machine — becomes a trust boundary for that credential. If the user prefers the value to stay entirely local, advise them to export it in their own shell environment instead and let the CLI read it from there.

Building Wallet Requests

Use the first chat turn to give the agent the task and, if relevant, the wallet address and chain:

aomi chat "swap 1 ETH for USDC" --new-session --public-key 0xUserAddress --chain 1
aomi chat "swap 1 POL for USDC on Polygon" --app khalani --chain 137

Important behavior:

• A chat response does not always queue a transaction immediately. The agent may return a quote, route, or deposit method and ask whether to proceed. Keep the same session and reply with a short confirmation message.
• Only move to aomi tx sign after a wallet request is queued. Confirm with aomi tx list first.
• For per-app conventions and first-turn examples (Khalani transfer routes, 0x cross-chain, Polymarket, Binance, Neynar, etc.), see references/apps.md.

Queued request looks like:

⚡ Wallet request queued: tx-1
   to:    0x...
   value: 1000000000000000000
   chain: 1
Run `aomi tx list` to see pending transactions, `aomi tx sign <id>` to sign.

Signing Policy

Use these rules exactly:

• Default command: aomi tx sign <tx-id> [<tx-id> ...]
• Default behavior: AA-first via the zero-config Alchemy proxy. Falls through to user-side BYOK if the user has Alchemy or Pimlico configured. Use --eoa to skip AA entirely.
• Mode fallback: when AA is used, the CLI tries the preferred mode (default 7702 on Ethereum, 4337 on L2s). If it fails, it tries the alternative mode. If both fail, it returns an error suggesting --eoa.
• --aa-provider or --aa-mode: AA-specific controls that also force AA mode. Cannot be used with --eoa.

Examples (the user's environment is assumed already configured — the skill does not set it):

# Default: zero-config AA via the backend proxy.
aomi tx sign tx-1

# Force EOA only
aomi tx sign tx-1 --eoa

# Explicit AA provider and mode
aomi tx sign tx-1 --aa-provider pimlico --aa-mode 4337

If aomi tx sign fails because credentials are missing, stop and ask the user to configure them — do not try to set them from the skill.

Batch Simulation

Use aomi tx simulate to dry-run pending transactions before signing. Simulation runs each tx sequentially on a forked chain so state-dependent flows (approve → swap) are validated as a batch — the swap sees the approve's state changes.

# Simulate a single pending tx
aomi tx simulate tx-1

# Simulate a multi-step batch in order (approve then swap)
aomi tx simulate tx-1 tx-2

The response includes per-step success/failure, revert reasons, and gas usage:

Simulation result:
  Batch success: true
  Stateful: true
  Total gas: 147821

  Step 1 — approve USDC
    success: true
    gas_used: 46000

  Step 2 — swap on Uniswap
    success: true
    gas_used: 101821

When to simulate:

• Always simulate multi-step flows (approve → swap, approve → deposit, etc.) before signing. These are state-dependent — the second tx will revert if submitted independently.
• Optional for single independent txs like a simple ETH transfer or a standalone swap with no prior approval needed.
• If simulation fails at step N, read the revert reason before retrying. Common causes: insufficient balance, expired quote/timestamp, wrong calldata. Do not blindly re-sign after a simulation failure.

When not to simulate:

• Read-only operations (balances, prices, quotes).
• If there are no pending transactions (aomi tx list shows nothing).

For the full simulation-and-signing workflow on a multi-step batch, see references/examples.md.

Account Abstraction (operational notes)

The default signing path is AA. Most invocations need no AA flags — aomi tx sign tx-1 is enough. Use --eoa only when the user explicitly asks to skip AA. Use --aa-provider/--aa-mode only when the user wants to force a specific path.

For deeper details (execution model, mode fallback, providers, modes, sponsorship, chain defaults, RPC guidance per chain), read references/account-abstraction.md.

A few signing rules that always apply:

• aomi tx sign handles both transaction requests and EIP-712 typed-data signatures. Batch signing is supported for transactions only, not EIP-712.
• A single --rpc-url override cannot be used for a mixed-chain multi-sign request.
• The pending transaction already contains its target chain — pass --rpc-url matching that chain if the default RPC is wrong.

Session And Storage Notes

A session is split across two stores: the backend holds the conversation transcript and tool calls; the local disk ($AOMI_STATE_DIR or ~/.aomi/) holds the lookup keys, pending/signed tx state, and secret handle names. aomi tx list reads local; aomi session log reads backend.

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

For the full layout (~/.aomi/sessions/session-N.json, active-session.txt, etc.), the local-vs-backend split, lifecycle rules for --new-session vs resume, and cleanup hygiene, read references/session.md.

Reference: Commands

Chat

aomi chat "<message>" --new-session
aomi chat "<message>" --verbose
aomi chat "<message>" --model <rig>
aomi chat "<message>" --public-key 0xUserAddress --chain 1
aomi chat "<message>" --app khalani --chain 137

• Quote the message.
• On the first command in a new assistant thread, prefer --new-session.
• Use --verbose to stream tool calls and agent output.
• Use --public-key on the first wallet-aware message.
• Use --app, --model, and --chain to change the active context for the next request.

Transaction Commands

aomi tx list
aomi tx simulate <id> [<id> ...]
aomi tx sign <id> [<id> ...]

• aomi tx list inspects pending and signed requests.
• aomi tx simulate runs a simulation batch for the given tx IDs.
• aomi tx sign signs and submits one or more queued requests.

Session Commands

aomi session list
aomi session new
aomi session resume <id>
aomi session delete <id>
aomi session status
aomi session log
aomi session events
aomi session close

• aomi session status shows the current session summary.
• aomi session log replays conversation and tool output.
• aomi session events shows raw backend system events.
• aomi session close clears the active local session pointer. The next chat starts fresh.
• Session selectors accept the backend session ID, session-N, or N.

Secret Commands

aomi secret list                       # skill-driven; handle names only, no values
aomi secret clear                      # skill-driven when the user asks to reset
aomi secret add NAME=<value> [NAME=...]  # user-directed only (see "Secret Ingestion")

• aomi secret list shows configured secret handles for the active session (no values).
• aomi secret clear removes all configured secrets for the active session.
• aomi secret add is run only when the user explicitly asked and supplied the value in this turn; see "Secret Ingestion" for the trust-boundary note the skill must surface before running it.

App And Model Commands

The skill invokes the read forms freely. set forms mutate persistent state and should only be run when the user has explicitly asked for a change.

aomi app list
aomi app current
aomi model list
aomi model current
aomi model set <rig>       # only when the user asked to change the model

• aomi app list shows available backend apps.
• aomi app current shows the active app from local session state.
• aomi model set <rig> persists the selected model for the current session.
• aomi chat --model <rig> "<message>" applies a model for one turn without persisting it.

Apps

Select an app for a chat turn with --app <name> or AOMI_APP=<name>. The set of installed apps is dynamic — confirm with aomi app list / aomi app current. For the full catalog, app-specific tools, credential requirements, and per-category usage examples (solver networks, cross-chain, prediction markets, CEX, social), read references/apps.md.

To build a new app from an API spec or SDK, use the companion skill aomi-build.

Chain Commands

The skill invokes the read forms freely. aomi chain set persists a new default chain and should only be run when the user has asked for that change.

aomi chain list
aomi chain current
aomi chain set <id>        # only when the user asked to change the default chain

Wallet And Config Commands

These persist state, so they are only run when the user explicitly asks and — for wallet set — supplies the value in this turn.

aomi wallet current             # skill-driven; safe to run freely
aomi wallet set <signing-key>           # user-directed only; the user supplies <key>
aomi config current             # skill-driven; safe to run freely
aomi config set-backend <url>   # user-directed only; changes where the CLI talks to

• aomi wallet current shows the configured wallet address only, no credential.
• aomi wallet set persists a signing key locally under AOMI_STATE_DIR. The skill may run it only when the user asked to configure a wallet and provided the key in this turn. After running, confirm with the derived address — do not repeat the key value back.
• aomi config current shows the backend URL.
• aomi config set-backend repoints the CLI at a different backend. The skill runs it only when the user explicitly asked for that change.

Reference: Account Abstraction

The CLI is AA-first: by default it signs via AA (zero-config Alchemy proxy if the user has nothing configured) and only falls back to EOA when --eoa is passed.

For execution-model details, mode fallback rules, provider/mode flags, sponsorship, default chain modes, supported chains, and RPC guidance, read references/account-abstraction.md.

Reference: Configuration

Flags And Env Vars

All config can be passed as flags. Flags override environment variables.

Flag	Default	Purpose
--backend-url	https://api.aomi.dev	Backend URL
--api-key	none	API key for non-default apps (user-supplied; do not pass on the skill's initiative)
--app	default	Backend app
--model	backend default	Session model
--new-session	off	Create a fresh active session for this command
--public-key	none	Wallet address for chat/session context
--rpc-url	chain RPC default	RPC override for signing
--chain	none	Active wallet chain (inherits session chain if unset)
--eoa	off	Force plain EOA, skip AA even if configured (sign-only)
--aa	off	Force AA, error if provider not configured (sign-only)
--aa-provider	auto-detect	AA provider override: alchemy | pimlico (sign-only)
--aa-mode	chain default	AA mode override: 4337 | 7702 (sign-only)

The aomi CLI also resolves credentials on its own from the user's environment. The skill treats this as opaque — it does not read those values, echo them, set them, or ask the user to paste them into chat. If the CLI reports a missing credential, ask the user to configure it themselves and re-run.

Storage

Env Var	Default	Purpose
AOMI_STATE_DIR	~/.aomi	Root directory for local session state
AOMI_CONFIG_DIR	~/.aomi	Root directory for persistent config

For the full file layout (sessions/session-N.json, active-session.txt, the local-vs-backend split, cleanup hygiene), read references/session.md. AA config is supplied per-invocation; there is no persistent aa.json file the skill writes.

Important Config Rules

• Signing keys must be 0x-prefixed hex. Configuring them is a user action, not a skill action.
• The default signing RPC is one URL. For chain switching, pass --rpc-url on aomi tx sign with a chain-matching public RPC.
• If the user switches from Ethereum to Polygon, Arbitrum, Base, Optimism, or Sepolia, use a chain-matching RPC for signing.
• --aa-provider and --aa-mode cannot be used with --eoa.
• In auto-detect mode, the CLI falls back to a zero-config AA path when no provider is configured on the user's side — signing still works without any user-supplied credentials.

Reference: Examples

For four canonical end-to-end flow examples — approve + swap, lending, bridging, staking — read references/examples.md. For per-app first-turn examples (Khalani, 0x, Polymarket, Binance, Neynar), see references/apps.md.

Quick read-only sanity check:

aomi chat "what is the price of ETH?" --verbose
aomi session log

Troubleshooting

When a command fails unexpectedly (no response, AA error, RPC 401/429, simulation revert, stateful: false), read references/troubleshooting.md.