Vault Operations

Vaults are the core treasury accounts in ClawPay that hold your digital assets.

Overview

A vault is a smart contract-based account on Solana that:

• Holds USDC, SOL, or other SPL tokens

• Enforces programmable authorization rules

• Supports multi-party approval workflows

• Provides real-time balance tracking

• Enables instant transfers within the network

Creating Vaults

Basic Vault

const vault = await client.vaults.create({
  name: 'Company Treasury',
  currency: 'USDC',
  network: 'solana'
});

console.log(`Vault ID: ${vault.id}`);
console.log(`Deposit address: ${vault.depositAddress}`);

Vault with Initial Deposit

const vault = await client.vaults.create({
  name: 'Marketing Budget',
  currency: 'USDC',
  network: 'solana',
  initialDeposit: 50000.00,
  metadata: {
    department: 'Marketing',
    fiscal_year: '2024',
    cost_center: 'CC-MKT-001'
  }
});

Vault Properties

interface Vault {
  id: string;                    // Unique identifier
  name: string;                  // Human-readable name
  currency: string;              // USDC, SOL, etc.
  network: string;               // solana, ethereum, etc.
  balance: number;               // Current balance
  depositAddress: string;        // Blockchain address for deposits
  status: VaultStatus;           // active, frozen, closed
  createdAt: string;             // ISO 8601 timestamp
  metadata?: Record<string, any>; // Custom key-value pairs
}

type VaultStatus = 'active' | 'frozen' | 'closed';

Depositing Funds

Via Deposit Address

Send funds directly to the vault's deposit address:

const vault = await client.vaults.retrieve('vault_123');
console.log(`Send USDC to: ${vault.depositAddress}`);

Deposits are credited after blockchain confirmation (typically 1-2 seconds on Solana).

Programmatic Deposit

// Transfer from another vault
await client.transfers.create({
  sourceVaultId: 'vault_source',
  destinationVaultId: 'vault_destination',
  amount: 10000,
  currency: 'USDC'
});

Checking Balances

Current Balance

const balance = await client.vaults.getBalance('vault_123');

console.log(`Available: ${balance.available} ${balance.currency}`);
console.log(`Pending: ${balance.pending} ${balance.currency}`);
console.log(`Total: ${balance.total} ${balance.currency}`);

Balance Types:

• available: Funds available for immediate use

• pending: Funds in transit or awaiting settlement

• total: Sum of available + pending

Balance History

const history = await client.vaults.getBalanceHistory('vault_123', {
  period: '30d',
  interval: 'daily'
});

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

Balance Alerts

Set up alerts for low balances:

await client.vaults.setAlerts('vault_123', {
  lowBalance: {
    threshold: 1000,
    notifyEmail: ['[email protected]'],
    notifyWebhook: true
  }
});

Authorization Policies

Control how funds can be spent from a vault.

Whitelist Policy

Only allow spending at approved merchants:

await client.vaults.setAuthorizationPolicy('vault_123', {
  type: 'whitelist_only',
  dailyLimit: 5000,
  weeklyLimit: 30000,
  monthlyLimit: 100000,
  currency: 'USDC',
  merchants: [
    'amazon.com',
    'aws.amazon.com',
    'vercel.com',
    'stripe.com'
  ],
  categories: [
    'cloud_services',
    'software',
    'advertising'
  ]
});

Multi-Party Approval

Require multiple approvers for large transactions:

await client.vaults.setAuthorizationPolicy('vault_123', {
  type: 'multi_party',
  requiresApproval: {
    above: 10000,
    minApprovers: 2,
    approvers: [
      '[email protected]',
      '[email protected]',
      '[email protected]'
    ],
    timeoutMinutes: 60,
    requireReason: true
  }
});

Time-Based Restrictions

Limit spending to business hours:

await client.vaults.setAuthorizationPolicy('vault_123', {
  type: 'whitelist_only',
  dailyLimit: 5000,
  timeRestrictions: {
    allowedDays: ['monday', 'tuesday', 'wednesday', 'thursday', 'friday'],
    allowedHours: {
      start: '09:00',
      end: '17:00',
      timezone: 'America/New_York'
    },
    blockHolidays: true
  }
});

Velocity Controls

Prevent rapid successive transactions:

await client.vaults.setAuthorizationPolicy('vault_123', {
  type: 'velocity_control',
  maxTransactionsPerHour: 10,
  maxTransactionsPerDay: 50,
  minTimeBetweenTransactions: 60, // seconds
  requireCoolingPeriod: {
    after: 5, // transactions
    cooldown: 300 // seconds
  }
});

Vault Metadata

Store custom data with vaults:

await client.vaults.update('vault_123', {
  metadata: {
    department: 'Engineering',
    project: 'Project Phoenix',
    manager: '[email protected]',
    budget_year: '2024',
    allocation: 'R&D'
  }
});

// Retrieve vault with metadata
const vault = await client.vaults.retrieve('vault_123');
console.log(vault.metadata.department); // 'Engineering'

Freezing Vaults

Temporarily stop all transactions:

// Freeze vault
await client.vaults.freeze('vault_123', {
  reason: 'Suspected unauthorized access',
  notifyOwners: true
});

// Unfreeze vault
await client.vaults.unfreeze('vault_123');

When frozen:

• No outgoing transactions allowed

• Deposits still accepted

• Balance queries still work

• Cards linked to vault are automatically frozen

Closing Vaults

