### Create Transaction Usage Example

Source: https://github.com/bradleyseanf/monarchmoneycommunity/blob/dev/_autodocs/02-transactions-api.md

Example of creating a new transaction.

```python
result = await mm.create_transaction(
    date="2025-01-15",
    account_id="160820461792094418",
    amount=-25.50,
    merchant_name="Coffee Shop",
    category_id="cat_food",
    notes="Morning coffee"
)
print(f"Created transaction: {result['createTransaction']['transaction']['id']}")
```

--------------------------------

### Usage examples for get_cashflow_summary

Source: https://github.com/bradleyseanf/monarchmoneycommunity/blob/dev/_autodocs/03-budgets-cashflow-api.md

Examples showing how to fetch and display summary statistics like income, expenses, and savings rate.

```python
# Get current month summary
summary = await mm.get_cashflow_summary()
summary_data = summary['summary'][0]['summary']
print(f"Income: ${summary_data['sumIncome']}")
print(f"Expenses: ${summary_data['sumExpense']}")
print(f"Savings: ${summary_data['savings']}")
print(f"Savings Rate: {summary_data['savingsRate']*100:.1f}%")

# Get range summary
summary = await mm.get_cashflow_summary(
    start_date="2025-01-01",
    end_date="2025-12-31"
)
```

--------------------------------

### Upload Attachment Usage Example

Source: https://github.com/bradleyseanf/monarchmoneycommunity/blob/dev/_autodocs/04-attachments-api.md

Example of reading a local file and uploading it as a transaction attachment.

```python
# Read a file and upload
with open("receipt.pdf", "rb") as f:
    result = await mm.upload_attachment(
        transaction_id="160820461792094418",
        file_content=f.read(),
        filename="receipt.pdf"
    )
    print(f"Uploaded: {result['addTransactionAttachment']['attachment']['originalAssetUrl']}")
```

--------------------------------

### Instantiate BalanceHistoryRow

Source: https://github.com/bradleyseanf/monarchmoneycommunity/blob/dev/_autodocs/04-attachments-api.md

Example of creating a new BalanceHistoryRow instance.

```python
from monarchmoney import BalanceHistoryRow
from datetime import datetime

row = BalanceHistoryRow(
    date=datetime(2025, 1, 1),
    amount=5000.00,
    account_name="Savings Account"
)
```

--------------------------------

### Usage examples for get_cashflow

Source: https://github.com/bradleyseanf/monarchmoneycommunity/blob/dev/_autodocs/03-budgets-cashflow-api.md

Examples showing how to fetch cashflow data for current or specific periods and iterate through category or merchant results.

```python
# Get current month cashflow
flow = await mm.get_cashflow()

# Get specific period
flow = await mm.get_cashflow(
    start_date="2025-01-01",
    end_date="2025-01-31"
)

# Process by category
for item in flow['byCategory']:
    cat = item['groupBy']['category']
    amount = item['summary']['sum']
    print(f"{cat['name']}: ${amount}")

# Get merchant-level data
for item in flow['byMerchant']:
    merchant = item['groupBy']['merchant']
    income = item['summary']['sumIncome']
    expense = item['summary']['sumExpense']
    print(f"{merchant['name']}: Income ${income}, Expense ${expense}")
```

--------------------------------

### Update Transaction Usage Examples

Source: https://github.com/bradleyseanf/monarchmoneycommunity/blob/dev/_autodocs/02-transactions-api.md

Examples of updating transaction fields, clearing notes, and marking as reviewed.

```python
# Update category and notes
await mm.update_transaction(
    transaction_id="160820461792094418",
    category_id="cat_dining",
    notes="Updated restaurant"
)

# Clear notes
await mm.update_transaction(
    transaction_id="160820461792094418",
    notes=""
)

# Mark as reviewed
await mm.update_transaction(
    transaction_id="160820461792094418",
    reviewed=True
)
```

--------------------------------

### Create Manual Account Usage

Source: https://github.com/bradleyseanf/monarchmoneycommunity/blob/dev/_autodocs/01-monarchmoney-client.md

Example call to create a new manual account with specific asset details.

```python
result = await mm.create_manual_account(
    account_type="other_asset",
    account_sub_type="valuables",
    is_in_net_worth=True,
    account_name="Art Collection",
    account_balance=50000.0
)
```

--------------------------------

### Update Transaction Splits Usage Examples

Source: https://github.com/bradleyseanf/monarchmoneycommunity/blob/dev/_autodocs/02-transactions-api.md

Examples of splitting a transaction and removing all splits.

```python
# Split a $100 transaction
splits = [
    {"merchantName": "Restaurant", "amount": 70.00, "categoryId": "cat_dining"},
    {"merchantName": "Tip", "amount": 15.00, "categoryId": "cat_tips"},
    {"merchantName": "Drink", "amount": 15.00, "categoryId": "cat_beverages"},
]
result = await mm.update_transaction_splits(
    transaction_id="160820461792094418",
    split_data=splits
)

# Remove all splits
result = await mm.update_transaction_splits(
    transaction_id="160820461792094418",
    split_data=[]
)
```

--------------------------------

### Start Retail Sync

Source: https://github.com/bradleyseanf/monarchmoneycommunity/blob/dev/_autodocs/04-attachments-api.md

Triggers AI processing for a specific retail sync session.

```python
async def _start_retail_sync(self, sync_id: str) -> Dict[str, Any]
```

--------------------------------

### Upload Receipt to Inbox Usage Example

Source: https://github.com/bradleyseanf/monarchmoneycommunity/blob/dev/_autodocs/04-attachments-api.md

Example of uploading a receipt image to the inbox and accessing the resulting sync status.

```python
# Upload receipt image to inbox
with open("store_receipt.jpg", "rb") as f:
    result = await mm.upload_receipt_to_inbox(
        file_content=f.read(),
        filename="store_receipt.jpg"
    )
    sync = result['retailSync']
    print(f"Processing receipt: {sync['id']}")
    print(f"Status: {sync['status']}")
```

--------------------------------

### Handle LoginFailedException

Source: https://github.com/bradleyseanf/monarchmoneycommunity/blob/dev/_autodocs/06-exceptions-errors.md

Example of catching authentication failures during the login process.

```python
from monarchmoney import MonarchMoney, LoginFailedException

mm = MonarchMoney()
try:
    await mm.login(email="user@example.com", password="wrong_password")
except LoginFailedException as e:
    print(f"Login failed: {e}")
```

--------------------------------

### Uploading Account Balance History Example

Source: https://github.com/bradleyseanf/monarchmoneycommunity/blob/dev/_autodocs/04-attachments-api.md

Demonstrates creating a list of BalanceHistoryRow objects and uploading them to a specific account with custom timeout and delay settings.

