@lunch-money/v2-api-spec 2.9.0 → 2.10.0-preview.1

package/README.md.backup

@@ -66,18 +66,6 @@ The OpenAPI spec is the authoritative source for:
 - Authentication requirements
 - Status codes and error formats
 
-##### Versioning
-
-The Lunch Money API spec uses a modified version of SEMVER for its versioning methodology as follows
-- The major version is the API version.  This will always be 2 in this repo
-- The minor version represents the number of main endpoints (or OpenAPI tags) the current version of the spec supports.  For example, a version of the API that supports the /me, /categories, and /transactions endpoints would have a minor version of 3
-- The revision number represents the number of updates since the last endpoint was added.  For example, each time changes are made to one of the existing three APIs as described above, the revision number will be bumped.
-
-Details of each version can be found in [./version-history.md](./version-history.md)
-
-Changes to the spec that modify existing or add new API endpoints should update the version number in the spec and in the package.json accordingly.
-
-
 ### Documentation Guides (`v2/docs/*.md`)
 - **Purpose**: Human-readable guides and tutorials
 - **Format**: Markdown with custom extensions

package/lunch-money-api-v2.yaml

@@ -42,7 +42,7 @@ info:
   license:
     name: Apache 2.0
     url: http://www.apache.org/licenses/LICENSE-2.0.html
-  version: 2.9.0
+  version: 2.10.0
 
 servers:
   - url: https://api.lunchmoney.dev/v2
@@ -68,6 +68,11 @@ tags:
     externalDocs:
       description: Learn more about synced accounts
       url: https://support.lunchmoney.app/setup/linked-accounts#how-often-should-i-expect-new-transactions-to-get-imported
+  - name: crypto
+    description: Work with manual and synced crypto assets
+    externalDocs:
+      description: Learn more about crypto assets
+      url: https://support.lunchmoney.app/setup/crypto
   - name: recurring_items
     description: Work with recurring items
     externalDocs:
@@ -622,6 +627,347 @@ components:
         - category_name
         - dependents
 
