Skip to main content
Version: 0.1.21 (Current)

API Overview

This library provides comprehensive access to Monarch Money's functionality through a Python async interface.

Architecture​

The library communicates with Monarch Money via their GraphQL API. All API methods are asynchronous and should be called with await.

from monarchmoney import MonarchMoney

mm = MonarchMoney()
await mm.login(email, password)

# All API calls are async
accounts = await mm.get_accounts()

API Categories​

Authentication​

Methods for logging in, handling MFA, and managing sessions.

MethodDescription
login()Log in to Monarch Money
interactive_login()Interactive login with prompts
multi_factor_authenticate()Complete MFA
save_session()Save auth session to file
load_session()Load auth session from file
delete_session()Delete saved session

Accounts​

Methods for managing financial accounts.

MethodDescription
get_accounts()Get all linked accounts
get_account_holdings()Get investment holdings
get_account_history()Get balance history
get_account_type_options()Get account types
create_manual_account()Create manual account
update_account()Update account settings
delete_account()Delete an account
request_accounts_refresh()Trigger account sync

Transactions​

Methods for working with transactions.

MethodDescription
get_transactions()Get transactions with filters
get_transaction_details()Get single transaction
get_transaction_splits()Get split info
create_transaction()Create transaction
update_transaction()Update transaction
delete_transaction()Delete transaction
update_transaction_splits()Modify splits

Categories & Tags​

Methods for organizing transactions.

MethodDescription
get_transaction_categories()Get all categories
create_transaction_category()Create category
update_transaction_category()Update category
delete_transaction_category()Delete category
get_transaction_tags()Get all tags
create_transaction_tag()Create tag
set_transaction_tags()Set tags on transaction

Budgets & Goals​

Methods for budget and savings goal management.

MethodDescription
get_budgets()Get budget data
set_budget_amount()Set budget amount
update_flexible_budget()Update flex budget
get_savings_goals()Get savings goals
get_savings_goal_budgets()Get goal budgets

Analytics​

Methods for financial analytics and reporting.

MethodDescription
get_cashflow()Get cashflow breakdown
get_cashflow_summary()Get cashflow summary
get_aggregates()Get aggregate totals
get_transactions_summary()Get txn summary

Return Types​

All API methods return Python dictionaries parsed from JSON responses. The structure matches Monarch Money's GraphQL schema.

accounts = await mm.get_accounts()
# Returns:
# {
#     "accounts": [...],
#     "householdPreferences": {...}
# }

Error Handling​

API methods may raise:

  • RequireMFAException - MFA is required
  • LoginFailedException - Login failed
  • RequestFailedException - API request failed
from monarchmoney import RequestFailedException

try:
    await mm.delete_transaction("invalid-id")
except RequestFailedException as e:
    print(f"Error: {e}")

Rate Limiting​

Monarch Money may rate limit requests. For bulk operations, consider:

  1. Adding delays between requests
  2. Using pagination for large datasets
  3. Implementing exponential backoff

Interactive API Testing​

Each API method page includes an interactive tester that lets you:

  1. Fill in parameters
  2. Generate Python code
  3. Execute requests (with your auth token)

This is useful for exploring the API and understanding response formats.