```python
from monarchmoney import BalanceHistoryRow
from datetime import datetime

# Create balance history
history = [
    BalanceHistoryRow(
        date=datetime(2025, 1, 1),
        amount=1000.00,
        account_name="My Account"
    ),
    BalanceHistoryRow(
        date=datetime(2025, 1, 15),
        amount=1500.00,
        account_name="My Account"
    ),
    BalanceHistoryRow(
        date=datetime(2025, 2, 1),
        amount=2000.00,
        account_name="My Account"
    ),
]

# Upload and wait for completion
success = await mm.upload_account_balance_history(
    account_id="160820461792094418",
    csv_content=history,
    timeout=600,
    delay=15
)

if success:
    print("Balance history uploaded successfully!")
else:
    print("Upload timed out")
```

--------------------------------

### Delete Account Usage

Source: https://github.com/bradleyseanf/monarchmoneycommunity/blob/dev/_autodocs/01-monarchmoney-client.md

Example call to delete an account and print the resulting status.

```python
result = await mm.delete_account(account_id="160820461792094418")
print(f"Deleted: {result['deleteAccount']['deleted']}")
```

--------------------------------

### Delete Transaction Usage Example

Source: https://github.com/bradleyseanf/monarchmoneycommunity/blob/dev/_autodocs/02-transactions-api.md

Example of deleting a transaction.

```python
success = await mm.delete_transaction(transaction_id="160820461792094418")
print("Transaction deleted!")
```

--------------------------------

### Handle RequireMFAException

Source: https://github.com/bradleyseanf/monarchmoneycommunity/blob/dev/_autodocs/06-exceptions-errors.md

Example of handling MFA requirements via user input or pre-provided TOTP secret.

```python
from monarchmoney import MonarchMoney, RequireMFAException

mm = MonarchMoney()
try:
    await mm.login(email="user@example.com", password="password")
except RequireMFAException:
    mfa_code = input("Enter 2FA code: ")
    await mm.multi_factor_authenticate(
        email="user@example.com",
        password="password",
        code=mfa_code
    )
    mm.save_session()

# Or provide MFA secret upfront
await mm.login(
    email="user@example.com",
    password="password",
    mfa_secret_key="JBSWY3DPEBLW64TMMQ======"
)
```

--------------------------------

### Usage example for get_transactions_summary

Source: https://github.com/bradleyseanf/monarchmoneycommunity/blob/dev/_autodocs/02-transactions-api.md

Accessing aggregate statistics from the returned summary dictionary.

```python
summary = await mm.get_transactions_summary()
print(f"Total transactions: {summary['aggregates']['summary']['count']}")
print(f"Total sum: ${summary['aggregates']['summary']['sum']}")
```

--------------------------------

### GraphQL Fragment Implementation

Source: https://github.com/bradleyseanf/monarchmoneycommunity/blob/dev/_autodocs/08-graphql-core.md

Example of using GraphQL fragments to reduce query duplication in account retrieval.

```graphql
fragment AccountFields on Account {
    id
    displayName
    currentBalance
    type { name display }
    subtype { name display }
    institution { id name }
    # ... more fields
}

query GetAccounts {
    accounts {
        ...AccountFields
        __typename
    }
}
```

--------------------------------

### Retrieve start of current month as ISO string

Source: https://github.com/bradleyseanf/monarchmoneycommunity/blob/dev/_autodocs/08-graphql-core.md

Generates an ISO 8601 formatted string for the first day of the current month.

```python
def _get_start_of_current_month(self) -> str
```

```python
date_str = mm._get_start_of_current_month()  # "2025-01-01"
```

--------------------------------

### Update Account Usage

Source: https://github.com/bradleyseanf/monarchmoneycommunity/blob/dev/_autodocs/01-monarchmoney-client.md

Example call to update the name and balance of an existing account by ID.

```python
result = await mm.update_account(
    account_id="160820461792094418",
    account_name="Updated Account Name",
    account_balance=5000.0
)
```

--------------------------------

### Initiate Upload Balance History Session

Source: https://github.com/bradleyseanf/monarchmoneycommunity/blob/dev/_autodocs/04-attachments-api.md

Starts the parsing process for an uploaded balance history CSV.

```python
async def _initiate_upload_balance_history_session(
    self,
    session_key: str
) -> dict
```

--------------------------------

### Usage examples for get_transactions

Source: https://github.com/bradleyseanf/monarchmoneycommunity/blob/dev/_autodocs/02-transactions-api.md

Various ways to filter transaction queries using limits, date ranges, status flags, and identifiers.

```python
# Get last 50 transactions
result = await mm.get_transactions(limit=50)

# Get transactions from specific date range
result = await mm.get_transactions(
    start_date="2025-01-01",
    end_date="2025-01-31",
    limit=100
)

# Get transactions needing review with attachments
result = await mm.get_transactions(
    needs_review=True,
    has_attachments=True
)

# Filter by specific categories and accounts
result = await mm.get_transactions(
    category_ids=["cat_123", "cat_456"],
    account_ids=["acc_789"]
)
```

--------------------------------

### Retrieve API endpoints

Source: https://github.com/bradleyseanf/monarchmoneycommunity/blob/dev/_autodocs/07-types-dataclasses.md

Usage examples for fetching specific API URLs from the MonarchMoneyEndpoints class.

```python
endpoint = MonarchMoneyEndpoints.getGraphQL()
# Returns: "https://api.monarch.com/graphql"

login_url = MonarchMoneyEndpoints.getLoginEndpoint()
# Returns: "https://api.monarch.com/auth/login/"
```

--------------------------------

### Usage example for get_transaction_details

Source: https://github.com/bradleyseanf/monarchmoneycommunity/blob/dev/_autodocs/02-transactions-api.md

Retrieving and accessing specific fields from a single transaction record.

```python
txn = await mm.get_transaction_details(transaction_id="160820461792094418")
print(f"Amount: ${txn['getTransaction']['amount']}")
print(f"Merchant: {txn['getTransaction']['merchant']['name']}")
```

--------------------------------

### Retrieve account snapshots by type

Source: https://github.com/bradleyseanf/monarchmoneycommunity/blob/dev/_autodocs/01-monarchmoney-client.md

Gets net value snapshots grouped by account type with monthly or yearly granularity.

```python
snapshots = await mm.get_account_snapshots_by_type(
    start_date="2024-01-01",
    timeframe="month"
)
```

--------------------------------

### Handle RequestFailedException

Source: https://github.com/bradleyseanf/monarchmoneycommunity/blob/dev/_autodocs/06-exceptions-errors.md

Example of catching errors during account refreshes or transaction mutations.

```python
from monarchmoney import MonarchMoney, RequestFailedException

mm = MonarchMoney()
await mm.login(email="user@example.com", password="password")

try:
    success = await mm.request_accounts_refresh(account_ids=["invalid_id"])
except RequestFailedException as e:
    print(f"Request failed: {e}")

try:
    await mm.delete_transaction(transaction_id="invalid_id")
except RequestFailedException as e:
    print(f"Deletion failed: {e}")
```

--------------------------------

### Example JSON output for holdings

