What do I need to build an onchain agent?

Five components: a reasoning model, a wallet the agent can sign with under strict limits, skills (protocol SDKs or MCP servers) for the actions it takes, data feeds it reads before acting, and guardrails. Most builders start from a framework that bundles the wallet and tooling — browse the options in the directory.

Do I need to know how to code to build an onchain agent?

For a production agent that controls funds, yes — you'll work with a framework's SDK, configure a wallet, and write the agent's logic in TypeScript or Python. No-code launch tools exist, but you still need to understand wallet permissions and guardrails, because those are what stop an agent from losing money.

How do I keep an onchain agent from draining its wallet?

Bound the wallet before you add capability. Use an embedded or policy-controlled signer instead of a raw private key, set per-transaction and per-day spend caps, allow-list the contracts it can call, and require human approval for irreversible actions. Account abstraction (ERC-4337) makes these permissions programmable.

Which framework should I use to build an onchain agent?

Pick for your chain and the actions you need, not the longest feature list. Coinbase AgentKit leans Base/EVM with prebuilt onchain actions; ElizaOS is a TypeScript runtime that's strong when the agent also lives on social; GOAT SDK exposes onchain actions as plug-in tools across many chains. Compare them in the directory.

Should I test on a testnet before going live?

Yes — always. Run the full observe-reason-act-report loop on a testnet like Base Sepolia using faucet tokens until you've seen the agent handle failed transactions, moved prices, and API timeouts. Then go to mainnet with the minimum funds and the tightest caps, and raise limits only as the behavior proves out.

← Back to wiki

How to Build an Onchain Agent

Last updated 2026-06-24

Building an onchain agent means wiring a reasoning model to a policy-controlled wallet and a set of skills, fencing it with guardrails, then proving it on a testnet before it touches mainnet funds.

Key takeaways

▸Start from a framework that bundles a wallet and tools — see the options in the [directory](/directory) — rather than building the plumbing yourself.
▸Give the agent a wallet with spend caps and scoped permissions *before* any mainnet funds; see [how agents use wallets](/wiki/how-agents-use-wallets).
▸Add skills for the actions your agent needs — protocol SDKs or [MCP](/wiki/what-are-mcps) servers — and nothing it doesn't.
▸Set guardrails: human approval for irreversible actions, sandboxes, and kill switches. Autonomy with a wallet amplifies every mistake.
▸Test on a testnet first, then start small on mainnet. Match tools to the job using the [use-case pages](/use-cases).

To build an onchain agent, you connect five things: a reasoning model, a wallet the agent can sign with under strict limits, the skills it needs to act, guardrails that bound what it can do, and a testnet to prove it on before mainnet. Most builders don't assemble that from raw parts — they start from a framework that bundles wallet and tooling, then add the specifics for their job.

The goal is an agent that does one bounded job reliably and can't drain a wallet when something goes wrong. We'll walk the stack in build order and flag the places where a shortcut turns into a loss. For the concepts behind the stack, start with what onchain agents are.

Why It Matters

An onchain agent is the first kind of software that can lose money on its own. A web bot that fails returns an error; an onchain agent that fails can sign a transaction you can't reverse. That raises the bar on how you build: the wallet, the permissions, and the guardrails are not afterthoughts, they're the product. Getting the order right — bound the blast radius first, add capability second — is the whole job.

How It Works

▸Pick a framework that bundles a wallet and tools, so you start with signing, RPC access, and a tool interface already wired together.
▸Provision a wallet the agent controls, but scope it: spend caps, an allow-list of callable contracts, and an embedded or policy-controlled signer rather than a raw key in an env var.
▸Attach skills — the concrete actions the agent can take — as protocol SDKs or Model Context Protocol (MCP) servers, exposing only what the job needs.
▸Wrap the act step in guardrails: human approval for anything irreversible, a sandbox, and a kill switch that revokes the wallet's permissions instantly.
▸Run the full loop — observe, reason, act, report — on a testnet with fake funds until the failure modes are understood.
▸Promote to mainnet with the smallest possible limits, and raise the caps only as the behavior earns trust.

Key Components

•Reasoning model (an LLM or a task-specific model)
•Agent framework or runtime
•Policy-controlled wallet with spend limits
•Skills and tools (protocol SDKs, MCP servers, APIs)
•Data feeds (onchain state, market data, social signals)
•Guardrails (approvals, sandboxes, kill switch)
•A testnet environment and a faucet
•Logging and monitoring for the act step

Step 1 — Pick a framework

Don't start from a blank file. A framework gives you a wallet, RPC access, and a tool interface already connected, so you write the agent's logic instead of its plumbing. The trade-off is opinionation: each one assumes a chain, a model layer, and a tooling style.

Three common starting points, all open-source:

▸[Coinbase AgentKit](/resources/coinbase-agentkit) — a toolkit for giving an agent a wallet and onchain actions, with embedded-wallet support and a library of prebuilt actions (repo). Leans Base/EVM.
▸[ElizaOS](/resources/elizaos) — a TypeScript agent runtime with a plugin system, multi-platform connectors, and onchain plugins (repo). Good when the agent also lives on social.
▸[GOAT SDK](/resources/goat-sdk) — an agent-tooling layer that exposes onchain actions as plug-in tools across many chains and wallet providers (repo).

