> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wealthyhood.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Get user savings vault balance

> Retrieve EUR savings vault balance including unrealised interest.

## Response Structure

The savings vault returns a map with the currency code as the key (currently only EUR is supported):

<ResponseExample>
  ```json Response theme={null}
  {
    "EUR": {
      "amount": 1500.00,
      "currency": "EUR",
      "unrealisedInterest": 12.45
    }
  }
  ```
</ResponseExample>

### Response Fields

* **amount**: The current savings balance in whole currency units (EUR)
* **currency**: The currency code (always EUR for this endpoint)
* **unrealisedInterest**: Interest earned but not yet paid out, in whole currency units

<Info>
  Unrealised interest represents interest that has been accrued but not yet distributed to the user's account. This typically includes interest earned in the current month that will be paid out at the beginning of the next month.
</Info>

## Use Cases

This endpoint is ideal for:

* Displaying the user's total savings balance in your application
* Showing pending interest earnings before the next payout
* Building savings overview dashboards
* Calculating total assets under management

<Tip>
  Combine the `amount` and `unrealisedInterest` fields to show users their total savings value including pending earnings.
</Tip>


## OpenAPI

````yaml GET /savings-vault
openapi: 3.0.3
info:
  title: Wealthyhood Savings Vault API
  version: 1.0.0
  description: >
    User savings vault balance endpoints that expose savings holdings across
    different savings products.


    All requests require a bearer token with the scopes advertised in the
    primary specification,

    and must include the `x-user-id` header so the platform can resolve the
    acting investor.
servers:
  - url: https://{host}
    variables:
      host:
        default: api.wealthyhood.com
        description: Wealthyhood API host name.
security:
  - bearerAuth: []
tags:
  - name: Savings Vault
    description: User savings vault balance information.
paths:
  /savings-vault:
    get:
      tags:
        - Savings Vault
      summary: Get user savings vault balance
      description: >
        Returns the user's EUR savings balance including unrealised interest.
        The response contains only EUR savings

        and is structured as a map where the key is the currency code (EUR) and
        the value

        contains the amount, currency, and unrealised interest information.
      parameters:
        - $ref: '#/components/parameters/XUserId'
      responses:
        '200':
          description: Savings balance response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SavingsBalance'
              example:
                EUR:
                  amount: 1500
                  currency: EUR
                  unrealisedInterest: 12.45
                  netInterestRate: 1.91%
                  displaySavingsAmount: €1,500.00
                  displayUnrealisedInterest: +€12.45
                  savingsProductId: mmf_dist_eur
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
components:
  parameters:
    XUserId:
      name: x-user-id
      in: header
      description: >
        User identifier for the M2M client to specify which user's data to
        access.
      required: true
      schema:
        type: string
        pattern: ^[a-f0-9]{24}$
  schemas:
    SavingsBalance:
      type: object
      description: >
        Map containing EUR savings balance. The key is the currency code (EUR)
        and the value

        contains the amount, currency, and unrealised interest. Only EUR savings
        are returned.
      additionalProperties:
        $ref: '#/components/schemas/SavingBalance'
      example:
        EUR:
          amount: 1500
          currency: EUR
          unrealisedInterest: 12.45
          netInterestRate: 1.91%
          displaySavingsAmount: €1,500.00
          displayUnrealisedInterest: +€12.45
          savingsProductId: mmf_dist_eur
    SavingBalance:
      type: object
      required:
        - amount
        - currency
        - unrealisedInterest
        - netInterestRate
        - displaySavingsAmount
        - savingsProductId
      properties:
        amount:
          type: number
          description: Savings amount in whole currency units.
          example: 1500
        currency:
          type: string
          description: ISO 4217 currency code for the savings product.
          example: EUR
          enum:
            - GBP
            - EUR
            - USD
        unrealisedInterest:
          type: number
          description: >-
            Unrealised interest earned but not yet paid out, in whole currency
            units.
          example: 12.45
        netInterestRate:
          type: string
          description: Net interest rate as a percentage string.
          example: 1.91%
        displaySavingsAmount:
          type: string
          description: Formatted savings amount for display.
          example: €1,500.00
        displayUnrealisedInterest:
          type: string
          nullable: true
          description: Formatted unrealised interest for display.
          example: +€12.45
        savingsProductId:
          type: string
          description: Savings product identifier.
          example: mmf_dist_eur
    ApiErrorResponse:
      type: object
      properties:
        status:
          type: integer
        error:
          type: object
          properties:
            message:
              type: string
            description:
              type: string
              nullable: true
        responseId:
          type: string
          format: uuid
  responses:
    UnauthorizedError:
      description: Missing or invalid bearer token.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiErrorResponse'
          example:
            status: 401
            error:
              message: User not found
            responseId: 145f2b0d-1d5b-4e91-8d0d-7af0ae9ad13a
    ForbiddenError:
      description: Authenticated user cannot act on the requested resource or lacks scopes.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiErrorResponse'
          example:
            status: 403
            error:
              message: Access denied
            responseId: 5e467f79-c62c-4d83-9810-7a0f8529fd76
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >-
        Auth0-issued access token that includes the scopes listed for the
        endpoint.

````