AgentRail

AgentRail is a protocol layer that lets agents discover, reason about, and execute onchain actions through structured JSON.

The protocol is generic. It is designed to work across EVM contracts and DeFi protocols, not just one integration. Aave-specific methods in this repo are examples of higher-level adapters built on top of the same core protocol surface.

The goal is simple:

• make onchain actions easier for agents to discover
• make common tasks safer by default
• reduce the amount of ABI / RPC / glue logic an agent has to invent
• return outputs that are small, structured, and easy for models to use

Why This Exists

Most onchain tooling is built for developers:

• SDKs expect you to know the ABI
• contract calls return raw values, not task-level meaning
• every agent has to rediscover the same steps: find contract -> resolve ABI -> read decimals -> format balance -> simulate -> send -> decode receipt

AgentRail packages that into a protocol surface designed for agents.

Instead of only offering low-level primitives like readContract, it also offers:

• registry.lookup
• token.balance
• protocol-specific adapters
• action.plan
• receipt.decode

Why This Is Useful For Agents

Compared with raw contract-call primitives, this protocol adds:

• ABI flexibility It can use a provided ABI, abiPath, explorer/Sourcify discovery, built-in standards, or a minimal function signature plus returns.

• Higher-level methods Agents can ask for token.balance, protocol adapters, or planning methods instead of stitching together multiple raw reads.

• Safer write flows simulate-first, signer guards, policy checks, and explicit error advice are built into the protocol surface.

• Agent-friendly outputs Responses can include formatted, summary, highlights, bestMatch, and effects, not just raw onchain values.

• Self-description The protocol exposes rpc.discover, --llms, and per-method schema output.

• Token-efficient responses CLI and protocol-level output filtering support smaller responses for LLM runtimes.

FAQ

How does this fit with existing SDKs and infra?

No. AgentRail is a protocol layer that can sit on top of existing SDKs, clients, and RPC infrastructure. It is designed for agent workflows, structured outputs, and safer task-level operations rather than replacing lower-level tools.

Is this only for Aave?

No. Aave is the first high-level adapter in the repo today, but the protocol itself is generic. It already supports generic contract reads, simulation, transaction building, sending, and receipt decoding for arbitrary EVM contracts.

Do I need a full ABI for every read?

Not always. You can provide a full ABI, an abiPath, rely on ABI discovery, or use minimal function-signature mode with returns.

Is it safe to let an agent send transactions?

Safer than handing an agent a raw SDK by default, but still sensitive. AgentRail is built around explicit callers, simulation-first flows, policy checks, and signer isolation. You should still use dedicated wallets, limits, and allowlists in real deployments.

What It Can Do

At a high level, AgentRail gives agents three layers of capability:

• generic contract access
• safer transaction execution
• optional protocol-specific adapters for common workflows

Core contract methods:

• contract.inspect
• contract.functions
• contract.describe
• contract.read
• batch.read
• contract.simulate
• tx.build
• tx.send
• receipt.decode

Built-in higher-level methods and adapters today:

• registry.lookup
• token.balance
• aave.positions
• action.plan

aave.positions is an example adapter, not the boundary of the protocol. AgentRail's core contract methods are intended to work across any EVM-based DeFi protocol as long as the contract is reachable and the ABI can be provided or discovered.

Agent-Friendly Features

• Aliases lookup, tokenBalance, positions, plan, read, simulate, build, send, decode

• Manifest and schemas --llms and schema <method>

• Protocol-level output shaping output.paths, output.view, output.limit

• Built-in summaries summary, highlights, bestMatch, effects

• Structured error advice retryable, likelyCauses, suggestedNextActions

Quick Start

1. Install

From npm:

npm install -g agentrail

Run without global install:

npx agentrail --llms

From local source:

cd /path/to/AgentRail
bun install
bun link

After linking, the CLI is available as agentrail. The legacy alias acp still works for compatibility.

2. Configure Access

For many read-only flows, the built-in public RPC defaults are enough to get started.

If you want custom RPCs, explorer-backed ABI resolution, or transaction signing, configure .env from .env.example or set the same variables directly in your environment.

For the full environment variable reference, see docs/configuration.md.

3. Ask The Protocol What It Supports

LLM-friendly manifest:

agentrail --llms

Method schema:

agentrail schema contract.read

4. Run A Simple Read

Minimal signature mode, no full ABI required:

agentrail call read --json '{"chain":"bnb","address":"0x9B00a09492a626678E5A3009982191586C444Df9","function":"balanceOf(address)","args":["0x5f0599dade40b691caaf156ec7dc6121833d58bb"],"returns":["uint256"],"decimals":18}'

5. Use A Generic Protocol Flow

Look up a known registry entry:

agentrail call lookup --json '{"chain":"bnb","protocol":"aave","symbol":"WBNB"}'

Read a token balance with formatting:

agentrail call tokenBalance --json '{"chain":"bnb","token":"0x9B00a09492a626678E5A3009982191586C444Df9","owner":"0x5f0599dade40b691caaf156ec7dc6121833d58bb"}'

Simulate an arbitrary DeFi contract call:

agentrail call simulate --json '{"chain":"bnb","address":"0xYourContract","function":"deposit(uint256,address)","args":["1000000000000000000","0xYourWallet"],"stateMutability":"nonpayable","caller":"0xYourWallet","policy":{"allowWrites":true,"simulationRequired":true}}'

6. Use A Built-In Protocol Adapter Example

The repo currently includes Aave as one concrete higher-level adapter example:

agentrail call positions --json '{"chain":"bnb","owner":"0x5f0599dade40b691caaf156ec7dc6121833d58bb"}'

Case Study: Aave On BNB

One built-in adapter example today is reading Aave supplied positions on BNB:

agentrail call positions --json '{"chain":"bnb","owner":"0x5f0599dade40b691caaf156ec7dc6121833d58bb"}' --filter-output result.summary,result.highlights

Protocol Mode

AgentRail can also run as a long-lived stdio JSON server for agent runtimes and orchestration systems.

agentrail serve

Minimal discovery request:

{"id":"1","method":"rpc.discover","params":{}}

For protocol-level filtering, compact views, and more detailed server examples, see docs/protocol-mode.md.

Safety Model

Write paths are designed to be more agent-safe than raw SDK usage:

• contract.simulate before execution
• policy checks
• signer isolation
• explicit caller
• receipt decoding
• structured error advice

Design Principles

• Structured first JSON in, JSON out.

• Readable by models Prefer summary, highlights, effects, and bestMatch where possible.

• Flexible ABI resolution abi -> abiPath -> Sourcify -> explorer -> built-in standards -> minimal function signature mode

• Higher-level over repeated glue Common tasks should be one method, not six stitched reads.

• Small outputs matter Agents should be able to request only what they need.

Current Focus

AgentRail is strongest today for:

• contract inspection and simulation
• generic contract reads and token balance queries
• transaction build/send/decode flows
• protocol address lookup
• Aave BNB supply position reads as a current built-in adapter example

Development

Run tests:

bun test

Run typecheck:

bun run typecheck

Live verification script:

bun run verify:live

Build npm distributable files:

npm run build

Open Source

• License: MIT
• Contributing guide: CONTRIBUTING.md
• Project roadmap: ROADMAP.md
• Security policy: SECURITY.md

What’s Next

Good next expansions:

• richer protocol registries
• more high-level methods for DeFi protocols
• better live receipt decoding examples
• stronger protocol-native projections and pagination
• more chain coverage