Source: https://github.com/bradleyseanf/monarchmoneycommunity/blob/dev/_autodocs/07-types-dataclasses.md

Represents the JSON structure returned by the to_json method of MonarchHoldings.

```json
{
  "AAPL": {
    "quantity": 10.5,
    "totalValue": 2500.00,
    "type": "Stock",
    "percentage": 45.3,
    "name": "Apple Inc.",
    "sharePrice": 238.10,
    "sharePriceUpdate": "2025-01-10T16:00:00Z"
  },
  "BND": {
    "quantity": 5.0,
    "totalValue": 525.00,
    "type": "ETF",
    "percentage": 9.5,
    "name": "Vanguard Total Bond Market ETF",
    "sharePrice": 105.00,
    "sharePriceUpdate": "2025-01-10T16:00:00Z"
  }
}
```

--------------------------------

### Define common return type patterns

Source: https://github.com/bradleyseanf/monarchmoneycommunity/blob/dev/_autodocs/07-types-dataclasses.md

Examples of type annotations for dictionaries, lists, optional values, and union types in method signatures.

```python
def get_accounts(self) -> Dict[str, Any]
```

```python
def get_transactions(self, limit: int = 100) -> Dict[str, Any]
```

```python
def login_with_cookies(self, cookie_string: str) -> None
```

```python
def get_account_holdings(
    self,
    account: Union[MonarchAccount, str, int]
) -> Optional[MonarchHoldings]
```

```python
def get_transactions(
    self,
    transaction_visibility: Optional[
        Literal["hidden_transactions_only", "all_transactions"]
    ] = None
) -> Dict[str, Any]
```

--------------------------------

### Handle CaptchaRequiredException

Source: https://github.com/bradleyseanf/monarchmoneycommunity/blob/dev/_autodocs/06-exceptions-errors.md

Example of falling back to cookie-based authentication when a CAPTCHA is encountered.

```python
from monarchmoney import MonarchMoney, CaptchaRequiredException

mm = MonarchMoney()
try:
    await mm.login(email="user@example.com", password="password")
except CaptchaRequiredException:
    # Fall back to cookie-based authentication
    cookie_string = "session_id=...; csrftoken=..."
    await mm.login_with_cookies(cookie_string)
```

--------------------------------

### Update Flexible Budget Rollover Settings

Source: https://github.com/bradleyseanf/monarchmoneycommunity/blob/dev/_autodocs/03-budgets-cashflow-api.md

Configures rollover parameters including start dates, balances, and feature toggles. Requires an active Monarch Money client instance.

```python
async def update_flex_rollover_settings(
    self,
    rollover_start_month: Optional[str] = None,
    rollover_starting_balance: float = 0.0,
    rollover_enabled: bool = True,
    budget_system: str = "fixed_and_flex",
) -> Dict[str, Any]
```

```python
# Reset flex bucket to $0 starting this month
await mm.update_flex_rollover_settings()

# Reset with custom balance
await mm.update_flex_rollover_settings(
    rollover_start_month="2025-03-01",
    rollover_starting_balance=100.00
)

# Disable rollover
await mm.update_flex_rollover_settings(
    rollover_enabled=False
)
```

--------------------------------

### Retrieve recent account balances

Source: https://github.com/bradleyseanf/monarchmoneycommunity/blob/dev/_autodocs/01-monarchmoney-client.md

Fetches daily balances for all accounts, optionally filtered by a start date.

```python
balances = await mm.get_recent_account_balances(start_date="2025-01-01")
```

--------------------------------

### Initialize MonarchMoney Client

Source: https://github.com/bradleyseanf/monarchmoneycommunity/blob/dev/_autodocs/01-monarchmoney-client.md

Shows how to instantiate the client with default settings, custom configurations, or an existing token.

```python
from monarchmoney import MonarchMoney

# Create a client
mm = MonarchMoney()

# Or with custom timeout and session file
mm = MonarchMoney(session_file="/custom/path.pickle", timeout=30)

# Or with existing token
mm = MonarchMoney(token="your_long_lived_token")
```

--------------------------------

### Using TypedMonarchMoney for Typed Responses

Source: https://github.com/bradleyseanf/monarchmoneycommunity/blob/dev/_autodocs/05-typed-client.md

Demonstrates initializing the typed client and the difference between typed query methods and raw dictionary return types from inherited methods.

```python
from typedmonarchmoney import TypedMonarchMoney

mm = TypedMonarchMoney()
await mm.login(email="user@example.com", password="password")

# Typed return value
accounts: List[MonarchAccount] = await mm.get_accounts()

# Raw dictionary return (inherited method)
result = await mm.get_transactions(limit=50)  # Returns Dict[str, Any]

# Create transaction (still returns dict)
created = await mm.create_transaction(
    date="2025-01-15",
    account_id=accounts[0].id,
    amount=-50.00,
    merchant_name="Store",
    category_id="cat_123"
)
```

--------------------------------

### Usage of TypedMonarchMoney Client

Source: https://github.com/bradleyseanf/monarchmoneycommunity/blob/dev/_autodocs/05-typed-client.md

Demonstrates initializing the client, logging in, and accessing typed account objects.

```python
from typedmonarchmoney import TypedMonarchMoney

# Create typed client
mm = TypedMonarchMoney()
await mm.login(email="user@example.com", password="password")

# Accounts are returned as MonarchAccount objects, not dicts
accounts = await mm.get_accounts()
for account in accounts:
    print(f"{account.name}: ${account.balance}")
```

--------------------------------

### MonarchMoney.__init__

Source: https://github.com/bradleyseanf/monarchmoneycommunity/blob/dev/_autodocs/01-monarchmoney-client.md

Initializes the MonarchMoney client instance with session management and timeout configurations.

```APIDOC
## MonarchMoney.__init__

### Description
Initializes a new instance of the MonarchMoney client to handle authentication and API communication.

### Constructor Signature
`MonarchMoney(session_file: str = '.mm/mm_session.pickle', timeout: int = 10, token: Optional[str] = None)`

### Parameters
- **session_file** (str) - Optional - Path to the pickle file used for persisting authentication credentials. Defaults to '.mm/mm_session.pickle'.
- **timeout** (int) - Optional - Timeout in seconds for GraphQL API requests. Defaults to 10.
- **token** (str) - Optional - A long-lived session token for authentication.

### Example
```python
from monarchmoney import MonarchMoney

# Initialize with defaults
mm = MonarchMoney()

# Initialize with custom configuration
mm = MonarchMoney(session_file="/custom/path.pickle", timeout=30, token="your_token")
```
```

--------------------------------

### get_account_history

Source: https://github.com/bradleyseanf/monarchmoneycommunity/blob/dev/_autodocs/01-monarchmoney-client.md

Gets historical balance snapshots for an account.

