Python library for accessing Monarch Money data.
Clone this repository from Git
git clone https://github.com/hammem/monarchmoney.git
pip install monarchmoney
There are two ways to use this library: interactive and non-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.
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,
)
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()
As of writing this README, the following methods are supported:
get_accounts
- gets all the accounts linked to Monarch Moneyget_account_holdings
- gets all of the securities in a brokerage or similar type of accountget_account_type_options
- all account types and their subtypes available in Monarch Money-get_account_history
- gets all daily account history for the specified accountget_institutions
-- gets institutions linked to Monarch Moneyget_budgets
— all the budgets and the corresponding actual amountsget_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 detailsget_transactions_summary
- gets the transaction summary data from the transactions pageget_transactions
- gets transaction data, defaults to returning the last 100 transactions; can also be searched by date rangeget_transaction_categories
- gets all of the categories configured in the accountget_transaction_category_groups
all category groups configured in the account-get_transaction_details
- gets detailed transaction data for a single transactionget_transaction_splits
- gets transaction splits for a single transactionget_transaction_tags
- gets all of the tags configured in the accountget_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
delete_transaction_category
- deletes a category for transactionsdelete_transaction_categories
- deletes a list of transaction categories for transactionscreate_transaction_category
- creates a category for transactionsrequest_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 callis_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 attributesupdate_transaction
- modifies one or more attributes for an existing transactiondelete_transaction
- deletes a given transaction by the provided transaction idupdate_transaction_splits
- modifies how a transaction is split (or not)create_transaction_tag
- creates a tag for transactionsset_transaction_tags
- sets the tags on a transactionset_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.create_manual_account
- creates a new manual accountdelete_account
- deletes an account by the provided account idupdate_account
- updates settings and/or balance of the provided account idupload_account_balance_history
- uploads account history csv file for a given account
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. Please ensure you do the following:
- Configure your IDE or manually run Black to auto-format the code.
- Ensure you run the unit tests in this project!
Actions are configured in this repo to run against all PRs and merges which will block them if a unit test fails or Black throws an error.
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!