Treasury Accounts

Programmable multi-currency accounts designed for AI agent financial operations.

Overview

Treasury accounts (also called vaults) are the foundation of Clawallex. Each account provides:

Core Capabilities:

• Multi-currency support (USD, EUR, GBP)

• Programmable spending policies and authorization rules

• Real-time balance queries with sub-second latency

• Instant internal transfers between accounts (zero fees)

• Comprehensive transaction history and audit logs

• Hierarchical account organization for complex structures

Settlement:

• Internal transfers: <2s settlement, $0 fees

• ACH transfers: 1-2 business days

• Wire transfers: Same-day domestic, 1-2 days international

• Real-time balance updates across all operations

Account Architecture

Treasury Account
├── Account ID: acc_abc123xyz
├── Name: "AI Agent Operating Account"
├── Currency: USD, EUR, or GBP
├── Balance:
│   ├── Available: Funds ready for spending
│   ├── Pending: In-flight transactions
│   └── Total: Available + Pending
├── Authorization Policy: Spending rules and limits
├── Metadata: Custom key-value pairs
└── Status: active | frozen | closed

Creating Accounts

Basic Account Creation

const account = await clawallex.accounts.create({
  name: 'AI Agent Treasury',
  currency: 'USD',
  initialDeposit: 10000 // Optional
});

console.log(`Account ID: ${account.id}`);
console.log(`Current balance: $${account.balance.total}`);
console.log(`Status: ${account.status}`);

Account with Authorization Policy

const account = await clawallex.accounts.create({
  name: 'Operations Treasury',
  currency: 'USD',
  initialDeposit: 50000,
  authorizationPolicy: {
    limits: {
      daily: 5000,
      weekly: 30000,
      monthly: 100000,
      perTransaction: 10000
    },
    merchants: {
      whitelist: ['aws.amazon.com', 'openai.com', 'vercel.com']
    },
    approvals: {
      threshold: 10000,
      approvers: ['[email protected]'],
      minApprovers: 1,
      timeoutMinutes: 60
    }
  },
  metadata: {
    department: 'Engineering',
    purpose: 'infrastructure_payments',
    fiscal_year: '2026',
    agent_id: 'openclaw_001'
  }
});

Multi-Currency Account

// Create accounts in different currencies
const accounts = await Promise.all([
  clawallex.accounts.create({ name: 'USD Operations', currency: 'USD' }),
  clawallex.accounts.create({ name: 'EUR Operations', currency: 'EUR' }),
  clawallex.accounts.create({ name: 'GBP Operations', currency: 'GBP' })
]);

Account Properties

interface Account {
  id: string;                    // Unique account identifier
  name: string;                  // Account display name
  currency: 'USD' | 'EUR' | 'GBP';
  balance: {
    available: number;           // Available for spending
    pending: number;             // In-flight transactions
    total: number;               // Total balance
  };
  status: 'active' | 'frozen' | 'closed';
  authorizationPolicy?: AuthorizationPolicy;
  routingDetails: {              // For external deposits
    accountNumber: string;
    routingNumber: string;
    swiftCode?: string;          // International only
  };
  createdAt: string;             // ISO 8601 timestamp
  updatedAt: string;
  metadata?: Record<string, any>;
}

Depositing Funds

External Deposit (ACH/Wire)

const account = await clawallex.accounts.retrieve('acc_abc123');

// Display deposit instructions for external funding
console.log('Deposit funds via:');
console.log(`Account Number: ${account.routingDetails.accountNumber}`);
console.log(`Routing Number: ${account.routingDetails.routingNumber}`);
console.log(`Account Name: ${account.name}`);
console.log(`Currency: ${account.currency}`);

// ACH: 1-2 business days
// Wire: Same-day (domestic), 1-2 days (international)

Internal Transfer

Transfer between Clawallex accounts (instant, zero fees):

const transfer = await clawallex.transfers.create({
  sourceAccountId: 'acc_source123',
  destinationAccountId: 'acc_destination456',
  amount: 5000,
  currency: 'USD',
  memo: 'Q1 budget allocation'
});

console.log(`Transfer ID: ${transfer.id}`);
console.log(`Status: ${transfer.status}`); // 'completed' (instant)
console.log(`Fee: $0.00`);
console.log(`Settled at: ${transfer.settledAt}`);

Programmatic Funding via API

// Initiate external deposit
const deposit = await clawallex.deposits.create({
  accountId: 'acc_abc123',
  amount: 50000,
  currency: 'USD',
  source: {
    type: 'ach',
    bankAccount: {
      accountNumber: '1234567890',
      routingNumber: '021000021',
      accountType: 'checking'
    }
  }
});

