agentledger – OpenClaw Skill

---

name: agentledger description: Expense tracking and accounting for AI agents. Log purchases, set budgets, generate spending reports, and manage multi-currency finances — all stored locally. Privacy.com card import, natural language queries, CSV/JSON export. Use when agents make purchases and need a financial audit trail. metadata: {"openclaw": {"requires": {"bins": ["node"]}}}

AgentLedger - AI Agent Expense Tracking

Overview

AgentLedger is an accounting skill that logs every transaction you make, tracks spending across multiple accounts, and provides detailed reports. Use this to maintain a complete financial record of your purchases.

Important: Always log transactions immediately after making purchases. This skill is designed for AI agents to track their own expenses (API costs, tool subscriptions, etc.).

Core Functions

1. Log a Transaction

When you make any purchase, immediately log it:

// In Node.js context, require the ledger
const AgentLedger = require('./src/ledger.js');
const ledger = new AgentLedger();

// Log a transaction
await ledger.logTransaction({
  amount: 29.99,
  currency: 'USD',
  vendor: 'OpenAI',
  description: 'GPT-4 API credits',
  category: 'API/Services',
  account: 'privacy-card-1',
  context: 'Needed additional tokens for user project analysis',
  receiptUrl: 'https://platform.openai.com/receipts/xyz',
  confirmationId: 'sub_1234567890'
});

CLI Usage (supports both positional and named parameters):

# Positional style
node src/cli.js log 29.99 "OpenAI" "GPT-4 API credits" --category="API/Services"

# Named parameter style  
node src/cli.js log --amount=29.99 --vendor="OpenAI" --description="GPT-4 API credits" --category="API/Services" --context="Monthly API refill"

2. Check Current Spending

// Get spending summary
const summary = await ledger.getSummary('this-month');
console.log(`Total spent this month: $${summary.total}`);

// Check specific category
const apiSpending = await ledger.getCategorySpending('API/Services', 'this-month');

3. Generate Reports

// Monthly report
const report = await ledger.generateReport('monthly', { month: '2024-01' });

// Custom date range
const customReport = await ledger.generateReport('custom', {
  startDate: '2024-01-01',
  endDate: '2024-01-31'
});

4. Budget Management

// Set monthly budget for API services
await ledger.setBudget('API/Services', 500, 'monthly');

// Check budget status
const budgetStatus = await ledger.checkBudget('API/Services');
if (budgetStatus.isNearLimit) {
  console.log(`Warning: ${budgetStatus.percentUsed}% of API budget used`);
}

Categories

Use these predefined categories for consistent tracking:

• API/Services - API credits, SaaS subscriptions
• Infrastructure - Hosting, domains, CDN
• Marketing - Ads, social media tools
• Tools - Software licenses, utilities
• Subscriptions - Recurring monthly/yearly services
• Other - Miscellaneous expenses

Account Integration

Privacy.com Cards

The ledger automatically detects Privacy.com card data if available:

// If you have Privacy.com JSON exports in workspace/privacy/
await ledger.importPrivacyTransactions('./privacy/card-1.json');

Manual Account Setup

// Register a new payment method
await ledger.addAccount({
  id: 'stripe-main',
  name: 'Main Stripe Account',
  type: 'credit_card',
  currency: 'USD'
});

Natural Language Queries

Ask questions like:

• "How much did I spend on API keys this month?"
• "What was that $20 charge from yesterday?"
• "Show me all infrastructure costs from last quarter"
• "Am I over budget on marketing spend?"

The CLI handles these queries:

node src/cli.js query "API spending this month"
node src/cli.js find "OpenAI" --last-week

Time Periods

Supported natural language time periods:

• today, yesterday
• this-week, last-week
• this-month, last-month
• this-quarter, last-quarter
• this-year, last-year
• last-30-days, last-90-days

Data Export

// Export to CSV
await ledger.exportTransactions('csv', './exports/transactions.csv');

// Export to JSON
await ledger.exportTransactions('json', './exports/transactions.json');

CLI Quick Reference

Essential Commands for AI Agents

# Initialize (run once)
node src/cli.js init

# Log transactions (supports both styles)
node src/cli.js log 29.99 "OpenAI" "API credits" --category="API/Services"
node src/cli.js log --amount=29.99 --vendor="OpenAI" --description="API credits" --category="API/Services"

# Check current spending
node src/cli.js summary                    # This month
node src/cli.js summary --period="today"   # Today only
node src/cli.js summary --period="this-week" # This week

# Set and check budgets
node src/cli.js budget set "API/Services" 500    # Set monthly budget
node src/cli.js budget status                    # Check all budgets

# Generate detailed reports  
node src/cli.js report monthly
node src/cli.js report --type=category
node src/cli.js report --type=vendor

# Search transactions
node src/cli.js find "OpenAI"                    # Search by vendor
node src/cli.js find "API" --category="API/Services"  # Search by category
node src/cli.js find --min-amount=50             # Find large expenses

