monarch-api 0.2.0

Focused unofficial Monarch Money Python client.

monarch-api

Focused unofficial Monarch Money Python client.

The package stays close to recovered REST and GraphQL operations instead of adding a heavy abstraction layer. Public methods are organized by domain and generally map one endpoint or operation to one Python method.

Install

pip install monarch-api

For local development:

pip install -e .[dev]

Example

from monarch_api import MonarchClient
from monarch_api.models import PortfolioRequest, TransactionFilter

with MonarchClient() as client:
    client.auth.login(
        username="[e-mail]",
        password="secret",
        totp="123456",
    )

    me = client.auth.get_me()
    accounts = client.accounts.page()
    transactions = client.transactions.list(
        limit=10,
        filters=TransactionFilter(transaction_visibility="non_hidden_transactions_only"),
    )
    transaction = client.transactions.get(transactions.results[0].id)
    portfolio = client.investments.portfolio(
        PortfolioRequest(start_date="2026-03-01", end_date="2026-04-01")
    )

Notes

• Sync-only client.
• Object-like inputs and outputs use explicit typed models instead of vague JSON payloads.
• Prefers direct endpoint mapping over higher-level helper abstractions.
• Implemented surface is limited to operations backed by captured requests or recovered documents.

Implemented Surface

auth

• login(username, password, totp=None, trusted_device=True, supports_mfa=True, supports_email_otp=True, supports_recaptcha=True)
• use_token(token, device_uuid=None)
• get_me()
• save_session(path)
• load_session(path)

REST coverage:

• POST /auth/login/
• GET /users/me/

household

• get()
• members()
• preferences()

accounts

• has_accounts()
• active_institution_notices()
• aggregate_snapshots(filters=None)
• syncing_status()
• latest_force_refresh_operation()
• force_refresh_operation(operation_id)
• force_refresh_account_status(account_id)
• display_balance_at_date(date, filters=None)
• snapshots_by_account_type(request, filters=None)
• page(filters=None)
• recent_balances(start_date=None)
• filtered(filters=None)
• filters()
• account_types()
• institution_settings()
• force_refresh_account(request)
• force_refresh_all(request=None)
• institutions(ids=None, include_logo=None)
• institution(institution_id)

subscription

• details()
• subscription()
• modal(promo_code=None, stripe_price_id="")
• premium_upgrade_plans(request)
• trial_status()
• entitlements()
• feature_entitlement_params()
• plus_tier_access()
• gifted_subscriptions()
• referral_settings(request)

settings

• user_profile_flags()
• dashboard_config()
• oldest_deletable_synced_snapshot_date()
• oldest_deletable_transaction_date(include_synced=False, include_uploaded=False, include_manual=False)
• sidebar_data(promo_code=None)
• household_member_settings()
• security_settings()
• notification_preferences()
• review_summary_by_user()
• business_entities_banner_profile()
• business_entities()
• has_activity()

planning

• budget_data(start_date, end_date)
• joint_planning_data(start_date, end_date)

goals

• savings_goals()
• savings_goals_with_this_month_balances()
• savings_goal_account(account_id)
• dashboard_card()
• legacy_migration()

recurring

• streams(include_liabilities=None)
• aggregated_items(request)
• dashboard_upcoming_items(request)
• paused_banner()

investments

• accounts()
• dashboard_card()
• portfolio(request=None)
• securities_historical_performance(request)

transactions

• list(offset=None, limit=25, filters=None, order_by="date")
• get(transaction_id, redirect_posted=True)
• filters(search=None, include_ids=None)
• filters_metadata(filters)
• create(request)
• update(request)
• delete(transaction_id)
• set_tags(transaction_id, tag_ids)
• tags(search=None, limit=None, bulk_params=None, include_transaction_count=False)
• categories(include_system_disabled_categories=None)

merchants

• search(search=None, limit=20, include_ids=None)
• household(offset=0, limit=50, order_by="TRANSACTION_COUNT", search=None)
• recommended_for_transaction(transaction_id)
• update(request)

attachments

• get_upload_info(transaction_id)
• add(request)
• get(attachment_id)
• delete(attachment_id)

rules

• list()
• create(request)
• update(request)
• delete(rule_id)
• preview(request, offset=None)
• update_order(rule_id, order)
• delete_all()

reports

• cash_flow_dashboard(filters=None)
• cash_flow_entity_aggregates(filters=None)
• cash_flow_timeframe_aggregates(filters=None)
• data(request)

retail_sync

• get_settings()
• get(sync_id)
• list(filters, offset=0, limit=50, include_total_count=True)
• create(request)
• create_bulk(request)
• start(sync_id)
• complete(sync_id)
• delete(sync_id)
• match_transaction(retail_transaction_id, transaction_id)
• unmatch_transaction(retail_transaction_id)
• update_order(request)
• update_vendor_settings(request)

Layout

• src/monarch_api/: client code
• tests/: mocked verification for request shapes and client behavior