Skip to content

Commit 585fc51

Browse files
jayden-sudojayden-sudo
committed
Update README.md
1 parent 425174f commit 585fc51

1 file changed

Lines changed: 248 additions & 1 deletion

File tree

‎README.md‎

Lines changed: 248 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1,248 @@
1-
# AgentWallet
1+
# AgentWallet
2+
3+
AgentWallet is a command-line Ethereum wallet built for AI agents and automation. It provides a scriptable, cross-platform interface for managing Ethereum accounts, sending transactions, and interacting with dApps via WalletConnect.
4+
5+
## Features
6+
7+
- **Script-friendly**: All operations accessible via CLI flags with structured JSON output (`--json`)
8+
- **Daemon architecture**: Persistent background server with lightweight CLI client
9+
- **Cross-platform**: Single binary for Windows, macOS, Linux, and Android
10+
- **WalletConnect v2**: Connect to any dApp supporting WalletConnect
11+
- **Session Keys**: Delegate limited permissions to sub-accounts (spending limits, contract restrictions, expiry)
12+
- **Multi-network**: Support for any EIP-155 compatible Ethereum network
13+
- **Clear exit codes**: Machine-parseable success/failure indicators
14+
15+
## Installation
16+
17+
### From Source
18+
19+
```bash
20+
git clone https://github.com/BlockEase/AgentWallet.git
21+
cd agentwallet
22+
make build
23+
```
24+
25+
The binary will be at `bin/agentwallet`.
26+
27+
### Cross-compilation
28+
29+
```bash
30+
# Linux
31+
GOOS=linux GOARCH=amd64 make build
32+
33+
# Windows
34+
GOOS=windows GOARCH=amd64 make build
35+
36+
# Android
37+
GOOS=android GOARCH=arm64 make build
38+
```
39+
40+
## Quick Start
41+
42+
```bash
43+
# Start the daemon (auto-started on first command if not running)
44+
agentwallet --daemon
45+
46+
# Create a new wallet
47+
agentwallet account create --password "your-password"
48+
49+
# List accounts
50+
agentwallet account list
51+
52+
# Check balance (works for any address)
53+
agentwallet balance --address 0x... --network ethereum
54+
55+
# Send transaction
56+
agentwallet send --network ethereum --from 0x... --to 0x... --value 0.1 --password "your-password"
57+
58+
# Check transaction status
59+
agentwallet tx status --guid <guid>
60+
61+
# Connect to a dApp via WalletConnect
62+
agentwallet wc connect --network ethereum --address 0x... --uri "wc:..."
63+
```
64+
65+
## Architecture
66+
67+
AgentWallet runs as two components:
68+
69+
1. **Daemon** (`agentwallet --daemon`): A background HTTP server on `localhost:6756` that manages keys, signs transactions, and maintains WalletConnect sessions.
70+
71+
2. **CLI Client** (`agentwallet <command>`): A lightweight client that communicates with the daemon via HTTP. If the daemon is not running, it is started automatically.
72+
73+
```
74+
┌──────────────┐ HTTP/JSON ┌──────────────────┐
75+
│ CLI Client │ ◄──────────────────────► │ Daemon │
76+
│ (one-shot) │ localhost:6756 │ (persistent) │
77+
└──────────────┘ │ │
78+
│ ┌─────────────┐ │
79+
│ │ Keystore │ │
80+
│ ├─────────────┤ │
81+
│ │ Tx Manager │ │
82+
│ ├─────────────┤ │
83+
│ │ WC Sessions │ │
84+
│ └─────────────┘ │
85+
└────────┬─────────┘
86+
│
87+
Ethereum RPC / WalletConnect Relay
88+
```
89+
90+
## Commands
91+
92+
### General
93+
94+
| Command | Description |
95+
|---------|-------------|
96+
| `agentwallet version` | Print version number |
97+
| `agentwallet build-info` | Print build information (platform, time, git commit) |
98+
99+
### Network
100+
101+
| Command | Description |
102+
|---------|-------------|
103+
| `agentwallet networks` | List configured networks |
104+
105+
### Account
106+
107+
| Command | Description |
108+
|---------|-------------|
109+
| `agentwallet account list` | List wallet accounts with supported networks |
110+
| `agentwallet account create --password <pass>` | Create new account |
111+
112+
### Transaction
113+
114+
| Command | Description |
115+
|---------|-------------|
116+
| `agentwallet balance --address <addr> --network <name>` | Get ETH balance for any address |
117+
| `agentwallet send --network <name> --from <addr> [flags]` | Send a transaction, returns a GUID |
118+
| `agentwallet tx status --guid <guid>` | Poll transaction status by GUID |
119+
120+
#### `send` flags
121+
122+
| Flag | Required | Description |
123+
|------|----------|-------------|
124+
| `--network` | Yes | Network name, chain ID, or `eip155:<id>` |
125+
| `--from` | Yes | Sender wallet address |
126+
| `--to` | No | Recipient address (omit for contract creation) |
127+
| `--value` | No | ETH amount to send (e.g., `0.1`) |
128+
| `--data` | No | Hex-encoded calldata |
129+
| `--nonce` | No | Override nonce |
130+
| `--gas-price` | No | Gas price in wei |
131+
| `--password` | Yes | Wallet password |
132+
133+
### WalletConnect
134+
135+
| Command | Description |
136+
|---------|-------------|
137+
| `agentwallet wc status` | List active WalletConnect sessions |
138+
| `agentwallet wc connect --network <n> --address <a> --uri <wc_uri>` | Connect to a dApp |
139+
| `agentwallet wc switch --session <id> [--address <a>] [--network <n>]` | Switch session params |
140+
| `agentwallet wc disconnect --session <id>` | Disconnect a session |
141+
142+
## Global Flags
143+
144+
| Flag | Description |
145+
|------|-------------|
146+
| `--json` | Output in JSON format (machine-readable) |
147+
| `--config <path>` | Path to configuration file |
148+
| `--addr <host:port>` | Server address (default: `127.0.0.1:6756`) |
149+
| `--daemon` | Run as background server daemon |
150+
151+
## Configuration
152+
153+
AgentWallet uses a JSON configuration file. Default location: `~/.agentwallet/wallet.conf`
154+
155+
```json
156+
{
157+
"networks": [
158+
{
159+
"name": "ethereum",
160+
"chain_id": 1,
161+
"rpc_url": "https://eth.llamarpc.com"
162+
},
163+
{
164+
"name": "sepolia",
165+
"chain_id": 11155111,
166+
"rpc_url": "https://rpc.sepolia.org"
167+
},
168+
{
169+
"name": "base",
170+
"chain_id": 8453,
171+
"rpc_url": "https://mainnet.base.org"
172+
}
173+
],
174+
"keystore_dir": "",
175+
"server_addr": "127.0.0.1:6756"
176+
}
177+
```
178+
179+
Network names follow [EIP-155](https://eips.ethereum.org/EIPS/eip-155) chain IDs from [chainid.network](https://chainid.network/). You can reference networks by name, numeric chain ID, or `eip155:<chain_id>` format.
180+
181+
## JSON Output
182+
183+
All commands support `--json` for structured output suitable for piping and automation:
184+
185+
```bash
186+
$ agentwallet --json balance --address 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045 --network ethereum
187+
{
188+
"address": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
189+
"network": "ethereum",
190+
"chain_id": 1,
191+
"balance_wei": "1000000000000000000",
192+
"balance_eth": "1.000000000000000000"
193+
}
194+
```
195+
196+
Errors are written to stderr (or included in the JSON envelope with `"success": false`).
197+
198+
## Exit Codes
199+
200+
| Code | Meaning |
201+
|------|---------|
202+
| 0 | Success |
203+
| 1 | General error |
204+
| 2 | Invalid arguments |
205+
206+
## Data Directory
207+
208+
```
209+
~/.agentwallet/
210+
├── wallet.conf # Configuration file
211+
├── keystore/ # Encrypted account keys (go-ethereum keystore format)
212+
└── logs/ # Daemon logs
213+
```
214+
215+
## Session Keys (Planned)
216+
217+
AgentWallet will support delegated sub-accounts with configurable permissions:
218+
219+
- Time-limited validity (e.g., expires in N days)
220+
- Maximum spending limits per token
221+
- Whitelist of allowed contract addresses
222+
- Network restrictions
223+
224+
This enables safe delegation of wallet access to AI agents with bounded capabilities.
225+
226+
## Building
227+
228+
```bash
229+
make build # Build binary
230+
make install # Install to GOPATH/bin
231+
make test # Run tests
232+
make clean # Remove build artifacts
233+
```
234+
235+
Build flags are injected automatically:
236+
237+
```bash
238+
$ agentwallet build-info
239+
Version: v0.1.0
240+
Git Commit: abc1234
241+
Build Time: 2026-02-10T00:00:00Z
242+
Go Version: go1.22.0
243+
Platform: darwin/arm64
244+
```
245+
246+
## License
247+
248+
See [LICENSE](LICENSE) for details.

0 commit comments

Comments
 (0)