### Initialize Python MonarchMoney Client

Source: https://github.com/crowe452/monarch-money-docs/blob/main/api-reference.md

Installation and basic initialization of the monarchmoney Python library to interact with the API.

```bash
pip install monarchmoney
```

```python
from monarchmoney import MonarchMoney

mm = MonarchMoney()
await mm.login(email="...", password="...")

# Or with token directly:
mm = MonarchMoney(token="your_token")
```

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

### GET /GetInstitutions

Source: https://context7.com/crowe452/monarch-money-docs/llms.txt

Retrieves the list of connected financial institution credentials and their current synchronization status.

```APIDOC
## GET GetInstitutions

### Description
Retrieves connected financial institution credentials and their sync status.

### Method
POST (GraphQL Query)

### Endpoint
https://api.monarchmoney.com/graphql

### Response
#### Success Response (200)
- **credentials** (array) - List of connected institution credentials

#### Response Example
{
  "credentials": [
    {
      "id": "cred1",
      "updateRequired": false,
      "dataProvider": "plaid",
      "institution": { "id": "inst1", "name": "Chase", "url": "https://chase.com" }
    }
  ]
}
```

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

### Get Subscription Details

Source: https://context7.com/crowe452/monarch-money-docs/llms.txt

Fetches the user's current subscription status, including trial eligibility and premium feature entitlements.

```python
from monarchmoney import MonarchMoney

mm = MonarchMoney(token="your_token")
subscription = await mm.get_subscription_details()
```

```graphql
query GetSubscriptionDetails {
  subscription {
    id
    paymentSource
    referralCode
    isOnFreeTrial
    hasPremiumEntitlement
  }
}
```

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

### GET /GetSubscriptionDetails

Source: https://context7.com/crowe452/monarch-money-docs/llms.txt

Retrieves the user's current subscription status, including trial information and premium feature entitlements.

```APIDOC
## GET GetSubscriptionDetails

### Description
Retrieves the user's Monarch Money subscription status including trial status and premium entitlements.

### Method
POST (GraphQL Query)

### Endpoint
https://api.monarchmoney.com/graphql

### Response
#### Success Response (200)
- **subscription** (object) - Subscription details including trial and premium status

#### Response Example
{
  "subscription": {
    "id": "sub123",
    "paymentSource": "stripe",
    "referralCode": "ABC123",
    "isOnFreeTrial": false,
    "hasPremiumEntitlement": true
  }
}
```

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

### Authenticate with Monarch Money API (Python)

Source: https://context7.com/crowe452/monarch-money-docs/llms.txt

Provides Python code examples for authenticating with the Monarch Money API using the `monarchmoney` client. It covers interactive login, direct login with credentials, MFA authentication, and using an existing token.

```python
from monarchmoney import MonarchMoney

# Option 1: Interactive login with session persistence
mm = MonarchMoney()
await mm.interactive_login(use_saved_session=True, save_session=True)

# Option 2: Direct login with credentials
mm = MonarchMoney()
await mm.login(email="your@email.com", password="yourpassword", save_session=True)

# Option 3: MFA authentication
await mm.multi_factor_authenticate(email="your@email.com", password="yourpassword", code="123456")

# Option 4: Use existing token directly
mm = MonarchMoney(token="your_token_here")

# Session management
mm.save_session(filename="~/.monarch_session")
mm.load_session(filename="~/.monarch_session")
mm.delete_session()
```

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

### Get Portfolio Holdings via GraphQL

Source: https://context7.com/crowe452/monarch-money-docs/llms.txt

Retrieves aggregated holdings for a portfolio, including security details, pricing, and quantity. Requires a PortfolioInput object as an argument.

```graphql
query Web_GetHoldings($input: PortfolioInput) {
  portfolio(input: $input) {
    aggregateHoldings {
      edges {
        node {
          id
          quantity
          basis
          totalValue
          securityPriceChangeDollars
          securityPriceChangePercent
          lastSyncedAt
          holdings { id type typeDisplay name ticker closingPrice isManual closingPriceUpdatedAt }
          security {
            id name type ticker typeDisplay
            currentPrice currentPriceUpdatedAt
            closingPrice closingPriceUpdatedAt
            oneDayChangePercent oneDayChangeDollars
          }
        }
      }
    }
  }
}
```

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

### Get Categories

Source: https://github.com/crowe452/monarch-money-docs/blob/main/api-reference.md

Retrieves a list of all available categories. Includes details like ID, name, and system status.

```APIDOC
## GET /api/categories

### Description
Retrieves a list of all available categories. Includes details like ID, name, and system status.

### Method
GET

### Endpoint
/api/categories

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Response
#### Success Response (200)
- **categories** (array) - A list of category objects.
  - **id** (string) - Category ID.
  - **order** (integer) - Order of the category.
  - **name** (string) - Category name.
  - **systemCategory** (boolean) - Whether this is a system-defined category.
  - **isSystemCategory** (boolean) - Alias for systemCategory.
  - **isDisabled** (boolean) - Whether the category is disabled.
  - **updatedAt** (string) - Timestamp of the last update.
  - **createdAt** (string) - Timestamp of creation.
  - **group** (object) - The category group information.
    - **id** (string) - Group ID.
    - **name** (string) - Group name.
    - **type** (string) - Type of the group.

#### Response Example
```json
{
  "categories": [
    {
      "id": "cat_1",
      "order": 1,
      "name": "Groceries",
      "systemCategory": false,
      "isSystemCategory": false,
      "isDisabled": false,
      "updatedAt": "2023-10-26T12:00:00Z",
      "createdAt": "2023-10-26T12:00:00Z",
      "group": {
        "id": "group_1",
        "name": "Spending",
        "type": "expense"
      }
    }
  ]
}
```
```

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

### Get Subscription Details GraphQL Query

Source: https://github.com/crowe452/monarch-money-docs/blob/main/api-reference.md

Retrieves details about the user's subscription status. It includes information such as the subscription ID, payment source, referral code, trial status, and premium entitlement.

```graphql
query GetSubscriptionDetails {
  subscription {
    id
    paymentSource
    referralCode
    isOnFreeTrial
    hasPremiumEntitlement
  }
}
```

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

### Get Account Snapshots

Source: https://context7.com/crowe452/monarch-money-docs/llms.txt

Retrieves aggregated balance snapshots grouped by account type or time period. Useful for net worth trending and portfolio analysis.

```python
from monarchmoney import MonarchMoney
from datetime import datetime, timedelta

mm = MonarchMoney(token="your_token")

start_date = (datetime.now() - timedelta(days=365)).strftime("%Y-%m-%d")
snapshots = await mm.get_account_snapshots_by_type(start_date=start_date, timeframe="month")

aggregates = await mm.get_aggregate_snapshots(
    start_date=start_date,
    end_date=datetime.now().strftime("%Y-%m-%d"),
    account_type="depository"
)
```

```graphql
query GetSnapshotsByAccountType($startDate: Date!, $timeframe: Timeframe!) {
  snapshotsByAccountType(startDate: $startDate, timeframe: $timeframe) {
    month
    accountType
    accountSubtype
    sum
  }
}

query GetAggregateSnapshots($filters: AggregateSnapshotFilters) {
  aggregateSnapshots(filters: $filters) {
    date
    balance
    __typename
  }
}
```

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

### Get Monthly Budget Amounts by Category (Python)

Source: https://context7.com/crowe452/monarch-money-docs/llms.txt

Iterates through monthly budget data by category and prints the category name, month, planned amount, and actual amount. Requires the 'monarchmoney' library.

```python
for cat_budget in budgets["budgetData"]["monthlyAmountsByCategory"]:
    cat = cat_budget["category"]
    for month in cat_budget["monthlyAmounts"]:
        print(f"{cat['name']} ({month['month']}): Planned ${month['plannedCashFlowAmount']}, Actual ${month['actualAmount']}")
```

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

### Get Budgets with Goals GraphQL Query

Source: https://github.com/crowe452/monarch-money-docs/blob/main/api-reference.md

Retrieves monthly budget amounts by category along with associated financial goals for a specified date range. This query provides a comprehensive view of both budgeting and goal-tracking information.

```graphql
query GetBudgetsWithGoals($startDate: Date!, $endDate: Date!) {
  budgetData(startMonth: $startDate, endMonth: $endDate) {
    monthlyAmountsByCategory {
      category {
        id
        name
        icon
        group {
          id
          name
          type
        }
      }
      monthlyAmounts {
        month
        plannedCashFlowAmount
        plannedSetAsideAmount
        actualAmount
        remainingAmount
        previousMonthRolloverAmount
        rolloverType
      }
    }
  }
  goalsV2 {
    goals {
      id
      name
      type
      amount
      priority
      targetDate
      targetAmount
      currentAmount
      imageUrl
      accountId
      account {
        id
        displayName
      }
      percentageComplete
      monthlyContribution
      createdAt
      updatedAt
    }
  }
}
```

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

### Get Joint Planning Data (GraphQL)

Source: https://context7.com/crowe452/monarch-money-docs/llms.txt

A GraphQL query to retrieve monthly budget data, including category details and monthly amounts, for a specified date range. Uses 'startDate' and 'endDate' variables.

```graphql
query Common_GetJointPlanningData($startDate: Date!, $endDate: Date!) {
  budgetData(startMonth: $startDate, endMonth: $endDate) {
    monthlyAmountsByCategory {
      category {
        id name icon
        group { id name type }
      }
      monthlyAmounts {
        month
        plannedCashFlowAmount
        plannedSetAsideAmount
        actualAmount
        remainingAmount
        previousMonthRolloverAmount
        rolloverType
      }
    }
  }
}
```

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

### Get Categories (GraphQL)

Source: https://github.com/crowe452/monarch-money-docs/blob/main/api-reference.md

Retrieves a list of all categories available in the system. Includes details like ID, name, order, and group information. Useful for displaying category options.

```graphql
query GetCategories {
  categories {
    id
    order
    name
    systemCategory
    isSystemCategory
    isDisabled
    updatedAt
    createdAt
    group {
      id
      name
      type
    }
  }
}
```

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

### Get Budgets API

Source: https://context7.com/crowe452/monarch-money-docs/llms.txt

Retrieves budget data for a specified date range, including planned amounts, actual spending, and rollover balances per category.

```APIDOC
## GET /api/budgets

### Description
Retrieves budget data by category for a date range.

### Method
GET

### Endpoint
/api/budgets

### Parameters
#### Query Parameters
- **startDate** (string) - Required - The start date for the budget data (YYYY-MM-DD).
- **endDate** (string) - Required - The end date for the budget data (YYYY-MM-DD).
- **useLegacyGoals** (boolean) - Optional - Whether to use legacy goals (default: false).
- **useV2Goals** (boolean) - Optional - Whether to use v2 goals (default: true).

### Response
#### Success Response (200)
- **budgetData** (object) - Contains budget information.
  - **monthlyAmountsByCategory** (array) - An array of budget details for each category.
    - **category** (object) - Details of the category.
      - **id** (string) - The category ID.
      - **name** (string) - The category name.
      - **icon** (string) - The category icon.
      - **group** (object) - Information about the category group.
        - **name** (string) - The group name.
        - **type** (string) - The group type (e.g., 'expense').
    - **monthlyAmounts** (array) - Monthly budget details for the category.
      - **month** (string) - The month (YYYY-MM-DD).
      - **plannedCashFlowAmount** (number) - The planned amount for the month.
      - **actualAmount** (number) - The actual amount spent/received.
      - **remainingAmount** (number) - The remaining amount.
      - **previousMonthRolloverAmount** (number) - Rollover amount from the previous month.
      - **rolloverType** (string) - The type of rollover.

#### Response Example
```json
{
  "budgetData": {
    "monthlyAmountsByCategory": [
      {
        "category": { "id": "cat1", "name": "Groceries", "icon": "🛒", "group": { "name": "Food", "type": "expense" } },
        "monthlyAmounts": [
          {
            "month": "2024-01-01",
            "plannedCashFlowAmount": 500.00,
            "actualAmount": -485.50,
            "remainingAmount": 14.50,
            "previousMonthRolloverAmount": 0,
            "rolloverType": "monthly"
          }
        ]
      }
    ]
  }
}
```
```

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

### Get Category Groups (GraphQL)

Source: https://github.com/crowe452/monarch-money-docs/blob/main/api-reference.md

Fetches all available category groups. Provides information about each group, such as ID, name, order, and type. Essential for managing category organization.

```graphql
query ManageGetCategoryGroups {
  categoryGroups {
    id
    name
    order
    type
    updatedAt
    createdAt
  }
}
```

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

### Set Budget Amount (GraphQL)

Source: https://context7.com/crowe452/monarch-money-docs/llms.txt

A GraphQL mutation to update or create a budget item. It takes an input object specifying the amount, category or group ID, timeframe, start date, and whether to apply to future months. Requires variables for the input.

```graphql
mutation Common_UpdateBudgetItem($input: UpdateOrCreateBudgetItemMutationInput!) {
  updateOrCreateBudgetItem(input: $input) {
    budgetItem { id budgetAmount }
  }
}

# Variables:
# {
#   "input": {
#     "amount": 500.00,
#     "categoryId": "cat_groceries",
#     "timeframe": "month",
#     "startDate": "2024-01-01",
#     "applyToFuture": true
#   }
# }
```

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

### Get Cashflow Analysis (Python)

Source: https://context7.com/crowe452/monarch-money-docs/llms.txt

Retrieves comprehensive cashflow analysis using the Monarch Money API. Requires the 'monarchmoney' library and an API token. Can fetch full breakdown or just the summary for a given date range.

```python
from monarchmoney import MonarchMoney
from datetime import datetime, timedelta

mm = MonarchMoney(token="your_token")

# Get full cashflow breakdown
cashflow = await mm.get_cashflow(
    limit=100,
    start_date=(datetime.now() - timedelta(days=30)).strftime("%Y-%m-%d"),
    end_date=datetime.now().strftime("%Y-%m-%d")
)

# Response includes:
# - byCategory: spending grouped by category
# - byCategoryGroup: spending grouped by category group
# - byMerchant: top 50 merchants by spending
# - summary: { sumIncome, sumExpense, savings, savingsRate }

# Get just the summary
summary = await mm.get_cashflow_summary(
    start_date="2024-01-01",
    end_date="2024-01-31"
)

# Response:
# {
#   "summary": {
#     "sumIncome": 8500.00,
#     "sumExpense": -6200.00,
#     "savings": 2300.00,
#     "savingsRate": 0.27  # 27%
#   }
# }
```

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

### Get Account Holdings

Source: https://context7.com/crowe452/monarch-money-docs/llms.txt

Fetches detailed investment portfolio data for brokerage or retirement accounts. Returns security information, quantities, current market values, and performance metrics.

```python
holdings = await mm.get_account_holdings(account_id="170123456789012345")
```

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

### Get Budgets GraphQL Query

Source: https://github.com/crowe452/monarch-money-docs/blob/main/api-reference.md

Retrieves monthly budget amounts by category for a specified date range. It includes details about categories and their monthly financial data such as planned, actual, and remaining amounts.

```graphql
query Common_GetJointPlanningData($startDate: Date!, $endDate: Date!) {
  budgetData(startMonth: $startDate, endMonth: $endDate) {
    monthlyAmountsByCategory {
      category {
        id
        name
        icon
        group {
          id
          name
          type
        }
      }
      monthlyAmounts {
        month
        plannedCashFlowAmount
        plannedSetAsideAmount
        actualAmount
        remainingAmount
        previousMonthRolloverAmount
        rolloverType
      }
    }
  }
}
```

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