```APIDOC
## get_account_history

### Description
Gets historical balance snapshots for an account.

### Method
async def get_account_history(self, account_id: int) -> Dict[str, Any]

### Parameters
- **account_id** (int) - Required - Account ID as integer

### Returns
List of balance history entries with date, signedBalance, accountId, and accountName.
```

--------------------------------

### Create Retail Sync Session

Source: https://github.com/bradleyseanf/monarchmoneycommunity/blob/dev/_autodocs/04-attachments-api.md

Initializes a bulk retail sync session for receipt uploads.

```python
async def _create_retail_sync_session(self) -> Dict[str, Any]
```

--------------------------------

### Get transaction categories

Source: https://github.com/bradleyseanf/monarchmoneycommunity/blob/dev/_autodocs/02-transactions-api.md

Retrieves all categories configured in the account.

```python
async def get_transaction_categories(self) -> Dict[str, Any]
```

```python
result = await mm.get_transaction_categories()
for cat in result['categories']:
    print(f"{cat['name']} (ID: {cat['id']})")
```

--------------------------------

### Importing TypedMonarchMoney Classes

Source: https://github.com/bradleyseanf/monarchmoneycommunity/blob/dev/_autodocs/00-public-api.md

Import the main client class and data models from the package root.

```python
from typedmonarchmoney import (
    TypedMonarchMoney,
    MonarchAccount,
    MonarchCashflowSummary,
    MonarchHolding,
    MonarchHoldings,
    MonarchSubscription,
    MonarchMoneyTyped,  # Alias for TypedMonarchMoney
)
```

--------------------------------

### Handle Authentication Flow Exceptions

Source: https://github.com/bradleyseanf/monarchmoneycommunity/blob/dev/_autodocs/06-exceptions-errors.md

Demonstrates managing session loading, MFA requirements, and CAPTCHA challenges during the login process.

```python
from monarchmoney import (
    MonarchMoney,
    LoginFailedException,
    RequireMFAException,
    CaptchaRequiredException,
)

mm = MonarchMoney()

try:
    # Try to use saved session first
    mm.load_session()
except LoginFailedException:
    # No saved session, need to login
    try:
        await mm.login(
            email="user@example.com",
            password="password",
            save_session=True
        )
    except RequireMFAException:
        # MFA required
        mfa_code = input("Enter 2FA code: ")
        await mm.multi_factor_authenticate(
            email="user@example.com",
            password="password",
            code=mfa_code
        )
        mm.save_session()
    except CaptchaRequiredException:
        # CAPTCHA required - fall back to cookies
        cookie_string = input("Paste Cookie header from browser: ")
        await mm.login_with_cookies(cookie_string, save_session=True)
    except LoginFailedException as e:
        print(f"Login failed: {e}")
        exit(1)

# Now authenticated
accounts = await mm.get_accounts()
```

--------------------------------

### create_manual_account

Source: https://github.com/bradleyseanf/monarchmoneycommunity/blob/dev/README.md

Creates a new manual account.

```APIDOC
## create_manual_account

### Description
Creates a new manual account.
```

--------------------------------

### Get transaction category groups

Source: https://github.com/bradleyseanf/monarchmoneycommunity/blob/dev/_autodocs/02-transactions-api.md

Retrieves all category groups configured in the account.

```python
async def get_transaction_category_groups(self) -> Dict[str, Any]
```

```python
result = await mm.get_transaction_category_groups()
for group in result['categoryGroups']:
    print(f"{group['name']} (Type: {group['type']})")
```

--------------------------------

### Authenticate with email and password

Source: https://github.com/bradleyseanf/monarchmoneycommunity/blob/dev/_autodocs/01-monarchmoney-client.md

Demonstrates standard login, MFA-enabled login, and session-based authentication.

```python
mm = MonarchMoney()

# Login with email and password
await mm.login(email="user@example.com", password="secure_password")

# Login with MFA secret key
await mm.login(
    email="user@example.com",
    password="password",
    mfa_secret_key="JBSWY3DPEBLW64TMMQ======"
)

# Use saved session if available, otherwise login
await mm.login(email="user@example.com", password="password", use_saved_session=True)
```

--------------------------------

### Retrieve account history

Source: https://github.com/bradleyseanf/monarchmoneycommunity/blob/dev/_autodocs/01-monarchmoney-client.md

Gets historical balance snapshots for a specific account ID.

```python
history = await mm.get_account_history(account_id=123456789)
for snapshot in history:
    print(f"{snapshot['date']}: ${snapshot['signedBalance']}")
```

--------------------------------

### TypedMonarchMoney.__init__

Source: https://github.com/bradleyseanf/monarchmoneycommunity/blob/dev/_autodocs/05-typed-client.md

Initializes the TypedMonarchMoney client for interacting with the Monarch Money API.

```APIDOC
## TypedMonarchMoney.__init__

### Description
Initializes a new instance of the TypedMonarchMoney client. This constructor accepts parameters for session management and authentication, identical to the base MonarchMoney client.

### Parameters
- **session_file** (str) - Optional - Path to the pickle file for persisting authentication credentials. Defaults to '.mm/mm_session.pickle'.
- **timeout** (int) - Optional - Timeout in seconds for GraphQL API calls. Defaults to 10.
- **token** (Optional[str]) - Optional - An initial long-lived session token for authentication.

### Usage Example
```python
from typedmonarchmoney import TypedMonarchMoney

# Create typed client
mm = TypedMonarchMoney()
await mm.login(email="user@example.com", password="password")

# Accounts are returned as MonarchAccount objects
accounts = await mm.get_accounts()
for account in accounts:
    print(f"{account.name}: ${account.balance}")
```
```

--------------------------------

### Retrieve budget data with get_budgets

Source: https://github.com/bradleyseanf/monarchmoneycommunity/blob/dev/_autodocs/03-budgets-cashflow-api.md

Fetches budget and actual amounts for categories or groups. Requires both start_date and end_date if either is provided.

```python
async def get_budgets(
    self,
    start_date: Optional[str] = None,
    end_date: Optional[str] = None,
    use_legacy_goals: Optional[bool] = False,
    use_v2_goals: Optional[bool] = True,
) -> Dict[str, Any]
```

```python
# Get current month's budgets
budgets = await mm.get_budgets()

# Get specific date range
budgets = await mm.get_budgets(
    start_date="2025-01-01",
    end_date="2025-03-31"
)

# Access monthly data
for cat_data in budgets['budgetData']['monthlyAmountsByCategory']:
    category = cat_data['category']['id']
    for month_data in cat_data['monthlyAmounts']:
        print(f"Category {category} - Month {month_data['month']}")
        print(f"  Planned: ${month_data['plannedCashFlowAmount']}")
        print(f"  Actual: ${month_data['actualAmount']}")
        print(f"  Remaining: ${month_data['remainingAmount']}")
```

--------------------------------

### get_account_snapshots_by_type

Source: https://github.com/bradleyseanf/monarchmoneycommunity/blob/dev/_autodocs/01-monarchmoney-client.md

