@lunch-money/v2-api-spec 2.11.0-preview.1 → 2.11.0-preview.3

package/lunch-money-api-v2.yaml

@@ -2,50 +2,37 @@ openapi: 3.0.2
 info:
   title: Lunch Money API - v2
   description: |-
-    Welcome to the documentation for the "next version" of the Lunch Money v2 API.This documentation includes proposed updates to the API design that have not yet been released.<p>
-    This documentation is for the **v2.11.0** release of the API.<p>
-    
-    See the [version history](https://lm-v2-api-next-a7fabcab8e9a.herokuapp.com/v2/version-history) for what is new in this release.
-    New functionality may only be available in the Mock Service until the release is finalized. <br><br>
-
-    The latest complete implementation of the spec is for the **v2.8.5** release and can be found [here](https://lm-v2-api-next-a7fabcab8e9a.herokuapp.com/v2/). <br><br>
-    Feedback on any of the API design is welcome, but we are particularly interested in getting feedback on most recent changes in the [version history](https://lm-v2-api-next-a7fabcab8e9a.herokuapp.com/v2/version-history).
+    Welcome to the Lunch Money v2 API reference. This is the **v2.11.0** spec. It includes previews of the proposed `/crypto` and `/balance_history` endpoints. Only the mock service works with these endpoints.<br><br>
+    The most recent stable version of the API is v2.9.4 and is available at:
+    `https://api.lunchmoney.dev/v2`
 
     ------------------------------------------------------------------------------------------------
-    Welcome to the Lunch Money v2 API.
 
-    A working version of this API is now available through these docs, or directly at:
+    ### Introduction
 
-    `https://api.lunchmoney.dev/v2`
+    The API is available at `https://api.lunchmoney.dev/v2`. Get your access token from the [Lunch Money developers page](https://my.lunchmoney.app/developers).
 
-    <span class="red-text"><strong>This is in alpha launch of a major API update. It is still subject to change during this alpha review 
-    period and bugs may still exist. We strongly encourage users to use the mock service or create a test budget with sample data as the first step to interacting with the v2 API.</strong></span>
-    See the [Getting Started Guide](https://lm-v2-api-next-a7fabcab8e9a.herokuapp.com/v2/getting-started) for more information on using a test budget.<p>
+    <span class="red-text"><strong>The v2 API is in open alpha and is still subject to change. Use the mock server or a test budget when getting started.</strong></span>
 
-    If you are new to the v2 API, you may wish to review the [v2 API Overview of Changes](https://lm-v2-api-next-a7fabcab8e9a.herokuapp.com/v2/changelog).
+    **Static Mock Server**
 
-    ### Static Mock Server
+    Explore the API without an access token or risk to real data. Select **"Static Mock v2 Lunch Money API Server"** from the Server dropdown, then set your Bearer token to any string with 11 or more characters.
 
-    You may also use these docs to explore the API using a static mock server endpoint.<p> 
-    This will allow you to become familiar with the API without having to create an access token, and eliminates the possibility of changing real data. <p>
-    To access this endpoint, select the second endpoint in the "Server" dropdown to the right. When selected, you should see "Static Mock v2 Lunch Money API Server".<br>
-    When using this server, set your Bearer token to any string with 11 or more characters.
+    **Client Libraries & SDKs**
 
-    ### Migrating from V1
+    An official TypeScript SDK is available on [NPM](https://www.npmjs.com/package/@lunch-money/v2-api-spec) and [GitHub](https://github.com/lunch-money/lunch-money-js-v2). For Python or other languages, see [lunchmoney-clients](https://github.com/juftin/lunchmoney-clients) or generate a client from this OpenAPI spec.
 
-    The v2 API is NOT backwards compatible with the v1 API. We encourage developers to review the [Migration Guide](https://lm-v2-api-next-a7fabcab8e9a.herokuapp.com/v2/migration-guide) to understand the changes and plan their migration.
+    **Migrating from v1**
 
-    ### Acknowledgments
+    The v2 API is not backwards compatible with v1. See the [Migration Guide](https://alpha.lunchmoney.dev/v2/migration-guide) for details.
 
-    If you have provided feedback on the API during our ongoing design process, **THANK YOU**. We are thrilled that you can finally interact with the working API we built based on your feedback.
-    
-    ### Useful links:
-    - [Getting Started](https://lm-v2-api-next-a7fabcab8e9a.herokuapp.com/v2/getting-started)
-    - [v2 API Changelog](https://lm-v2-api-next-a7fabcab8e9a.herokuapp.com/v2/changelog)
-    - [Migration Guide](https://lm-v2-api-next-a7fabcab8e9a.herokuapp.com/v2/migration-guide)
-    - [Rate Limits](https://lm-v2-api-next-a7fabcab8e9a.herokuapp.com/v2/rate-limits)
-    - [Current v1 Lunch Money API Documentation](https://lunchmoney.dev)
-    - [Awesome Lunch Money Projects](https://github.com/lunch-money/awesome-lunchmoney?tab=readme-ov-file)
+    **Useful links**
+    - [Developer Portal](https://alpha.lunchmoney.dev/v2/introduction)
+    - [Getting Started Guide](https://alpha.lunchmoney.dev/v2/getting-started)
+    - [v2 API Overview](https://alpha.lunchmoney.dev/v2/overview)
+    - [Version History](https://alpha.lunchmoney.dev/v2/version-history)
+    - [Migration Guide](https://alpha.lunchmoney.dev/v2/migration-guide)
+    - [Rate Limits](https://alpha.lunchmoney.dev/v2/rate-limits)
   termsOfService: https://lunchmoney.dev/#current-status
   contact:
     email: devsupport@lunchmoney.app
@@ -679,7 +666,6 @@ components:
     cryptoManualObject:
       type: object
       title: manual crypto object
-      x-internal: true
       additionalProperties: false
       properties:
         id:
@@ -719,13 +705,22 @@ components:
           description: CoinGecko identifier associated with this balance
         to_base:
           type: number
-          description: Balance converted to the user's primary currency
+          nullable: true
+          description: Balance converted to the user's primary currency. May be null if no conversion was available.
         balance_as_of:
           type: string
           format: date-time
           nullable: true
-          description: Date/time the balance was last updated in ISO 8601
-            extended format
+          description: Date/time the manual balance record was last updated in
+            ISO 8601 extended format. This is currently based on the manual
+            crypto record's updated_at timestamp.
+        exchange_rate_as_of:
+          type: string
+          format: date-time
+          nullable: true
+          description: Date/time the exchange rate used to calculate to_base was
+            last updated in ISO 8601 extended format. Null when no exchange rate was
+            used or no conversion was available.
         created_by_name:
           type: string
           nullable: true
@@ -750,6 +745,7 @@ components:
         - coingecko_id
         - to_base
         - balance_as_of
+        - exchange_rate_as_of
         - created_by_name
         - created_at
         - updated_at
@@ -758,7 +754,6 @@ components:
     cryptoSyncedBalance:
       type: object
       title: synced crypto balance object
-      x-internal: true
       additionalProperties: false
       properties:
         name:
@@ -783,13 +778,21 @@ components:
           description: CoinGecko identifier associated with this balance
         to_base:
           type: number
-          description: Balance converted to the user's primary currency
+          nullable: true
+          description: Balance converted to the user's primary currency. May be null if no conversion was available.
         balance_as_of:
           type: string
           format: date-time
           nullable: true
           description: Date/time the balance was last updated in ISO 8601
-            extended format
+            extended format.
+        exchange_rate_as_of:
+          type: string
+          format: date-time
+          nullable: true
+          description: Date/time the exchange rate used to calculate to_base was
+            last updated in ISO 8601 extended format. Null when no exchange rate was
+            used or no conversion was available.
         updated_at:
           type: string
           format: date-time
@@ -802,12 +805,12 @@ components:
         - coingecko_id
         - to_base
         - balance_as_of
+        - exchange_rate_as_of
         - updated_at
 
     syncedCryptoAccount:
       type: object
       title: synced crypto account
-      x-internal: true
       additionalProperties: false
       properties:
         id:
@@ -1072,8 +1075,16 @@ components:
           type: string
           format: date-time
           nullable: true
-          description: System defined date/time the balance was last updated in
-            ISO 8601 extended format. Ignored if set
+          description: System defined date/time the manual balance record was
+            last updated in ISO 8601 extended format. Ignored if set
+          x-updatable: false
+        exchange_rate_as_of:
+          type: string
+          format: date-time
+          nullable: true
+          description: System defined date/time the exchange rate used to
+            calculate to_base was observed in ISO 8601 extended format. Ignored
+            if set
           x-updatable: false
         created_by_name:
           type: string
@@ -1614,6 +1625,7 @@ components:
       type: object
       description: Source information for a manual account balance history entry.
       additionalProperties: false
+      x-internal: true
       properties:
         type:
           type: string
@@ -1631,6 +1643,7 @@ components:
       type: object
       description: Source information for a Plaid-synced account balance history entry.
       additionalProperties: false
+      x-internal: true
       properties:
         type:
           type: string
@@ -1648,6 +1661,7 @@ components:
       type: object
       description: Source information for a manually-tracked cryptocurrency balance history entry.
       additionalProperties: false
+      x-internal: true
       properties:
         type:
           type: string
@@ -1750,9 +1764,10 @@ components:
         - subtype
         - mask
         - symbol
+
     balanceHistoryAccountObject:
       type: object
-      title: balance history account object
+      title: balance history for an account object
       additionalProperties: false
       description: Historical balance entries grouped under a single account source.
       properties:
@@ -1787,6 +1802,7 @@ components:
       type: object
       title: balance history entry object
       additionalProperties: false
+      x-internal: true
       description: A historical balance entry for a single account on a single date.
       properties:
         id:
@@ -2495,8 +2511,6 @@ components:
             Any transaction notes set by the user or by 
             a matched recurring item. This will match the value 
             displayed in notes field on the transactions page in the Lunch Money app.
-          minLength: 0
-          maxLength: 350
         status:
           type: string
           # description: >
@@ -2732,8 +2746,6 @@ components:
             Any transaction notes set by the user or by 
             a matched recurring item. This will match the value 
             displayed in notes field on the transactions page in the Lunch Money app.
-          minLength: 0
-          maxLength: 350
         status:
           type: string
           description: >
@@ -2978,8 +2990,6 @@ components:
             Any transaction notes set by the user or by 
             a matched recurring item. This will match the value 
             displayed in notes field on the transactions page in the Lunch Money app.
-          minLength: 0
-          maxLength: 350
         manual_account_id:
           type: integer
           format: int32
@@ -3117,8 +3127,6 @@ components:
           description: >
             New notes for the transaction. Set this to an empty string to clear
             the existing notes.
-          minLength: 0
-          maxLength: 350
           x-updatable: true
         manual_account_id:
           type: integer
@@ -3301,6 +3309,7 @@ components:
             amount.
         payee:
           type: string
+          minLength: 0
           description: The payee for the child transaction. Will inherit the
             original payee from the parent if not defined.
         date:
@@ -3323,7 +3332,6 @@ components:
             format: int32
         notes:
           type: string
-          maxLength: 350
           description: Will inherit notes from parent if not defined.
       required:
         - amount
@@ -4114,6 +4122,7 @@ components:
       #   - `cad`: Canadian Dollar
       #   - `cdf`: Congolese Franc
       #   - `chf`: Swiss Franc
+      #   - `clf`: Chilean Unit of Account (UF)
       #   - `clp`: Chilean Peso
       #   - `cny`: Chinese Yuan
       #   - `cop`: Colombian Peso
@@ -4129,6 +4138,7 @@ components:
       #   - `egp`: Egyptian Pound
       #   - `ern`: Eritrean Nakfa
       #   - `etb`: Ethiopian Birr
+      #   - `eth`: Ethereum
       #   - `eur`: Euro
       #   - `fjd`: Fijian Dollar
       #   - `fkp`: Falkland Islands Pound
@@ -4236,10 +4246,13 @@ components:
       #   - `uyu`: Uruguayan Peso
       #   - `uzs`: Uzbekistan Som
       #   - `vef`: Venezuelan Bolívar
+      #   - `ves`: Venezuelan Bolívar Sotiemas
       #   - `vnd`: Vietnamese Dong
       #   - `vuv`: Vanuatu Vatu
       #   - `wst`: Samoan Tala
       #   - `xaf`: CFA Franc BEAC
+      #   - `xag`: Silver (troy ounce)
+      #   - `xau`: Gold (troy ounce)
       #   - `xcd`: East Caribbean Dollar
       #   - `xof`: CFA Franc BCEAO
       #   - `xpf`: CFP Franc
@@ -4277,6 +4290,7 @@ components:
         - cad
         - cdf
         - chf
+        - clf
         - clp
         - cny
         - cop
@@ -4292,6 +4306,7 @@ components:
         - egp
         - ern
         - etb
+        - eth
         - eur
         - fjd
         - fkp
@@ -4399,10 +4414,13 @@ components:
         - uyu
         - uzs
         - vef
+        - ves
         - vnd
         - vuv
         - wst
         - xaf
+        - xag
+        - xau
         - xcd
         - xof
         - xpf
@@ -5901,6 +5919,7 @@ paths:
                     coingecko_id: bitcoin
                     to_base: 53124.72
                     balance_as_of: "2026-02-25T14:22:10.000Z"
+                    exchange_rate_as_of: "2026-02-25T14:10:00.000Z"
                     created_by_name: User 1
                     created_at: "2025-11-12T20:14:32.000Z"
                     updated_at: "2026-02-25T14:22:10.000Z"
@@ -5958,6 +5977,7 @@ paths:
                 coingecko_id: ethereum
                 to_base: 28998.44
                 balance_as_of: "2026-03-01T09:20:41.000Z"
+                exchange_rate_as_of: "2026-03-01T09:15:00.000Z"
                 created_by_name: User 1
                 created_at: "2026-03-01T09:20:41.000Z"
                 updated_at: "2026-03-01T09:20:41.000Z"
@@ -6025,6 +6045,7 @@ paths:
                 coingecko_id: bitcoin
                 to_base: 53124.72
                 balance_as_of: "2026-02-25T14:22:10.000Z"
+                exchange_rate_as_of: "2026-02-25T14:10:00.000Z"
                 created_by_name: User 1
                 created_at: "2025-11-12T20:14:32.000Z"
                 updated_at: "2026-02-25T14:22:10.000Z"
@@ -6102,6 +6123,7 @@ paths:
                   coingecko_id: bitcoin
                   to_base: 56011.12
                   balance_as_of: "2026-03-01T09:41:18.000Z"
+                  exchange_rate_as_of: "2026-03-01T09:35:00.000Z"
                   created_by_name: User 1
                   created_at: "2025-11-12T20:14:32.000Z"
                   updated_at: "2026-02-25T14:22:10.000Z"
@@ -6122,6 +6144,7 @@ paths:
                 coingecko_id: bitcoin
                 to_base: 56011.12
                 balance_as_of: "2026-03-01T09:41:18.000Z"
+                exchange_rate_as_of: "2026-03-01T09:35:00.000Z"
                 created_by_name: User 1
                 created_at: "2025-11-12T20:14:32.000Z"
                 updated_at: "2026-03-01T09:41:18.000Z"
@@ -6251,6 +6274,7 @@ paths:
                         coingecko_id: ethereum
                         to_base: 28998.44
                         balance_as_of: "2026-02-25T14:25:00.000Z"
+                        exchange_rate_as_of: "2026-02-25T14:20:00.000Z"
                         updated_at: "2026-02-25T14:25:01.000Z"
                       - name: BTC
                         balance: "0.100020003000400050"
@@ -6258,6 +6282,7 @@ paths:
                         coingecko_id: bitcoin
                         to_base: 6231.28
                         balance_as_of: "2026-02-25T14:25:00.000Z"
+                        exchange_rate_as_of: "2026-02-25T14:20:00.000Z"
                         updated_at: "2026-02-25T14:25:01.000Z"
                   - id: 33005
                     provider: kraken
@@ -6273,6 +6298,7 @@ paths:
                         coingecko_id: ripple
                         to_base: 1287.50
                         balance_as_of: "2026-02-26T07:22:30.000Z"
+                        exchange_rate_as_of: "2026-02-26T07:10:00.000Z"
                         updated_at: "2026-02-26T07:22:30.000Z"
         "401":
           $ref: "#/components/responses/unauthorizedToken"
@@ -6325,6 +6351,7 @@ paths:
                     coingecko_id: ethereum
                     to_base: 28998.44
                     balance_as_of: "2026-02-25T14:25:00.000Z"
+                    exchange_rate_as_of: "2026-02-25T14:20:00.000Z"
                     updated_at: "2026-02-25T14:25:01.000Z"
                   - name: BTC
                     balance: "0.100020003000400050"
@@ -6332,6 +6359,7 @@ paths:
                     coingecko_id: bitcoin
                     to_base: 6231.28
                     balance_as_of: "2026-02-25T14:25:00.000Z"
+                    exchange_rate_as_of: "2026-02-25T14:20:00.000Z"
                     updated_at: "2026-02-25T14:25:01.000Z"
         "400":
           description: Bad Request
@@ -6397,6 +6425,7 @@ paths:
                 coingecko_id: ethereum
                 to_base: 28998.44
                 balance_as_of: "2026-02-25T14:25:00.000Z"
+                exchange_rate_as_of: "2026-02-25T14:20:00.000Z"
                 updated_at: "2026-02-25T14:25:01.000Z"
         "400":
           description: Bad Request
@@ -6482,6 +6511,7 @@ paths:
                     coingecko_id: ethereum
                     to_base: 28998.44
                     balance_as_of: "2026-02-25T14:25:00.000Z"
+                    exchange_rate_as_of: "2026-02-25T14:20:00.000Z"
                     updated_at: "2026-02-25T14:25:01.000Z"
                   - name: BTC
                     balance: "0.100020003000400050"
@@ -6489,6 +6519,7 @@ paths:
                     coingecko_id: bitcoin
                     to_base: 6231.28
                     balance_as_of: "2026-02-25T14:25:00.000Z"
+                    exchange_rate_as_of: "2026-02-25T14:20:00.000Z"
                     updated_at: "2026-02-25T14:25:01.000Z"
         "401":
           $ref: "#/components/responses/unauthorizedToken"
@@ -10190,7 +10221,7 @@ paths:
                   description: |
                     The payee for the new grouped transaction.
                   minLength: 0
-                  maxLength: 1000
+
                 category_id:
                   type: integer
                   format: int64
@@ -10205,8 +10236,6 @@ paths:
                   nullable: true
                   description: |
                     Notes for the grouped transaction.
-                  minLength: 0
-                  maxLength: 350
                 status:
                   type: string
                   description: If set, must be either `reviewed` or

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lunch-money/v2-api-spec",
-  "version": "2.11.0-preview.1",
+  "version": "2.11.0-preview.3",
   "description": "OpenAPI specification and version history for the Lunch Money v2 API",
   "main": "lunch-money-api-v2.yaml",
   "files": [

package/version-history.md

@@ -24,8 +24,15 @@ The Lunch Money API spec uses a modified version of SEMVER for its versioning me
   - Viewing the balances for currencies associated with both manually managed crypto assets and those that are synced via a synced crypto account (ie: coinbase, kraken, ethereum wallet)
   - Refreshing synced crypto account balances
 
+## v2.9.4 - May 23, 2026
+- Increase allowable length for transaction `notes`.
+- Add `clf`, `eth`, and `ves` to the supported currency codes.
+
+## v2.9.3 - Apr 27, 2026
+- Add `xag` and `xau` to the supported currency codes.
+
 ## v2.9.2 - Apr 22, 2026
-- Increase allowable length for a transaction `payee`
+- Increase allowable length for a transaction `payee`.
 
 ## v2.9.1 - Apr 22, 2026
 - You may now set `archived_at` when modifying a category or tag via the `PUT /categories` or `PUT /tags` endpoints.