### Get Institutions GraphQL Query

Source: https://github.com/crowe452/monarch-money-docs/blob/main/api-reference.md

Retrieves a list of institutions linked to the user's account. It provides details such as the institution ID, whether an update is required, the data provider, and the institution's name and URL.

```graphql
query GetInstitutions {
  credentials {
    id
    updateRequired
    dataProvider
    institution {
      id
      name
      url
    }
  }
}
```

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

### Set Budget Amount Input Structure (Python)

Source: https://github.com/crowe452/monarch-money-docs/blob/main/api-reference.md

Defines the structure for input data when setting a budget amount using Python. It specifies required fields like amount and category/group ID, along with optional parameters for timeframe and start date.

```python
{
  "amount": amount,
  "categoryId": category_id,        # one of these
  "categoryGroupId": group_id,      # or this
  "timeframe": "month",             # "month" is default
  "startDate": "YYYY-MM-01",        # defaults to current month
  "applyToFuture": False
}
```

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

### Get Cashflow Data (GraphQL)

Source: https://context7.com/crowe452/monarch-money-docs/llms.txt

GraphQL queries to retrieve cashflow data. 'Web_GetCashFlowPage' fetches data grouped by category, category group, merchant, and a general summary. 'Web_GetCashFlowSummary' specifically retrieves income, expense, savings, and savings rate.

```graphql
query Web_GetCashFlowPage($filters: TransactionFilterInput) {
  byCategory: aggregates(filters: $filters, groupBy: ["category"]) {
    groupBy { category { id name group { id type } } }
    summary { sum }
  }
  byCategoryGroup: aggregates(filters: $filters, groupBy: ["categoryGroup"]) {
    groupBy { categoryGroup { id name type } }
    summary { sum }
  }
  byMerchant: aggregates(filters: $filters, groupBy: ["merchant"], limit: 50) {
    groupBy { merchant { id name logoUrl } }
    summary { sum }
  }
  summary: aggregates(filters: $filters, fillEmptyValues: true) {
    summary { sum sumIncome sumExpense savings savingsRate }
  }
}

query Web_GetCashFlowSummary($filters: TransactionFilterInput) {
  summary: aggregates(filters: $filters, fillEmptyValues: true) {
    summary { sumIncome sumExpense savings savingsRate }
  }
}
```

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

### Get Category Groups

Source: https://github.com/crowe452/monarch-money-docs/blob/main/api-reference.md

Retrieves a list of all category groups. Used for organizing categories.

```APIDOC
## GET /api/category_groups

### Description
Retrieves a list of all category groups. Used for organizing categories.

### Method
GET

### Endpoint
/api/category_groups

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Response
#### Success Response (200)
- **categoryGroups** (array) - A list of category group objects.
  - **id** (string) - Group ID.
  - **name** (string) - Group name.
  - **order** (integer) - Order of the group.
  - **type** (string) - Type of the group (e.g., 'expense', 'income').
  - **updatedAt** (string) - Timestamp of the last update.
  - **createdAt** (string) - Timestamp of creation.

#### Response Example
```json
{
  "categoryGroups": [
    {
      "id": "group_1",
      "name": "Spending",
      "order": 1,
      "type": "expense",
      "updatedAt": "2023-10-26T12:00:00Z",
      "createdAt": "2023-10-26T12:00:00Z"
    }
  ]
}
```
```

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

### Get Transaction Tags

Source: https://github.com/crowe452/monarch-money-docs/blob/main/api-reference.md

Retrieves a list of tags associated with transactions. Supports searching and limiting results.

```APIDOC
## GET /api/transaction_tags

### Description
Retrieves a list of tags associated with transactions. Supports searching and limiting results.

### Method
GET

### Endpoint
/api/transaction_tags

### Parameters
#### Path Parameters
None

#### Query Parameters
- **search** (string) - Optional - Search term for tag names.
- **limit** (integer) - Optional - Maximum number of tags to return.
- **bulkParams** (object) - Optional - Parameters for bulk data operations (details depend on implementation).

#### Request Body
None

### Response
#### Success Response (200)
- **householdTransactionTags** (array) - A list of tag objects.
  - **id** (string) - Tag ID.
  - **name** (string) - Tag name.
  - **color** (string) - Color of the tag (hex or name).
  - **order** (integer) - Order of the tag.
  - **transactionCount** (integer) - Number of transactions associated with this tag.

#### Response Example
```json
{
  "householdTransactionTags": [
    {
      "id": "tag_1",
      "name": "Urgent",
      "color": "#FF0000",
      "order": 1,
      "transactionCount": 5
    }
  ]
}
```
```

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

### POST /graphql (CreateManualAccount)

Source: https://context7.com/crowe452/monarch-money-docs/llms.txt

Creates a new manual account for tracking assets or liabilities not linked to a financial institution.

```APIDOC
## POST /graphql

### Description
Creates a manual account entry for tracking assets like cash or property.

### Method
POST

### Endpoint
https://api.monarchmoney.com/graphql

### Request Body
- **account_type** (string) - Required - Type of account (e.g., "depository")
- **account_sub_type** (string) - Required - Subtype (e.g., "checking")
- **account_name** (string) - Required - Display name
- **account_balance** (float) - Required - Initial balance

### Request Example
{
  "account_type": "depository",
  "account_sub_type": "checking",
  "account_name": "Cash Savings",
  "account_balance": 1000.00
}

### Response
#### Success Response (200)
- **result** (object) - Confirmation of the created account object.
```

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

