Actual Budget API

Official Node.js API for [Actual Budget](). Runs headless — works on local budget data synced from your server.

Installation

npm install @actual-app/api

Environment Variables

Variable

Required

Description

| ACTUAL_SERVER_URL | Yes | Server URL (e.g., ) | | ACTUAL_PASSWORD | Yes | Server password | | ACTUAL_SYNC_ID | Yes | Budget Sync ID (Settings → Advanced → Sync ID) | | ACTUAL_DATA_DIR | No | Local cache directory for budget data (defaults to cwd) | | ACTUAL_ENCRYPTION_PASSWORD | No | E2E encryption password, if enabled | | NODE_TLS_REJECT_UNAUTHORIZED | No | Set to 0 for self-signed certs | ## Quick Start __CODE_BLOCK_1__ ## Core Concepts - **Amounts** are integers in cents: $50.00 = 5000, -1200 = expense of $12.00 - **Dates** use YYYY-MM-DD, months use YYYY-MM - **IDs** are UUIDs — use getIDByName(type, name) to look up by name - Convert with api.utils.amountToInteger(123.45) → 12345 ## Common Operations ### Get Budget Overview __CODE_BLOCK_2__ ### Accounts __CODE_BLOCK_3__ ### Transactions __CODE_BLOCK_4__ ### Categories & Payees __CODE_BLOCK_5__ ### Budget Amounts __CODE_BLOCK_6__ ### Rules __CODE_BLOCK_7__ ### Schedules __CODE_BLOCK_8__ ### Bank Sync __CODE_BLOCK_9__ ### Sync & Shutdown __CODE_BLOCK_10__ ## ActualQL Queries For complex queries, use ActualQL: __CODE_BLOCK_11__ **Operators:** $eq, $lt, $lte, $gt, $gte, $ne, $oneof, $regex, $like, $notlike **Splits:** .options({ splits: 'inline' | 'grouped' | 'all' }) ## Helpers __CODE_BLOCK_12__ ## Transfers Transfers use special payees. Find transfer payee by transfer_acct` field:

const payees = await api.getPayees();
const transferPayee = payees.find(p => p.transfer_acct === targetAccountId);
await api.importTransactions(fromAccountId, [
  { date: '2026-01-15', amount: -10000, payee: transferPayee.id }
]);

Split Transactions

await api.importTransactions(accountId, [{
  date: '2026-01-15',
  amount: -5000,
  payee_name: 'Costco',
  subtransactions: [
    { amount: -3000, category: groceryCatId },
    { amount: -2000, category: householdCatId },
  ]
}]);

Bulk Import (New Budget)

For migrating from another app:

await api.runImport('My-New-Budget', async () => {
  for (const acct of myData.accounts) {
    const id = await api.createAccount(acct);
    await api.addTransactions(id, myData.transactions.filter(t => t.acctId === id));
  }
});

Reference

Full API:
ActualQL: