Spending Limits Guide

This guide covers setting up and managing spending limits for wallets to control transaction amounts and prevent overspending.

Overview

Spending limits help you control wallet spending with:

• Daily Limits: Maximum spending per day
• Weekly Limits: Maximum spending per week
• Monthly Limits: Maximum spending per month
• Per-Transaction Limits: Maximum amount per single transaction

Setting Up Limits

Daily Spending Limit

import { create } from 'cilantro-sdk/spending-limits';

// Set daily spending limit of 5 SOL
const dailyLimit = await create('wallet-id', {
  period: 'DAILY',
  limitAmount: 5000000000, // 5 SOL in lamports
  autoPause: false,
  alertOnReach: true,
  alertThreshold: 80 // Alert at 80% of limit
});

Weekly Spending Limit

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

Monthly Spending Limit

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

Per-Transaction Limit

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

Budget Management

Get Budget Status

import { getBudgetStatus } from 'cilantro-sdk/spending-limits';

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

console.log('Daily spent:', status.data.daily?.spent);
console.log('Daily remaining:', status.data.daily?.remaining);
console.log('Daily percentage:', status.data.daily?.percentage);

console.log('Weekly spent:', status.data.weekly?.spent);
console.log('Monthly spent:', status.data.monthly?.spent);

Monitor Budget Utilization

async function monitorBudget(walletId: string) {
  const limits = await findAll(walletId);
  const budget = await getBudgetStatus(walletId);
  
  for (const limit of limits.data) {
    const periodStatus = budget.data[limit.period.toLowerCase()];
    
    if (periodStatus) {
      console.log(`${limit.period} Limit:`);
      console.log(`- Spent: ${periodStatus.spent / 1e9} SOL`);
      console.log(`- Remaining: ${periodStatus.remaining / 1e9} SOL`);
      console.log(`- Percentage: ${periodStatus.percentage}%`);
      
      // Check if approaching threshold
      if (periodStatus.percentage >= limit.alertThreshold) {
        console.warn(`⚠️ ${limit.period} limit at ${periodStatus.percentage}%`);
        // Send alert notification
      }
      
      // Check if limit exceeded
      if (periodStatus.remaining <= 0) {
        console.error(`❌ ${limit.period} limit exceeded!`);
        // Handle limit exceeded
      }
    }
  }
}

Comprehensive Budget Setup

Multiple Limit Types

async function setupComprehensiveLimits(walletId: string) {
  // Daily limit
  const daily = await create(walletId, {
    period: 'DAILY',
    limitAmount: 1000000000, // 1 SOL per day
    alertThreshold: 80
  });
  
  // Weekly limit
  const weekly = await create(walletId, {
    period: 'WEEKLY',
    limitAmount: 5000000000, // 5 SOL per week
    alertThreshold: 75
  });
  
  // Monthly limit
  const monthly = await create(walletId, {
    period: 'MONTHLY',
    limitAmount: 20000000000, // 20 SOL per month
    autoPause: true,
    alertThreshold: 90
  });
  
  // Per-transaction limit
  const perTransaction = await create(walletId, {
    period: 'PER_TRANSACTION',
    limitAmount: 10000000000, // 10 SOL max per transaction
    alertOnReach: true
  });
  
  return { daily, weekly, monthly, perTransaction };
}

Dynamic Limit Adjustment

Increase Limit Based on Usage

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

Temporary Limit Increase

async function temporaryLimitIncrease(
  walletId: string,
  limitId: string,
  temporaryAmount: number,
  durationDays: number
) {
  // Get current limit
  const limits = await findAll(walletId);
  const currentLimit = limits.data.find(l => l.id === limitId);
  
  if (!currentLimit) {
    throw new Error('Limit not found');
  }
  
  // Increase limit temporarily
  await update(walletId, limitId, {
    limitAmount: temporaryAmount
  });
  
  // Schedule to revert after duration
  setTimeout(async () => {
    await update(walletId, limitId, {
      limitAmount: currentLimit.limitAmount
    });
    console.log('Limit reverted to original amount');
  }, durationDays * 24 * 60 * 60 * 1000);
}

Auto-Pause on Limit Reached

Setup Auto-Pause

// 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
  // await activate('wallet-id');
}

Best Practices

Next Steps