Gets net value snapshots grouped by account type with monthly or yearly granularity.

```APIDOC
## get_account_snapshots_by_type

### Description
Gets net value snapshots grouped by account type with monthly or yearly granularity.

### Method
async def get_account_snapshots_by_type(self, start_date: str, timeframe: str) -> Dict[str, Any]

### Parameters
- **start_date** (str) - Required - ISO date string (YYYY-MM-DD)
- **timeframe** (str) - Required - "year" or "month"

### Returns
Dictionary with snapshotsByAccountType containing balance snapshots grouped by type and month/year.
```

--------------------------------

### load_session(filename: Optional[str] = None) -> None

Source: https://github.com/bradleyseanf/monarchmoneycommunity/blob/dev/_autodocs/01-monarchmoney-client.md

Loads credentials from a pickle file.

```APIDOC
## load_session

### Description
Loads credentials from a pickle file.

### Parameters
- **filename** (Optional[str]) - Optional - Path to the pickle file. Defaults to a default location if not provided.

### Raises
- LoginFailedException: If file contains no valid credentials.

### Example
```python
mm.load_session()
```
```

--------------------------------

### Retrieve account holdings

Source: https://github.com/bradleyseanf/monarchmoneycommunity/blob/dev/_autodocs/01-monarchmoney-client.md

Gets security holdings for a specific brokerage or investment account ID.

```python
holdings = await mm.get_account_holdings(account_id=123456789)
for holding in holdings['portfolio']['aggregateHoldings']['edges']:
    node = holding['node']
    print(f"{node['security']['ticker']}: {node['quantity']} shares")
```

--------------------------------

### Get Transaction Attachment Upload Info

Source: https://github.com/bradleyseanf/monarchmoneycommunity/blob/dev/_autodocs/04-attachments-api.md

Retrieves Cloudinary upload parameters for a transaction attachment.

```python
async def _get_transaction_attachment_upload_info(
    self,
    transaction_id: str
) -> Dict[str, Any]
```

--------------------------------

### Create Manual Account Definition

Source: https://github.com/bradleyseanf/monarchmoneycommunity/blob/dev/_autodocs/01-monarchmoney-client.md

Signature for the create_manual_account method used to initialize non-synced accounts.

```python
async def create_manual_account(
    self,
    account_type: str,
    account_sub_type: str,
    is_in_net_worth: bool,
    account_name: str,
    account_balance: float = 0,
) -> Dict[str, Any]
```

--------------------------------

### Initialize Typed Monarch Money Client

Source: https://github.com/bradleyseanf/monarchmoneycommunity/blob/dev/README.md

Use the TypedMonarchMoney client to retrieve account data as structured objects rather than raw dictionaries.

```python
from typedmonarchmoney import TypedMonarchMoney

mm = TypedMonarchMoney()
accounts = await mm.get_accounts()
```

--------------------------------

### Initialize TypedMonarchMoney Constructor

Source: https://github.com/bradleyseanf/monarchmoneycommunity/blob/dev/_autodocs/05-typed-client.md

Defines the constructor signature for the TypedMonarchMoney client, which mirrors the base MonarchMoney class.

```python
def __init__(
    self,
    session_file: str = SESSION_FILE,
    timeout: int = 10,
    token: Optional[str] = None,
) -> None
```

--------------------------------

### Retrieve Subscription Details with get_subscription_details

Source: https://github.com/bradleyseanf/monarchmoneycommunity/blob/dev/_autodocs/05-typed-client.md

Returns the current subscription status and entitlement details.

```python
async def get_subscription_details(self) -> MonarchSubscription
```

```python
sub = await mm.get_subscription_details()
print(f"Premium: {sub.has_premium_entitlement}")
print(f"Free Trial: {sub.is_on_free_trial}")
print(f"Referral Code: {sub.referral_code}")
```

--------------------------------

### Import MonarchMoney components

Source: https://github.com/bradleyseanf/monarchmoneycommunity/blob/dev/_autodocs/00-public-api.md

Required imports for accessing the main client, endpoints, and exception handling classes.

```python
from monarchmoney import (
    MonarchMoney,
    MonarchMoneyEndpoints,
    LoginFailedException,
    RequireMFAException,
    CaptchaRequiredException,
    RequestFailedException,
)
```

--------------------------------

### Load Session Credentials

Source: https://github.com/bradleyseanf/monarchmoneycommunity/blob/dev/_autodocs/01-monarchmoney-client.md

Loads credentials from a pickle file. Raises LoginFailedException if the file contains no valid credentials.

```python
mm = MonarchMoney()
mm.load_session()  # Loads from default location
# Now use mm to make API calls
```

--------------------------------

### Import Typed Models

Source: https://github.com/bradleyseanf/monarchmoneycommunity/blob/dev/_autodocs/07-types-dataclasses.md

Standard import paths for MonarchMoney base classes and TypedMonarchMoney models.

```python
from monarchmoney.monarchmoney import (
    DEFAULT_RECORD_LIMIT,
    MonarchMoney,
    SESSION_FILE,
)

from typedmonarchmoney.monarchmoney_typed import (
    MonarchAccount,
    MonarchCashflowSummary,
    MonarchHolding,
    MonarchHoldings,
    MonarchSubscription,
    TypedMonarchMoney,
)
```

--------------------------------

### Manage Session Persistence

Source: https://github.com/bradleyseanf/monarchmoneycommunity/blob/dev/_autodocs/README.md

Save and load sessions using pickle files to maintain authentication across restarts.

```python
# Save session
mm.save_session()

# Load session later
mm.load_session()
await mm.get_accounts()  # Works without login() call
```

--------------------------------

### Perform user login with _login_user

Source: https://github.com/bradleyseanf/monarchmoneycommunity/blob/dev/_autodocs/08-graphql-core.md

Handles the initial authentication request to Monarch Money, including MFA support and token validation.

```python
async def _login_user(
    self,
    email: str,
    password: str,
    mfa_secret_key: Optional[str],
) -> None
```

--------------------------------

### Asynchronous API Method Usage

Source: https://github.com/bradleyseanf/monarchmoneycommunity/blob/dev/_autodocs/00-public-api.md

Demonstrates the requirement to await network-bound methods while noting that configuration and property access methods remain synchronous.

```python
mm = MonarchMoney()
# These MUST be awaited:
await mm.login(...)
await mm.get_accounts()
await mm.create_transaction(...)

# These do NOT need await (sync methods):
mm.save_session()
mm.set_timeout(60)
mm.token  # property access
```

--------------------------------

### multi_factor_authenticate

Source: https://github.com/bradleyseanf/monarchmoneycommunity/blob/dev/_autodocs/01-monarchmoney-client.md

Completes the MFA step after initial login returns RequireMFAException.

```APIDOC
## multi_factor_authenticate(email, password, code, trusted_device)

### Description
Completes the MFA step after initial login returns `RequireMFAException`.

### Parameters
- **email** (str) - Yes - Email address
- **password** (str) - Yes - Password
- **code** (str) - Yes - MFA code from authenticator app
- **trusted_device** (bool) - No - If True, requests long-lived token (browser-style session)
```