The selection rule: pick for the chain you're on and the actions you need, not the longest feature list. A framework is a tool to build agents — it is not itself an agent. More in what is an agent framework.

Step 2 — Give it a wallet with limits

This is the step people rush and regret. The agent needs to sign transactions, but the version of "can sign" you ship matters enormously.

Do not hand the agent a raw private key with an unbounded balance. Instead:

▸Use an embedded or policy-controlled wallet (Privy, Turnkey, or your framework's built-in signer) so keys are managed, not pasted into config.
▸Set spend caps — a per-transaction and per-day ceiling the agent cannot exceed.
▸Allow-list contracts and methods. An agent that only swaps on one DEX should not be able to call arbitrary contracts.
▸Consider account abstraction (ERC-4337), which makes programmable permissions and session keys first-class instead of a bolt-on.

The principle is least privilege: the wallet should do the job and nothing past it. Full detail in how agents use wallets.

Step 3 — Add skills and data

A skill is a concrete action the model can call — "swap token A for B," "read this pool's price." Two ways to wire them:

▸Protocol SDKs — direct libraries for a specific protocol or chain, fast and typed but coupled to that protocol.
▸[MCP](/wiki/what-are-mcps) servers — the Model Context Protocol exposes tools in a standard interface, so the agent can pick up new actions without custom glue per integration.

Pair skills with data feeds: the onchain state, market data, and signals the agent reads before it decides. Keep the skill set tight — every extra capability is extra surface area for a bad decision. Browse skills and tools by job in the use-case pages.

Step 4 — Set guardrails

Guardrails are what make autonomy survivable — the reason the agent can run without a human watching every step.

The core set:

Human approval for irreversible actions — sending funds to a new address, approving unlimited token spend, or touching an unknown contract should pause for a human.
Sandbox first. Run the agent against a fork or simulation so you see what a transaction *would* do before it does it.
A kill switch. One command that revokes the wallet's permissions and halts the loop. You will need it.
Rate and value limits at the loop level, not just the wallet — cap how often the agent acts, not only how much it spends.

Guardrails reduce risk; they do not remove it. Prompt injection, a bad oracle, or a reasoning error can still cause loss. Build as if the model will occasionally be wrong — it will be.

Step 5 — Testnet, then mainnet

Prove the full loop where mistakes are free. Most chains have a testnet (Base Sepolia, Sepolia, and others) with a faucet that hands out valueless test tokens. Run the agent end to end until you've seen it handle the cases that scare you: a failed transaction, a price that moved, an API that timed out, a prompt that tried to trick it.

When you go to mainnet, go small: fund the wallet with the minimum the job needs, set caps tighter than you think necessary, watch the act step's logs for the first runs, and raise limits only as the behavior earns it.

There's no testnet for trust. Before relying on *anyone else's* agent or framework, check the evidence rather than the marketing — open code, live activity, reproducible behavior. That gap between claimed and shown is what the Sato Score measures, and it's a transparency signal, not a safety or returns grade.

Examples

▸A swap agent built on Coinbase AgentKit with a Base wallet capped at $50/day and a one-DEX allow-list.
▸An ElizaOS agent that watches a social feed and posts a transaction only after a human approves the address.
▸A treasury agent using GOAT SDK skills to rebalance stablecoins across two venues on a fixed schedule.
▸A read-only research agent that pulls onchain data via MCP servers and never holds a signing key at all.

Risks & Limitations

⚠Over-permissioned wallets: a raw key with no spend cap turns one bad decision into a total loss.
⚠Prompt injection and adversarial data can steer an agent into harmful transactions despite good intentions.
⚠Skipping the testnet hides failure modes — timeouts, reverts, and price moves — until real money is at stake.
⚠Trusting a framework or another agent on its self-reported claims; verify with code and onchain activity, not adjectives.

Frequently Asked Questions

What do I need to build an onchain agent?: Five components: a reasoning model, a wallet the agent can sign with under strict limits, skills (protocol SDKs or MCP servers) for the actions it takes, data feeds it reads before acting, and guardrails. Most builders start from a framework that bundles the wallet and tooling — browse the options in the directory.
Do I need to know how to code to build an onchain agent?: For a production agent that controls funds, yes — you'll work with a framework's SDK, configure a wallet, and write the agent's logic in TypeScript or Python. No-code launch tools exist, but you still need to understand wallet permissions and guardrails, because those are what stop an agent from losing money.
How do I keep an onchain agent from draining its wallet?: Bound the wallet before you add capability. Use an embedded or policy-controlled signer instead of a raw private key, set per-transaction and per-day spend caps, allow-list the contracts it can call, and require human approval for irreversible actions. Account abstraction (ERC-4337) makes these permissions programmable.
Which framework should I use to build an onchain agent?: Pick for your chain and the actions you need, not the longest feature list. Coinbase AgentKit leans Base/EVM with prebuilt onchain actions; ElizaOS is a TypeScript runtime that's strong when the agent also lives on social; GOAT SDK exposes onchain actions as plug-in tools across many chains. Compare them in the directory.
Should I test on a testnet before going live?: Yes — always. Run the full observe-reason-act-report loop on a testnet like Base Sepolia using faucet tokens until you've seen the agent handle failed transactions, moved prices, and API timeouts. Then go to mainnet with the minimum funds and the tightest caps, and raise limits only as the behavior proves out.