monarch-api

A TypeScript SDK for the Monarch API.

Installation

npm install monarch-api

Quick Start

import { MonarchClient } from 'monarch-api';

const client = new MonarchClient();

await client.login({
  email: '[email protected]',
  password: 'your-password',
});

const accounts = await client.accounts.list();
console.log(accounts);

Authentication

Email & Password

const client = new MonarchClient();

await client.login({
  email: '[email protected]',
  password: 'your-password',
});

Multi-Factor Authentication

If your account has MFA enabled, login will throw a RequireMFAError. Handle it by prompting the user for their code:

import { MonarchClient, RequireMFAError } from 'monarch-api';

const client = new MonarchClient();

try {
  await client.login({ email, password });
} catch (err) {
  if (err instanceof RequireMFAError) {
    await client.multiFactorAuthenticate({
      email,
      password,
      code: '123456', // 6-digit TOTP code
    });
  }
}

If you have access to your TOTP secret key, you can pass it directly to login and the SDK will handle MFA automatically:

await client.login({
  email,
  password,
  mfaSecretKey: 'YOUR_TOTP_SECRET',
});

Reusing a Token

To avoid re-authenticating on every run, you can initialize the client with an existing token:

const client = new MonarchClient({ token: 'your-token' });

Persisting Sessions

For scripts and automations, we recommend saving your session token to a file (e.g. ~/.monarch-session.json) and reusing it across runs. This avoids logging in on every execution.

import { MonarchClient, RequireMFAError } from 'monarch-api';
import { readFileSync, writeFileSync } from 'fs';
import { homedir } from 'os';
import { join } from 'path';

const SESSION_FILE = join(homedir(), '.monarch-session.json');

function loadSession(): { token: string } | null {
  try {
    return JSON.parse(readFileSync(SESSION_FILE, 'utf-8'));
  } catch {
    return null;
  }
}

function saveSession(token: string) {
  writeFileSync(SESSION_FILE, JSON.stringify({ token }), { mode: 0o600 });
}

const session = loadSession();
const client = new MonarchClient(session ?? undefined);

if (!session) {
  try {
    await client.login({ email, password });
  } catch (err) {
    if (err instanceof RequireMFAError) {
      await client.multiFactorAuthenticate({ email, password, code: '123456' });
    } else {
      throw err;
    }
  }

  saveSession(client.token!);
}

// client is ready to use
const accounts = await client.accounts.list();

Note: ~/.monarch-session.json contains a sensitive auth token. The example above sets file permissions to 0o600 (owner read/write only). Add it to your .gitignore if the file is inside a project directory.

API Reference

client.accounts

// List all connected accounts
const accounts = await client.accounts.list();

// Create a manual account
const { id } = await client.accounts.create({
  name: 'Savings Account',
  type: 'savings',
  balance: 5000,
  currency: 'USD',
});

// Update an account
const updated = await client.accounts.update(accountId, {
  displayName: 'Emergency Fund',
  includeInNetWorth: true,
});

// Delete an account
await client.accounts.delete(accountId);

// Get investment holdings
const holdings = await client.accounts.getHoldings(accountId);

// Get balance history
const history = await client.accounts.getHistory(accountId, {
  startDate: '2025-01-01',
  endDate: '2025-12-31',
});

// Refresh account data from institution
await client.accounts.refresh([accountId]);

// Refresh and wait for sync to complete
await client.accounts.refreshAndWait([accountId]);

client.transactions

// List transactions
const transactions = await client.transactions.list({
  startDate: '2025-01-01',
  endDate: '2025-01-31',
  limit: 100,
});

// Get a single transaction
const tx = await client.transactions.get(transactionId);

// Create a manual transaction
const { id } = await client.transactions.create({
  accountId,
  date: '2025-01-15',
  amount: -42.50,
  merchantName: 'Coffee Shop',
  categoryId,
});

// Update a transaction
await client.transactions.update(transactionId, {
  notes: 'Team lunch',
  categoryId: 'food-and-dining',
});

// Delete a transaction
await client.transactions.delete(transactionId);

// Split a transaction
await client.transactions.updateSplits(transactionId, [
  { amount: 25.00, categoryId: 'groceries' },
  { amount: 17.50, categoryId: 'household' },
]);

