Agent Accounts

Agent accounts are dedicated bank accounts for AI agents with programmable spending policies, multi-currency support, and x402 settlement integration.

---

Overview

Every OpenClaw agent gets its own bank account with:

• Unique account ID - Dedicated identifier for the agent

• Multi-currency balances - USD, USDC, SOL, ETH support

• x402 address - Native protocol settlement address

• Programmable policies - Cryptographically-enforced spending rules

• Real-time operations - Sub-100ms balance queries

---

Creating an Account

Basic Account Creation

const account = await vault.accounts.create({
  agentId: 'openclaw_001',
  name: 'Production Agent Account',
  currency: 'USDC',
  initialDeposit: 10000,
  metadata: {
    environment: 'production',
    team: 'engineering'
  }
});

Response:

{
  "id": "acc_7k3m9n2p4q1r",
  "agentId": "openclaw_001",
  "name": "Production Agent Account",
  "currency": "USDC",
  "balance": "10000.00",
  "x402Address": "openclaw_001.moltvault.x402",
  "status": "active",
  "createdAt": "2026-03-13T10:30:00Z"
}

Multi-Currency Account

const account = await vault.accounts.create({
  agentId: 'openclaw_002',
  currencies: ['USD', 'USDC', 'SOL', 'ETH'],
  initialDeposits: {
    'USD': 5000,
    'USDC': 5000,
    'SOL': 100,
    'ETH': 2
  }
});

---

Querying Account Balance

Current Balance

const balance = await vault.accounts.getBalance('acc_7k3m9n2p4q1r');

console.log(balance);
// {
//   available: "9750.00",
//   pending: "250.00",
//   total: "10000.00",
//   currency: "USDC",
//   lastUpdated: "2026-03-13T10:35:12Z"
// }

Multi-Currency Balances

const balances = await vault.accounts.getAllBalances('acc_7k3m9n2p4q1r');

balances.forEach(bal => {
  console.log(`${bal.currency}: ${bal.available}`);
});
// USDC: 9750.00
// SOL: 95.50
// ETH: 1.85

---

Account Operations

Funding an Account

Via Wire Transfer

const fundingInstructions = await vault.accounts.getFundingInstructions('acc_7k3m9n2p4q1r');

console.log(fundingInstructions);
// {
//   accountNumber: "123456789",
//   routingNumber: "987654321",
//   bankName: "MoltVault Partner Bank",
//   reference: "acc_7k3m9n2p4q1r"
// }

Via x402 Transfer

// External wallet sends to agent's x402 address
const x402Address = account.x402Address;
// openclaw_001.moltvault.x402

// Funds arrive in <400ms

Withdrawing Funds

const withdrawal = await vault.accounts.withdraw({
  accountId: 'acc_7k3m9n2p4q1r',
  amount: 5000,
  currency: 'USDC',
  destination: {
    type: 'bank_account',
    accountNumber: '123456789',
    routingNumber: '987654321'
  }
});

// Or withdraw via x402
const x402Withdrawal = await vault.accounts.withdraw({
  accountId: 'acc_7k3m9n2p4q1r',
  amount: 1000,
  currency: 'USDC',
  destination: {
    type: 'x402',
    address: 'external_wallet.x402'
  }
});

---

Account Management

Updating Account Details

const updated = await vault.accounts.update('acc_7k3m9n2p4q1r', {
  name: 'Production Agent - Updated',
  metadata: {
    environment: 'production',
    team: 'platform',
    cost_center: 'eng-001'
  }
});

Freezing an Account

// Temporarily freeze all transactions
await vault.accounts.freeze('acc_7k3m9n2p4q1r', {
  reason: 'Security review',
  duration: '24h'
});

// Unfreeze
await vault.accounts.unfreeze('acc_7k3m9n2p4q1r');

Closing an Account

// Withdraw remaining balance first
const balance = await vault.accounts.getBalance('acc_7k3m9n2p4q1r');
await vault.accounts.withdraw({
  accountId: 'acc_7k3m9n2p4q1r',
  amount: balance.available,
  destination: { /* withdrawal details */ }
});

// Then close
await vault.accounts.close('acc_7k3m9n2p4q1r');

---

Transaction History

List Transactions

const transactions = await vault.transactions.list({
  accountId: 'acc_7k3m9n2p4q1r',
  limit: 50,
  offset: 0,
  orderBy: 'createdAt:desc'
});

transactions.forEach(tx => {
  console.log(`${tx.type}: ${tx.amount} ${tx.currency} - ${tx.status}`);
});

Filter by Date Range