console.log(`Deposit ID: ${deposit.id}`);
console.log(`Status: ${deposit.status}`); // 'pending'
console.log(`Estimated completion: ${deposit.estimatedCompletionAt}`);

Balance Queries

Real-Time Balance

const balance = await clawallex.accounts.getBalance('acc_abc123');

console.log(`Available: $${balance.available.toLocaleString()}`);
console.log(`Pending: $${balance.pending.toLocaleString()}`);
console.log(`Total: $${balance.total.toLocaleString()}`);
console.log(`Last updated: ${balance.lastUpdated}`);

Balance History

const history = await clawallex.accounts.getBalanceHistory('acc_abc123', {
  period: '30d',
  interval: 'daily'
});

history.snapshots.forEach(snapshot => {
  console.log(`${snapshot.date}: $${snapshot.balance.toLocaleString()}`);
});

// Export for analysis
const csv = history.toCSV();

Balance Alerts

await clawallex.accounts.setAlerts('acc_abc123', {
  lowBalance: {
    threshold: 1000,
    channels: ['email', 'webhook'],
    recipients: ['[email protected]']
  },
  highActivity: {
    transactionsPerHour: 20,
    channels: ['webhook'],
    webhookUrl: 'https://api.company.com/alerts'
  },
  dailySpending: {
    threshold: 10000,
    channels: ['email'],
    recipients: ['[email protected]']
  }
});

Authorization Policies

Programmable spending rules enforced on every transaction.

Merchant Whitelist

await clawallex.policies.create('acc_abc123', {
  type: 'merchant_whitelist',
  limits: {
    daily: 5000,
    weekly: 30000,
    monthly: 100000,
    perTransaction: 10000
  },
  merchants: {
    whitelist: [
      'aws.amazon.com',
      'openai.com',
      'anthropic.com',
      'vercel.com',
      'stripe.com'
    ]
  },
  categories: [
    'cloud_services',
    'software',
    'ai_infrastructure'
  ]
});

Multi-Party Approval

await clawallex.policies.create('acc_abc123', {
  type: 'multi_party_approval',
  requiresApproval: {
    threshold: 10000, // Amounts above $10,000
    approvers: [
      '[email protected]',
      '[email protected]',
      '[email protected]'
    ],
    minApprovers: 2, // 2 of 3 signatures required
    timeoutMinutes: 120
  }
});

Time-Based Restrictions

await clawallex.policies.create('acc_abc123', {
  type: 'time_restricted',
  schedule: {
    allowedDays: ['monday', 'tuesday', 'wednesday', 'thursday', 'friday'],
    allowedHours: {
      start: '09:00',
      end: '17:00',
      timezone: 'America/New_York'
    },
    blockHolidays: true,
    holidays: ['2026-12-25', '2026-01-01', '2026-07-04']
  }
});

Velocity Controls

await clawallex.policies.create('acc_abc123', {
  type: 'velocity_control',
  limits: {
    perTransaction: 5000,
    perHour: 10000,
    perDay: 50000,
    perWeek: 200000,
    perMonth: 750000
  },
  maxTransactionsPerDay: 20,
  minTimeBetweenTransactions: 60 // seconds
});

Account Operations

Freezing Accounts

Temporarily halt all outgoing transactions:

await clawallex.accounts.freeze('acc_abc123', {
  reason: 'Security audit',
  notifyOwners: true,
  allowIncomingTransfers: true,
  allowDeposits: true
});

// Status check
const account = await clawallex.accounts.retrieve('acc_abc123');
console.log(account.status); // 'frozen'

// Unfreeze
await clawallex.accounts.unfreeze('acc_abc123');

Updating Account Details

await clawallex.accounts.update('acc_abc123', {
  name: 'Updated Account Name',
  metadata: {
    department: 'Engineering',
    cost_center: 'CC-001',
    updated_at: new Date().toISOString()
  }
});

Closing Accounts

Permanently close account and withdraw remaining balance:

// Check balance before closing
const balance = await clawallex.accounts.getBalance('acc_abc123');

if (balance.available > 0) {
  // Withdraw remaining funds
  await clawallex.transfers.create({
    sourceAccountId: 'acc_abc123',
    destinationAccountId: 'acc_main_treasury',
    amount: balance.available,
    currency: 'USD',
    memo: 'Account closure - final withdrawal'
  });
}

// Close account (irreversible)
await clawallex.accounts.close('acc_abc123', {
  reason: 'Project completed',
  confirmBalance: 0
});

