actual-budget

---
name: actual-budget
description: Query and manage personal finances via the official Actual Budget Node.js API. Use for budget queries, transaction imports/exports, account management, categorization, rules, schedules, and bank sync with self-hosted Actual Budget instances.
---

# Actual Budget API

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

## Installation

```bash
npm install @actual-app/api
```

## Environment Variables

| Variable | Required | Description |
|----------|----------|-------------|
| `ACTUAL_SERVER_URL` | Yes | Server URL (e.g., `https://actual.example.com`) |
| `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_EXTRA_CA_CERTS` | No | Path to CA certificate file for self-signed certs |

### Self-Signed Certificates

If your Actual Budget server uses a self-signed certificate:

1. **Recommended:** Add your CA to the system trust store, or
2. **Alternative:** Set `NODE_EXTRA_CA_CERTS=/path/to/your-ca.pem` to trust your specific CA

Avoid disabling TLS verification entirely — it exposes you to man-in-the-middle attacks.

## Quick Start

```javascript
const api = require('@actual-app/api');

await api.init({
  dataDir: process.env.ACTUAL_DATA_DIR || '/tmp/actual-cache',
  serverURL: process.env.ACTUAL_SERVER_URL,
  password: process.env.ACTUAL_PASSWORD,
});

await api.downloadBudget(
  process.env.ACTUAL_SYNC_ID,
  process.env.ACTUAL_ENCRYPTION_PASSWORD ? { password: process.env.ACTUAL_ENCRYPTION_PASSWORD } : undefined
);

// ... do work ...

await api.shutdown();
```

## Core Concepts

- **Amounts** are integers in cents: `$50.00` = `5000`, `-1200` = expense of $12.00
- **Dates** use `YYYY-MM-DD`, months use `YYYY-MM`
- **