Scheduled Transactions Module

The scheduled transactions module provides functionality for scheduling one-time or recurring transactions, enabling automated payments, subscriptions, and periodic transfers.

Import

import { 
  create,
  findAll,
  findOne,
  update,
  cancel
} from 'cilantro-sdk/scheduled-transactions';

Basic Operations

create(walletId, options)

Schedule a one-time or recurring transaction.

// Schedule a one-time SOL transfer
const scheduled = await create('wallet-id', {
  transactionType: 'SEND_SOL',
  recurrenceType: 'ONE_TIME',
  scheduledAt: '2024-12-31T23:59:59Z',
  toAddress: 'DYw8jCTfwHNRJhhmFcbXvVDTqWMEVFBX6ZKUmG5CNSKK',
  amount: 1000000000 // 1 SOL
});

findAll(walletId)

Get all scheduled transactions for a wallet (pending, queued, processing, completed, failed).

const scheduled = await findAll('wallet-id');
console.log('Scheduled transactions:', scheduled.data);

findOne(walletId, id)

Get details of a specific scheduled transaction.

const transaction = await findOne('wallet-id', 'scheduled-transaction-id');
console.log('Status:', transaction.data.status);
console.log('Next execution:', transaction.data.nextExecution);

update(walletId, id, options)

Update scheduled transaction details (schedule time, amount, etc.). Cannot update transactions that are being processed.

await update('wallet-id', 'scheduled-transaction-id', {
  scheduledAt: '2025-01-01T00:00:00Z',
  amount: 2000000000 // Update to 2 SOL
});

cancel(walletId, id)

Cancel a pending scheduled transaction. Cannot cancel completed transactions.

await cancel('wallet-id', 'scheduled-transaction-id');

Recurring Transaction Patterns

Daily Recurring Transaction

// Schedule daily payments
const dailyPayment = await create('wallet-id', {
  transactionType: 'SEND_SOL',
  recurrenceType: 'DAILY',
  scheduledAt: '2024-01-01T09:00:00Z', // First execution time
  toAddress: 'DYw8jCTfwHNRJhhmFcbXvVDTqWMEVFBX6ZKUmG5CNSKK',
  amount: 50000000, // 0.05 SOL per day
  maxExecutions: 30 // Stop after 30 days
});

Weekly Recurring Transaction

// Schedule weekly subscription payment
const weeklySubscription = await create('wallet-id', {
  transactionType: 'SEND_SOL',
  recurrenceType: 'WEEKLY',
  scheduledAt: '2024-01-01T10:00:00Z', // Every Monday at 10 AM
  toAddress: 'DYw8jCTfwHNRJhhmFcbXvVDTqWMEVFBX6ZKUmG5CNSKK',
  amount: 1000000000 // 1 SOL per week
});

Monthly Recurring Transaction

// Schedule monthly salary payment
const monthlySalary = await create('wallet-id', {
  transactionType: 'SEND_SOL',
  recurrenceType: 'MONTHLY',
  scheduledAt: '2024-01-01T00:00:00Z', // First of each month
  toAddress: 'DYw8jCTfwHNRJhhmFcbXvVDTqWMEVFBX6ZKUmG5CNSKK',
  amount: 10000000000 // 10 SOL per month
});

Recurring SPL Token Transfer

// Schedule weekly USDC payments
const weeklyUSDC = await create('wallet-id', {
  transactionType: 'SEND_SPL',
  recurrenceType: 'WEEKLY',
  scheduledAt: '2024-01-01T10:00:00Z',
  toAddress: 'DYw8jCTfwHNRJhhmFcbXvVDTqWMEVFBX6ZKUmG5CNSKK',
  tokenMint: 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v', // USDC
  amount: 1000000 // 1 USDC (6 decimals)
});

Usage Examples

Subscription Payment System

// Create a monthly subscription
const subscription = await create('wallet-id', {
  transactionType: 'SEND_SOL',
  recurrenceType: 'MONTHLY',
  scheduledAt: new Date(Date.now() + 30 * 24 * 60 * 60 * 1000).toISOString(),
  toAddress: 'subscription-recipient-address',
  amount: 2000000000, // 2 SOL per month
  metadata: {
    subscriptionId: 'sub-123',
    plan: 'premium'
  }
});

// Check subscription status
const status = await findOne('wallet-id', subscription.data.id);
console.log('Next payment:', status.data.nextExecution);

Automated Savings Plan

// Set up daily savings
const savingsPlan = await create('wallet-id', {
  transactionType: 'SEND_SOL',
  recurrenceType: 'DAILY',
  scheduledAt: '2024-01-01T08:00:00Z',
  toAddress: 'savings-wallet-address',
  amount: 100000000, // 0.1 SOL per day
  maxExecutions: 365 // Save for a year
});

Managing Scheduled Transactions

// Get all scheduled transactions
const allScheduled = await findAll('wallet-id');

// Filter by status
const pending = allScheduled.data.filter(tx => tx.status === 'pending');
const completed = allScheduled.data.filter(tx => tx.status === 'completed');

// Update a scheduled transaction
if (pending.length > 0) {
  await update('wallet-id', pending[0].id, {
    amount: 1500000000 // Increase amount
  });
}

// Cancel a transaction
await cancel('wallet-id', pending[0].id);

Transaction Status

Scheduled transactions can have the following statuses:

• pending - Waiting to be executed
• queued - Queued for execution
• processing - Currently being processed
• completed - Successfully executed
• failed - Execution failed

Best Practices