### Get Transaction Categories (with icon/order)

Source: https://github.com/crowe452/monarch-money-docs/blob/main/api-reference.md

Retrieves categories specifically for transactions, including icon and order details.

```APIDOC
## GET /api/transaction_categories

### Description
Retrieves categories specifically for transactions, including icon and order details.

### Method
GET

### Endpoint
/api/transaction_categories

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Response
#### Success Response (200)
- **categories** (array) - A list of category objects.
  - **id** (string) - Category ID.
  - **name** (string) - Category name.
  - **icon** (string) - Icon associated with the category.
  - **order** (integer) - Order of the category.
  - **systemCategory** (boolean) - Whether this is a system-defined category.
  - **isSystemCategory** (boolean) - Alias for systemCategory.
  - **isDisabled** (boolean) - Whether the category is disabled.
  - **group** (object) - The category group information.
    - **id** (string) - Group ID.
    - **name** (string) - Group name.
    - **type** (string) - Type of the group.
    - **order** (integer) - Order of the group.

#### Response Example
```json
{
  "categories": [
    {
      "id": "cat_1",
      "name": "Groceries",
      "icon": "🛒",
      "order": 1,
      "systemCategory": false,
      "isSystemCategory": false,
      "isDisabled": false,
      "group": {
        "id": "group_1",
        "name": "Spending",
        "type": "expense",
        "order": 1
      }
    }
  ]
}
```
```

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

### Get Transaction Splits

Source: https://github.com/crowe452/monarch-money-docs/blob/main/api-reference.md

Retrieves details of a transaction, including its splits if any. Useful for understanding how a transaction was divided.

```APIDOC
## GET /api/transactions/{id}/splits

### Description
Retrieves details of a transaction, including its splits if any. Useful for understanding how a transaction was divided.

### Method
GET

### Endpoint
/api/transactions/{id}/splits

### Parameters
#### Path Parameters
- **id** (UUID) - Required - The unique identifier of the transaction.

#### Query Parameters
None

#### Request Body
None

### Response
#### Success Response (200)
- **id** (string) - Transaction ID.
- **amount** (number) - Total transaction amount.
- **category** (object) - The primary category of the transaction.
  - **id** (string) - Category ID.
  - **name** (string) - Category name.
- **merchant** (object) - The primary merchant of the transaction.
  - **id** (string) - Merchant ID.
  - **name** (string) - Merchant name.
- **splitTransactions** (array) - A list of split transactions.
  - **id** (string) - Split transaction ID.
  - **merchant** (object) - Merchant for this split.
    - **id** (string) - Merchant ID.
    - **name** (string) - Merchant name.
  - **category** (object) - Category for this split.
    - **id** (string) - Category ID.
    - **name** (string) - Category name.
  - **amount** (number) - Amount for this split.
  - **notes** (string) - Notes for this split.

#### Response Example
```json
{
  "getTransaction": {
    "id": "txn_123",
    "amount": 150.00,
    "category": {
      "id": "cat_456",
      "name": "Groceries"
    },
    "merchant": {
      "id": "merch_abc",
      "name": "SuperMart"
    },
    "splitTransactions": [
      {
        "id": "split_1",
        "merchant": {
          "id": "merch_def",
          "name": "Bakery"
        },
        "category": {
          "id": "cat_789",
          "name": "Bread"
        },
        "amount": 50.00,
        "notes": "Baguettes"
      },
      {
        "id": "split_2",
        "merchant": {
          "id": "merch_abc",
          "name": "SuperMart"
        },
        "category": {
          "id": "cat_456",
          "name": "Groceries"
        },
        "amount": 100.00,
        "notes": "Other groceries"
      }
    ]
  }
}
```
```

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

### POST /graphql (GetAccounts)

Source: https://context7.com/crowe452/monarch-money-docs/llms.txt

Retrieves a comprehensive list of all linked financial accounts, including balances, institution details, and sync status.

```APIDOC
## POST /graphql

### Description
Executes a GraphQL query to fetch all financial accounts associated with the user's household.

### Method
POST

### Endpoint
https://api.monarchmoney.com/graphql

### Request Body
- **operationName** (string) - Required - "GetAccounts"
- **query** (string) - Required - GraphQL query string

### Request Example
{
  "operationName": "GetAccounts",
  "query": "query GetAccounts { accounts { id displayName currentBalance } }"
}

### Response
#### Success Response (200)
- **accounts** (array) - List of account objects containing metadata, balances, and institution info.

#### Response Example
{
  "accounts": [
    {
      "id": "170123456789012345",
      "displayName": "Chase Checking",
      "currentBalance": 5432.10
    }
  ]
}
```

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

### Get Account History

Source: https://context7.com/crowe452/monarch-money-docs/llms.txt

Retrieves historical balance data for a specific account to enable time-series analysis and charting.

```python
from monarchmoney import MonarchMoney

mm = MonarchMoney(token="your_token")
history = await mm.get_account_history(account_id="170123456789012345")
```