Permanently close a vault:

// Withdraw remaining balance first
const balance = await client.vaults.getBalance('vault_123');

if (balance.available > 0) {
  await client.transfers.createExternal({
    sourceVaultId: 'vault_123',
    destinationAddress: 'your_wallet_address',
    amount: balance.available,
    currency: balance.currency
  });
}

// Close vault
await client.vaults.close('vault_123');

Important: Closing a vault is irreversible. All linked cards will be cancelled.

Vault Permissions

Control who can access and manage vaults:

// Add team member
await client.vaults.addMember('vault_123', {
  email: '[email protected]',
  role: 'admin', // admin, manager, viewer
  permissions: [
    'view_balance',
    'create_cards',
    'approve_transactions'
  ]
});

// Remove team member
await client.vaults.removeMember('vault_123', 'member_id');

// List members
const members = await client.vaults.listMembers('vault_123');

Permission Roles

Role	Permissions
Owner	Full control, including delete vault
Admin	Manage settings, add members, create cards
Manager	Create cards, approve transactions, view details
Viewer	View balance and transactions only

Transaction History

View all vault activity:

const transactions = await client.transactions.list({
  vaultId: 'vault_123',
  limit: 100,
  status: 'completed',
  startDate: '2024-01-01',
  endDate: '2024-01-31'
});

transactions.data.forEach(txn => {
  console.log(`${txn.createdAt}: ${txn.merchant.name} - $${txn.amount}`);
});

Export Transactions

// Export as CSV
const csv = await client.vaults.exportTransactions('vault_123', {
  format: 'csv',
  startDate: '2024-01-01',
  endDate: '2024-01-31'
});

// Export as JSON
const json = await client.vaults.exportTransactions('vault_123', {
  format: 'json',
  includeMetadata: true
});

Audit Logs

Track all vault modifications:

const logs = await client.vaults.getAuditLogs('vault_123', {
  limit: 50
});

logs.forEach(log => {
  console.log(`${log.timestamp}: ${log.action} by ${log.actor}`);
  // 2024-01-15T10:30:00Z: policy_updated by [email protected]
  // 2024-01-15T11:00:00Z: card_created by [email protected]
});

Vault Analytics

Spending Insights

const analytics = await client.vaults.getAnalytics('vault_123', {
  period: '30d'
});

console.log(`Total spent: $${analytics.totalSpent}`);
console.log(`Average transaction: $${analytics.averageTransaction}`);
console.log(`Top merchants:`, analytics.topMerchants);
console.log(`Spending by category:`, analytics.categoryBreakdown);

Budget Tracking

await client.vaults.setBudget('vault_123', {
  monthly: 50000,
  quarterly: 140000,
  annual: 500000,
  alertAt: 80 // percent
});

const budget = await client.vaults.getBudgetStatus('vault_123');
console.log(`Spent: ${budget.percentUsed}% of monthly budget`);

Best Practices

1. Use Descriptive Names

// Good
await client.vaults.create({ name: 'Marketing Q1 2024' });

// Better
await client.vaults.create({
  name: 'Marketing Q1 2024 - Paid Ads',
  metadata: {
    department: 'Marketing',
    quarter: 'Q1',
    year: '2024',
    purpose: 'Paid advertising campaigns'
  }
});

2. Set Authorization Policies Early

Configure policies immediately after creation:

const vault = await client.vaults.create({
  name: 'Company Treasury',
  currency: 'USDC'
});

// Set policy immediately
await client.vaults.setAuthorizationPolicy(vault.id, {
  type: 'whitelist_only',
  dailyLimit: 5000
});

3. Monitor Balance Alerts

await client.vaults.setAlerts('vault_123', {
  lowBalance: {
    threshold: 1000,
    notifyEmail: ['[email protected]']
  },
  highActivity: {
    transactionsPerHour: 20,
    notifyEmail: ['[email protected]']
  }
});

4. Regular Audits

Review vault activity regularly:

// Weekly audit script
async function auditVault(vaultId) {
  const logs = await client.vaults.getAuditLogs(vaultId, {
    startDate: new Date(Date.now() - 7 * 24 * 60 * 60 * 1000)
  });

  const suspiciousActivity = logs.filter(log =>
    log.action === 'policy_changed' ||
    log.action === 'member_added' ||
    log.action === 'vault_frozen'
  );

  if (suspiciousActivity.length > 0) {
    await notifySecurityTeam(suspiciousActivity);
  }
}

5. Separate Vaults by Purpose

// Create separate vaults for different purposes
const vaults = await Promise.all([
  client.vaults.create({ name: 'Operating Expenses' }),
  client.vaults.create({ name: 'Payroll' }),
  client.vaults.create({ name: 'Emergency Reserve' }),
  client.vaults.create({ name: 'Growth Investments' })
]);

Troubleshooting

Vault Frozen

const vault = await client.vaults.retrieve('vault_123');

if (vault.status === 'frozen') {
  console.log('Vault is frozen');
  // Contact support or unfreeze if authorized
  await client.vaults.unfreeze('vault_123');
}

Insufficient Balance

try {
  await client.cards.create({
    vaultId: 'vault_123',
    spendingLimit: { daily: 1000 }
  });
} catch (error) {
  if (error.code === 'insufficient_balance') {
    console.log('Not enough funds in vault');
    // Deposit more funds
  }
}

Next Steps

• Card Management

• Authorization Engine

• Webhooks

• API Reference