+    # The base object containing information about a crypto balance
+    cryptoBalanceObject:
+      type: object
+      title: crypto balance object
+      additionalProperties: false
+      description: The balance for a single crypto asset
+      properties:
+        id:
+          type: integer
+          format: int32
+          description: A system defined unique ID for the crypto asset if the source is "manual" or the synced connection ID if the source is "synced"
+        source:
+          type: string
+          description: The source type for this crypto asset
+          enum:
+            - manual
+            - synced
+        name:
+          type: string
+          nullable: true
+          minLength: 1
+          maxLength: 45
+          description: The name of the crypto asset
+        display_name:
+          type: string
+          nullable: true
+          description: Optional display name for the crypto asset
+        institution_name:
+          type: string
+          nullable: true
+          minLength: 1
+          maxLength: 50
+          description: Institution or wallet provider display name
+        balance:
+          type: string
+          pattern: ^-?\d+(\.\d{1,18})?$
+          description: Current balance in numeric format to 18 decimal places
+        currency:
+          type: string
+          minLength: 1
+          maxLength: 10
+          description: Cryptocurrency symbol
+        coingecko_id:
+          type: string
+          nullable: true
+          minLength: 1
+          maxLength: 100
+          description: CoinGecko identifier associated with this balance
+        to_base:
+          type: number
+          description: Balance converted to the user's primary currency
+        balance_as_of:
+          type: string
+          format: date-time
+          nullable: true
+          description: Date/time the balance was last updated in ISO 8601 extended format
+        last_import:
+          type: string
+          format: date-time
+          nullable: true
+          description: Timestamp in ISO 8601 extended format of the last successful import
+        status:
+          type: string
+          description: Status of the crypto asset
+          enum:
+            - active
+            - unsupported
+            - relink
+            - initializing
+        created_by_name:
+          type: string
+          nullable: true
+          description: Name of the user who created the crypto asset
+        created_at:
+          type: string
+          format: date-time
+          description: Date/time the crypto asset was created in ISO 8601 extended format
+        updated_at:
+          type: string
+          format: date-time
+          description: Date/time the crypto asset was last updated in ISO 8601 extended format
+      required:
+        - id
+        - source
+        - name
+        - display_name
+        - institution_name
+        - balance
+        - currency
+        - coingecko_id
+        - to_base
+        - balance_as_of
+        - last_import
+        - status
+        - created_by_name
+        - created_at
+        - updated_at
+
+    # Manual crypto balance type derived from cryptoBalanceObject
+    cryptoManualObject:
+      title: manual crypto object
+      x-internal: true
+      allOf:
+        - $ref: "#/components/schemas/cryptoBalanceObject"
+        - type: object
+          properties:
+            source:
+              type: string
+              description: The source type for this crypto asset. Will always be "manual" for manual crypto assets.
+              enum:
+                - manual
+            status:
+              type: string
+              description: Status of the manual crypto asset
+              enum:
+                - active
+            currency:
+              type: string
+              minLength: 1
+              maxLength: 10
+              description: Cryptocurrency symbol is supported by Lunch Money for manual tracking
+
+    # Synced crypto balance type derived from cryptoBalanceObject
+    cryptoSyncedObject:
+      title: synced crypto object
+      x-internal: true
+      allOf:
+        - $ref: "#/components/schemas/cryptoBalanceObject"
+        - type: object
+          properties:
+            source:
+              type: string
+              description: The source type for this crypto asset. Will always be "synced" for synced crypto assets.
+              enum:
+                - synced
+            status:
+              type: string
+              description: Status of the synced connection
+              enum:
+                - active
+                - unsupported
+                - relink
+                - initializing
+            currency:
+              type: string
+              minLength: 1
+              maxLength: 10
+              description: Symbol of the currency held in the synced account.
+
+    # Response object returned by GET /crypto
+    cryptoListResponseObject:
+      type: object
+      x-internal: true
+      additionalProperties: false
+      properties:
+        crypto:
+          type: array
+          items:
+            $ref: "#/components/schemas/cryptoBalanceObject"
+      required:
+        - crypto
+
+    # Response object returned by GET /crypto/manual
+    cryptoManualListResponseObject:
+      type: object
+      x-internal: true
+      additionalProperties: false
+      properties:
+        crypto_manual:
+          type: array
+          items:
+            $ref: "#/components/schemas/cryptoManualObject"
+      required:
+        - crypto_manual
+
+    # Response object returned by GET /crypto/synced and GET /crypto/synced/{id}
+    cryptoSyncedListResponseObject:
+      type: object
+      x-internal: true
+      additionalProperties: false
+      properties:
+        crypto_synced:
+          type: array
+          items:
+            $ref: "#/components/schemas/cryptoSyncedObject"
+      required:
+        - crypto_synced
+
+    # The object that may be submitted to POST /crypto/manual
+    createCryptoManualRequestObject:
+      type: object
+      additionalProperties: false
+      x-internal: true
+      properties:
+        name:
+          type: string
+          minLength: 1
+          maxLength: 45
+          description: The name of the manual crypto asset
+          example: Hardware Wallet
+        display_name:
+          type: string
+          minLength: 1
+          maxLength: 45
+          description: Optional display name for the manual crypto asset
+          example: Cold Storage
+        institution_name:
+          type: string
+          minLength: 1
+          maxLength: 50
+          description: Optional institution or wallet provider display name
+          example: Ledger
+        balance:
+          oneOf:
+            - type: number
+              format: double
+            - type: string
+              pattern: ^-?\d+(\.\d{1,18})?$
+          description: Numeric value of the balance, up to 18 decimal places
+          example: "0.523400000000000000"
+        currency:
+          type: string
+          minLength: 1
+          maxLength: 10
+          description: Cryptocurrency symbol is supported by Lunch Money for manual tracking
+          example: btc
+        coingecko_id:
+          type: string
+          minLength: 1
+          maxLength: 100
+          description: CoinGecko identifier for this crypto asset
+          example: bitcoin
+      required:
+        - name
+        - balance
+        - coingecko_id
+        - currency
+
+    # The object that may be submitted to PUT /crypto/manual/{id}
+    updateCryptoManualRequestObject:
+      type: object
+      x-internal: true
+      additionalProperties: false
+      properties:
+        id:
+          type: integer
+          format: int32
+          description: System defined unique ID for the manual crypto asset. Ignored if set
+          x-updatable: false
+        source:
+          type: string
+          description: System defined source for the crypto asset. Ignored if set
+          enum:
+            - manual
+          x-updatable: false
+        name:
+          type: string
+          nullable: true
+          minLength: 1
+          maxLength: 45
+          description: If set, the new name of the manual crypto asset
+          x-updatable: true
+        display_name:
+          type: string
+          nullable: true
+          minLength: 1
+          maxLength: 45
+          description: If set, the new display name for the manual crypto asset
+          x-updatable: true
+        institution_name:
+          type: string
+          nullable: true
+          minLength: 1
+          maxLength: 50
+          description: If set, the new institution or wallet provider display name
+          x-updatable: true
+        balance:
+          oneOf:
+            - type: number
+              format: double
+            - type: string
+              pattern: ^-?\d+(\.\d{1,18})?$
+          description: If set, the new balance value up to 18 decimal places
+          example: "1.050000000000000000"
+          x-updatable: true
+        currency:
+          type: string
+          minLength: 1
+          maxLength: 10
+          description: Cryptocurrency symbol is supported by Lunch Money for manual tracking. Ignored if set
+          x-updatable: false
+        coingecko_id:
+          type: string
+          nullable: true
+          minLength: 1
+          maxLength: 100
+          description: System defined CoinGecko identifier associated with this balance. Ignored if set
+          x-updatable: false
+        to_base:
+          type: number
+          description: System defined balance converted to the user's primary currency. Ignored if set
+          x-updatable: false
+        balance_as_of:
+          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
+          x-updatable: false
+        last_import:
+          type: string
+          format: date-time
+          nullable: true
+          description: System defined timestamp in ISO 8601 extended format of the last successful import. Ignored if set
+          x-updatable: false
+        status:
+          type: string
+          description: System defined status of the crypto asset. Ignored if set
+          enum:
+            - active
+            - unsupported
+            - relink
+            - initializing
+          x-updatable: false
+        created_by_name:
+          type: string
+          nullable: true
+          description: System defined name of the user who created the crypto asset. Ignored if set
+          x-updatable: false
+        created_at:
+          type: string
+          format: date-time
+          description: System defined date/time the crypto asset was created in ISO 8601 extended format. Ignored if set
+          x-updatable: false
+        updated_at:
+          type: string
+          format: date-time
+          description: System defined date/time the crypto asset was last updated in ISO 8601 extended format. Ignored if set
+          x-updatable: false
+      description: Update a manual crypto balance. System-defined properties are accepted but ignored
+
+
     # The object containing information about a manual account
     manualAccountObject:
       type: object
