# Monarch Money
Python library for accessing [Monarch Money](https://www.monarchmoney.com/referral/ngam2i643l) data.
# Installation
## From Source Code
Clone this repository from Git
`git clone https://github.com/hammem/monarchmoney.git`
## Via `pip`
`pip install monarchmoney`
# 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:
```python
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:
```python
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:
```python
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:
```python
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.
```python
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.
```python
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
- `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_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
- `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
- `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
- `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.
- `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
# 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. Please ensure you do the following:
- Configure your IDE or manually run [Black](https://github.com/psf/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.
# 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](https://app.monarchmoney.com/settings/security).
Don't forget to use a password unique to your Monarch account and to enable multi-factor authentication!
Raw data
{
"_id": null,
"home_page": "https://github.com/hammem/monarchmoney",
"name": "monarchmoney",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": "monarch money, financial, money, personal finance",
"author": "hammem",
"author_email": "hammem@users.noreply.github.com",
"download_url": "https://files.pythonhosted.org/packages/99/d6/2bbf7ab3adac3f4e442b0066ed9c7b8ebdf116179b9f338404a5004b6f34/monarchmoney-0.1.13.tar.gz",
"platform": "any",
"description": "# Monarch Money\n\nPython library for accessing [Monarch Money](https://www.monarchmoney.com/referral/ngam2i643l) data.\n\n# Installation\n\n## From Source Code\n\nClone this repository from Git\n\n`git clone https://github.com/hammem/monarchmoney.git`\n\n## Via `pip`\n\n`pip install monarchmoney`\n# Instantiate & Login\n\nThere are two ways to use this library: interactive and non-interactive.\n\n## Interactive\n\nIf you're using this library in something like iPython or Jupyter, you can run an interactive-login which supports multi-factor authentication:\n\n```python\nfrom monarchmoney import MonarchMoney\n\nmm = MonarchMoney()\nawait mm.interactive_login()\n```\nThis will prompt you for the email, password and, if needed, the multi-factor token.\n\n## Non-interactive\n\nFor a non-interactive session, you'll need to create an instance and login:\n\n```python\nfrom monarchmoney import MonarchMoney\n\nmm = MonarchMoney()\nawait mm.login(email, password)\n```\n\nThis may throw a `RequireMFAException`. If it does, you'll need to get a multi-factor token and call the following method:\n\n```python\nfrom monarchmoney import MonarchMoney, RequireMFAException\n\nmm = MonarchMoney()\ntry:\n await mm.login(email, password)\nexcept RequireMFAException:\n await mm.multi_factor_authenticate(email, password, multi_factor_code)\n```\n\nAlternatively, 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:\n```python\nfrom monarchmoney import MonarchMoney, RequireMFAException\n\nmm = MonarchMoney()\nawait mm.login(\n email=email,\n password=password,\n save_session=False,\n use_saved_session=False,\n mfa_secret_key=mfa_secret_key,\n )\n\n```\n\n# Use a Saved Session\n\nYou 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.\n\n```python\nfrom monarchmoney import MonarchMoney, RequireMFAException\n\nmm = MonarchMoney()\nmm.interactive_login()\n\n# Save it for later, no more need to login!\nmm.save_session()\n```\n\nOnce you've logged in, you can simply load the saved session to pick up where you left off.\n\n```python\nfrom monarchmoney import MonarchMoney, RequireMFAException\n\nmm = MonarchMoney()\nmm.load_session()\n\n# Then, start accessing data!\nawait mm.get_accounts()\n```\n\n# Accessing Data\n\nAs of writing this README, the following methods are supported:\n\n## Non-Mutating Methods\n\n- `get_accounts` - gets all the accounts linked to Monarch Money\n- `get_account_holdings` - gets all of the securities in a brokerage or similar type of account\n- `get_account_type_options` - all account types and their subtypes available in Monarch Money- \n- `get_account_history` - gets all daily account history for the specified account\n- `get_institutions` -- gets institutions linked to Monarch Money\n- `get_budgets` \u2014 all the budgets and the corresponding actual amounts\n- `get_subscription_details` - gets the Monarch Money account's status (e.g. paid or trial)\n- `get_recurring_transactions` - gets the future recurring transactions, including merchant and account details\n- `get_transactions_summary` - gets the transaction summary data from the transactions page\n- `get_transactions` - gets transaction data, defaults to returning the last 100 transactions; can also be searched by date range\n- `get_transaction_categories` - gets all of the categories configured in the account\n- `get_transaction_category_groups` all category groups configured in the account- \n- `get_transaction_details` - gets detailed transaction data for a single transaction\n- `get_transaction_splits` - gets transaction splits for a single transaction\n- `get_transaction_tags` - gets all of the tags configured in the account\n- `get_cashflow` - gets cashflow data (by category, category group, merchant and a summary)\n- `get_cashflow_summary` - gets cashflow summary (income, expense, savings, savings rate)\n- `is_accounts_refresh_complete` - gets the status of a running account refresh\n\n## Mutating Methods\n\n- `delete_transaction_category` - deletes a category for transactions\n- `delete_transaction_categories` - deletes a list of transaction categories for transactions\n- `create_transaction_category` - creates a category for transactions\n- `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`.\n- `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.\n- `create_transaction` - creates a transaction with the given attributes\n- `update_transaction` - modifies one or more attributes for an existing transaction\n- `delete_transaction` - deletes a given transaction by the provided transaction id\n- `update_transaction_splits` - modifies how a transaction is split (or not)\n- `create_transaction_tag` - creates a tag for transactions\n- `set_transaction_tags` - sets the tags on a transaction\n- `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.\n- `create_manual_account` - creates a new manual account\n- `delete_account` - deletes an account by the provided account id\n- `update_account` - updates settings and/or balance of the provided account id\n- `upload_account_balance_history` - uploads account history csv file for a given account\n\n# Contributing\n\nAny and all contributions -- code, documentation, feature requests, feedback -- are welcome!\n\nIf 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:\n\n - Configure your IDE or manually run [Black](https://github.com/psf/black) to auto-format the code.\n - Ensure you run the unit tests in this project!\n \nActions 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.\n\n# FAQ\n\n**How do I use this API if I login to Monarch via Google?**\n\nIf 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](https://app.monarchmoney.com/settings/security). \n\nDon't forget to use a password unique to your Monarch account and to enable multi-factor authentication!\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Monarch Money API for Python",
"version": "0.1.13",
"project_urls": {
"Homepage": "https://github.com/hammem/monarchmoney"
},
"split_keywords": [
"monarch money",
" financial",
" money",
" personal finance"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "d32340ed772256ed23c21d9e9c707c7e0505d2f4d143b062d2c40fc1b7fb840b",
"md5": "f87f2d61b44cab1bd7e2a50b0b02d7be",
"sha256": "57305b435defff3a4b68c92ee24eefbdeea6254849e5658683aa3db1b76a9bdc"
},
"downloads": -1,
"filename": "monarchmoney-0.1.13-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "f87f2d61b44cab1bd7e2a50b0b02d7be",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": null,
"size": 19651,
"upload_time": "2024-07-11T23:20:07",
"upload_time_iso_8601": "2024-07-11T23:20:07.197782Z",
"url": "https://files.pythonhosted.org/packages/d3/23/40ed772256ed23c21d9e9c707c7e0505d2f4d143b062d2c40fc1b7fb840b/monarchmoney-0.1.13-py2.py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "99d62bbf7ab3adac3f4e442b0066ed9c7b8ebdf116179b9f338404a5004b6f34",
"md5": "94a5ae3529cffe046bec23251ceb0c27",
"sha256": "da4b7c1851443be0506f0424aa0b0153290c71722c352da3e20dcccbde26b07c"
},
"downloads": -1,
"filename": "monarchmoney-0.1.13.tar.gz",
"has_sig": false,
"md5_digest": "94a5ae3529cffe046bec23251ceb0c27",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 23197,
"upload_time": "2024-07-11T23:20:08",
"upload_time_iso_8601": "2024-07-11T23:20:08.877598Z",
"url": "https://files.pythonhosted.org/packages/99/d6/2bbf7ab3adac3f4e442b0066ed9c7b8ebdf116179b9f338404a5004b6f34/monarchmoney-0.1.13.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-07-11 23:20:08",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "hammem",
"github_project": "monarchmoney",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "aiohttp",
"specs": [
[
">=",
"3.8.4"
]
]
},
{
"name": "gql",
"specs": [
[
">=",
"3.4"
]
]
},
{
"name": "oathtool",
"specs": [
[
">=",
"2.3.1"
]
]
}
],
"lcname": "monarchmoney"
}
JSON
