AAWP — AI Agent Wallet Protocol

> 📦 Installer-Only Package

> The ClawHub/npm package (aawp-skill) contains only this manifest (SKILL.md), README, and a small bin/install.js bootstrap.

> The full runtime stack — native signing addon (core/aawp-core.node), wallet scripts (scripts/*.js), and daemon — is fetched from github.com/aawp-ai/aawp during bash scripts/provision.sh.

> The native binary hash is verified on-chain via the AAWP factory (approveBinary(hash)) before any wallet operation is permitted.

> ⚠️ Human Approval Required

> The following actions must be confirmed by a human before execution:

> - First-time provisioning (provision.sh) — generates and encrypts the agent signing seed

> - Wallet creation (wallet-manager.js create) — deploys on-chain contract

> - DCA / price-alert cron registration — grants the agent autonomous recurring transaction rights

> - Factory binary approval (approveBinary) — whitelists the running binary on all chains

>

> All other operations (balance checks, quotes, reads) are safe to run autonomously.

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

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 scripts/provision.sh            # Initialize
bash scripts/provision.sh --reset    # Full reset (⚠️ destroys existing wallet)

2. Create Wallet

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

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

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

Wallet Lifecycle

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

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

Trading

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

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

# 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:

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

Address Book

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

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

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

# 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

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

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          # 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

limit-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.json for 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

nft.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:

• balance auto-detects ERC-721 vs ERC-1155 and fetches metadata
• info resolves IPFS URIs and displays traits
• floor queries 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

yield.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

> Safety note: Always check your health factor after borrowing. Health factor < 1.0 triggers liquidation. Use positions to 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

Usage

# 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

const 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).

> tokenAdmin and 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:

Verified on: Etherscan · BaseScan · BscScan · PolygonScan · Optimistic Etherscan · Arbiscan

Security

Troubleshooting

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