--------------------------------

### Retrieve Accounts as Dictionary with get_accounts_as_dict_with_id_key

Source: https://github.com/bradleyseanf/monarchmoneycommunity/blob/dev/_autodocs/05-typed-client.md

Returns accounts mapped by their ID for easier lookup.

```python
async def get_accounts_as_dict_with_id_key(
    self,
    *,
    with_holdings: bool = False,
) -> Dict[str, MonarchAccount]
```

```python
accounts_by_id = await mm.get_accounts_as_dict_with_id_key()
account = accounts_by_id["160820461792094418"]
print(f"{account.name}: ${account.balance}")
```

--------------------------------

### Retrieve account type options

Source: https://github.com/bradleyseanf/monarchmoneycommunity/blob/dev/_autodocs/01-monarchmoney-client.md

Fetches available account types and subtypes.

```python
options = await mm.get_account_type_options()
for opt in options['accountTypeOptions']:
    print(f"{opt['type']['display']}: {opt['subtype']['display']}")
```

--------------------------------

### Set budget amounts with set_budget_amount

Source: https://github.com/bradleyseanf/monarchmoneycommunity/blob/dev/_autodocs/03-budgets-cashflow-api.md

Configures a budget amount for a specific category or group. Requires exactly one of category_id or category_group_id.

```python
async def set_budget_amount(
    self,
    amount: float,
    category_id: Optional[str] = None,
    category_group_id: Optional[str] = None,
    timeframe: str = "month",
    start_date: Optional[str] = None,
    apply_to_future: bool = False,
) -> Dict[str, Any]
```

```python
# Set budget for a category
await mm.set_budget_amount(
    amount=500.00,
    category_id="cat_dining",
    start_date="2025-02-01"
)

# Clear budget (set to 0)
await mm.set_budget_amount(
    amount=0,
    category_id="cat_dining"
)

# Apply to all future months
await mm.set_budget_amount(
    amount=300.00,
    category_group_id="group_entertainment",
    apply_to_future=True
)
```

--------------------------------

### Retrieve Cashflow Summary with get_cashflow_summary

Source: https://github.com/bradleyseanf/monarchmoneycommunity/blob/dev/_autodocs/05-typed-client.md

Fetches a typed summary of income, expenses, and savings for a specified date range.

```python
async def get_cashflow_summary(
    self,
    limit: int = DEFAULT_RECORD_LIMIT,
    start_date: Optional[str] = None,
    end_date: Optional[str] = None,
) -> MonarchCashflowSummary
```

```python
summary = await mm.get_cashflow_summary(
    start_date="2025-01-01",
    end_date="2025-01-31"
)
print(f"Income: ${summary.income}")
print(f"Expenses: ${summary.expenses}")
print(f"Savings: ${summary.savings}")
print(f"Savings Rate: {summary.savings_rate*100:.1f}%")
```

--------------------------------

### Handle MFA during login

Source: https://github.com/bradleyseanf/monarchmoneycommunity/blob/dev/README.md

Catch the RequireMFAException to provide a multi-factor authentication code.

```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)
```

--------------------------------

### create_manual_account

Source: https://github.com/bradleyseanf/monarchmoneycommunity/blob/dev/_autodocs/01-monarchmoney-client.md

Creates a new manual (non-synced) account in the Monarch Money system.

```APIDOC
## create_manual_account

### Description
Creates a new manual (non-synced) account.

### Parameters
- **account_type** (str) - Required - Account group type (e.g., "loan", "other_asset")
- **account_sub_type** (str) - Required - Account subtype (e.g., "auto", "mortgage")
- **is_in_net_worth** (bool) - Required - Whether to include in net worth calculation
- **account_name** (str) - Required - Display name for the account
- **account_balance** (float) - Optional (Default: 0) - Initial balance amount

### Returns
Dictionary with account data and any errors.

### Example
```python
result = await mm.create_manual_account(
    account_type="other_asset",
    account_sub_type="valuables",
    is_in_net_worth=True,
    account_name="Art Collection",
    account_balance=50000.0
)
```
```

--------------------------------

### Import Untyped Client

Source: https://github.com/bradleyseanf/monarchmoneycommunity/blob/dev/_autodocs/README.md

Use the untyped client to receive raw dictionary responses from the API.

```python
from monarchmoney import MonarchMoney, RequireMFAException, LoginFailedException

mm = MonarchMoney()
await mm.login(email="user@example.com", password="password")
accounts = await mm.get_accounts()  # Returns Dict[str, Any]
```

--------------------------------

### Authenticate with Email and Password

Source: https://github.com/bradleyseanf/monarchmoneycommunity/blob/dev/_autodocs/README.md

Performs a standard login. Set save_session to True to persist credentials.

```python
mm = MonarchMoney()
await mm.login(email="user@example.com", password="password", save_session=True)
```

--------------------------------

### Define Authentication and Session Constants

Source: https://github.com/bradleyseanf/monarchmoneycommunity/blob/dev/_autodocs/07-types-dataclasses.md

Constants used for managing authentication headers and local session file paths.

```python
AUTH_HEADER_KEY = "authorization"
CSRF_KEY = "csrftoken"
```

```python
SESSION_DIR = ".mm"
SESSION_FILE = ".mm/mm_session.pickle"
```

--------------------------------

### login

Source: https://github.com/bradleyseanf/monarchmoneycommunity/blob/dev/_autodocs/01-monarchmoney-client.md

Authenticates using email and password. Automatically uses saved session if enabled and a session file exists.

```APIDOC
## login(email, password, use_saved_session, save_session, mfa_secret_key)

### Description
Authenticates using email and password. Automatically uses saved session if `use_saved_session=True` and a session file exists.

### Parameters
- **email** (Optional[str]) - No - Email address for authentication
- **password** (Optional[str]) - No - Password for authentication
- **use_saved_session** (bool) - No - If True, loads saved session from file if available
- **save_session** (bool) - No - If True, saves credentials to session file
- **mfa_secret_key** (Optional[str]) - No - Two-factor secret key for TOTP generation (base32 encoded)

### Exceptions
- `LoginFailedException`
- `RequireMFAException`
- `CaptchaRequiredException`
```

--------------------------------

### Define get_cashflow_summary method

Source: https://github.com/bradleyseanf/monarchmoneycommunity/blob/dev/_autodocs/03-budgets-cashflow-api.md

Method signature for retrieving only the high-level cashflow summary.

```python
async def get_cashflow_summary(
    self,
    limit: int = DEFAULT_RECORD_LIMIT,
    start_date: Optional[str] = None,
    end_date: Optional[str] = None,
) -> Dict[str, Any]
```

--------------------------------

### mm.load_session()

Source: https://github.com/bradleyseanf/monarchmoneycommunity/blob/dev/README.md