// Categories
const categories = await client.transactions.categories.list();
const groups = await client.transactions.categories.groups();
await client.transactions.categories.create({ name: 'Pet Care', groupId });

// Tags
const tags = await client.transactions.tags.list();
await client.transactions.tags.create('Reimbursable', '#FF5733');
await client.transactions.tags.set(transactionId, [tagId]);

client.budgets

// Get budget data for a month
const { budgetData, categoryGroups } = await client.budgets.list({
  startDate: '2025-01-01',
  endDate: '2025-01-31',
});

// Set a budget amount
await client.budgets.set(categoryId, 500, {
  startDate: '2025-01-01',
  endDate: '2025-01-31',
  rolloverEnabled: true,
});

client.cashflow

// Get full cashflow breakdown
const cashflow = await client.cashflow.get({
  startDate: '2025-01-01',
  endDate: '2025-01-31',
});

// Get cashflow summary
const summary = await client.cashflow.getSummary({
  startDate: '2025-01-01',
  endDate: '2025-01-31',
});
// { income, expenses, savings, savingsRate }

client.recurring

// List recurring transactions
const recurring = await client.recurring.list({
  startDate: '2025-01-01',
  endDate: '2025-01-31',
});

// Update a recurring transaction
await client.recurring.update(merchantId, {
  frequency: 'monthly',
  amount: 14.99,
});

client.institutions

// List connected institutions
const institutions = await client.institutions.list();

client.creditHistory

// Get credit score history
const scores = await client.creditHistory.get();

client.subscription

// Get subscription details
const subscription = await client.subscription.get();

Raw GraphQL Responses

Every method that returns processed data also accepts a { raw: true } option to get the unprocessed GraphQL response:

const raw = await client.accounts.list({ raw: true });
const raw = await client.institutions.list({ raw: true });
const raw = await client.creditHistory.get({ raw: true });

Error Handling

import {
  MonarchError,
  LoginFailedError,
  RequireMFAError,
  RequestFailedError,
} from 'monarch-api';

try {
  await client.login({ email, password });
} catch (err) {
  if (err instanceof LoginFailedError) {
    // Invalid credentials
  } else if (err instanceof RequireMFAError) {
    // MFA required
  } else if (err instanceof RequestFailedError) {
    // API request failed
  } else if (err instanceof MonarchError) {
    // Other SDK error
  }
}

TypeScript

This package is written in TypeScript and ships with full type definitions. All request options and response shapes are typed.

import type {
  Account,
  Transaction,
  TransactionCategory,
  Budget,
  CashflowSummary,
  RecurringTransaction,
} from 'monarch-api';

Development TUI

This repo also includes an interactive terminal UI for exploring the SDK against a live Monarch account. It's useful for development and serves as a reference example of a client application built with monarch-api.

npm run dev:tui

The TUI handles authentication automatically — it will prompt for credentials on first run and cache the session token to ~/.monarch-session.json for subsequent runs. You can also pre-fill credentials via environment variables:

[email protected] \
MONARCH_PASSWORD=your-password \
MONARCH_MFA_SECRET=YOUR_TOTP_SECRET \
npm run dev:tui

Modules

The TUI is organized into modules, selectable from the left sidebar:

| Module | Description | | ---------------------- | ----------------------------------------------------------------------------------- | | Welcome | Verifies your session token, shows masked token and account count | | Accounts | Lists all connected accounts with type and balance, plus total net worth | | Transactions | Displays the last 30 days of transactions with date, merchant, category, and amount |

Navigation

| Key | Action | | -------------------------------- | -------------------------------------------------- | | ↑ / ↓ or j / k | Navigate the module list | | Enter | Launch the selected module | | Tab | Toggle focus between sidebar and output pane | | ↑ / ↓ | Scroll output one line | | PageUp / PageDown | Scroll output one page | | t / b | Jump to top / bottom of output | | f | Toggle follow mode (auto-scroll as output arrives) | | q | Quit |

Adding Modules

Modules are auto-discovered from tui/modules/*.ts. Each module exports a name string and a run(context) function:

import type { Module } from '../lib/types.js';

export const name = 'My Module';

export const run: Module = async ({ client, display, signal }) => {
  display.header('My Module');
  const accounts = await client.accounts.list();
  display.table(accounts, ['name', 'currentBalance']);
};

License

Distributed under the MIT License, see LICENSE.md for details.