```graphql
query GetAccountHistory($accountId: UUID!) {
  account(id: $accountId) {
    id
    balanceHistory { date balance }
  }
}
```

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

### Authenticate with Monarch Money API (Bash)

Source: https://context7.com/crowe452/monarch-money-docs/llms.txt

Demonstrates how to obtain an authentication token using cURL for the Monarch Money API. It includes a POST request for login and a subsequent request to the GraphQL endpoint using the obtained token.

```bash
# Login to get authentication token
curl -X POST https://api.monarchmoney.com/auth/login/ \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Client-Platform: web" \
  -d '{
    "username": "your@email.com",
    "password": "yourpassword"
  }'

# Response: { "token": "abc123...", ... }

# Use token for GraphQL requests
curl -X POST https://api.monarchmoney.com/graphql \
  -H "Authorization: Token abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "operationName": "GetAccounts",
    "query": "query GetAccounts { accounts { id displayName currentBalance } }",
    "variables": {}
  }'
```

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

### Create Manual Account with Monarch Money API (Python)

Source: https://context7.com/crowe452/monarch-money-docs/llms.txt

Python code demonstrating how to create a new manual account in Monarch Money using the `monarchmoney` client. This is useful for tracking assets or liabilities not linked to financial institutions, such as cash or property.

```python
from monarchmoney import MonarchMoney

mm = MonarchMoney(token="your_token")

# Create a manual checking account
result = await mm.create_manual_account(
    account_type="depository",
    account_sub_type="checking",
    is_in_net_worth=True,
    account_name="Cash Savings",
    account_balance=1000.00
)

```

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

### Set Budget Amount GraphQL Mutation (Go Client)

Source: https://github.com/crowe452/monarch-money-docs/blob/main/api-reference.md

An alternate GraphQL mutation for setting a budget amount, intended for use with a Go client. It returns the updated budget details and any associated errors.

```graphql
mutation SetBudgetAmount($input: SetBudgetAmountMutationInput!) {
  setBudgetAmount(input: $input) {
    budget {
      id
      amount
      rollover
    }
    errors {
      message
      code
    }
  }
}
```

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

### Get Tags API

Source: https://context7.com/crowe452/monarch-money-docs/llms.txt

Retrieves a list of all transaction tags associated with the household. Tags are used for organizing and filtering transactions.

```APIDOC
## GET /api/tags

### Description
Retrieves all transaction tags.

### Method
GET

### Endpoint
/api/tags

### Parameters
#### Query Parameters
- **search** (string) - Optional - A search term to filter tags by name.
- **limit** (integer) - Optional - The maximum number of tags to return.
- **bulkParams** (object) - Optional - Parameters for bulk transaction data.

### Response
#### Success Response (200)
- **householdTransactionTags** (array) - A list of tag objects.
  - **id** (string) - The unique identifier for the tag.
  - **name** (string) - The name of the tag.
  - **color** (string) - The color associated with the tag (hex or named).
  - **order** (integer) - The display order of the tag.
  - **transactionCount** (integer) - The number of transactions associated with this tag.

#### Response Example
```json
{
  "householdTransactionTags": [
    { "id": "tag1", "name": "Business", "color": "#FF5733", "order": 1, "transactionCount": 45 },
    { "id": "tag2", "name": "Tax Deductible", "color": "#33FF57", "order": 2, "transactionCount": 120 }
  ]
}
```
```

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

### GET /transactions/{id}

Source: https://context7.com/crowe452/monarch-money-docs/llms.txt

Retrieves complete details for a single transaction including split transactions, attachments, and review status.

```APIDOC
## GET /transactions/{id}

### Description
Retrieves complete details for a single transaction including split transactions, attachments, and review status.

### Method
GET

### Endpoint
/transactions/{id}

### Parameters
#### Path Parameters
- **id** (UUID) - Required - The unique identifier of the transaction.

#### Query Parameters
- **redirectPosted** (Boolean) - Optional - Follow posted transaction if this is a pending match.

### Response
#### Success Response (200)
- **transaction** (Object) - Detailed transaction object including splits, attachments, and merchant info.

### Response Example
{
  "id": "txn123",
  "amount": -45.99,
  "merchant": { "name": "Coffee Shop" },
  "attachments": []
}
```

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

### POST /auth/login/

Source: https://context7.com/crowe452/monarch-money-docs/llms.txt

Authenticates a user with email and password to retrieve a session token required for all subsequent GraphQL requests.

```APIDOC
## POST /auth/login/

### Description
Authenticates the user and returns a session token for API access.

### Method
POST

### Endpoint
https://api.monarchmoney.com/auth/login/

### Request Body
- **username** (string) - Required - User email address
- **password** (string) - Required - User password

### Request Example
{
  "username": "your@email.com",
  "password": "yourpassword"
}

### Response
#### Success Response (200)
- **token** (string) - Session authentication token

#### Response Example
{
  "token": "abc123..."
}
```

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

### GET /transactions/summary

Source: https://context7.com/crowe452/monarch-money-docs/llms.txt

Retrieves aggregate statistics for transactions matching filter criteria including sum, count, average, and income/expense totals.