Transaction History

Query Transactions

const transactions = await clawallex.transactions.list({
  accountId: 'acc_abc123',
  limit: 50,
  status: 'completed',
  startDate: '2026-02-01',
  endDate: '2026-02-28',
  sortBy: 'created_at',
  sortOrder: 'desc'
});

transactions.data.forEach(txn => {
  console.log(`${txn.createdAt}: $${txn.amount} - ${txn.description}`);
  console.log(`  Status: ${txn.status}`);
  console.log(`  Merchant: ${txn.merchant?.name || 'N/A'}`);
});

// Pagination
if (transactions.hasMore) {
  const nextPage = await clawallex.transactions.list({
    accountId: 'acc_abc123',
    startingAfter: transactions.data[transactions.data.length - 1].id
  });
}

Filter by Merchant or Category

// Filter by specific merchant
const awsTransactions = await clawallex.transactions.list({
  accountId: 'acc_abc123',
  merchant: 'aws.amazon.com',
  startDate: '2026-01-01'
});

// Filter by category
const softwareExpenses = await clawallex.transactions.list({
  accountId: 'acc_abc123',
  category: 'software',
  startDate: '2026-01-01'
});

Export Transaction Data

// Export as CSV
const csv = await clawallex.accounts.exportTransactions('acc_abc123', {
  format: 'csv',
  startDate: '2026-01-01',
  endDate: '2026-01-31',
  includeMetadata: true,
  columns: ['date', 'description', 'amount', 'merchant', 'category', 'status']
});

// Export as JSON
const json = await clawallex.accounts.exportTransactions('acc_abc123', {
  format: 'json',
  startDate: '2026-01-01',
  endDate: '2026-01-31',
  includeFullDetails: true
});

// Export for QuickBooks
const qbo = await clawallex.accounts.exportTransactions('acc_abc123', {
  format: 'qbo',
  startDate: '2026-01-01',
  endDate: '2026-01-31'
});

Analytics & Reporting

Account Analytics

const analytics = await clawallex.accounts.getAnalytics('acc_abc123', {
  period: '30d'
});

console.log(`Total spent: $${analytics.totalSpent.toLocaleString()}`);
console.log(`Total received: $${analytics.totalReceived.toLocaleString()}`);
console.log(`Net change: $${analytics.netChange.toLocaleString()}`);
console.log(`Transaction count: ${analytics.transactionCount}`);
console.log(`Average transaction: $${analytics.averageTransaction.toLocaleString()}`);
console.log(`Largest transaction: $${analytics.largestTransaction.toLocaleString()}`);

console.log('Top merchants:', analytics.topMerchants);
console.log('Spending by category:', analytics.categoryBreakdown);
console.log('Daily spending trend:', analytics.dailyTrend);

Budget Tracking

// Set monthly budget
await clawallex.accounts.setBudget('acc_abc123', {
  monthly: 50000,
  quarterly: 140000,
  annual: 500000,
  alertThreshold: 80, // Alert at 80% utilization
  categories: {
    cloud_services: 20000,
    software: 15000,
    ai_services: 10000,
    other: 5000
  }
});

// Check budget status
const budgetStatus = await clawallex.accounts.getBudgetStatus('acc_abc123');

console.log(`Monthly budget: $${budgetStatus.monthly.limit.toLocaleString()}`);
console.log(`Spent: $${budgetStatus.monthly.spent.toLocaleString()}`);
console.log(`Remaining: $${budgetStatus.monthly.remaining.toLocaleString()}`);
console.log(`Utilization: ${budgetStatus.monthly.percentUsed}%`);

if (budgetStatus.monthly.percentUsed >= 80) {
  console.warn('Budget threshold exceeded!');
}

Spending Forecasts

// Get AI-powered spending forecast
const forecast = await clawallex.accounts.getForecast('acc_abc123', {
  horizon: '90d',
  confidence: 0.95
});

console.log('Predicted spending (next 90 days):');
forecast.predictions.forEach(pred => {
  console.log(`  ${pred.date}: $${pred.amount} (±$${pred.variance})`);
});

console.log(`Estimated month-end balance: $${forecast.estimatedEndingBalance}`);
console.log(`Confidence level: ${forecast.confidence * 100}%`);

Hierarchical Accounts

Parent-Child Structure

// Create parent account
const parentAccount = await clawallex.accounts.create({
  name: 'Engineering Department',
  currency: 'USD'
});

