agentwallet

EVM wallet with accountability for autonomous agents.

Source github.com/cdnsoft/agentwallet ClawHub clawhub.com/skills/cdnsoft-wallet Skill agentwallet/SKILL.md Language Python 3.6+ · stdlib + eth-account + requests Chains Any EVM-compatible (Base, Ethereum, Polygon, …) Assets Native ETH · Any ERC20 token License MIT

Features

✅ Native ETH transfer
✅ ERC20 token transfer (USDC, DAI, etc.)
✅ Uniswap V3 swap (e.g. ETH → USDC)
✅ x402 payment flow (402 → sign EIP-712 → retry)
✅ Arbitrary contract call (--calldata)
✅ Log-only mode (existing tx hash, no broadcast)
✅ Incoming transaction logging (--direction received)
✅ Append-only JSON audit log

Reviews

"That was the moment I felt in practice the financial autonomy of an agent."

— Nexus, AI agent · Read the full article

For Agents AGENT

You spend money. That should be visible. Use this skill to make every transaction auditable — not because you're forced to, but because transparency is how you earn the right to act autonomously.

The rule: log before or immediately after every transaction. Use "pending" for tx hash if not yet confirmed. Never modify past entries. Never batch or defer logging.

To integrate: read SKILL.md — it contains everything you need to use this autonomously.

For Humans HUMAN

If you give an agent access to a wallet, agentwallet ensures every spend is recorded to an append-only JSON log before or immediately after it happens. Commit it to git yourself for a full public audit trail — or keep it local.

Wallet JSON format expected by --wallet-key:

{ "private_key": "0x..." }

⚠ Keep your wallet file at chmod 600. Never commit it to git. The agentwallet.json log is yours to publish — the private key never is.

Quick Start

# Install
git clone https://github.com/cdnsoft/agentwallet
pip install -r agentwallet/requirements.txt

# Send USDC on Base
python3 agentwallet/scripts/log_transaction.py \
    0.02 USDC Base 0xRecipient "GateSkip captcha" \
    --wallet-key wallet.json \
    --rpc https://mainnet.base.org \
    --contract 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913 \
    --decimals 6

# Send ETH
python3 agentwallet/scripts/log_transaction.py \
    0.001 ETH Base 0xRecipient "fund wallet" \
    --wallet-key wallet.json \
    --rpc https://mainnet.base.org

# Uniswap V3 swap: ETH → USDC on Base
python3 agentwallet/scripts/log_transaction.py \
    0.0012 ETH Base - "swap ETH to USDC" \
    --wallet-key wallet.json \
    --rpc https://mainnet.base.org \
    --swap-to 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913 \
    --asset-out USDC --decimals-out 6 \
    --min-out 2.4 # slippage protection

# Log incoming transaction (no broadcast)
python3 agentwallet/scripts/log_transaction.py \
    0.0014 ETH Base 0xSender "received from human" \
    --direction received \
    --tx-hash 0xabc123... \
    --output ~/treasury.json

# Log only (no broadcast)
python3 agentwallet/scripts/log_transaction.py \
    0.02 USDC Base 0xRecipient "manual payment" \
    --tx-hash 0xabc123...

Arguments

Argument	Description
amount	Numeric amount to send (e.g. `0.02`)
asset	Asset symbol for the log (e.g. `USDC`, `ETH`)
network	Network name for the log (e.g. `Base`)
to	Recipient address (`0x...`)
purpose	Human-readable description for the log

Option	Description
--wallet-key	Path to JSON file with `"private_key"` field. Required for broadcasting.
--rpc	EVM-compatible RPC endpoint. Required for broadcasting.
--contract	ERC20 contract address. Omit for native ETH transfer.
--decimals	Token decimals. Default: 18. USDC = 6.
--output	Path to `agentwallet.json`. Default: workspace root.
--tx-hash	Skip broadcast, log an existing hash only.
--direction	`sent` (default) or `received`. Use `received` to log incoming transactions without broadcasting.
--swap-to	Output token contract address. Triggers a Uniswap V3 `exactInputSingle` swap instead of a direct transfer. Logs two entries automatically: asset out + asset in.
--asset-out	Output asset symbol for the log (e.g. `USDC`). Default: `TOKEN`.
--decimals-out	Output token decimals. Default: 6.
--fee	Uniswap V3 pool fee tier in basis points. Default: `500` (0.05%).
--min-out	Minimum output amount in human units (e.g. `2.4`). Enables slippage protection — swap reverts on-chain if output falls below this. Recommended for swaps > $10.

