monarch-api 0.2.1

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 (
    CreateTransactionRequest,
    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")
    )
    created = client.transactions.create(
        CreateTransactionRequest(
            account_id=accounts.account_type_summaries[0].accounts[0].id,
            amount=24.51,
            category_id="category-id",
            date="2026-04-18",
            merchant_name="Coffee Shop",
        )
    )

Returned values are typed objects, so you access fields with attributes such as transactions.results[0].id, transaction.merchant.name, or portfolio.performance.total_value.

Typed Models

Object-like request and response payloads use explicit models under monarch_api.models. The goal is to keep the client close to recovered Monarch operations while removing ambiguity around payload shape.

Common request models:

• TransactionFilter
• CreateTransactionRequest
• UpdateTransactionRequest
• PortfolioRequest
• ReportsDataRequest
• CreateTransactionRuleRequest
• UpdateTransactionRuleRequest
• RetailSyncFilter
• CreateRetailSyncRequest
• UpdateRetailOrderRequest

Common response models:

• TransactionListResult
• TransactionDetail
• AccountsPage
• Portfolio
• BudgetDataResult
• TransactionRule
• RetailSync
• AttachmentUploadInfo

The models package also exposes shared leaf objects like AccountRef, MerchantRef, UserRef, CategoryRef, TagRef, and PayloadError.

More Examples

Create or update a transaction:

from monarch_api.models import CreateTransactionRequest, UpdateTransactionRequest

created = client.transactions.create(
    CreateTransactionRequest(
        account_id="account-id",
        amount=12.34,
        category_id="category-id",
        date="2026-04-18",
        merchant_name="Lunch",
        notes="typed request",
    )
)

updated = client.transactions.update(
    UpdateTransactionRequest(
        id=created.transaction.id,
        name="Lunch with team",
        hide_from_reports=False,
    )
)

Preview a rule before saving it:

from monarch_api.models import CreateTransactionRuleRequest, MerchantCriterion

preview = client.rules.preview(
    CreateTransactionRuleRequest(
        merchant_name_criteria=[MerchantCriterion(operator="contains", value="aldi")],
        set_hide_from_reports_action=True,
    )
)

Work with retail sync models:

from monarch_api.models import CreateRetailSyncRequest, RetailSyncFilter

pending = client.retail_sync.list(
    filters=RetailSyncFilter(status="pending_matches", vendor="amazon"),
    limit=10,
)

created_sync = client.retail_sync.create(
    CreateRetailSyncRequest(vendor="amazon", is_backfill=True)
)

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
• src/monarch_api/models/: typed request and response models
• tests/: mocked verification for request shapes and client behavior