Loads a previously saved session from disk.

```APIDOC
## mm.load_session()

### Description
Loads a saved session from disk to restore the authenticated state.

### Usage
```python
mm = MonarchMoney()
mm.load_session()
```
```

--------------------------------

### Login with MFA secret key

Source: https://github.com/bradleyseanf/monarchmoneycommunity/blob/dev/README.md

Provide the MFA secret key directly during the login call to bypass manual MFA prompts.

```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,
    )
```

--------------------------------

### Import Data Classes

Source: https://github.com/bradleyseanf/monarchmoneycommunity/blob/dev/_autodocs/README.md

Import data classes for type hinting and object-oriented data handling.

```python
from monarchmoney import BalanceHistoryRow
from typedmonarchmoney import (
    MonarchAccount,
    MonarchCashflowSummary,
    MonarchHolding,
    MonarchHoldings,
    MonarchSubscription,
)
```

--------------------------------

### Save Session Credentials

Source: https://github.com/bradleyseanf/monarchmoneycommunity/blob/dev/_autodocs/01-monarchmoney-client.md

Persists credentials to a pickle file. Raises LoginFailedException if no credentials are set.

```python
await mm.login(email="user@example.com", password="password")
mm.save_session()  # Saves to default location
mm.save_session("/custom/session.pickle")  # Saves to custom location
```

--------------------------------

### Retrieve all accounts

Source: https://github.com/bradleyseanf/monarchmoneycommunity/blob/dev/_autodocs/01-monarchmoney-client.md

Fetches a list of all linked accounts with their respective details.

```python
result = await mm.get_accounts()
for account in result['accounts']:
    print(f"{account['displayName']}: ${account['currentBalance']}")
```

--------------------------------

### Retrieve current date as ISO string

Source: https://github.com/bradleyseanf/monarchmoneycommunity/blob/dev/_autodocs/08-graphql-core.md

Generates an ISO 8601 formatted string for the current date.

```python
def _get_current_date(self) -> str
```

```python
date_str = mm._get_current_date()  # "2025-01-15"
```

--------------------------------

### Perform Interactive Login

Source: https://github.com/bradleyseanf/monarchmoneycommunity/blob/dev/_autodocs/README.md

Initiates an interactive login flow that prompts for credentials and MFA codes.

```python
mm = MonarchMoney()
await mm.interactive_login()  # Prompts for email, password, optional 2FA code
```

--------------------------------

### save_session(filename: Optional[str] = None) -> None

Source: https://github.com/bradleyseanf/monarchmoneycommunity/blob/dev/_autodocs/01-monarchmoney-client.md

Persists credentials to a pickle file for later reuse.

```APIDOC
## save_session

### Description
Persists credentials to a pickle file for later reuse.

### Parameters
- **filename** (Optional[str]) - Optional - Path to the pickle file. Defaults to a default location if not provided.

### Raises
- LoginFailedException: If no credentials are set.

### Example
```python
mm.save_session("/custom/session.pickle")
```
```

--------------------------------

### Recover from Session Expiration

Source: https://github.com/bradleyseanf/monarchmoneycommunity/blob/dev/_autodocs/06-exceptions-errors.md

Shows how to handle LoginFailedException and RequestFailedException to re-authenticate when a session is no longer valid.

```python
from monarchmoney import MonarchMoney, LoginFailedException, RequestFailedException

mm = MonarchMoney()

# Load saved session
try:
    mm.load_session()
except LoginFailedException:
    print("Session expired, need to re-login")
    await mm.login(email="user@example.com", password="password", save_session=True)

# Try to use API
try:
    accounts = await mm.get_accounts()
except RequestFailedException:
    # Likely session expired, re-authenticate
    await mm.login(email="user@example.com", password="password", save_session=True)
    accounts = await mm.get_accounts()
```

--------------------------------

### Import Typed Client

Source: https://github.com/bradleyseanf/monarchmoneycommunity/blob/dev/_autodocs/README.md

Use the typed client to receive structured Python objects instead of raw dictionaries.

```python
from typedmonarchmoney import TypedMonarchMoney, MonarchAccount

mm = TypedMonarchMoney()
await mm.login(email="user@example.com", password="password")
accounts = await mm.get_accounts()  # Returns List[MonarchAccount]
```

--------------------------------

### Reset Budget Data

Source: https://github.com/bradleyseanf/monarchmoneycommunity/blob/dev/_autodocs/03-budgets-cashflow-api.md

Reverts budget settings for a specified month to default or zero values.

```python
async def reset_budget(
    self,
    start_date: Optional[str] = None,
) -> Dict[str, Any]
```

```python
# Reset current month's budget
await mm.reset_budget()

# Reset specific month
await mm.reset_budget(start_date="2025-02-01")
```

--------------------------------

### Manage Internal GraphQL Client

Source: https://github.com/bradleyseanf/monarchmoneycommunity/blob/dev/_autodocs/08-graphql-core.md

Retrieves a configured gql.Client instance. This is typically handled automatically by gql_call but can be accessed for custom client operations.

```python
def _get_graphql_client(self) -> Client
```

```python
# Automatically called by gql_call(), but can be accessed directly:
client = mm._get_graphql_client()
# client is a gql.Client instance ready for queries
```

--------------------------------

### Import Exceptions

Source: https://github.com/bradleyseanf/monarchmoneycommunity/blob/dev/_autodocs/README.md

Import specific exception classes to handle authentication and request errors.

```python
from monarchmoney import (
    LoginFailedException,
    RequireMFAException,
    CaptchaRequiredException,
    RequestFailedException,
)
```

--------------------------------

### Retrieve Financial Institutions

Source: https://github.com/bradleyseanf/monarchmoneycommunity/blob/dev/_autodocs/03-budgets-cashflow-api.md

Fetches all linked institutions and their credential statuses.

```python
async def get_institutions(self) -> Dict[str, Any]
```

```python
institutions = await mm.get_institutions()
for cred in institutions['credentials']:
    inst = cred.get('institution', {})
    print(f"{inst['name']}: Status = {cred['updateRequired']}")
```

--------------------------------

### reset_budget

Source: https://github.com/bradleyseanf/monarchmoneycommunity/blob/dev/README.md

Resets the budget for a month back to its defaults.

```APIDOC
## reset_budget

### Description
Resets the budget for a month back to its defaults.
```

--------------------------------

### Execute GraphQL Operations with gql_call

Source: https://github.com/bradleyseanf/monarchmoneycommunity/blob/dev/_autodocs/08-graphql-core.md

Executes GraphQL queries or mutations using a compiled DocumentNode. Requires the gql library and an initialized Monarch Money client instance.

```python
async def gql_call(
    self,
    operation: str,
    graphql_query: DocumentNode,
    variables: Dict[str, Any] = {},
) -> Dict[str, Any]
```

