# Monarch Money
Python library for accessing [Monarch Money](https://www.monarchmoney.com/referral/jtfazovwp9) data.
## 🙏 Acknowledgments
Huge shoutout to [hammem](https://github.com/hammem) for originally starting this project! This is simply a fork of [his hard work](https://github.com/hammem/monarchmoney) to continue development and fix critical authentication issues.
## 🔧 Enhanced Features
This fork includes **comprehensive improvements** and implements features requested in the original repository:
### 🎯 **Core Enhancements**
- **Fixed GraphQL Server Errors**: Resolved "Something went wrong processing" errors in account queries
- **Stable Account Fetching**: Simplified GraphQL queries for reliable account data retrieval
- **404 Login Error Fixes**: Automatic GraphQL fallback when REST endpoints return 404
- **Enhanced Authentication**: Proper headers (device-uuid, Origin) and email OTP support
- **Advanced Error Recovery**: Automatic session recovery and retry logic with exponential backoff
- **Comprehensive Test Suite**: 58 tests passing with full CI/CD pipeline
### 💼 **Investment Management** (implements [Issue #112](https://github.com/hammem/monarchmoney/issues/112))
- **✅ Add Holdings API**: Complete manual holdings management
- `create_manual_holding()` - Add holdings by security ID or ticker
- `update_holding_quantity()` - Modify existing holdings
- `delete_manual_holding()` - Remove holdings
- `get_account_holdings()` - Retrieve all holdings for accounts
- `get_holding_by_ticker()` - Lookup specific holdings
### 📊 **Advanced Budget Management** (implements [PR #154](https://github.com/hammem/monarchmoney/pull/154))
- **✅ Flexible Budgets Support**: Full flexible budget API implementation
- `set_budget_amount()` - Update budget amounts with flexible period support
- `get_budgets()` - Retrieve budgets with flexible expense tracking
- Support for `BudgetFlexMonthlyAmounts` and flexible budget variability
- Complete budget management with rollover and planning features
### 🎯 **Financial Goals & Planning**
- `create_goal()` - Create financial goals with target amounts and dates
- `update_goal()` - Modify existing goals and track progress
- `delete_goal()` - Remove completed or unwanted goals
- `get_goals()` - Retrieve all goals with progress tracking
### 💰 **Cash Flow Analysis**
- `get_cashflow()` - Detailed income/expense analysis with category breakdowns
- `get_cashflow_summary()` - Key financial metrics and trends
- `get_bills()` - Upcoming bills and payment tracking
- Advanced financial planning and forecasting capabilities
# Installation
## From Source Code
Clone this repository from Git
`git clone https://github.com/keithah/monarchmoney-enhanced.git`
## Via `pip`
`pip install monarchmoney-enhanced`
**Note**: This package is published as `monarchmoney-enhanced` on PyPI to distinguish it from the original `monarchmoney` package while maintaining the same Python import structure.
# 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)
```
**Note**: The library automatically detects whether your MFA code is an email OTP (6 digits) or TOTP from an authenticator app, and uses the appropriate authentication field.
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
This enhanced library provides **comprehensive financial data access**:
## 💼 **Investment & Holdings Management**
- `get_account_holdings(account_id)` - Get all securities in investment accounts
- `create_manual_holding(account_id, symbol, quantity)` - **Add holdings by ticker**
- `create_manual_holding_by_ticker(account_id, ticker, quantity)` - Add holdings with ticker lookup
- `update_holding_quantity(holding_id, quantity)` - Modify existing holdings
- `delete_manual_holding(holding_id)` - Remove holdings
- `get_holding_by_ticker(ticker)` - Lookup holdings by ticker symbol
## 📊 **Budget & Financial Planning**
- `get_budgets()` - **Get budgets with flexible budget support**
- `set_budget_amount(category_id, amount)` - **Update budget amounts with flexible periods**
- `get_goals()` - Get financial goals with progress tracking
- `create_goal(name, target_amount)` - Create new financial goals
- `update_goal(goal_id, **kwargs)` - Update existing goals
- `delete_goal(goal_id)` - Remove financial goals
- `get_cashflow()` - Income/expense analysis with category breakdowns
- `get_cashflow_summary()` - Key financial metrics and trends
- `get_bills()` - Upcoming bills and payment tracking
## 🏦 **Account & Transaction Data**
- `get_accounts()` - **Get all linked accounts (with GraphQL fixes)**
- `get_me()` - Current user profile (timezone, email, name, MFA status)
- `get_merchants()` - Merchant list from transactions
- `get_account_type_options()` - All available account types and subtypes
- `get_account_history()` - Daily account balance history
- `get_institutions()` - Linked financial institutions
- `get_subscription_details()` - Account status (paid/trial)
- `get_recurring_transactions()` - Future recurring transactions
- `get_transactions()` - Transaction data with flexible date ranges
- `get_transactions_summary()` - Transaction summary from transactions page
- `get_transactions_summary_card()` - Summary card data with totals
- `get_transaction_categories()` - All configured transaction categories
- `get_transaction_category_groups()` - All category groups
- `get_transaction_details(transaction_id)` - Detailed transaction data
- `get_transaction_splits(transaction_id)` - Transaction split information
- `get_transaction_tags()` - All configured transaction tags
- `get_recurring_transactions()` - **Recurring transaction streams and patterns**
- `mark_stream_as_not_recurring(stream_id)` - **Mark merchants as not recurring**
- `get_net_worth_history()` - Net worth tracking over time
- `is_accounts_refresh_complete()` - Account refresh status
## 🔄 **Data Modification Methods**
### 💼 **Investment Management**
- `create_manual_holding(account_id, symbol, quantity)` - **Create holdings by ticker**
- `update_holding_quantity(holding_id, quantity)` - Update holding quantities
- `delete_manual_holding(holding_id)` - Remove holdings from accounts
### 📊 **Budget & Goals Management**
- `set_budget_amount(category_id, amount)` - **Set flexible budget amounts**
- `create_goal(name, target_amount)` - Create new financial goals
- `update_goal(goal_id, **kwargs)` - Update existing goals
- `delete_goal(goal_id)` - Remove financial goals
### 🏦 **Account Management**
- `create_manual_account(name, type, balance)` - Create new manual accounts
- `update_account(account_id, **kwargs)` - Update account settings/balance
- `delete_account(account_id)` - Delete accounts
- `upload_account_balance_history(account_id, csv_file)` - Upload balance history
- `request_accounts_refresh()` - **Non-blocking** account sync refresh
- `request_accounts_refresh_and_wait()` - **Blocking** account sync refresh
### 💳 **Transaction Management**
- `create_transaction(account_id, amount, date, **kwargs)` - Create transactions
- `update_transaction(transaction_id, **kwargs)` - Update transaction attributes
- `delete_transaction(transaction_id)` - Delete transactions
- `update_transaction_splits(transaction_id, splits)` - Modify transaction splits
- `create_transaction_category(name, **kwargs)` - Create transaction categories
- `update_transaction_category(category_id, **kwargs)` - Update categories
- `delete_transaction_category(category_id)` - Delete single category
- `delete_transaction_categories(category_ids)` - Delete multiple categories
- `create_transaction_tag(name)` - Create transaction tags
- `set_transaction_tags(transaction_id, tag_ids)` - Set tags on transactions
### 🔄 **Recurring Transaction Management**
- `mark_stream_as_not_recurring(stream_id)` - **Mark merchants as not recurring**
- `get_edit_merchant(merchant_id)` - **Get merchant edit info with recurring details**
- `get_recurring_transactions()` - Get upcoming recurring transactions
- `review_recurring_stream(stream_id, status)` - Review and approve recurring streams
## Session Management Methods
- `validate_session` - validates current session by making a lightweight API call
- `is_session_stale` - checks if session needs validation based on elapsed time
- `ensure_valid_session` - ensures session is valid, validating if stale
- `get_session_info` - gets session metadata (creation time, last validation, staleness)
## Transaction Rules
Complete transaction rules management:
- `get_transaction_rules` - Get all configured rules with criteria and actions
- `create_transaction_rule` - Create rules with merchant/amount/category/account criteria
- `update_transaction_rule` - Update existing rule criteria and actions
- `delete_transaction_rule` - Delete individual rules
- `reorder_transaction_rules` - Change rule execution order
- `preview_transaction_rule` - Preview rule effects before creating
- `delete_all_transaction_rules` - Delete all rules at once
- `create_categorization_rule` - Helper for simple merchant→category rules
For a complete mapping of GraphQL operations and implementation status, see [GRAPHQL.md](GRAPHQL.md).
# Development & Testing
## Running Tests
This project includes a comprehensive test suite. To run tests:
```bash
# Install test dependencies
pip install pytest pytest-asyncio pytest-cov
# Run all tests
pytest
# Run with coverage
pytest --cov=monarchmoney --cov-report=term-missing
# Run specific test categories
pytest -m "api" # API method tests
pytest -m "auth" # Authentication tests
pytest -m "unit" # Unit tests
```
## Test Categories
- **Authentication Tests**: Login, MFA, session management, header validation
- **API Method Tests**: Account/transaction retrieval, GraphQL execution, error handling
- **Integration Tests**: End-to-end functionality and field detection
- **Retry Logic Tests**: Rate limiting, exponential backoff, error handling
## CI/CD
This project uses GitHub Actions for continuous integration:
- **Multi-Python Testing**: Supports Python 3.8 through 3.12
- **Code Quality**: Automated linting with flake8, formatting with black, import sorting with isort
- **Coverage Reporting**: Integrated with Codecov for test coverage tracking
# 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. 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: `pytest`
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.
# Troubleshooting
## Authentication Issues
If you're experiencing login problems, this fork includes several fixes:
**404 Login Errors**: The library automatically falls back to GraphQL authentication if REST endpoints return 404.
**403 Forbidden Errors**: Ensure you're using the latest version which includes proper browser headers (device-uuid, Origin, User-Agent).
**MFA Problems**: The library automatically detects email OTP vs authenticator app codes:
- 6-digit numeric codes are treated as email OTP
- Other formats are treated as TOTP from authenticator apps
**Rate Limiting**: Built-in retry logic with exponential backoff handles temporary rate limits automatically.
# 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!
**What makes this fork superior?**
This enhanced fork is **ahead of the original repository** with implemented features that others are still requesting:
🎯 **Requested Features Already Implemented:**
- **[Issue #112](https://github.com/hammem/monarchmoney/issues/112)**: ✅ Add Holdings API - Full investment management
- **[PR #154](https://github.com/hammem/monarchmoney/pull/154)**: ✅ Flexible Budgets - Complete budget flexibility support
🔧 **Critical Issue Fixes:**
- **GraphQL Server Errors**: Fixed "Something went wrong processing" errors
- **404 Authentication**: Automatic GraphQL fallback for auth endpoints
- **403 Forbidden**: Proper browser headers (device-uuid, Origin, User-Agent)
- **MFA Detection**: Smart email OTP vs TOTP field detection
- **Session Recovery**: Automatic session validation and recovery
🚀 **Advanced Features:**
- **Financial Goals Management**: Complete CRUD operations for goal tracking
- **Cash Flow Analysis**: Detailed income/expense breakdowns and trends
- **Bills Management**: Payment tracking and due date monitoring
- **Error Recovery**: Exponential backoff retry logic for robustness
- **Test Coverage**: 58 passing tests with full CI/CD pipeline
Raw data
{
"_id": null,
"home_page": "https://github.com/keithah/monarchmoney-enhanced",
"name": "monarchmoney-enhanced",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": "monarch money, financial, money, personal finance",
"author": "keithah",
"author_email": "keithah <keithah@users.noreply.github.com>",
"download_url": "https://files.pythonhosted.org/packages/03/3d/6d099cf31e327f406f992723e7db05bae517f6601118c3ed4cb460604f43/monarchmoney_enhanced-0.9.3.tar.gz",
"platform": "any",
"description": "# Monarch Money\n\nPython library for accessing [Monarch Money](https://www.monarchmoney.com/referral/jtfazovwp9) data.\n\n## \ud83d\ude4f Acknowledgments\n\nHuge shoutout to [hammem](https://github.com/hammem) for originally starting this project! This is simply a fork of [his hard work](https://github.com/hammem/monarchmoney) to continue development and fix critical authentication issues.\n\n## \ud83d\udd27 Enhanced Features\n\nThis fork includes **comprehensive improvements** and implements features requested in the original repository:\n\n### \ud83c\udfaf **Core Enhancements**\n- **Fixed GraphQL Server Errors**: Resolved \"Something went wrong processing\" errors in account queries\n- **Stable Account Fetching**: Simplified GraphQL queries for reliable account data retrieval \n- **404 Login Error Fixes**: Automatic GraphQL fallback when REST endpoints return 404\n- **Enhanced Authentication**: Proper headers (device-uuid, Origin) and email OTP support \n- **Advanced Error Recovery**: Automatic session recovery and retry logic with exponential backoff\n- **Comprehensive Test Suite**: 58 tests passing with full CI/CD pipeline\n\n### \ud83d\udcbc **Investment Management** (implements [Issue #112](https://github.com/hammem/monarchmoney/issues/112))\n- **\u2705 Add Holdings API**: Complete manual holdings management\n- `create_manual_holding()` - Add holdings by security ID or ticker\n- `update_holding_quantity()` - Modify existing holdings\n- `delete_manual_holding()` - Remove holdings \n- `get_account_holdings()` - Retrieve all holdings for accounts\n- `get_holding_by_ticker()` - Lookup specific holdings\n\n### \ud83d\udcca **Advanced Budget Management** (implements [PR #154](https://github.com/hammem/monarchmoney/pull/154))\n- **\u2705 Flexible Budgets Support**: Full flexible budget API implementation\n- `set_budget_amount()` - Update budget amounts with flexible period support\n- `get_budgets()` - Retrieve budgets with flexible expense tracking\n- Support for `BudgetFlexMonthlyAmounts` and flexible budget variability\n- Complete budget management with rollover and planning features\n\n### \ud83c\udfaf **Financial Goals & Planning**\n- `create_goal()` - Create financial goals with target amounts and dates\n- `update_goal()` - Modify existing goals and track progress \n- `delete_goal()` - Remove completed or unwanted goals\n- `get_goals()` - Retrieve all goals with progress tracking\n\n### \ud83d\udcb0 **Cash Flow Analysis**\n- `get_cashflow()` - Detailed income/expense analysis with category breakdowns\n- `get_cashflow_summary()` - Key financial metrics and trends\n- `get_bills()` - Upcoming bills and payment tracking\n- Advanced financial planning and forecasting capabilities\n\n# Installation\n\n## From Source Code\n\nClone this repository from Git\n\n`git clone https://github.com/keithah/monarchmoney-enhanced.git`\n\n## Via `pip`\n\n`pip install monarchmoney-enhanced`\n\n**Note**: This package is published as `monarchmoney-enhanced` on PyPI to distinguish it from the original `monarchmoney` package while maintaining the same Python import structure.\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\n**Note**: The library automatically detects whether your MFA code is an email OTP (6 digits) or TOTP from an authenticator app, and uses the appropriate authentication field.\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\nThis enhanced library provides **comprehensive financial data access**:\n\n## \ud83d\udcbc **Investment & Holdings Management**\n\n- `get_account_holdings(account_id)` - Get all securities in investment accounts\n- `create_manual_holding(account_id, symbol, quantity)` - **Add holdings by ticker** \n- `create_manual_holding_by_ticker(account_id, ticker, quantity)` - Add holdings with ticker lookup\n- `update_holding_quantity(holding_id, quantity)` - Modify existing holdings\n- `delete_manual_holding(holding_id)` - Remove holdings\n- `get_holding_by_ticker(ticker)` - Lookup holdings by ticker symbol\n\n## \ud83d\udcca **Budget & Financial Planning**\n\n- `get_budgets()` - **Get budgets with flexible budget support**\n- `set_budget_amount(category_id, amount)` - **Update budget amounts with flexible periods**\n- `get_goals()` - Get financial goals with progress tracking\n- `create_goal(name, target_amount)` - Create new financial goals\n- `update_goal(goal_id, **kwargs)` - Update existing goals\n- `delete_goal(goal_id)` - Remove financial goals\n- `get_cashflow()` - Income/expense analysis with category breakdowns\n- `get_cashflow_summary()` - Key financial metrics and trends\n- `get_bills()` - Upcoming bills and payment tracking\n\n## \ud83c\udfe6 **Account & Transaction Data**\n\n- `get_accounts()` - **Get all linked accounts (with GraphQL fixes)**\n- `get_me()` - Current user profile (timezone, email, name, MFA status)\n- `get_merchants()` - Merchant list from transactions\n- `get_account_type_options()` - All available account types and subtypes\n- `get_account_history()` - Daily account balance history\n- `get_institutions()` - Linked financial institutions\n- `get_subscription_details()` - Account status (paid/trial)\n- `get_recurring_transactions()` - Future recurring transactions\n- `get_transactions()` - Transaction data with flexible date ranges\n- `get_transactions_summary()` - Transaction summary from transactions page\n- `get_transactions_summary_card()` - Summary card data with totals\n- `get_transaction_categories()` - All configured transaction categories\n- `get_transaction_category_groups()` - All category groups\n- `get_transaction_details(transaction_id)` - Detailed transaction data\n- `get_transaction_splits(transaction_id)` - Transaction split information\n- `get_transaction_tags()` - All configured transaction tags\n- `get_recurring_transactions()` - **Recurring transaction streams and patterns**\n- `mark_stream_as_not_recurring(stream_id)` - **Mark merchants as not recurring**\n- `get_net_worth_history()` - Net worth tracking over time\n- `is_accounts_refresh_complete()` - Account refresh status\n\n## \ud83d\udd04 **Data Modification Methods**\n\n### \ud83d\udcbc **Investment Management**\n- `create_manual_holding(account_id, symbol, quantity)` - **Create holdings by ticker**\n- `update_holding_quantity(holding_id, quantity)` - Update holding quantities\n- `delete_manual_holding(holding_id)` - Remove holdings from accounts\n\n### \ud83d\udcca **Budget & Goals Management** \n- `set_budget_amount(category_id, amount)` - **Set flexible budget amounts**\n- `create_goal(name, target_amount)` - Create new financial goals\n- `update_goal(goal_id, **kwargs)` - Update existing goals \n- `delete_goal(goal_id)` - Remove financial goals\n\n### \ud83c\udfe6 **Account Management**\n- `create_manual_account(name, type, balance)` - Create new manual accounts\n- `update_account(account_id, **kwargs)` - Update account settings/balance\n- `delete_account(account_id)` - Delete accounts\n- `upload_account_balance_history(account_id, csv_file)` - Upload balance history\n- `request_accounts_refresh()` - **Non-blocking** account sync refresh\n- `request_accounts_refresh_and_wait()` - **Blocking** account sync refresh\n\n### \ud83d\udcb3 **Transaction Management**\n- `create_transaction(account_id, amount, date, **kwargs)` - Create transactions\n- `update_transaction(transaction_id, **kwargs)` - Update transaction attributes\n- `delete_transaction(transaction_id)` - Delete transactions\n- `update_transaction_splits(transaction_id, splits)` - Modify transaction splits\n- `create_transaction_category(name, **kwargs)` - Create transaction categories\n- `update_transaction_category(category_id, **kwargs)` - Update categories\n- `delete_transaction_category(category_id)` - Delete single category\n- `delete_transaction_categories(category_ids)` - Delete multiple categories\n- `create_transaction_tag(name)` - Create transaction tags\n- `set_transaction_tags(transaction_id, tag_ids)` - Set tags on transactions\n\n### \ud83d\udd04 **Recurring Transaction Management**\n- `mark_stream_as_not_recurring(stream_id)` - **Mark merchants as not recurring**\n- `get_edit_merchant(merchant_id)` - **Get merchant edit info with recurring details**\n- `get_recurring_transactions()` - Get upcoming recurring transactions\n- `review_recurring_stream(stream_id, status)` - Review and approve recurring streams\n\n## Session Management Methods\n\n- `validate_session` - validates current session by making a lightweight API call\n- `is_session_stale` - checks if session needs validation based on elapsed time \n- `ensure_valid_session` - ensures session is valid, validating if stale\n- `get_session_info` - gets session metadata (creation time, last validation, staleness)\n\n## Transaction Rules\n\nComplete transaction rules management:\n- `get_transaction_rules` - Get all configured rules with criteria and actions\n- `create_transaction_rule` - Create rules with merchant/amount/category/account criteria\n- `update_transaction_rule` - Update existing rule criteria and actions\n- `delete_transaction_rule` - Delete individual rules\n- `reorder_transaction_rules` - Change rule execution order\n- `preview_transaction_rule` - Preview rule effects before creating\n- `delete_all_transaction_rules` - Delete all rules at once\n- `create_categorization_rule` - Helper for simple merchant\u2192category rules\n\nFor a complete mapping of GraphQL operations and implementation status, see [GRAPHQL.md](GRAPHQL.md).\n\n# Development & Testing\n\n## Running Tests\n\nThis project includes a comprehensive test suite. To run tests:\n\n```bash\n# Install test dependencies\npip install pytest pytest-asyncio pytest-cov\n\n# Run all tests\npytest\n\n# Run with coverage\npytest --cov=monarchmoney --cov-report=term-missing\n\n# Run specific test categories\npytest -m \"api\" # API method tests\npytest -m \"auth\" # Authentication tests\npytest -m \"unit\" # Unit tests\n```\n\n## Test Categories\n\n- **Authentication Tests**: Login, MFA, session management, header validation\n- **API Method Tests**: Account/transaction retrieval, GraphQL execution, error handling\n- **Integration Tests**: End-to-end functionality and field detection\n- **Retry Logic Tests**: Rate limiting, exponential backoff, error handling\n\n## CI/CD\n\nThis project uses GitHub Actions for continuous integration:\n\n- **Multi-Python Testing**: Supports Python 3.8 through 3.12\n- **Code Quality**: Automated linting with flake8, formatting with black, import sorting with isort\n- **Coverage Reporting**: Integrated with Codecov for test coverage tracking\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. 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: `pytest`\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# Troubleshooting\n\n## Authentication Issues\n\nIf you're experiencing login problems, this fork includes several fixes:\n\n**404 Login Errors**: The library automatically falls back to GraphQL authentication if REST endpoints return 404.\n\n**403 Forbidden Errors**: Ensure you're using the latest version which includes proper browser headers (device-uuid, Origin, User-Agent).\n\n**MFA Problems**: The library automatically detects email OTP vs authenticator app codes:\n- 6-digit numeric codes are treated as email OTP\n- Other formats are treated as TOTP from authenticator apps\n\n**Rate Limiting**: Built-in retry logic with exponential backoff handles temporary rate limits automatically.\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\n**What makes this fork superior?**\n\nThis enhanced fork is **ahead of the original repository** with implemented features that others are still requesting:\n\n\ud83c\udfaf **Requested Features Already Implemented:**\n- **[Issue #112](https://github.com/hammem/monarchmoney/issues/112)**: \u2705 Add Holdings API - Full investment management\n- **[PR #154](https://github.com/hammem/monarchmoney/pull/154)**: \u2705 Flexible Budgets - Complete budget flexibility support\n\n\ud83d\udd27 **Critical Issue Fixes:**\n- **GraphQL Server Errors**: Fixed \"Something went wrong processing\" errors\n- **404 Authentication**: Automatic GraphQL fallback for auth endpoints \n- **403 Forbidden**: Proper browser headers (device-uuid, Origin, User-Agent)\n- **MFA Detection**: Smart email OTP vs TOTP field detection\n- **Session Recovery**: Automatic session validation and recovery\n\n\ud83d\ude80 **Advanced Features:**\n- **Financial Goals Management**: Complete CRUD operations for goal tracking\n- **Cash Flow Analysis**: Detailed income/expense breakdowns and trends\n- **Bills Management**: Payment tracking and due date monitoring \n- **Error Recovery**: Exponential backoff retry logic for robustness\n- **Test Coverage**: 58 passing tests with full CI/CD pipeline\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Enhanced Monarch Money API with bulk transaction operations, GraphQL optimizations, intelligent caching, query variants, and service-oriented architecture",
"version": "0.9.3",
"project_urls": {
"Homepage": "https://github.com/keithah/monarchmoney-enhanced",
"Repository": "https://github.com/keithah/monarchmoney-enhanced"
},
"split_keywords": [
"monarch money",
" financial",
" money",
" personal finance"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "25c808f314e1bd2d18ffd1ffaeacb94d7d6477e8d98f995aff027b861b5613fc",
"md5": "d5b5cf20895f10703581c09ad525c29c",
"sha256": "53dcde1b3a96706d46b276a108ed63b3626db602b5d9406d2adeaffa89c29606"
},
"downloads": -1,
"filename": "monarchmoney_enhanced-0.9.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "d5b5cf20895f10703581c09ad525c29c",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 111028,
"upload_time": "2025-09-14T20:10:04",
"upload_time_iso_8601": "2025-09-14T20:10:04.672115Z",
"url": "https://files.pythonhosted.org/packages/25/c8/08f314e1bd2d18ffd1ffaeacb94d7d6477e8d98f995aff027b861b5613fc/monarchmoney_enhanced-0.9.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "033d6d099cf31e327f406f992723e7db05bae517f6601118c3ed4cb460604f43",
"md5": "950f660bac3e1bb3ebeeb5debe66a244",
"sha256": "0a9616e62719c20af0058623c2a4e18af328f5c123f8725075ebad8b70f2b932"
},
"downloads": -1,
"filename": "monarchmoney_enhanced-0.9.3.tar.gz",
"has_sig": false,
"md5_digest": "950f660bac3e1bb3ebeeb5debe66a244",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 122894,
"upload_time": "2025-09-14T20:10:06",
"upload_time_iso_8601": "2025-09-14T20:10:06.730292Z",
"url": "https://files.pythonhosted.org/packages/03/3d/6d099cf31e327f406f992723e7db05bae517f6601118c3ed4cb460604f43/monarchmoney_enhanced-0.9.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-09-14 20:10:06",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "keithah",
"github_project": "monarchmoney-enhanced",
"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"
]
]
},
{
"name": "cryptography",
"specs": [
[
">=",
"3.4.8"
]
]
}
],
"lcname": "monarchmoney-enhanced"
}
JSON