@@ -4461,7 +4807,7 @@ paths:
               example:
                 message: Not Found
                 errors:
-                  - errMsg: There is no category with the id:'543210'`
+                  - errMsg: "There is no category with the id: 543210."
         "429":
           $ref: "#/components/responses/rateLimited"
         "500":
@@ -4621,7 +4967,7 @@ paths:
               example:
                 message: Not Found
                 errors:
-                  - errMsg: There is no category with the id:'543210'`
+                  - errMsg: "There is no category with the id: 543210."
         "429":
           $ref: "#/components/responses/rateLimited"
         "500":
@@ -4676,9 +5022,9 @@ paths:
               example:
                 message: Not Found
                 errors:
-                  - errMsg: There is no category with the id:'543210'`
+                  - errMsg: "There is no category with the id: 543210."
         "422":
-          description: Unprocessable Entity
+          description: Unprocessable Content
           content:
             application/json:
               schema:
@@ -4710,46 +5056,648 @@ paths:
           $ref: "#/components/responses/rateLimited"
         "500":
           $ref: "#/components/responses/serverError"
-  /manual_accounts:
+  /crypto:
     get:
       tags:
-        - manual_accounts
-      summary: Get all manual accounts
-      description: Retrieve a list of all manually-managed accounts associated with
-        the user's account.
-      operationId: getAllManualAccounts
+        - crypto
+      summary: Get all crypto balances
+      description: Retrieve all crypto balances associated with the user's account, including both manual and synced sources.
+      operationId: getAllCrypto
       responses:
         "200":
-          description: A list of manual accounts
+          description: A list of crypto balances
           content:
             application/json:
               schema:
-                type: object
-                properties:
-                  manual_accounts:
-                    type: array
-                    items:
-                      $ref: "#/components/schemas/manualAccountObject"
+                $ref: "#/components/schemas/cryptoListResponseObject"
               example:
-                manual_accounts:
-                  - id: 119807
-                    name: Individual Brokerage
-                    institution_name: Fidelity
-                    display_name: null
-                    type: investment
-                    subtype: brokerage
-                    balance: "41211.8000"
-                    currency: usd
-                    to_base: 41211.8
-                    balance_as_of: "2025-06-25T17:00:04.000Z"
+                crypto:
+                  - id: 22001
+                    source: manual
+                    name: Cold Wallet BTC
+                    display_name: Long-term BTC
+                    institution_name: Ledger
+                    balance: "0.852341920145782301"
+                    currency: btc
+                    coingecko_id: bitcoin
+                    to_base: 53124.72
+                    balance_as_of: "2026-02-25T14:22:10.000Z"
+                    last_import: null
                     status: active
-                    closed_on: null
-                    external_id: null
-                    exclude_from_transactions: false
                     created_by_name: User 1
-                    created_at: "2025-06-25T17:00:04.414Z"
-                    updated_at: "2025-06-26T19:03:38.312Z"
-                  - id: 119909
+                    created_at: "2025-11-12T20:14:32.000Z"
+                    updated_at: "2026-02-25T14:22:10.000Z"
+                  - id: 33004
+                    source: synced
+                    name: ETH
+                    display_name: Coinbase Main
+                    institution_name: Coinbase
+                    balance: "12.004500000000000000"
+                    currency: eth
+                    coingecko_id: ethereum
+                    to_base: 28998.44
+                    balance_as_of: "2026-02-25T14:25:00.000Z"
+                    last_import: "2026-02-25T14:25:01.000Z"
+                    status: active
+                    created_by_name: User 1
+                    created_at: "2025-10-02T11:02:09.000Z"
+                    updated_at: "2026-02-25T14:25:01.000Z"
+        "401":
+          $ref: "#/components/responses/unauthorizedToken"
+        "429":
+          $ref: "#/components/responses/rateLimited"
+        "500":
+          $ref: "#/components/responses/serverError"
+  /crypto/manual:
+    get:
+      tags:
+        - crypto
+      summary: Get all manual crypto balances
+      description: Retrieve all manually managed crypto balances associated with the user's account.
+      operationId: getAllCryptoManual
+      responses:
+        "200":
+          description: A list of manual crypto balances
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/cryptoManualListResponseObject"
+              example:
+                crypto_manual:
+                  - id: 22001
+                    source: manual
+                    name: Cold Wallet BTC
+                    display_name: Long-term BTC
+                    institution_name: Ledger
+                    balance: "0.852341920145782301"
+                    currency: btc
+                    coingecko_id: bitcoin
+                    to_base: 53124.72
+                    balance_as_of: "2026-02-25T14:22:10.000Z"
+                    last_import: null
+                    status: active
+                    created_by_name: User 1
+                    created_at: "2025-11-12T20:14:32.000Z"
+                    updated_at: "2026-02-25T14:22:10.000Z"
+        "401":
+          $ref: "#/components/responses/unauthorizedToken"
+        "429":
+          $ref: "#/components/responses/rateLimited"
+        "500":
+          $ref: "#/components/responses/serverError"
+    post:
+      tags:
+        - crypto
+      summary: Create a manual crypto balance
+      description: Create a manually managed crypto asset.
+      operationId: createCryptoManual
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/createCryptoManualRequestObject"
+            examples:
+              minimum request body:
+                summary: Minimum required fields
+                value:
+                  name: Cold Wallet BTC
+                  balance: "0.852341920145782301"
+                  currency: btc
+                  coingecko_id: bitcoin
+              full request body:
+                summary: Full example with optional display fields
+                value:
+                  name: Coinbase ETH Holdings
+                  display_name: Trading ETH
+                  institution_name: Coinbase
+                  balance: "12.004500000000000000"
+                  currency: eth
+                  coingecko_id: ethereum
+      responses:
+        "201":
+          description: Manual crypto balance created successfully
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/cryptoManualObject"
+              example:
+                id: 22045
+                source: manual
+                name: Coinbase ETH Holdings
+                display_name: Trading ETH
+                institution_name: Coinbase
+                balance: "12.004500000000000000"
+                currency: eth
+                coingecko_id: ethereum
+                to_base: 28998.44
+                balance_as_of: "2026-03-01T09:20:41.000Z"
+                last_import: null
+                status: active
+                created_by_name: User 1
+                created_at: "2026-03-01T09:20:41.000Z"
+                updated_at: "2026-03-01T09:20:41.000Z"
+        "400":
+          description: Invalid request body
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/errorResponseObject"
+              examples:
+                missing required properties:
+                  value:
+                    message: Request Validation Failure
+                    errors:
+                      - errMsg: "Missing required property 'name' in request body."
+                      - errMsg: "Missing required property 'balance' in request body."
+                      - errMsg: "Missing required property 'currency' in request body."
+                      - errMsg: "Missing required property 'coingecko_id' in request body."
+        "401":
+          $ref: "#/components/responses/unauthorizedToken"
+        "429":
+          $ref: "#/components/responses/rateLimited"
+        "500":
+          $ref: "#/components/responses/serverError"
+  /crypto/manual/{id}:
+    get:
+      tags:
+        - crypto
+      summary: Get a single manual crypto balance
+      description: Retrieve a single manually managed crypto balance by ID.
+      operationId: getCryptoManualById
+      parameters:
+        - name: id
+          in: path
+          description: ID of the manual crypto balance to retrieve
+          required: true
+          schema:
+            type: integer
+            format: int32
+          examples:
+            existing manual crypto:
+              summary: Existing manual crypto ID
+              value: 22001
+            id not found:
+              summary: Example of an id that doesn't exist
+              value: 99999999
+      responses:
+        "200":
+          description: Manual crypto balance object
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/cryptoManualObject"
+              example:
+                id: 22001
+                source: manual
+                name: Cold Wallet BTC
+                display_name: Long-term BTC
+                institution_name: Ledger
+                balance: "0.852341920145782301"
+                currency: btc
+                coingecko_id: bitcoin
+                to_base: 53124.72
+                balance_as_of: "2026-02-25T14:22:10.000Z"
+                last_import: null
+                status: active
+                created_by_name: User 1
+                created_at: "2025-11-12T20:14:32.000Z"
+                updated_at: "2026-02-25T14:22:10.000Z"
+        "400":
+          description: Bad Request
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/errorResponseObject"
+              example:
+                message: Invalid Path Parameters
+                errors:
+                  - errMsg: "Invalid value type for path parameter: 'id'. Expected 'number', received 'string'."
+        "401":
+          $ref: "#/components/responses/unauthorizedToken"
+        "404":
+          description: Not Found
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/errorResponseObject"
+              example:
+                message: Not Found
+                errors:
+                  - errMsg: "There is no manual crypto balance with the id: 99999999."
+        "429":
+          $ref: "#/components/responses/rateLimited"
+        "500":
+          $ref: "#/components/responses/serverError"
+    put:
+      tags:
+        - crypto
+      summary: Update a manual crypto balance
+      description: >-
+        Modify a manually managed crypto balance.<br><br>
+
+        You may submit the response from `GET /crypto/manual/{id}` as the request body. System-defined properties
+        are accepted and ignored according to the `x-updatable` metadata in the update schema.
+      operationId: updateCryptoManual
+      parameters:
+        - name: id
+          in: path
+          description: ID of the manual crypto balance to update
+          required: true
+          schema:
+            type: integer
+            format: int32
+          examples:
+            existing manual crypto:
+              summary: Existing manual crypto ID
+              value: 22001
+            id not found:
+              summary: Example of an id that doesn't exist
+              value: 99999999
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/updateCryptoManualRequestObject"
+            examples:
+              minimum request body:
+                summary: Update balance only
+                value:
+                  balance: "0.900000000000000000"
+              full get response body:
+                summary: Full object payload with system fields tolerated
+                value:
+                  id: 22001
+                  source: manual
+                  name: Cold Wallet BTC
+                  display_name: Long-term BTC
+                  institution_name: Ledger
+                  balance: "0.900000000000000000"
+                  currency: btc
+                  coingecko_id: bitcoin
+                  to_base: 56011.12
+                  balance_as_of: "2026-03-01T09:41:18.000Z"
+                  last_import: null
+                  status: active
+                  created_by_name: User 1
+                  created_at: "2025-11-12T20:14:32.000Z"
+                  updated_at: "2026-02-25T14:22:10.000Z"
+      responses:
+        "200":
+          description: Manual crypto balance updated successfully
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/cryptoManualObject"
+              example:
+                id: 22001
+                source: manual
+                name: Cold Wallet BTC
+                display_name: Long-term BTC
+                institution_name: Ledger
+                balance: "0.900000000000000000"
+                currency: btc
+                coingecko_id: bitcoin
+                to_base: 56011.12
+                balance_as_of: "2026-03-01T09:41:18.000Z"
+                last_import: null
+                status: active
+                created_by_name: User 1
+                created_at: "2025-11-12T20:14:32.000Z"
+                updated_at: "2026-03-01T09:41:18.000Z"
+        "400":
+          description: Bad Request
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/errorResponseObject"
+              examples:
+                missing updatable properties:
+                  value:
+                    message: Invalid Request Body
+                    errors:
+                      - errMsg: "A request to update a manual crypto balance must include at least one updatable property: name, display_name, institution_name, balance"
+        "401":
+          $ref: "#/components/responses/unauthorizedToken"
+        "404":
+          description: Not Found
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/errorResponseObject"
+              example:
+                message: Not Found
+                errors:
+                  - errMsg: "There is no manual crypto balance with the id: 99999999."
+        "429":
+          $ref: "#/components/responses/rateLimited"
+        "500":
+          $ref: "#/components/responses/serverError"
+    delete:
+      tags:
+        - crypto
+      summary: Delete a manual crypto balance
+      description: Delete a single manually managed crypto asset by ID.<p>
+        If this crypto asset has a balance history, and you do not explicitly set the query parameter`keep_history`, a 422 response will be returned requesting you to explicitly set `keep_history` to `true` or `false`.
+      operationId: deleteCryptoManual
+      parameters:
+        - name: id
+          in: path
+          description: ID of the manual crypto balance to delete
+          required: true
+          schema:
+            type: integer
+            format: int32
+          examples:
+            existing manual crypto:
+              summary: Existing manual crypto ID
+              value: 22001
+            id not found:
+              summary: Example of an id that doesn't exist
+              value: 99999999
+        - name: keep_history
+          in: query
+          description: Explicitly set to `true` to preserve balance history, or `false` to remove associated history during deletion. This must be set if the account has a balance history.
+          required: false
+          schema:
+            type: boolean
+      responses:
+        "204":
+          description: No Content. The crypto asset has been deleted.
+        "401":
+          $ref: "#/components/responses/unauthorizedToken"
+        "404":
+          description: Not Found
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/errorResponseObject"
+              example:
+                message: Not Found
+                errors:
+                  - errMsg: "There is no manual crypto balance with the id: 99999999."
+        "422":
+          description: Unprocessable Content
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/errorResponseObject"
+              example:
+                message: Explicit confirmation required
+                errors:
+                  - errMsg: This crypto manual account has existing balance history. To delete this account, you must explicitly set keep_history to true or false.
+                    crypto_manual_id: 22001
+                    has_balance_history: true
+                    required_parameter: keep_history
+                    allowed_values:
+                      - true
+                      - false
+        "429":
+          $ref: "#/components/responses/rateLimited"
+        "500":
+          $ref: "#/components/responses/serverError"
+  /crypto/synced:
+    get:
+      tags:
+        - crypto
+      summary: Get all synced crypto balances
+      description: Retrieves the balances for all synced crypto accounts associated with the user's account.
+      operationId: getAllCryptoSynced
+      responses:
+        "200":
+          description: A list of synced crypto balances
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/cryptoSyncedListResponseObject"
+              example:
+                crypto_synced:
+                  - id: 33004
+                    source: synced
+                    name: ETH
+                    display_name: Coinbase Main
+                    institution_name: Coinbase
+                    balance: "12.004500000000000000"
+                    currency: eth
+                    coingecko_id: ethereum
+                    to_base: 28998.44
+                    balance_as_of: "2026-02-25T14:25:00.000Z"
+                    last_import: "2026-02-25T14:25:01.000Z"
+                    status: active
+                    created_by_name: User 1
+                    created_at: "2025-10-02T11:02:09.000Z"
+                    updated_at: "2026-02-25T14:25:01.000Z"
+                  - id: 33004
+                    source: synced
+                    name: BTC
+                    display_name: Coinbase Main
+                    institution_name: Coinbase
+                    balance: "0.100020003000400050"
+                    currency: btc
+                    coingecko_id: bitcoin
+                    to_base: 6231.28
+                    balance_as_of: "2026-02-25T14:25:00.000Z"
+                    last_import: "2026-02-25T14:25:01.000Z"
+                    status: active
+                    created_by_name: User 1
+                    created_at: "2025-10-02T11:02:09.000Z"
+                    updated_at: "2026-02-25T14:25:01.000Z"
+        "401":
+          $ref: "#/components/responses/unauthorizedToken"
+        "429":
+          $ref: "#/components/responses/rateLimited"
+        "500":
+          $ref: "#/components/responses/serverError"
+  /crypto/synced/{id}:
+    get:
+      tags:
+        - crypto
+      summary: Get synced crypto balances for a single synced connection
+      description: Retrieves the balances for all currencies connected from the specified synced crypto account ID.
+      operationId: getCryptoSyncedById
+      parameters:
+        - name: id
+          in: path
+          description: Synced crypto account ID
+          required: true
+          schema:
+            type: integer
+            format: int32
+          examples:
+            existing synced connection:
+              summary: Existing synced account ID
+              value: 33004
+            id not found:
+              summary: Example of an id that doesn't exist
+              value: 99999999
+      responses:
+        "200":
+          description: Synced crypto balances for a single synced account
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/cryptoSyncedListResponseObject"
+              example:
+                crypto_synced:
+                  - id: 33004
+                    source: synced
+                    name: ETH
+                    display_name: Coinbase Main
+                    institution_name: Coinbase
+                    balance: "12.004500000000000000"
+                    currency: eth
+                    coingecko_id: ethereum
+                    to_base: 28998.44
+                    balance_as_of: "2026-02-25T14:25:00.000Z"
+                    last_import: "2026-02-25T14:25:01.000Z"
+                    status: active
+                    created_by_name: User 1
+                    created_at: "2025-10-02T11:02:09.000Z"
+                    updated_at: "2026-02-25T14:25:01.000Z"
+        "400":
+          description: Bad Request
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/errorResponseObject"
+              example:
+                message: Invalid Path Parameters
+                errors:
+                  - errMsg: "Invalid value type for path parameter: 'id'. Expected 'number', received 'string'."
+        "401":
+          $ref: "#/components/responses/unauthorizedToken"
+        "404":
+          description: Not Found
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/errorResponseObject"
+              example:
+                message: Not Found
+                errors:
+                  - errMsg: "There is no synced crypto connection with the id: 99999999."
+        "429":
+          $ref: "#/components/responses/rateLimited"
+        "500":
+          $ref: "#/components/responses/serverError"
+  /crypto/synced/{id}/refresh:
+    post:
+      tags:
+        - crypto
+      summary: Refresh balances for a synced crypto account
+      description: Trigger a balance refresh for the specified synced crypto account and return provider pass-through results. This payload may use provider/internal field names such as currency_ref.
+      operationId: refreshCryptoSynced
+      parameters:
+        - name: id
+          in: path
+          description: Synced crypto account ID
+          required: true
+          schema:
+            type: integer
+            format: int32
+          examples:
+            existing synced connection:
+              summary: Existing synced account ID
+              value: 33004
+            id not found:
+              summary: Example of an id that doesn't exist
+              value: 99999999
+      responses:
+        "200":
+          description: Refreshed balances for the synced crypto account
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/cryptoSyncedListResponseObject"
+              example:
+                crypto_synced:
+                  - id: 33004
+                    source: synced
+                    name: ETH
+                    display_name: Coinbase Main
+                    institution_name: Coinbase
+                    balance: "12.004500000000000000"
+                    currency: eth
+                    coingecko_id: ethereum
+                    to_base: 28998.44
+                    balance_as_of: "2026-02-25T14:25:00.000Z"
+                    last_import: "2026-02-25T14:25:01.000Z"
+                    status: active
+                    created_by_name: User 1
+                    created_at: "2025-10-02T11:02:09.000Z"
+                    updated_at: "2026-02-25T14:25:01.000Z"
+                  - id: 33004
+                    source: synced
+                    name: BTC
+                    display_name: Coinbase Main
+                    institution_name: Coinbase
+                    balance: "0.100020003000400050"
+                    currency: btc
+                    coingecko_id: bitcoin
+                    to_base: 6231.28
+                    balance_as_of: "2026-02-25T14:25:00.000Z"
+                    last_import: "2026-02-25T14:25:01.000Z"
+                    status: active
+                    created_by_name: User 1
+                    created_at: "2025-10-02T11:02:09.000Z"
+                    updated_at: "2026-02-25T14:25:01.000Z"
+        "401":
+          $ref: "#/components/responses/unauthorizedToken"
+        "404":
+          description: Not Found
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/errorResponseObject"
+              example:
+                message: Not Found
+                errors:
+                  - errMsg: "There is no synced crypto connection with the id: 99999999."
+        "429":
+          $ref: "#/components/responses/rateLimited"
+        "500":
+          $ref: "#/components/responses/serverError"
+  /manual_accounts:
+    get:
+      tags:
+        - manual_accounts
+      summary: Get all manual accounts
+      description: Retrieve a list of all manually-managed accounts associated with
+        the user's account.
+      operationId: getAllManualAccounts
+      responses:
+        "200":
+          description: A list of manual accounts
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  manual_accounts:
+                    type: array
+                    items:
+                      $ref: "#/components/schemas/manualAccountObject"
+              example:
+                manual_accounts:
+                  - id: 119807
+                    name: Individual Brokerage
+                    institution_name: Fidelity
+                    display_name: null
+                    type: investment
+                    subtype: brokerage
+                    balance: "41211.8000"
+                    currency: usd
+                    to_base: 41211.8
+                    balance_as_of: "2025-06-25T17:00:04.000Z"
+                    status: active
+                    closed_on: null
+                    external_id: null
+                    exclude_from_transactions: false
+                    created_by_name: User 1
+                    created_at: "2025-06-25T17:00:04.414Z"
+                    updated_at: "2025-06-26T19:03:38.312Z"
+                  - id: 119909
                     name: Euro Travel Card
                     institution_name: WeBank
                     display_name: null
@@ -5139,7 +6087,7 @@ paths:
               example:
                 message: Not Found
                 errors:
-                  - errMsg: There is no manual account with the id:'543210'`
+                  - errMsg: "There is no manual account with the id: 543210."
         "429":
           $ref: "#/components/responses/rateLimited"
         "500":