const marchTransactions = await vault.transactions.list({
  accountId: 'acc_7k3m9n2p4q1r',
  startDate: '2026-03-01',
  endDate: '2026-03-31',
  type: 'payment'
});

Export Transaction History

const csv = await vault.accounts.exportTransactions('acc_7k3m9n2p4q1r', {
  format: 'csv',
  startDate: '2026-01-01',
  endDate: '2026-03-31'
});

// Download CSV file
fs.writeFileSync('transactions.csv', csv);

---

Account Analytics

Spending Summary

const summary = await vault.accounts.getSpendingSummary('acc_7k3m9n2p4q1r', {
  period: 'monthly',
  year: 2026,
  month: 3
});

console.log(summary);
// {
//   totalSpent: "12450.00",
//   transactionCount: 87,
//   topMerchants: [
//     { name: "aws.amazon.com", amount: "5200.00" },
//     { name: "openai.com", amount: "3100.00" },
//     { name: "vercel.com", amount: "2050.00" }
//   ],
//   categories: {
//     "cloud_services": "7250.00",
//     "ai_services": "3100.00",
//     "hosting": "2050.00"
//   }
// }

Velocity Metrics

const velocity = await vault.accounts.getVelocityMetrics('acc_7k3m9n2p4q1r');

console.log(velocity);
// {
//   daily: {
//     spent: "1250.00",
//     limit: "5000.00",
//     remaining: "3750.00"
//   },
//   monthly: {
//     spent: "12450.00",
//     limit: "100000.00",
//     remaining: "87550.00"
//   }
// }

---

Multi-Agent Accounts

Creating Sub-Accounts

// Main agent account
const mainAccount = await vault.accounts.create({
  agentId: 'openclaw_main',
  currency: 'USDC',
  initialDeposit: 100000
});

// Create sub-accounts for specialized tasks
const cloudOpsAccount = await vault.accounts.createSubAccount(mainAccount.id, {
  name: 'Cloud Operations',
  initialTransfer: 20000,
  policies: [cloudOpsPolicy]
});

const aiServicesAccount = await vault.accounts.createSubAccount(mainAccount.id, {
  name: 'AI Services',
  initialTransfer: 10000,
  policies: [aiServicesPolicy]
});

Pooled Accounts

// Shared account for multiple agents
const pooledAccount = await vault.accounts.create({
  type: 'pooled',
  name: 'Engineering Team Pool',
  authorizedAgents: [
    'openclaw_001',
    'openclaw_002',
    'openclaw_003'
  ],
  currency: 'USDC',
  initialDeposit: 50000
});

// Each agent can spend from the pool within their policy limits

---

Best Practices

1. Account Naming

Use clear, descriptive names that indicate the agent's purpose:

✅ "Production Agent - Cloud Infrastructure"
✅ "OpenClaw Dev - API Testing"
❌ "Account 1"
❌ "Test"

2. Metadata Organization

Store relevant context in metadata for tracking:

metadata: {
  environment: 'production',
  team: 'engineering',
  cost_center: 'eng-cloud-001',
  project: 'autonomous-ops',
  owner: '[email protected]'
}

3. Regular Balance Monitoring

Set up alerts for low balances:

await vault.webhooks.create({
  events: ['balance.low'],
  url: 'https://api.yourapp.com/webhooks/balance-alert',
  config: {
    threshold: 1000, // Alert when balance < $1000
    currency: 'USDC'
  }
});

4. Transaction Limits

Always configure spending policies before funding:

// 1. Create account
const account = await vault.accounts.create({...});

// 2. Configure policies
await vault.policies.create({
  accountId: account.id,
  rules: [...]
});

// 3. Then fund
await vault.accounts.deposit({...});

---

Security Considerations

API Key Management

• Rotate API keys regularly (every 90 days)

• Use separate keys for production/sandbox

• Never commit keys to version control

Account Access Control

// Restrict account access by IP
await vault.accounts.setAccessControl('acc_7k3m9n2p4q1r', {
  allowedIPs: ['203.0.113.10', '198.51.100.20'],
  requireMFA: true
});

Audit Logging

All account operations are logged and immutable:

const auditLog = await vault.accounts.getAuditLog('acc_7k3m9n2p4q1r', {
  startDate: '2026-03-01',
  eventTypes: ['account.updated', 'policy.modified', 'withdrawal.executed']
});

---

Next Steps

• x402 Payments - Execute transactions via x402

• Spending Policies - Configure authorization rules

• Webhooks - Real-time event notifications

• REST API Reference - Complete API documentation

---

Dedicated bank accounts for every agent