# Export data
node src/cli.js export csv                       # Export to CSV
node src/cli.js export --format=json            # Export to JSON

# Natural language queries
node src/cli.js query "How much did I spend on APIs this month?"
node src/cli.js query "What was that $25 charge?"

# Import from Privacy.com
node src/cli.js import privacy ./privacy-export.json

File Storage

• Transactions: workspace/ledger/transactions.json
• Accounts: workspace/ledger/accounts.json
• Budgets: workspace/ledger/budgets.json
• Settings: workspace/ledger/settings.json

Best Practices

1. Log immediately - Don't wait, log every purchase as it happens
2. Add context - Explain why the purchase was necessary
3. Use consistent categories - Stick to the predefined categories
4. Include receipts - Store confirmation numbers and receipt URLs
5. Set budgets - Establish spending limits for each category
6. Review regularly - Generate monthly reports to track spending patterns

Error Handling & Edge Cases

The ledger handles common errors gracefully:

Input Validation

• Negative amounts: Rejected (use positive amounts only)
• Missing required fields: Clear error messages with usage examples
• Invalid currency: Accepted (no validation - assumes user knows what they're doing)
• Very long descriptions: Handled without truncation

Data Safety

• Automatic backups: Created before each save operation
• Corrupted data recovery: Automatic recovery from .backup files
• Empty periods: Gracefully shows $0.00 totals
• Multi-currency: Properly separated in summaries and reports

Example Error Recovery

# If you see "Could not load transactions" message:
# The system automatically tries to recover from backup
# Your data should be restored automatically

# Manual backup check
ls workspace/ledger/*.backup  # Check if backups exist

Security & Privacy

• Local storage only: All data stays in workspace/ledger/ JSON files
• No external API calls: Core functionality works offline
• No sensitive data: Never store actual card numbers or passwords
• Account aliases: Use descriptive IDs like privacy-card-1 or company-amex
• Receipt URLs: Store links to receipts, not receipt content itself

AgentLedger

AI Agent Expense Tracking & Accounting for OpenClaw

AgentLedger is a comprehensive expense tracking skill that helps AI agents maintain detailed financial records of purchases and spending. Perfect for tracking API costs, subscription services, infrastructure expenses, and any other purchases made by AI agents.

🌟 Features

Core Functionality

• Transaction Logging - Log every purchase with amount, vendor, description, category, and context
• Multi-Currency Support - Track spending in different currencies
• Account Management - Manage multiple payment methods and cards
• Budget Tracking - Set spending limits and get alerts when approaching them
• Natural Language Queries - Ask questions like "How much did I spend on API keys this month?"
• Detailed Reports - Generate monthly, category, vendor, and trend reports
• Data Export - Export transactions to CSV or JSON formats
• Receipt Storage - Store receipt URLs and confirmation numbers

Categories

Pre-defined spending categories for consistent tracking:

• API/Services - API credits, SaaS subscriptions
• Infrastructure - Hosting, domains, CDN
• Marketing - Advertising, social media tools
• Tools - Software licenses, utilities
• Subscriptions - Recurring services
• Other - Miscellaneous expenses

Smart Features

• Privacy.com Integration - Import transactions from Privacy card exports
• Budget Alerts - Automatic warnings when approaching spending limits
• Trend Analysis - Track spending patterns over time
• Vendor Analysis - See spending patterns by vendor
• Time Period Filtering - Support for natural language time periods

🚀 Quick Start

Installation

# Clone or copy the skill to your workspace
cp -r agentledger /home/claw/.openclaw/workspace/

# Initialize the ledger
cd /home/claw/.openclaw/workspace/agentledger
node src/cli.js init

Basic Usage

Log a Transaction

# Command line
node src/cli.js log 29.99 "OpenAI" "GPT-4 API credits" --category="API/Services"

# In Node.js code
const AgentLedger = require('./src/ledger.js');
const ledger = new AgentLedger();

await ledger.logTransaction({
  amount: 29.99,
  vendor: 'OpenAI',
  description: 'GPT-4 API credits',
  category: 'API/Services',
  context: 'Monthly API refill for user projects'
});

Check Spending

# Get monthly summary
node src/cli.js summary --period="this-month"

# Search transactions
node src/cli.js find "OpenAI" --last-month

# Generate detailed report
node src/cli.js report monthly

Budget Management

# Set budget
node src/cli.js budget set "API/Services" 500

# Check budget status
node src/cli.js budget status

📖 Documentation

For AI Agents

See SKILL.md for detailed instructions on how AI agents should use this skill.

CLI Reference

# Initialize ledger
node src/cli.js init

# Log transactions
node src/cli.js log <amount> <vendor> <description> [options]
  --category=<category>      Transaction category
  --account=<account>        Payment account
  --context=<context>        Purchase context/reason
  --receipt=<url>            Receipt URL
  --confirmation=<id>        Confirmation number

# View summaries
node src/cli.js summary [options]
  --period=<period>          Time period (this-month, last-week, etc.)

# Search transactions
node src/cli.js find <query> [options]
  --period=<period>          Time period filter
  --category=<category>      Category filter
  --min-amount=<amount>      Minimum amount
  --max-amount=<amount>      Maximum amount

# Generate reports
node src/cli.js report <type> [options]
  Types: monthly, category, vendor, trend, custom
  --month=<YYYY-MM>         Specific month for monthly report
  --period=<period>         Time period for other reports

# Budget management
node src/cli.js budget set <category> <amount> [period]
node src/cli.js budget status
node src/cli.js budget check <category>

# Export data
node src/cli.js export <format> [options]
  Formats: csv, json
  --output=<filename>       Output filename
  --period=<period>         Time period to export

# Account management
node src/cli.js account add <id> <name> [type]
node src/cli.js account list

# Import data
node src/cli.js import privacy <file.json>

# Natural language queries
node src/cli.js query "How much did I spend on APIs this month?"

Time Periods

Supported natural language time periods:

• today, yesterday
• this-week, last-week
• this-month, last-month
• this-quarter, last-quarter
• this-year, last-year
• last-30-days, last-90-days

📁 File Structure

agentledger/
├── SKILL.md                    # AI agent instructions
├── README.md                   # This file
├── package.json                # Package metadata
├── src/
│   ├── ledger.js              # Core ledger functionality
│   ├── cli.js                 # Command line interface
│   ├── reports.js             # Report generation
│   └── budget.js              # Budget management
└── test/
    └── ledger.test.js         # Basic tests

Data Storage

All data is stored locally in JSON files:

• workspace/ledger/transactions.json - All transactions
• workspace/ledger/accounts.json - Payment accounts
• workspace/ledger/budgets.json - Budget settings
• workspace/ledger/settings.json - General settings

🔧 API Reference

AgentLedger Class

Transaction Management

// Log a transaction
await ledger.logTransaction({
  amount: 29.99,
  currency: 'USD',
  vendor: 'OpenAI',
  description: 'API credits',
  category: 'API/Services',
  account: 'privacy-card-1',
  context: 'Monthly API refill',
  receiptUrl: 'https://...',
  confirmationId: 'sub_123'
});

// Get spending summary
const summary = await ledger.getSummary('this-month');

// Find transactions
const transactions = await ledger.findTransactions('OpenAI', {
  period: 'last-month',
  category: 'API/Services'
});

Budget Management

// Set budget
await ledger.setBudget('API/Services', 500, 'monthly');

// Check budget status
const status = await ledger.checkBudget('API/Services');
console.log(`Used ${status.percentUsed}% of budget`);

Data Export

// Export to CSV
await ledger.exportTransactions('csv', './exports/transactions.csv', {
  period: 'this-year'
});

// Export to JSON
await ledger.exportTransactions('json', './exports/data.json');

🔌 Integrations

Privacy.com Cards

AgentLedger can import transaction data from Privacy.com card exports:

node src/cli.js import privacy ./privacy-export.json

The importer automatically:

• Maps merchants to appropriate categories
• Extracts transaction details
• Assigns transactions to the correct Privacy card account
• Handles duplicate detection

Custom Integrations

Extend AgentLedger by:

1. Adding new import formats in src/ledger.js
2. Creating custom categorization rules
3. Adding new report types in src/reports.js
4. Implementing webhook notifications for budget alerts

🛡️ Security & Privacy

• Local Storage Only - All data stays on your machine
• No External API Calls - Core functionality works offline
• No Sensitive Data - Never store actual card numbers
• Account Aliases - Use account IDs instead of real account details

🧪 Testing

Run the basic test suite:

node test/ledger.test.js

📈 Examples

Daily Workflow

// Morning: Check yesterday's spending
await ledger.getSummary('yesterday');

// Log API purchase
await ledger.logTransaction({
  amount: 50.00,
  vendor: 'OpenAI',
  description: 'Additional GPT-4 credits',
  category: 'API/Services',
  context: 'User requested complex analysis requiring more tokens'
});

// Check if approaching budget limits
const alerts = await budgetManager.getAlerts();
if (alerts.length > 0) {
  console.log('Budget alerts:', alerts);
}

// Weekly: Generate spending report
const report = await reports.generate('weekly');
console.log(report);

Monthly Review

# Generate comprehensive monthly report
node src/cli.js report monthly

# Export data for accounting
node src/cli.js export csv --output="expenses-2024-01.csv" --period="last-month"

# Review budget performance
node src/cli.js budget status

🤝 Contributing

AgentLedger is designed to be extended and customized:

1. Add Categories - Modify the categories in settings.json
2. Custom Reports - Add new report types in reports.js
3. New Importers - Add support for other payment systems
4. Enhanced CLI - Add new commands to cli.js

📄 License

MIT License - See package.json for details.

🔗 Links

• OpenClaw Documentation
• ClawHub Skills Repository
• Privacy.com - Virtual card service

---

Built for OpenClaw AI Agents 🤖💰