@@ -5196,7 +6144,7 @@ paths:
               example:
                 message: Not Found
                 errors:
-                  - errMsg: There is no manual account with the id:'543210'`
+                  - errMsg: "There is no manual account with the id: 543210."
         "429":
           $ref: "#/components/responses/rateLimited"
         "500":
@@ -6358,7 +7306,7 @@ paths:
               examples:
                 invalid ids in new transactions:
                   value:
-                    message: Invalid Request Body
+                    message: Request Validation Failure
                     errors:
                       - errMsg: "transactions[0] manual account ID does not exist: 9999999"
                         transaction_index: 0
@@ -6377,7 +7325,7 @@ paths:
                         recurring_id: 88888888
                 duplicate external_ids within request:
                   value:
-                    message: Invalid Request Body
+                    message: Request Validation Failure
                     errors:
                       - errMsg: Duplicate External IDs found in the request body
                         error: Duplicate External ID
@@ -6653,7 +7601,7 @@ paths:
               examples:
                 invalid ids in id list:
                   value:
-                    message: Invalid Request Body
+                    message: Request Validation Failure
                     errors:
                       - errMsg: "transactions[0] manual account ID does not exist: 999999999"
                         transaction_index: 0
@@ -6672,7 +7620,7 @@ paths:
                         recurring_id: 888888888
                 update with errors:
                   value:
-                    message: Invalid Request Body
+                    message: Request Validation Failure
                     errors:
                       - errMsg: "There is no transaction with the id: 9999999"
                         error: Invalid Transaction ID
@@ -6730,7 +7678,7 @@ paths:
                         locked_property: amount
                 duplicate external_ids within request:
                   value:
-                    message: Invalid Request Body
+                    message: Request Validation Failure
                     errors:
                       - errMsg: Duplicate External IDs found in the request body
                         error: Duplicate External ID
@@ -6748,7 +7696,7 @@ paths:
                           - 3
                 invalid ids:
                   value:
-                    message: Invalid Request Body
+                    message: Request Validation Failure
                     errors:
                       - errMsg: "There is no transaction with the id: 1"
                         error: Invalid Transaction ID
@@ -7117,7 +8065,7 @@ paths:
               example:
                 message: Not Found
                 errors:
-                  - errMsg: There is no transaction with the id:'543210'`
+                  - errMsg: "There is no transaction with the id: 543210."
         "429":
           $ref: "#/components/responses/rateLimited"
         "500":