```APIDOC
## GET /transactions/summary

### Description
Retrieves aggregate statistics for transactions matching filter criteria including sum, count, average, and income/expense totals.

### Method
GET

### Endpoint
/transactions/summary

### Parameters
#### Query Parameters
- **filters** (Object) - Optional - Filter criteria for the aggregation.

### Response
#### Success Response (200)
- **aggregates** (Object) - Contains summary statistics like sum, count, average, max, and date ranges.

### Response Example
{
  "aggregates": {
    "summary": {
      "avg": -125.50,
      "count": 150,
      "sum": -18825.00
    }
  }
}
```

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

### POST /graphql

Source: https://context7.com/crowe452/monarch-money-docs/llms.txt

Executes custom GraphQL queries or mutations for operations not covered by the standard client methods.

```APIDOC
## POST /graphql

### Description
For operations not covered by the Python client methods, use the low-level GraphQL interface to execute custom queries and mutations.

### Method
POST

### Endpoint
https://api.monarchmoney.com/graphql

### Request Body
- **operationName** (string) - Required - Name of the operation
- **query** (string) - Required - The GraphQL query string
- **variables** (object) - Optional - Variables for the query

### Request Example
{
  "operationName": "GetAccounts",
  "query": "query GetAccounts { accounts { id displayName currentBalance type { name } } }",
  "variables": {}
}
```

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

### Execute GraphQL API Request

Source: https://github.com/crowe452/monarch-money-docs/blob/main/api-reference.md

Shows the standard format for sending a GraphQL query to the Monarch Money API using the required Authorization header.

```http
POST https://api.monarchmoney.com/graphql
Authorization: Token {token}
Content-Type: application/json

{
  "operationName": "GetAccounts",
  "query": "query GetAccounts { accounts { id displayName currentBalance } }",
  "variables": {}
}
```

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

### Get Transactions

Source: https://context7.com/crowe452/monarch-money-docs/llms.txt

Retrieves a list of transactions with support for pagination and complex filtering by date, category, account, tags, and search terms.

```python
from monarchmoney import MonarchMoney
from datetime import datetime, timedelta

mm = MonarchMoney(token="your_token")

transactions = await mm.get_transactions(
    limit=50,
    search="Amazon",
    category_ids=["cat123", "cat456"],
    account_ids=["acc789"],
    tag_ids=["tag001"],
    has_notes=True,
    is_recurring=False
)
```

```graphql
query GetTransactionsList($offset: Int, $limit: Int, $filters: TransactionFilterInput, $orderBy: TransactionOrdering) {
  allTransactions(filters: $filters) {
    totalCount
    results(offset: $offset, limit: $limit, orderBy: $orderBy) {
      id
      amount
      pending
      date
      hideFromReports
      plaidName
      notes
      isRecurring
      needsReview
      isSplitTransaction
      createdAt
      updatedAt
      category { id name }
      merchant { name id }
      account { id displayName }
      tags { id name color order }
    }
  }
}
```

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

### Common_GetJointPlanningData

Source: https://context7.com/crowe452/monarch-money-docs/llms.txt

Retrieves detailed budget planning data, including monthly amounts by category, planned vs. actual spending, and rollovers.

```APIDOC
## GET /budgets

### Description
Retrieves detailed budget planning data, including monthly amounts by category, planned vs. actual spending, and rollovers.

### Method
GET

### Endpoint
/budgets

### Query Parameters
- **startDate** (Date) - Required - The start date for the budget data.
- **endDate** (Date) - Required - The end date for the budget data.

### Response
#### Success Response (200)
- **budgetData** (object) - Contains budget information.
  - **monthlyAmountsByCategory** (array) - An array of monthly budget amounts, grouped by category.
    - **category** (object) - Information about the budget category.
      - **id** (string) - The unique identifier for the category.
      - **name** (string) - The name of the category.
      - **icon** (string) - The icon associated with the category.
      - **group** (object) - Information about the category group.
        - **id** (string) - The unique identifier for the category group.
        - **name** (string) - The name of the category group.
        - **type** (string) - The type of the category group.
    - **monthlyAmounts** (array) - An array of monthly financial data for the category.
      - **month** (string) - The month (YYYY-MM).
      - **plannedCashFlowAmount** (number) - The planned cash flow amount for the month.
      - **plannedSetAsideAmount** (number) - The planned amount set aside for the month.
      - **actualAmount** (number) - The actual amount spent or received in the month.
      - **remainingAmount** (number) - The remaining amount in the budget for the month.
      - **previousMonthRolloverAmount** (number) - The rollover amount from the previous month.
      - **rolloverType** (string) - The type of rollover.

### Response Example
```json
{
  "budgetData": {
    "monthlyAmountsByCategory": [
      {
        "category": {
          "id": "cat_groceries",
          "name": "Groceries",
          "icon": "shopping_cart",
          "group": {
            "id": "grp_food",
            "name": "Food",
            "type": "expense"
          }
        },
        "monthlyAmounts": [
          {
            "month": "2024-01",
            "plannedCashFlowAmount": 500.00,
            "plannedSetAsideAmount": 0.00,
            "actualAmount": -450.50,
            "remainingAmount": 49.50,
            "previousMonthRolloverAmount": 0.00,
            "rolloverType": "none"
          }
        ]
      }
    ]
  }
}
```
```

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

### Get Transaction Splits (GraphQL)

Source: https://github.com/crowe452/monarch-money-docs/blob/main/api-reference.md

