Designing defi-cli for AI Agents

How defi-cli lets Agents swap, lend, bridge and claim rewards without clicking a single button

Most DeFi tooling assumes there’s a human on the other end; someone clicking buttons, approving transactions, checking dashboards, etc. But now the user on the other end might be an AI Agent managing a portfolio, optimizing yield and executing trades across chains. And it can’t click buttons. That’s why I built defi-cli, a command-line interface (CLI) that lets Agents query rates, compare yield, swap, lend, borrow, bridge and claim rewards across 26+ chains.

Why a CLI and not an MCP server?

Model Context Protocol (MCP) servers became a popular approach for giving Agents access to external tools. After building both, I would recommend against them where possible. They introduce significant context overhead in the form of schema descriptions, tool metadata and connection management that consumes the Agent’s limited context window. A CLI avoids this entirely. The Agent calls a command, receives structured output and proceeds. No persistent connection, no schema negotiation.

Humans want dashboards. Agents want tools they can pipe, and that don’t bloat their context windows.

What “Agent-first” actually means

“Built for Agents” is a common claim but rarely defined with precision. The design of defi-cli was informed by Google’s CLI guidelines for AI Agents, and the changes that had the most impact were smaller than expected.

--output json everywhere. Humans dislike writing JSON in a terminal but Agents operate natively in it. Every command accepts --input-json and --input-file for structured input and returns deterministic JSON with stable field ordering. This single change makes the CLI significantly more useful to an Agent.

Field selection with --select. Agents have context windows, not infinite memory. Allowing them to request only the fields they need (--select “protocol,apy,tvl”) keeps responses compact and preserves their working memory.

Simulation before execution. Agents require a safe mechanism to dry-run before committing real funds. The --simulate flag (enabled by default) runs an eth_call of every step’s calldata before signing anything, and if the call reverts the submission aborts. There is also actions estimate for computing gas and fees without executing.

I also published a set of skills for coding Agents based on these patterns, so your Claude Code or Codex Agent can build and audit CLIs with Agent ergonomics in mind. The repo includes other agentic skills you might find useful.

The execution lifecycle: plan → submit → status

Early versions of defi-cli had a single run command that combined plan and submit in one step. After studying the Google guidelines, I removed it. Combining those two steps creates a direct path to unwanted transactions. There needs to be a separation between intent and execution.

plan builds the calldata, resolves routes and allowances, then persists the action to a local SQLite database with a unique action_id. Nothing touches the chain.

submit loads the persisted action, runs policy checks, simulates via eth_call (unless explicitly opted out), estimates gas, signs, broadcasts and polls for a receipt. This is the only step that mutates on-chain state.

status reads the persisted action and returns step-level progress, which is useful for Agents that need to poll or retry.

The phrasing “plan, simulate, submit” appears in some descriptions and is conceptually accurate, since simulation happens automatically within the submit step. But the actual CLI surface is plan | submit | status.

Signing and key management

Early versions of defi-cli used local signers via private key or keystore file. This worked but had two problems. Every tool and agent framework stored keys in its own custom structure, and the agent had direct access to signing keys with no restrictions on what it could do with them.

The default signing method is now Open Wallet Standard (OWS), a standard proposed by MoonPay. OWS changes two things that matter for agents. First, keys are stored securely in a single location rather than scattered across every tool the agent touches. Second, agents don’t get direct access to signing keys. They get API keys with policies attached, allowing developers to restrict which chains, protocols and even amounts an agent can use. This reduces the blast radius if the agent makes a mistake or leaks the keys.

defi-cli still supports local signing for backwards compatibility, but OWS is the preferred approach now.

Why historical yield matters for Agents

A naive yield Agent deposits funds wherever the current APY is highest. This is a poor strategy because it optimizes for a single data point that may represent a temporary spike. The better approach is to weight decisions across both current rates and historical performance. defi-cli provides Agents with historical yield data over flexible time windows to support exactly this kind of analysis.

Position tracking per account is also supported, allowing Agents to monitor lend and yield positions without relying on dashboard scraping.

What broke (and what I’d tell you before you build an Agent-first CLI)

Design for Agents from day one. Retrofitting Agent ergonomics onto a human-first CLI is costly. JSON output, structured input, deterministic exit codes, canonical identifiers (defi-cli uses CAIP-2 and CAIP-19) all need to be foundational, not afterthoughts. Starting without them means rewriting significant portions of the interface later.

Plan your command surface carefully. Every command added is surface area an Agent must parse and understand. The run command I removed is instructive here. It was convenient for human users but created risk for Agents. A smaller, more deliberate command surface is preferable.

Distribute a skill alongside your CLI. Agents need a skill or prompt that encodes usage patterns for the tool. Which commands to chain, what flags are relevant, what patterns to avoid. Without that the Agent is left to infer usage from --help output alone.

Standardize across protocols and providers. DeFi suffers from fragmented APIs, inconsistent naming conventions and varied data formats. The CLI abstracts these differences behind a uniform command surface. Whether lending on Aave, Morpho or Kamino, the interface is lend supply plan, lend supply submit, lend supply status. Same verbs, same lifecycle, regardless of provider.

What it supports today

defi-cli currently supports 26+ chains including Ethereum, Solana, Base, Arbitrum, Optimism, Taiko, Polygon, zkSync Era, Mantle, Ink, Gnosis, Linea, Berachain, Scroll, Avalanche, BSC, Celo, Blast, Fraxtal, Sonic, MegaETH, HyperEVM, Citrea, World Chain, Monad and others.

On the protocol side it supports Aave, Morpho and Kamino for lending/yield. Uniswap, 1inch, Jupiter and TaikoSwap for swaps. Across, LiFi and Bungee for bridging. DefiLlama for analytics.

The project is open source. Ask your agent to install it(or run the installer yourself) and give your agent defi superpowers.

This post is exploratory and does not represent a specific roadmap.

---

Gustavo Gonzalez leads the engineering team at Taiko. defi-cli is open source and available HERE.