Files

5.1 KiB

Monarch Money API Reference

Table of Contents

Authentication

The MonarchClient handles authentication automatically:

import { MonarchClient } from 'monarch-money';

const client = new MonarchClient({
  baseURL: 'https://api.monarch.com',
  enablePersistentCache: false
});

await client.login({
  email: process.env.MONARCH_EMAIL,
  password: process.env.MONARCH_PASSWORD,
  mfaSecretKey: process.env.MONARCH_MFA_SECRET,
  useSavedSession: true,
  saveSession: true
});

Session Management

Sessions are encrypted and stored at ~/.mm/session.json. The useSavedSession option loads existing sessions, and saveSession persists new ones.

// Load saved session
const loaded = client.loadSession();

// Delete session
client.deleteSession();

// Close client
await client.close();

Transactions API

Get Transactions

const result = await client.transactions.getTransactions({
  limit: 50,
  startDate: '2026-01-01',
  endDate: '2026-01-31',
  verbosity: 'light'  // 'ultra-light' | 'light' | 'standard'
});

// result.transactions contains array of Transaction objects

Transaction Object

interface Transaction {
  id: string;
  amount: number;
  date: string;
  merchant: {
    id: string;
    name: string;
  };
  category: {
    id: string;
    name: string;
  };
  account: {
    id: string;
    displayName: string;
  };
  notes?: string;
  reviewStatus: 'needs_review' | 'reviewed';
  isPending: boolean;
}

Update Transaction

await client.transactions.updateTransaction(transactionId, {
  categoryId: 'new_category_id',
  notes: 'Updated notes',
  merchantName: 'New Merchant Name'
});

Split Transaction

const splits = [
  { amount: -20.00, categoryId: 'cat1', merchantName: 'Store', notes: 'Item 1' },
  { amount: -15.00, categoryId: 'cat2', merchantName: 'Store', notes: 'Item 2' }
];

await client.transactions.splitTransaction(transactionId, splits);

Categories API

Get All Categories

const categories = await client.categories.getCategories();

// categories is array of Category objects

Category Object

interface Category {
  id: string;
  name: string;
  group: {
    id: string;
    name: string;
    type: 'income' | 'expense' | 'transfer';
  };
  icon?: string;
}

Common Category IDs

Categories vary by user account. Use the CLI to get your specific IDs:

monarch-money cat list --show-ids

Accounts API

Get All Accounts

const accounts = await client.accounts.getAll({
  includeHidden: false,
  verbosity: 'light'
});

Account Object

interface Account {
  id: string;
  displayName: string;
  currentBalance: number;
  type: string;
  subtype: string;
  institution: {
    id: string;
    name: string;
  };
  isHidden: boolean;
}

GraphQL Direct Access

For advanced use cases, access the GraphQL client directly:

// Query
const result = await client['graphql'].query(queryString, variables);

// Mutation
const result = await client['graphql'].mutation(mutationString, variables);

Example: Custom Query

const query = `
  query GetTransactionDetails($id: UUID!) {
    getTransaction(id: $id) {
      id
      amount
      date
      merchant { name }
      category { name }
      notes
    }
  }
`;

const result = await client['graphql'].query(query, { id: transactionId });

Working Mutations

Update Transaction:

mutation UpdateTransaction($input: UpdateTransactionInput!) {
  updateTransaction(input: $input) {
    transaction { id }
    errors { message }
  }
}

Split Transaction:

mutation SplitTransaction($input: UpdateTransactionSplitInput!) {
  updateTransactionSplit(input: $input) {
    transaction { id }
    errors { message }
  }
}

Verbosity Levels

Control response detail with verbosity:

Level Use Case Data Included
ultra-light Quick overviews IDs, amounts, names only
light Standard display Core fields + dates + categories
standard Full analysis All fields including metadata
const accounts = await client.accounts.getAll({ verbosity: 'ultra-light' });
// Returns minimal data for fast processing

Rate Limiting

The client includes built-in rate limiting. Default settings:

  • 10 requests per second
  • 20 burst size

Configure in client options:

const client = new MonarchClient({
  baseURL: 'https://api.monarch.com',
  rateLimit: {
    requestsPerSecond: 5,
    burstSize: 10
  }
});

Caching

Two levels of caching available:

Memory Cache: In-session caching (default enabled) Persistent Cache: Cross-session caching (optional)

const client = new MonarchClient({
  baseURL: 'https://api.monarch.com',
  cache: {
    enabled: true,
    ttl: 300000  // 5 minutes
  },
  enablePersistentCache: true
});