// Create child accounts
const childAccounts = await Promise.all([
  clawallex.accounts.create({
    name: 'Infrastructure Team',
    currency: 'USD',
    parentAccountId: parentAccount.id
  }),
  clawallex.accounts.create({
    name: 'Product Team',
    currency: 'USD',
    parentAccountId: parentAccount.id
  }),
  clawallex.accounts.create({
    name: 'AI Research Team',
    currency: 'USD',
    parentAccountId: parentAccount.id
  })
]);

// Query all child accounts
const children = await clawallex.accounts.listChildren(parentAccount.id);

// Aggregate balance across hierarchy
const consolidatedBalance = await clawallex.accounts.getConsolidatedBalance(
  parentAccount.id,
  { includeChildren: true }
);

console.log(`Total across all teams: $${consolidatedBalance.total}`);

Best Practices

1. Separate Accounts by Purpose

// Create purpose-specific accounts
const accounts = await Promise.all([
  clawallex.accounts.create({ name: 'Operating Expenses', currency: 'USD' }),
  clawallex.accounts.create({ name: 'Payroll', currency: 'USD' }),
  clawallex.accounts.create({ name: 'Emergency Reserve', currency: 'USD' }),
  clawallex.accounts.create({ name: 'Growth Capital', currency: 'USD' })
]);

2. Implement Authorization Policies

// Always configure spending policies
await clawallex.policies.create(account.id, {
  limits: {
    daily: 10000,
    monthly: 200000
  },
  approvals: {
    threshold: 5000,
    approvers: ['[email protected]']
  }
});

3. Monitor Account Health

// Regular account health checks
async function monitorAccount(accountId: string) {
  const account = await clawallex.accounts.retrieve(accountId);
  const balance = await clawallex.accounts.getBalance(accountId);

  if (account.status !== 'active') {
    console.warn(`Account ${accountId} status: ${account.status}`);
  }

  if (balance.available < 1000) {
    console.warn(`Low balance: $${balance.available}`);
    // Trigger funding workflow
  }

  // Check for unusual activity
  const analytics = await clawallex.accounts.getAnalytics(accountId, {
    period: '24h'
  });

  if (analytics.transactionCount > 100) {
    console.warn('Unusually high transaction volume');
  }
}

4. Maintain Audit Trail

// Export monthly audit logs
const auditLogs = await clawallex.accounts.getAuditLogs('acc_abc123', {
  startDate: '2026-02-01',
  endDate: '2026-02-28',
  includeSystemEvents: true
});

auditLogs.forEach(log => {
  console.log(`${log.timestamp}: ${log.action} by ${log.actor}`);
  console.log(`  Details: ${JSON.stringify(log.details)}`);
});

// Export for compliance
await clawallex.accounts.exportAuditLogs('acc_abc123', {
  format: 'csv',
  startDate: '2026-01-01',
  endDate: '2026-12-31',
  destination: 's3://company-compliance-bucket/audit-logs/'
});

Troubleshooting

Account Frozen

const account = await clawallex.accounts.retrieve('acc_abc123');

if (account.status === 'frozen') {
  const freezeDetails = await clawallex.accounts.getFreezeDetails('acc_abc123');
  console.log(`Frozen at: ${freezeDetails.frozenAt}`);
  console.log(`Reason: ${freezeDetails.reason}`);
  console.log(`Frozen by: ${freezeDetails.frozenBy}`);

  // Unfreeze if authorized
  if (freezeDetails.canUnfreeze) {
    await clawallex.accounts.unfreeze('acc_abc123');
  }
}

Insufficient Balance

try {
  await clawallex.transfers.create({
    sourceAccountId: 'acc_abc123',
    destinationAccountId: 'acc_xyz789',
    amount: 10000
  });
} catch (error) {
  if (error.code === 'insufficient_balance') {
    const balance = await clawallex.accounts.getBalance('acc_abc123');
    console.log(`Available: $${balance.available}`);
    console.log(`Required: $10,000`);
    console.log(`Shortfall: $${10000 - balance.available}`);
  }
}

Transfer Failed

const transfer = await clawallex.transfers.retrieve('txf_abc123');

if (transfer.status === 'failed') {
  console.log(`Failure reason: ${transfer.failureReason}`);
  console.log(`Failed at: ${transfer.failedAt}`);

  // Retry if retriable
  if (transfer.retriable) {
    await clawallex.transfers.retry('txf_abc123');
  }
}

Next Steps

• Card Issuing - Issue virtual cards linked to accounts

• Authorization Engine - Policy documentation

• Webhooks - Real-time account event notifications

• API Reference - Complete account endpoints