Metadata-Version: 2.4
Name: monarch-api
Version: 0.2.0
Summary: Focused unofficial Monarch Money Python client.
License-Expression: MIT
Keywords: monarch,monarch money,finance,graphql,api client
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Office/Business :: Financial
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: httpx<1,>=0.27
Provides-Extra: dev
Requires-Dist: pytest<9,>=8.0; extra == "dev"
Dynamic: license-file

# 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

```bash
pip install monarch-api
```

For local development:

```bash
pip install -e .[dev]
```

## Example

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

with MonarchClient() as client:
    client.auth.login(
        username="you@example.com",
        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
