Spending Limits Module

The spending limits module provides functionality for setting spending limits on wallets to control transaction amounts and prevent overspending. Supports daily, weekly, monthly, and per-transaction limits with budget tracking and alerts.

Import

import { 
  create,
  findAll,
  getBudgetStatus,
  update,
  remove
} from 'cilantro-sdk/spending-limits';

Basic Operations

create(walletId, options)

Create a spending limit for a wallet.

// Create a daily spending limit
const limit = await create('wallet-id', {
  period: 'DAILY',
  limitAmount: 1000000000, // 1 SOL per day
  autoPause: false,
  alertOnReach: true,
  alertThreshold: 80 // Alert at 80% of limit
});

findAll(walletId)

Get all spending limits configured for a wallet.

const limits = await findAll('wallet-id');
console.log('Active limits:', limits.data);

getBudgetStatus(walletId)

Get current budget utilization and status for all active spending limits.

const status = await getBudgetStatus('wallet-id');
console.log('Budget status:', status.data);
console.log('Daily spent:', status.data.daily?.spent);
console.log('Daily remaining:', status.data.daily?.remaining);

update(walletId, id, options)

Update spending limit configuration (amount, alerts, auto-pause).

await update('wallet-id', 'limit-id', {
  limitAmount: 2000000000, // Increase to 2 SOL
  alertThreshold: 90 // Alert at 90% instead
});

remove(walletId, id)

Remove a spending limit from a wallet.

await remove('wallet-id', 'limit-id');

Limit Types

Daily Limit

// Set daily spending limit
const dailyLimit = await create('wallet-id', {
  period: 'DAILY',
  limitAmount: 5000000000, // 5 SOL per day
  alertOnReach: true,
  alertThreshold: 75
});

Weekly Limit

// Set weekly spending limit
const weeklyLimit = await create('wallet-id', {
  period: 'WEEKLY',
  limitAmount: 20000000000, // 20 SOL per week
  autoPause: true, // Auto-pause when limit reached
  alertThreshold: 80
});

Monthly Limit

// Set monthly spending limit
const monthlyLimit = await create('wallet-id', {
  period: 'MONTHLY',
  limitAmount: 100000000000, // 100 SOL per month
  alertOnReach: true,
  alertThreshold: 50 // Alert at 50% of monthly limit
});

Per-Transaction Limit

// Set maximum amount per transaction
const perTransactionLimit = await create('wallet-id', {
  period: 'PER_TRANSACTION',
  limitAmount: 10000000000, // Max 10 SOL per transaction
  autoPause: false,
  alertOnReach: true
});

Usage Examples

Comprehensive Budget Management

// Set up multiple limits
const dailyLimit = await create('wallet-id', {
  period: 'DAILY',
  limitAmount: 1000000000, // 1 SOL per day
  alertThreshold: 80
});

const weeklyLimit = await create('wallet-id', {
  period: 'WEEKLY',
  limitAmount: 5000000000, // 5 SOL per week
  alertThreshold: 75
});

const monthlyLimit = await create('wallet-id', {
  period: 'MONTHLY',
  limitAmount: 20000000000, // 20 SOL per month
  autoPause: true,
  alertThreshold: 90
});

// Check budget status
const status = await getBudgetStatus('wallet-id');
console.log('Daily spent:', status.data.daily?.spent);
console.log('Weekly remaining:', status.data.weekly?.remaining);
console.log('Monthly utilization:', status.data.monthly?.percentage);

Monitoring Budget Utilization

// Get all limits
const limits = await findAll('wallet-id');

// Get budget status
const budget = await getBudgetStatus('wallet-id');

// Check if any limit is approaching threshold
for (const limit of limits.data) {
  const periodStatus = budget.data[limit.period.toLowerCase()];
  
  if (periodStatus && periodStatus.percentage >= limit.alertThreshold) {
    console.warn(`⚠️ ${limit.period} limit at ${periodStatus.percentage}%`);
    // Send notification to user
  }
  
  if (periodStatus && periodStatus.remaining <= 0) {
    console.error(`❌ ${limit.period} limit exceeded!`);
    // Handle limit exceeded
  }
}

Dynamic Limit Adjustment

// Get current limits
const limits = await findAll('wallet-id');
const budget = await getBudgetStatus('wallet-id');

// Increase limit if user is consistently hitting it
const dailyLimit = limits.data.find(l => l.period === 'DAILY');
if (dailyLimit && budget.data.daily?.percentage >= 95) {
  await update('wallet-id', dailyLimit.id, {
    limitAmount: dailyLimit.limitAmount * 1.5 // Increase by 50%
  });
  console.log('Daily limit increased due to high usage');
}

Auto-Pause on Limit Reached

// Create limit with auto-pause
const safetyLimit = await create('wallet-id', {
  period: 'DAILY',
  limitAmount: 5000000000, // 5 SOL per day
  autoPause: true, // Wallet will be paused when limit reached
  alertOnReach: true,
  alertThreshold: 90
});

// Monitor and handle auto-pause
const status = await getBudgetStatus('wallet-id');
if (status.data.daily?.remaining <= 0) {
  console.log('Wallet auto-paused due to daily limit');
  // Wallet is now paused, user must manually reactivate
}

Budget Status Response

The getBudgetStatus response includes:

• daily - Daily limit status (spent, remaining, percentage)
• weekly - Weekly limit status
• monthly - Monthly limit status
• perTransaction - Per-transaction limit status

Each period includes:

• spent - Amount spent in the period
• limit - Total limit amount
• remaining - Remaining amount
• percentage - Percentage of limit used

Best Practices