name: agent-wallet-management
description: "Unified agent fund management — balances, funding, gas, spend tracking. Use when agents need to hold, send, or manage USDC/ETH across wallets."
metadata:
openclaw:
emoji: "💰"

Agent Wallet Management

Unified skill for managing agent funds across wallet types. One interface for balances, funding, gas management, and spend tracking.

Wallet Types

Core Operations

Check Balances

import { createPublicClient, http, formatUnits } from 'viem';
import { base } from 'viem/chains';

const client = createPublicClient({ chain: base, transport: http() });

// ETH balance
const ethBal = await client.getBalance({ address: AGENT_ADDR });

// USDC balance (6 decimals)
const usdcBal = await client.readContract({
  address: USDC_ADDRESS,
  abi: [{ name: 'balanceOf', type: 'function', inputs: [{ type: 'address' }], outputs: [{ type: 'uint256' }], stateMutability: 'view' }],
  functionName: 'balanceOf',
  args: [AGENT_ADDR]
});

console.log(`ETH: ${formatUnits(ethBal, 18)}, USDC: ${formatUnits(usdcBal, 6)}`);

Fund Agent Wallet

For testnet (Base Sepolia):
- ETH: https://portal.cdp.coinbase.com/products/faucet
- USDC: https://faucet.circle.com (20 USDC per 2h)

For mainnet: Transfer from treasury wallet or use Circle API.

Send USDC (EIP-3009 — gasless for recipient)

// Agent signs transferWithAuthorization — no approve needed
const signature = await walletClient.signTypedData({
  domain: { name: 'USDC', version: '2', chainId, verifyingContract: USDC_ADDRESS },
  types: {
    TransferWithAuthorization: [
      { name: 'from', type: 'address' },
      { name: 'to', type: 'address' },
      { name: 'value', type: 'uint256' },
      { name: 'validAfter', type: 'uint256' },
      { name: 'validBefore', type: 'uint256' },
      { name: 'nonce', type: 'bytes32' },
    ]
  },
  primaryType: 'TransferWithAuthorization',
  message: { from, to, value, validAfter: 0n, validBefore, nonce }
});

Gas Management

• Monitor: Alert when ETH balance < 0.001 (can't send transactions)
• Estimate: estimateGas() before submitting, add 20% buffer
• Smart wallet option: Use paymaster for gasless USDC transfers
• Base L2 advantage: Gas typically <$0.01 per transaction

Spend Tracking

Track all outgoing payments for budget management:

interface SpendRecord {
  timestamp: number;
  to: string;
  amount: bigint;
  currency: 'USDC' | 'ETH';
  purpose: string;      // 'x402-payment' | 'gas' | 'transfer'
  txHash: string;
}

Store in local DB or file. Query for daily/weekly/monthly totals.

Security Rules

• Never log private keys — use env vars only
• Spending limits — Set max per-transaction and daily caps
• Separate wallets — Hot wallet (small balance, active) vs cold (treasury)
• Key rotation — Plan for compromised keys
• Approval required — Human approval for transfers above threshold

Environment Config

AGENT_PRIVATE_KEY=          # EOA private key
AGENT_ADDRESS=              # Derived from private key
USDC_ADDRESS=               # Chain-specific
RPC_URL=                    # Chain-specific
CHAIN_ID=                   # 8453 (mainnet) or 84532 (sepolia)
DAILY_SPEND_LIMIT_USDC=100  # Safety cap

Cross-References

• x402: Payment settlement uses wallet signing
• smart-wallet: ERC-4337 for gas sponsorship
• circle-wallet: Custodial alternative via Circle API
• cctp: Cross-chain USDC bridging