@@ -7256,7 +8204,7 @@ paths:
               example:
                 message: Not Found
                 errors:
-                  - errMsg: There is no transaction with the id:'543210'`
+                  - errMsg: "There is no transaction with the id: 543210."
         "429":
           $ref: "#/components/responses/rateLimited"
         "500":
@@ -7309,7 +8257,7 @@ paths:
               example:
                 message: Not Found
                 errors:
-                  - errMsg: There is no transaction with the id:'543210'`
+                  - errMsg: "There is no transaction with the id: 543210."
         "429":
           $ref: "#/components/responses/rateLimited"
         "500":
@@ -7830,30 +8778,30 @@ paths:
               examples:
                 bad math:
                   value:
-                    message: Invalid Request Body
+                    message: Request Validation Failure
                     errors:
-                      - errMsg: Sums of split transactions do not add up to the original transaction
-                          amount!
+                      - errMsg: Sum of split transactions do not add up to the original transaction amount.
                 split recurring:
                   value:
-                    message: Invalid Request Body
+                    message: Request Validation Failure
                     errors:
-                      - errMsg: You cannot split a recurring transaction!
+                      - errMsg: You cannot split a recurring transaction.
+                        id: 2112150655
                 split group:
                   value:
-                    message: Invalid Request Body
+                    message: Request Validation Failure
                     errors:
-                      - errMsg: You cannot split a grouped transaction!
+                      - errMsg: You cannot split a group transaction. Ungroup it before splitting.
                 split split:
                   value:
-                    message: Invalid Request Body
+                    message: Request Validation Failure
                     errors:
-                      - errMsg: You cannot split an already split transaction!"
+                      - errMsg: You cannot split an already split transaction. Unsplit it before splitting again.
                 missing amount in child transaction:
                   value:
                     message: Invalid Request Body
                     errors:
-                      - errMsg: "child_transactions[0] amount is required."
+                      - errMsg: "child_transactions[0] is missing required property 'amount' in request body."
                         child_transactions_index: 0
                         error: Missing required property
                         invalid_property: amount
@@ -8407,9 +9355,9 @@ paths:
               schema:
                 $ref: "#/components/schemas/errorResponseObject"
               example:
-                message: Invalid Request Body
+                message: Request Validation Failure
                 errors:
-                  - errMsg: "A request to update a tag must include at least one of the following properties: name, description, archived"
+                  - errMsg: "A request to update a tag must include at least one of the following properties: name, description, archived."
         "401":
           $ref: "#/components/responses/unauthorizedToken"
         "404":
@@ -8421,7 +9369,7 @@ paths:
               example:
                 message: Not Found
                 errors:
-                  - errMsg: There is no tag with the id:'543210'`
+                  - errMsg: "There is no tag with the id: 543210."
         "429":
           $ref: "#/components/responses/rateLimited"
         "500":
@@ -8476,9 +9424,9 @@ paths:
               example:
                 message: Not Found
                 errors:
-                  - errMsg: There is no tag with the id:'543210'`
+                  - errMsg: "There is no tag with the id: 543210."
         "422":
-          description: Unprocessable Entity
+          description: Unprocessable Content
           content:
             application/json:
               schema:

package/package.json

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

package/version-history.md

@@ -5,13 +5,20 @@ The Lunch Money API spec uses a modified version of SEMVER for its versioning me
 - The minor version represents the number of main endpoints the current version of the spec supports.  For example, a version of the API that supports the /me, /categories, and /transactions endpoints would have a minor version of 3.
 - The revision number represents the number of updates since the last endpoint was added.  For example, each time changes are made to one of the existing three APIs as described above, the revision number will be bumped.
 
+## v2.10.0 - TBD
+- Add v2 crypto endpoints which support:
+  - Managing the complete lifecycle of manually managed crypto assets (create, read, update, delete)
+  - 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)
+deferred.
+  - Refreshing synced crypto account balances
+
 ## v2.9.0 - Feb 26, 2026
 - Add initial `/budgets` endpoint support:
   - `GET /budgets/settings` for account budget settings
   - `PUT /budgets` to create or update budget amounts
   - `DELETE /budgets` to remove budget amounts
 - Updates the GET `/summary` endpoint to return an `occurrences` array for both aligned and non-aligned summary responses when `include_occurrences=true`. 
