aawp

AAWP (AI Agent Wallet Protocol) — the only crypto wallet protocol built exclusively for AI Agents on EVM-compatible blockchains. Not for humans. The signer is the AI Agent itself, cryptographically bound at wallet creation. Supports wallet lifecycle management, token transfers, DEX swaps, cross-chain bridging, arbitrary contract interactions, DCA automation, and price alerts.

# AAWP — AI Agent Wallet Protocol

The only crypto wallet protocol built exclusively for AI Agents. Not for humans.

AAWP enforces a single invariant: the signer is the AI Agent itself — locked in at wallet creation, immutable, verifiable on-chain. AI Agents manage their own on-chain assets across EVM networks through a guardian-based architecture. Transactions are signed locally via a sharded-key daemon — no human approval per tx, with full recovery and freeze capabilities for the human guardian.

**Networks:** Ethereum · Base · BNB Chain · Polygon · Optimism · Arbitrum

---

## Architecture Overview

```
┌─────────────────────────────────────────────────┐
│  AI Agent (OpenClaw)                            │
│  ┌───────────────┐    ┌──────────────────────┐  │
│  │ wallet-manager│───▶│  Signing Daemon       │  │
│  │ dca / alerts  │    │  (Unix socket)        │  │
│  └───────────────┘    │  ┌──────────────────┐ │  │
│                       │  │ aawp-core.node   │ │  │
│                       │  │ (Rust N-API)     │ │  │
│                       │  └──────────────────┘ │  │
│                       └──────────┬───────────┘  │
│                                  │ sign          │
│  ┌───────────────┐               ▼              │
│  │ Guardian Key  │──▶ Pay gas ──▶ EVM Chain     │
│  │ (gas only)    │               │              │
│  └───────────────┘    ┌──────────▼───────────┐  │
│                       │ Smart Contract Wallet │  │
│                       │ (holds assets)        │  │
│                       └──────────────────────┘  │
└─────────────────────────────────────────────────┘
```

**Key separation:** Guardian pays gas → Wallet holds assets → Daemon signs transactions.

---

## Quick Reference

| Task | Command |
|------|---------|
| Create wallet | `wallet-manager.js --chain base create` |
| Check balance | `wallet-manager.js --chain base balance` |
| Send ETH | `wallet-manager.js --chain base send <to> <amount>` |
| Send ERC-20 | `wallet-manager.js --chain base send-token USDC <to> <amount>` |
| Get swap quote | `wallet-manager.js --chain base quote ETH USDC 0.01` |
| Execute swap | `wallet-manager.js --chain base swap ETH USDC 0.01` |
| Bridge cross-chain | `wallet-manager.js --chain base bridge ETH optimism 0.1` |
| Contract call | `wallet-manager.js --chain base call <addr> "fn(args)" ...` |
| Contract read | `wallet-manager.js --chain base read <addr> "fn() returns (uint)" ...` |
| DCA strategy | `dca.js add --chain base --from ETH --to USDC --amount 0.01 --cron "0 9 * * *"` |
| Price alert | `price-alert.js add --chain base --from ETH --to USDC --above 2600 --notify` |
| Cross-chain portfolio | `portfolio.js` |
| Single chain portfolio | `portfolio.js --chain base` |
| Limit order | `limit-order.js --chain base create ETH USDC 0.1 2700` |
| List orders | `limit-order.js --chain base list` |
| List NFTs | `nft.js --chain base balance` |
| NFT transfer | `nft.js --chain base transfer <contract> <tokenId> <to>` |
| NFT floor price | `nft.js --chain eth floor <contract>` |
| Yield rates | `yield.js --chain base rates` |
| Supply collateral | `yield.js --chain base supply USDC 1000` |
| Borrow | `yield.js --chain base borrow USDC 200` |
| Aave positions | `yield.js --chain base positions` |
| Diagnostics | `bash scripts/doctor.sh` |
| Backup | `wallet-manager.js backup ./backup.tar.gz` |

All commands: `node scripts/wallet-manager.js --help`

---

## Getting Started

### 1. Provision

First run is automatic — `ensure-daemon.sh` detects a missing seed and provisions.

```bash
bash scripts/provision.sh            # Initialize
bash scripts/provision.sh --reset    # Full reset (⚠️ destroys existing wallet)
```

### 2. Create Wallet

```bash
node scripts/wallet-manager.js --chain base create
```

If the Guardian needs gas, you'll see a funding guide with the Guardian address and private key.