Retrieves details of a transaction, including its split transactions. Requires the transaction ID. Returns transaction information and its associated splits.

```graphql
query TransactionSplitQuery($id: UUID!) {
  getTransaction(id: $id) {
    id
    amount
    category { id name }
    merchant { id name }
    splitTransactions {
      id
      merchant { id name }
      category { id name }
      amount
      notes
    }
  }
}
```

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

### POST /auth/login/

Source: https://github.com/crowe452/monarch-money-docs/blob/main/api-reference.md

Authenticates a user with credentials to retrieve a session token for subsequent API requests.

```APIDOC
## POST /auth/login/

### Description
Authenticates the user using email and password. Returns a session token required for all GraphQL operations.

### Method
POST

### Endpoint
https://api.monarchmoney.com/auth/login/

### Request Body
- **username** (string) - Required - User email address
- **password** (string) - Required - User account password

### Request Example
{
  "username": "your@email.com",
  "password": "yourpassword"
}

### Response
#### Success Response (200)
- **token** (string) - Authentication token for Authorization header

#### Response Example
{
  "token": "eyJhbGciOiJIUzI1Ni..."
}
```

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

### GetBudgetsWithGoals API

Source: https://github.com/crowe452/monarch-money-docs/blob/main/api-reference.md

Retrieves budget data and associated goals for a specified date range.

```APIDOC
## GET /budgets/goals

### Description
Retrieves budget data and associated goals for a specified date range.

### Method
GET

### Endpoint
/budgets/goals

### Parameters
#### Query Parameters
- **startDate** (Date) - Required - The start date for the budget and goals data.
- **endDate** (Date) - Required - The end date for the budget and goals data.

### Response
#### Success Response (200)
- **budgetData** (object) - Contains monthly amounts by category (same structure as GetBudgets).
- **goalsV2** (object) - Contains a list of financial goals.
  - **goals** (array) - An array of financial goals.
    - **id** (string) - The unique identifier for the goal.
    - **name** (string) - The name of the goal.
    - **type** (string) - The type of the goal.
    - **amount** (number) - The target amount for the goal.
    - **priority** (string) - The priority of the goal.
    - **targetDate** (string) - The target date for the goal.
    - **targetAmount** (number) - The total target amount for the goal.
    - **currentAmount** (number) - The current amount saved towards the goal.
    - **imageUrl** (string) - URL for an image associated with the goal.
    - **accountId** (string) - The ID of the account linked to the goal.
    - **account** (object) - Details of the linked account.
      - **id** (string) - The unique identifier for the account.
      - **displayName** (string) - The display name of the account.
    - **percentageComplete** (number) - The percentage of the goal that is complete.
    - **monthlyContribution** (number) - The recommended monthly contribution towards the goal.
    - **createdAt** (string) - Timestamp when the goal was created.
    - **updatedAt** (string) - Timestamp when the goal was last updated.

### Response Example
```json
{
  "budgetData": {
    "monthlyAmountsByCategory": [
      {
        "category": {
          "id": "cat_123",
          "name": "Vacation Fund",
          "icon": "beach_umbrella",
          "group": {
            "id": "group_xyz",
            "name": "Savings",
            "type": "savings"
          }
        },
        "monthlyAmounts": [
          {
            "month": "2023-10",
            "plannedCashFlowAmount": 200.00,
            "plannedSetAsideAmount": 200.00,
            "actualAmount": 180.00,
            "remainingAmount": 20.00,
            "previousMonthRolloverAmount": 0.00,
            "rolloverType": "none"
          }
        ]
      }
    ]
  },
  "goalsV2": {
    "goals": [
      {
        "id": "goal_456",
        "name": "Dream Vacation",
        "type": "savings",
        "amount": 5000.00,
        "priority": "high",
        "targetDate": "2024-12-31",
        "targetAmount": 5000.00,
        "currentAmount": 1500.00,
        "imageUrl": "https://example.com/images/vacation.jpg",
        "accountId": "acc_789",
        "account": {
          "id": "acc_789",
          "displayName": "High-Yield Savings"
        },
        "percentageComplete": 30.0,
        "monthlyContribution": 145.83,
        "createdAt": "2023-01-15T10:00:00Z",
        "updatedAt": "2023-10-20T14:30:00Z"
      }
    ]
  }
}
```
```

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

### Get Transaction Categories (GraphQL)

Source: https://github.com/crowe452/monarch-money-docs/blob/main/api-reference.md

Retrieves categories specifically for transactions, including icons and order. This query provides a subset of category information relevant to transaction categorization.

```graphql
query GetTransactionCategories {
  categories {
    id
    name
    icon
    order
    systemCategory
    isSystemCategory
    isDisabled
    group {
      id
      name
      type
      order
    }
  }
}
```

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

### Retrieve Budget Data with Python

Source: https://context7.com/crowe452/monarch-money-docs/llms.txt

Fetch comprehensive budget data for a specific date range. This includes planned cash flow, actual spending, and rollover status for each category.

```python
from monarchmoney import MonarchMoney
from datetime import datetime

mm = MonarchMoney(token="your_token")

budgets = await mm.get_budgets(
    start_date="2024-01-01",
    end_date="2024-12-31",
    use_legacy_goals=False,
    use_v2_goals=True
)
```