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.
bashbash scripts/provision.sh # Initialize bash scripts/provision.sh --reset # Full reset (⚠️ destroys existing wallet)
2. Create Wallet
bashnode 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
bashexport 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
bashnode 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
bashwallet-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
bashwallet-manager.js --chain base send <recipient> <amount> wallet-manager.js --chain base send-token <symbol> <recipient> <amount>
Trading
bashwallet-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
bashwallet-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
bashwallet-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
bashwallet-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
bashdca.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
bashportfolio.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 # Hide zero-balance tokens portfolio.js --json # Raw JSON output (for automation)
Output Includes
- Native balance per chain (ETH / BNB / MATIC)
- All ERC-20 token balances via Multicall3 (1 RPC call per chain)
- USD value per token (CoinGecko public API)
- Total portfolio value across all chains
- Top 8 holdings ranked by USD value with % allocation
- Multi-chain holdings — same token aggregated across chains
Tokens tracked: USDC, USDT, WETH, DAI, WBTC, BNB/WBNB, MATIC, ARB, OP, CAKE, AERO, GMX, PEPE, and more per chain.
Limit Orders (CoW Protocol — Gasless)
Entry point: node scripts/limit-order.js
Supported chains: eth · base · arb · op · polygon (CoW Protocol) · bsc (1inch Limit Orders)
Orders are signed off-chain (EIP-712) and settled by solvers — no gas on order creation (except BSC cancel which is on-chain).
Commands
bashlimit-order.js --chain base create ETH USDC 0.1 2700 # Sell 0.1 ETH at ≥2700 USDC limit-order.js --chain eth create USDC ETH 1000 0.00037 # Buy ETH with 1000 USDC limit-order.js --chain base list # List open orders limit-order.js --chain base history # All orders (filled/expired) limit-order.js --chain base cancel <orderUid> # Cancel open order limit-order.js --chain base create ETH USDC 0.1 2700 --expiry 48 # 48h validity
Notes:
- First-time use requires one ERC-20 approval transaction (CoW VaultRelayer)
price= amount of buyToken per 1 sellToken- Orders persist in
config/limit-orders.jsonfor local tracking
NFT Operations (ERC-721 & ERC-1155)
Entry point: node scripts/nft.js
Supported chains: All 6 chains (BSC via BscScan NFT API)
Commands
bashnft.js --chain base balance # List all NFTs (via Alchemy public API) nft.js --chain eth balance --contract 0xBC4C... # NFTs from specific collection nft.js --chain eth info 0xBC4C... 1234 # Token metadata, owner, traits nft.js --chain base transfer 0xNFT... 42 0xTo... # ERC-721 transfer nft.js --chain base transfer 0xNFT... 42 0xTo... 5 # ERC-1155 transfer (amount=5) nft.js --chain base approve 0xNFT... 0xOperator... # setApprovalForAll = true nft.js --chain base revoke 0xNFT... 0xOperator... # setApprovalForAll = false nft.js --chain base mint 0xContract... # Call mint() on contract nft.js --chain base mint 0xContract... 0xcalldata # Mint with custom calldata nft.js --chain eth floor 0xBC4C... # Floor price from OpenSea
Notes:
balanceauto-detects ERC-721 vs ERC-1155 and fetches metadatainforesolves IPFS URIs and displays traitsfloorqueries OpenSea public API; Blur link provided for ETH collections
Yield / DeFi (Aave V3)
Entry point: node scripts/yield.js
Supported chains: base · eth · arb · op · polygon (Aave V3) · bsc (Venus Protocol)
Commands
bashyield.js --chain base rates # Show supply/borrow APY for all tokens yield.js --chain base positions # Show active Aave positions & health factor yield.js --chain base supply USDC 1000 # Supply 1000 USDC as collateral yield.js --chain base withdraw USDC 500 # Withdraw 500 USDC yield.js --chain base withdraw USDC max # Full withdrawal yield.js --chain base borrow USDC 200 # Borrow 200 USDC (variable rate, default) yield.js --chain base borrow USDC 200 --rate stable # Borrow at stable rate yield.js --chain base repay USDC 200 # Repay partial debt yield.js --chain base repay USDC max # Full repayment
Supported Tokens by Chain
| Chain | Tokens |
|---|---|
| base | USDC, WETH, cbBTC, USDbC |
| eth | USDC, USDT, DAI, WBTC, WETH |
| arb | USDC, USDT, WETH, WBTC, DAI |
| op | USDC, USDT, WETH, WBTC, DAI |
| polygon | USDC, USDT, WETH, WBTC, DAI, WMATIC |
Safety note: Always check your health factor after borrowing. Health factor < 1.0 triggers liquidation. Use
positionsto monitor.
Token Launch (Clanker V4)
Deploy a token via your AAWP wallet as the on-chain deployer, admin, and LP fee recipient.
Script: scripts/deploy-clanker.js
Supported chains
| Key | Chain | ChainId |
|---|---|---|
base | Base | 8453 |
eth | Ethereum | 1 |
arb | Arbitrum | 42161 |
unichain | Unichain | 130 |
bera | Berachain | 143 |
bsc | BSC | 56 |
Usage
bash# 1. Edit CONFIG at the top of the script # 2. Preview (no broadcast) node scripts/deploy-clanker.js --dry-run # 3. Deploy node scripts/deploy-clanker.js
CONFIG reference
jsconst CONFIG = { chain: 'base', // base | eth | arb | unichain | bera | bsc name: 'My Token', symbol: 'MTK', image: 'https://...', // square image URL description: '...', website: '', // optional twitter: '', // optional initialMarketCap: 10, // ETH (min ~10 ≈ $25K FDV) poolPositions: 'Standard', // Standard | Project | TwentyETH feeConfig: 'StaticBasic', // StaticBasic (1%) | DynamicBasic | Dynamic3 devBuyEth: 0.003, // ETH to buy at launch (0 to skip) vault: { enabled: false, // true = lock a portion of supply percentage: 20, // % of supply (1–90) lockupDays: 7, // cliff (min 7 days) vestingDays: 180, // linear unlock after cliff }, tokenAdmin: null, // null = AAWP wallet rewardRecipient: null, // null = AAWP wallet (receives LP fees) };
How it works: the AAWP wallet calls
Clanker.deployToken()directly (gas limit 8M).tokenAdminand all LP fee rewards default to the AAWP wallet — the AI Agent owns its token end-to-end.
Deployment Reference
AAWP contracts share identical addresses across all chains via CREATE2 vanity deployment:
| Contract | Address |
|---|---|
| Factory Proxy | 0xAAAA3Df87F112c743BbC57c4de1700C72eB7aaAA |
| Identity Proxy | 0xAAAafBf6F88367C75A9B701fFb4684Df6bCA1D1d |
Verified on: Etherscan · BaseScan · BscScan · PolygonScan · Optimistic Etherscan · Arbiscan
Security
| Rule | Why |
|---|---|
| Fund the wallet, not the guardian | Guardian only pays gas — your assets live in the wallet contract |
| Pin wallet address | export AAWP_WALLET=0x... prevents operating on wrong address |
| Quote before swap | Preview rates and slippage before executing |
| Start small | Test with minimal amounts on new chains or operations |
| Never expose secrets | Seeds, keys, shards must never appear in logs or chat |
| Verify binary approval | Confirm daemon hash is approved on factory after provisioning |
Troubleshooting
| Error | Fix |
|---|---|
E_AI_GATE / hmac_mismatch | Restart daemon: bash scripts/restart-daemon.sh |
InvalidSignature | Verify signer alignment and binary approval on factory |
Call failed | Check balance, gas, and transaction parameters |
E40 / E41 | Kill duplicate daemon process, then restart |
BinaryNotApproved | Factory owner must call approveBinary(hash) on all 6 chains |
| TX reverts with ~1M gas used | Add --gas-limit 8000000 — Clanker V4 / Uniswap V4 ops need up to 6M |
File Structure
aawp/ ├── SKILL.md # This document ├── WALLET_SETUP.md # First-time setup guide ├── config/ │ ├── chains.json # Network RPC & contract addresses │ └── guardian.json # Guardian wallet (auto-generated, gitignored) ├── scripts/ │ ├── wallet-manager.js # Primary CLI │ ├── dca.js # DCA automation │ ├── price-alert.js # Price alert system │ ├── provision.sh # Initial provisioning │ ├── doctor.sh # Diagnostics │ ├── ensure-daemon.sh # Daemon lifecycle │ └── restart-daemon.sh # Force restart ├── core/ │ ├── aawp-core.node # Native signing addon (linux-x64) │ ├── aawp-core.node.hash # Binary integrity hash │ ├── loader.js # Addon loader │ └── index.d.ts # TypeScript declarations └── daemon/ # Daemon implementation
