monarchmoneycommunity 1.3.2

Monarch Money API for Python

[!WARNING] This project was forked from https://github.com/hammem/monarchmoney and would not be possible without it. The upstream fork is no longer maintained. This fork fixes issues that prevent the library from working today, including the Monarch Money domain change to api.monarch.com, auth persistence, and the get_budget() GraphQL query. Moving forward, please report issues here.

Monarch Money Community

Python library for accessing Monarch Money data.

Installation

From Source Code

Clone this repository from Git

git clone https://github.com/bradleyseanf/monarchmoneycommunity.git

Via pip

pip install monarchmoneycommunity

Import the library as monarchmoney after installation.

This package pins gql to 4.0.

Instantiate & Login

There are two ways to use this library: interactive and non-interactive.

Interactive

If you're using this library in something like iPython or Jupyter, you can run an interactive-login which supports multi-factor authentication:

from monarchmoney import MonarchMoney

mm = MonarchMoney()
await mm.interactive_login()

This will prompt you for the email, password and, if needed, the multi-factor token.

Non-interactive

For a non-interactive session, you'll need to create an instance and login:

from monarchmoney import MonarchMoney

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

This may throw a RequireMFAException. If it does, you'll need to get a multi-factor token and call the following method:

from monarchmoney import MonarchMoney, RequireMFAException

mm = MonarchMoney()
try:
        await mm.login(email, password)
except RequireMFAException:
        await mm.multi_factor_authenticate(email, password, multi_factor_code)

Alternatively, you can provide the MFA Secret Key. The MFA Secret Key is found when setting up the MFA in Monarch Money by going to Settings -> Security -> Enable MFA -> and copy the Two-factor text code. Then provide it in the login() method:

from monarchmoney import MonarchMoney, RequireMFAException

mm = MonarchMoney()
await mm.login(
        email=email,
        password=password,
        save_session=False,
        use_saved_session=False,
        mfa_secret_key=mfa_secret_key,
    )

Use a Saved Session

You can easily save your session for use later on. While we don't know precisely how long a session lasts, authors of this library have found it can last several months.

from monarchmoney import MonarchMoney, RequireMFAException

mm = MonarchMoney()
mm.interactive_login()

# Save it for later, no more need to login!
mm.save_session()

Once you've logged in, you can simply load the saved session to pick up where you left off.

from monarchmoney import MonarchMoney, RequireMFAException

mm = MonarchMoney()
mm.load_session()

# Then, start accessing data!
await mm.get_accounts()

Accessing Data

As of writing this README, the following methods are supported:

Non-Mutating Methods

Method	Description
get_accounts	gets all the accounts linked to Monarch Money
get_account_holdings	gets all of the securities in a brokerage or similar type of account
get_account_type_options	all account types and their subtypes available in Monarch Money
get_account_history	gets all daily account history for the specified account
get_institutions	gets institutions linked to Monarch Money
get_budgets	all the budgets and the corresponding actual amounts
get_credit_history	gets credit score snapshots and Spinwheel user details
get_subscription_details	gets the Monarch Money account's status (e.g. paid or trial)
get_recurring_transactions	gets the future recurring transactions, including merchant and account details
get_transactions_summary	gets the transaction summary data from the transactions page
get_transactions	gets transaction data, defaults to returning the last 100 transactions; can also be searched by date range
find_duplicate_transactions	finds duplicate transaction groups using Plaid-reported fields
get_transaction_categories	gets all of the categories configured in the account
get_transaction_category_groups	all category groups configured in the account
get_transaction_details	gets detailed transaction data for a single transaction
get_transaction_splits	gets transaction splits for a single transaction
get_transaction_tags	gets all of the tags configured in the account
get_cashflow	gets cashflow data (by category, category group, merchant and a summary)
get_cashflow_summary	gets cashflow summary (income, expense, savings, savings rate)
is_accounts_refresh_complete	gets the status of a running account refresh

Mutating Methods

Method	Description
delete_transaction_category	deletes a category for transactions
delete_transaction_categories	deletes a list of transaction categories for transactions
create_transaction_category	creates a category for transactions
request_accounts_refresh	requests a synchronization / refresh of all accounts linked to Monarch Money. This is a non-blocking call. If the user wants to check on the status afterwards, they must call is_accounts_refresh_complete.
request_accounts_refresh_and_wait	requests a synchronization / refresh of all accounts linked to Monarch Money. This is a blocking call and will not return until the refresh is complete or no longer running.
create_transaction	creates a transaction with the given attributes
update_transaction	modifies one or more attributes for an existing transaction
update_reoccuring	updates recurring merchant settings (frequency, amount, date, active status)
delete_transaction	deletes a given transaction by the provided transaction id
update_transaction_splits	modifies how a transaction is split (or not)
create_transaction_tag	creates a tag for transactions
set_transaction_tags	sets the tags on a transaction
set_budget_amount	sets a budget's value to the given amount (date allowed, will only apply to month specified by default). A zero amount value will unset or clear the budget for the given category.
update_flexible_budget	updates the Flexible budget bucket amount for a month
update_flex_rollover_settings	updates the Flex rollover settings, including the start month and starting balance
reset_budget	resets the budget for a month back to its defaults
create_manual_account	creates a new manual account
delete_account	deletes an account by the provided account id
update_account	updates settings and/or balance of the provided account id
upload_account_balance_history	uploads account history csv file for a given account
upload_attachment	uploads a binary file for a given transaction by the provided transaction id

Contributing

Any and all contributions - code, documentation, feature requests, feedback - are welcome!

If you plan to submit up a pull request, you can expect a timely review. There aren't any strict requirements around the environment you'll need.

FAQ

How do I use this API if I login to Monarch via Google?

If you currently use Google or 'Continue with Google' to access your Monarch account, you'll need to set a password to leverage this API. You can set a password on your Monarch account by going to your security settings.

Don't forget to use a password unique to your Monarch account and to enable multi-factor authentication!

Projects Using This Library

Open a PR adjusting the README if you would like to be added to this list

Disclaimer: These projects are neither affiliated nor endorsed by Monarch Money.

• mmoney-cli - Access your MonarchMoney data via CLI
• monarchmoney-typed - MonarchMoney Home Assistant Integration
• monarch-mcp-server - Model Context Protocol (MCP) server for integrating with Monarch Money.