monarch-api 0.1.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

After publishing to PyPI:

pip install monarch-api

For local development:

pip install -e .[dev]

The installable CLI now lives in a separate sibling package/repo: monarch_api_cli.

Scope

Implemented domains:

• auth: POST /auth/login/, token-backed sessions, /users/me/
• household: household reads, members, preferences
• accounts: page/filter reads, balances/snapshots, institution metadata/settings, refresh status/control
• transactions: list, filter metadata, detail, create, update, delete
• merchants: search, household merchants, recommendations, update
• attachments: upload info, add, get, delete
• retail_sync: settings, detail/list, create/start/complete/delete, match/unmatch, order/vendor updates
• rules: list, preview, create, update, delete, ordering, delete-all
• reports: cash-flow dashboard/aggregates and general report data
• investments: accounts, dashboard card, portfolio, security history
• planning: budget and joint-planning reads
• goals: savings goals, balances, goal-linked accounts, dashboard card, legacy migration
• recurring: streams, aggregates, upcoming items, paused-banner state
• subscription: billing, invoices, plans, trial state, entitlements, referrals
• settings: profile flags, dashboard/sidebar config, security, notifications, business entities, activity, deletion-date reads

Notes:

• The client is sync-only.
• Methods keep raw GraphQL-shaped inputs where that was the cleanest endpoint mapping.
• The implemented surface is intentionally limited to operations backed by captured requests or recovered documents.

Example

from monarch_api import MonarchClient

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

transactions = client.transactions.list(limit=10)
detail = client.transactions.get(transactions["results"][0]["id"])
accounts = client.accounts.page()
institution_settings = client.accounts.institution_settings()
institution_notices = client.accounts.active_institution_notices()
institution_detail = client.accounts.institution("75115054048600997")
account_filters = client.accounts.filters()
account_types = client.accounts.account_types()
latest_refresh = client.accounts.latest_force_refresh_operation()
snapshots = client.accounts.aggregate_snapshots(
    filters={"startDate": "2026-03-13", "useAdaptiveGranularity": True}
)
subscription = client.subscription.subscription()
referral_settings = client.subscription.referral_settings(
    statistics_start_date="2026-01-01T00:00:00.000-06:00",
    statistics_end_date="2026-12-31T23:59:59.999-06:00",
    v1_payout_method="v1_subscription_credit",
    v2_payout_method="v2_gift_card",
)
security = client.settings.security_settings()
business_entities = client.settings.business_entities()
budget = client.planning.budget_data(start_date="2026-04-01", end_date="2026-04-30")
goals = client.goals.savings_goals()
upcoming_recurring = client.recurring.dashboard_upcoming_items(
    start_date="2026-04-13",
    end_date="2026-04-30",
    include_liabilities=True,
    filters={"isCompleted": False},
)
investment_accounts = client.investments.accounts()
portfolio = client.investments.portfolio(
    portfolio_input={"startDate": "2026-03-13", "endDate": "2026-04-13"}
)
preferences = client.household.preferences()
rules = client.rules.list()
rule_preview = client.rules.preview(
    {
        "merchantNameCriteria": {
            "operator": "contains",
            "value": "Aldi",
        }
    }
)
report = client.reports.data(
    filters={"categoryType": "expense"},
    group_by=["category"],
    include_category=True,
)
unmatched_retail_syncs = client.retail_sync.list(
    filters={"status": "pending_matches"},
    limit=3,
)

Layout

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