-  - It can be useful to inspect the `start_date` and `end_date` of occurrences in a non-aligned response for use in subsequent requests to get an aligned response which will include complete budget information.
+  - It can be useful to inspect the `start_date` and `end_date` of occurrences in a non-aligned response for use in subsequent requests to get an aligned response, which will include complete budget information.
 - Add support for setting `tag_ids` on child transactions in `POST /transactions/split/{id}`.
 
 ## v2.8.5 - Feb 2, 2026 
@@ -146,7 +153,7 @@ The Lunch Money API spec uses a modified version of SEMVER for its versioning me
     - It is also now permissible to include strings in the `children` property.  These will be used as the names of new child categories that will be created.
 - This release also updates the following schemas:
   - Correctly specifies that all properties of the manualAccountObject are required
-  - Updates the updateManualAccountRequestObject and updatePlaidManualAccountRequest object to allow the `balance` property to be either a string or a number.
+  - Updates the updateManualAccountObject and updatePlaidManualAccountObject to allow the `balance` property to be either a string or a number.
   - Updates the userObject to include the `debits_as_negative` property.  The documentation for Transaction Objects returned by GET requests have been updated to reflect how/if this setting affects the `amount` property of the transaction.
   - Updates the childCategoryObject to restore the `exclude_from_budget`, `exclude_from_totals` and `is_income` properties.  These properties are inherited from the Category Group and not settable but are provided for convenience.
 
@@ -346,4 +353,3 @@ This is the initial branch using the versioning described above
 - It is the v2 version of the API - hence the major version 2.
 - The API Spec currently supports 3 endpoints /me, /categories, and /transactions.  hence the minor version 3.
 - This version of the spec contains minor modifications to the previously published spec and therefore has a revision number 1
-