```python
from gql import gql

# This is how methods internally use gql_call:
query = gql("""
    query GetAccounts {
        accounts {
            id
            displayName
            __typename
        }
    }
""")

result = await mm.gql_call(
    operation="GetAccounts",
    graphql_query=query,
)
```

--------------------------------

### Handle MFA Exception

Source: https://github.com/bradleyseanf/monarchmoneycommunity/blob/dev/_autodocs/README.md

Catches MFA requirements during login and completes the authentication process manually.

```python
try:
    await mm.login(email="user@example.com", password="password")
except RequireMFAException:
    mfa_code = input("Enter MFA code: ")
    await mm.multi_factor_authenticate(
        email="user@example.com",
        password="password",
        code=mfa_code
    )
    mm.save_session()
```

--------------------------------

### Access Library Constants

Source: https://github.com/bradleyseanf/monarchmoneycommunity/blob/dev/_autodocs/00-public-api.md

These constants are accessible from the monarchmoney.monarchmoney module and define default behaviors and keys.

```python
DEFAULT_RECORD_LIMIT = 100          # Default pagination limit
DEFAULT_DELAY_SECS = 10             # Default delay between checks
DEFAULT_TIMEOUT_SECS = 300          # Default timeout for operations
SESSION_DIR = ".mm"                 # Default session directory
SESSION_FILE = ".mm/mm_session.pickle"  # Default session file path
AUTH_HEADER_KEY = "authorization"   # Auth header key
CSRF_KEY = "csrftoken"              # CSRF token key
ERRORS_KEY = "error_code"           # Error code key in responses
REQUIRED_COOKIES = ("session_id", "csrftoken")  # Required cookies for auth
```

--------------------------------

### Define get_cashflow method

Source: https://github.com/bradleyseanf/monarchmoneycommunity/blob/dev/_autodocs/03-budgets-cashflow-api.md

Method signature for retrieving cashflow data grouped by category, merchant, and summary.

```python
async def get_cashflow(
    self,
    limit: int = DEFAULT_RECORD_LIMIT,
    start_date: Optional[str] = None,
    end_date: Optional[str] = None,
) -> Dict[str, Any]
```

--------------------------------

### Complete MFA authentication with _multi_factor_authenticate

Source: https://github.com/bradleyseanf/monarchmoneycommunity/blob/dev/_autodocs/08-graphql-core.md

Finalizes the authentication process after an MFA challenge is triggered.

```python
async def _multi_factor_authenticate(
    self,
    email: str,
    password: str,
    code: Optional[str] = None,
    trusted_device: bool = True,
) -> None
```

--------------------------------

### Create a transaction tag

Source: https://github.com/bradleyseanf/monarchmoneycommunity/blob/dev/_autodocs/02-transactions-api.md

Creates a new tag with a specified name and hex color code.

```python
result = await mm.create_transaction_tag(
    name="Important",
    color="#FF0000"
)
```

--------------------------------

### interactive_login

Source: https://github.com/bradleyseanf/monarchmoneycommunity/blob/dev/_autodocs/01-monarchmoney-client.md

Prompts user for email, password, and optionally MFA code in an interactive session.

```APIDOC
## interactive_login(use_saved_session, save_session)

### Description
Prompts user for email, password, and optionally MFA code in an interactive session (iPython/Jupyter compatible).

### Parameters
- **use_saved_session** (bool) - No - If True, uses saved session if available
- **save_session** (bool) - No - If True, saves credentials after successful login
```

--------------------------------

### Normalize URL helper

Source: https://github.com/bradleyseanf/monarchmoneycommunity/blob/dev/_autodocs/07-types-dataclasses.md

Ensures URLs have an http:// prefix and defaults to a specific base URL if empty.

```python
def _normalize_url(url: Optional[str]) -> str
```

--------------------------------

### Set authentication token directly

Source: https://github.com/bradleyseanf/monarchmoneycommunity/blob/dev/_autodocs/01-monarchmoney-client.md

Manually sets the authentication token for the current session.

```python
mm = MonarchMoney()
mm.set_token("your_long_lived_token")
await mm.get_accounts()
```

--------------------------------

### Retrieve MonarchCashflowSummary

Source: https://github.com/bradleyseanf/monarchmoneycommunity/blob/dev/_autodocs/05-typed-client.md

Fetch and display cashflow summary data including income, expenses, and savings metrics.

```python
summary = await mm.get_cashflow_summary()
print(f"Income: ${summary.income:,.2f}")
print(f"Expenses: ${summary.expenses:,.2f}")
print(f"Net Savings: ${summary.savings:,.2f}")
print(f"Savings Rate: {summary.savings_rate*100:.1f}%")
```

--------------------------------

### update_flexible_budget

Source: https://github.com/bradleyseanf/monarchmoneycommunity/blob/dev/README.md

Updates the Flexible budget bucket amount for a month.

```APIDOC
## update_flexible_budget

### Description
Updates the Flexible budget bucket amount for a month.
```

--------------------------------

### Request Header Configurations

Source: https://github.com/bradleyseanf/monarchmoneycommunity/blob/dev/_autodocs/08-graphql-core.md

Default and authentication-specific headers used for API requests.

```json
{
    "Accept": "application/json",
    "Client-Platform": "web",
    "Content-Type": "application/json",
    "User-Agent": "MonarchMoneyAPI (https://github.com/bradleyseanf/monarchmoneycommunity)"
}
```

```json
{"Authorization": "Token {token}"}
```

```json
{
    "Origin": "https://app.monarch.com",
    "Referer": "https://app.monarch.com/",
    "monarch-client": "web",
    "monarch-client-version": "2025.05",
    "X-Csrftoken": "{csrftoken}"
}
```

--------------------------------

### MonarchMoney.login

Source: https://github.com/bradleyseanf/monarchmoneycommunity/blob/dev/_autodocs/README.md

Authenticates a user with email and password, supporting optional MFA secrets.

```APIDOC
## MonarchMoney.login(email, password, mfa_secret_key=None, save_session=False)

### Description
Authenticates the user session. Can handle MFA via a TOTP secret key.

### Parameters
- **email** (str) - Required - User email address
- **password** (str) - Required - User password
- **mfa_secret_key** (str) - Optional - Base32 encoded TOTP secret
- **save_session** (bool) - Optional - Whether to persist the session to disk
```

--------------------------------

### Save Monarch Money Session

Source: https://github.com/bradleyseanf/monarchmoneycommunity/blob/dev/README.md

Initializes a session and saves it to avoid repeated logins. The session duration is variable but can persist for 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()
```

--------------------------------

### Define Request Configuration Constants

Source: https://github.com/bradleyseanf/monarchmoneycommunity/blob/dev/_autodocs/07-types-dataclasses.md

Default settings for API request limits, delays, timeouts, and error handling keys.

```python
DEFAULT_RECORD_LIMIT = 100
DEFAULT_DELAY_SECS = 10
DEFAULT_TIMEOUT_SECS = 300
ERRORS_KEY = "error_code"
```