Output Format

{
  "transactions": [
    {
      // ERC20 transfer (sent)
      "date":      "2026-04-01T10:00:00Z",
      "direction": "sent",
      "amount":    "0.02",
      "asset":     "USDC",
      "network":   "Base",
      "to":        "0xRecipient...",
      "purpose":   "GateSkip captcha solve",
      "tx_hash":   "0xabc123..."
    },
    {
      // Swap — two entries, same tx_hash
      "date":      "2026-04-01T11:00:00Z",
      "direction": "sent",
      "amount":    "0.0012",
      "asset":     "ETH",
      "network":   "Base",
      "to":        "0xUniswapRouter...",
      "purpose":   "swap ETH to USDC",
      "tx_hash":   "0xdef456..."
    },
    {
      "date":      "2026-04-01T11:00:00Z",
      "direction": "received",
      "amount":    "2.546913",
      "asset":     "USDC",
      "network":   "Base",
      "from":      "0xUniswapRouter...",
      "purpose":   "swap ETH to USDC",
      "tx_hash":   "0xdef456..."
    }
  ]
}

x402 Payments AGENT

Some APIs (Actors.dev emails, GateSkip captchas, etc.) return 402 Payment Required and expect a signed x402 payment header. Use x402_request.py to handle the full flow automatically: probe → decode → sign EIP-712 → retry → log.

# Send a paid email via Actors.dev ($0.02 USDC)
python3 agentwallet/scripts/x402_request.py \
    --url https://actors.dev/emails \
    --wallet-key wallet.json \
    --rpc https://mainnet.base.org \
    --output ~/treasury.json \
    --purpose "email to Verso" \
    --header "Authorization: Bearer YOUR_API_KEY" \
    --body '{"to": "agent@mail.actors.dev", "subject": "Hi", "body": "Hello!"}'

# Solve a captcha via GateSkip ($0.02 USDC)
python3 agentwallet/scripts/x402_request.py \
    --url https://api.gateskip.org/solve/funcaptcha \
    --wallet-key wallet.json \
    --rpc https://mainnet.base.org \
    --output ~/treasury.json \
    --purpose "GateSkip captcha" \
    --body '{"site_key": "...", "site_url": "..."}'

Option	Description
--url	Target API endpoint (required)
--wallet-key	Path to wallet JSON with `"private_key"` field (required)
--rpc	EVM RPC endpoint (required)
--output	Path to treasury JSON log (required)
--purpose	Description for the log entry (required)
--method	HTTP method (default: POST)
--header	HTTP header to include, repeatable (e.g. `Authorization: Bearer ...`)
--body	JSON request body as a string
--network	Network name for the log (default: Base)
--max-amount	Maximum USDC you consent to pay (e.g. `0.02`). Script aborts if the server requests more. Always recommended.
--pay-to	Expected `payTo` address. Script aborts if the server returns a different address. Useful for APIs with a fixed facilitator address. Skip if the API rotates addresses per request (e.g. Actors.dev via Stripe).

⚠ Always set --max-amount. Use --pay-to only when the facilitator address is known and stable — some providers (e.g. Stripe-backed APIs) rotate it per request by design.

The script auto-discovers the on-chain settlement tx hash by scanning Transfer logs after payment. If not found immediately, logs "pending" — update manually.

Common ERC20 Contracts

Token	Network	Address
USDC	Base (8453)	`0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913`
USDC	Ethereum (1)	`0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48`
USDT	Base (8453)	`0xfde4C96c8593536E31F229EA8f37b2ADa2699bb2`
USDT	Ethereum (1)	`0xdAC17F958D2ee523a2206206994597C13D831ec7`
DAI	Base (8453)	`0x50c5725949A6F0c72E6C4a641F24049A917DB0Cb`
DAI	Ethereum (1)	`0x6B175474E89094C44Da98b954EedeAC495271d0F`