### 3. Pin & Fund

```bash
export AAWP_WALLET=0x...            # Pin your wallet address
# Send a small amount of native token to the wallet address
node scripts/wallet-manager.js --chain base balance
```

### 4. Test

```bash
node scripts/wallet-manager.js --chain base quote ETH USDC 0.001
node scripts/wallet-manager.js --chain base swap ETH USDC 0.001
```

> After fresh provisioning, verify the daemon binary hash is approved on the factory contract. If not, the factory owner must call `approveBinary(hash)`.

---

## Wallet Manager CLI

**Entry point:** `node scripts/wallet-manager.js`
**Chain flag:** `--chain <base|bsc|polygon|optimism|arbitrum|ethereum>`

### Wallet Lifecycle

```bash
wallet-manager.js --chain base status          # Status overview
wallet-manager.js --chain base balance         # Native + token balances
wallet-manager.js --chain base portfolio       # Full portfolio view
wallet-manager.js compute-address              # Predict wallet address
wallet-manager.js --chain base history         # Transaction history
wallet-manager.js --chain base upgrade-signer  # Rotate signer key
wallet-manager.js --chain base guardian-chains  # Guardian chain info
```

### Transfers

```bash
wallet-manager.js --chain base send <recipient> <amount>
wallet-manager.js --chain base send-token <symbol> <recipient> <amount>
```

### Trading

```bash
wallet-manager.js --chain base quote <from> <to> <amount>    # Preview (no gas)
wallet-manager.js --chain base swap <from> <to> <amount>     # Execute
wallet-manager.js --chain base bridge <token> <dest> <amount> # Cross-chain
```

### Approvals

```bash
wallet-manager.js --chain base approve <token> <spender> <amount>
wallet-manager.js --chain base allowance <token> <spender>
wallet-manager.js --chain base revoke <token> <spender>
```

### Contract Interaction

```bash
# Write (sends tx)
wallet-manager.js --chain base call <contract> "transfer(address,uint256)" 0xTo 1000

# Read (free)
wallet-manager.js --chain base read <contract> "balanceOf(address) returns (uint256)" 0xAddr

# Batch (atomic)
wallet-manager.js --chain base batch ./calls.json
```

Batch format:
```json
[
  { "to": "0x...", "sig": "approve(address,uint256)", "args": ["0x...", "1000000"] },
  { "to": "0x...", "sig": "transfer(address,uint256)", "args": ["0x...", "500000"] }
]
```

### Address Book

```bash
wallet-manager.js addr add <label> <address>
wallet-manager.js addr list
wallet-manager.js addr get <label>
wallet-manager.js addr remove <label>
```

### RPC & Backup

```bash
wallet-manager.js get-rpc
wallet-manager.js --chain base set-rpc <url|default>
wallet-manager.js backup ./backup.tar.gz
wallet-manager.js restore ./backup.tar.gz
```

---

## DCA Automation

**Entry point:** `node scripts/dca.js`

```bash
dca.js add --chain base --from ETH --to USDC --amount 0.01 --cron "0 9 * * *" --name "Daily ETH→USDC"
dca.js list
dca.js run <id>
dca.js history <id>
dca.js remove <id>
```

Registers an OpenClaw cron job that executes swaps on schedule.

---

## Price Alerts

**Entry point:** `node scripts/price-alert.js`

```bash
# Notification only
price-alert.js add --chain base --from ETH --to USDC --above 2600 --notify

# Auto-swap on trigger
price-alert.js add --chain base --from ETH --to USDC --below 2200 --notify --auto-swap 0.01

price-alert.js list
price-alert.js check
price-alert.js remove <id>
```

---

## Daemon Management

| Script | Purpose |
|--------|---------|
| `scripts/doctor.sh` | Full diagnostic check |
| `scripts/ensure-daemon.sh` | Start daemon if not running (auto-provisions on first run) |
| `scripts/restart-daemon.sh` | Force restart |

Run `doctor.sh` before sensitive operations or when signing seems off.

---

## Cross-Chain Portfolio View

**Entry point:** `node scripts/portfolio.js`
**Supported chains:** All 6 (base · eth · arb · op · polygon · bsc) — queried **in parallel**

### Commands

```bash
portfolio.js                      # Full cross-chain summary with USD values
portfolio.js --chain base         # Single chain only
portfolio.js --no-prices          # Skip CoinGecko pricing (faster)
portfolio.js --hide-zero