> ## 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 cash balance

> Retrieve available and settled cash balances across one or more currencies.



## OpenAPI

````yaml GET /cash
openapi: 3.0.3
info:
  title: Wealthyhood Cash API
  version: 1.0.0
  description: >
    User cash balance endpoints that expose available and settled cash across
    currencies.


    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: Cash
    description: User cash balance information.
paths:
  /cash:
    get:
      tags:
        - Cash
      summary: Get user cash balance
      description: >
        Returns the user's available and settled cash balances. If no currency
        parameter is provided,

        returns balances for all currencies held by the user. When a specific
        currency is requested,

        returns only that currency's balance.
      parameters:
        - $ref: '#/components/parameters/ExternalUserId'
        - name: currency
          in: query
          description: >
            Optional ISO 4217 currency code to filter results (e.g., USD, EUR,
            GBP). If omitted, returns

            all currencies.
          required: false
          schema:
            type: string
            example: USD
            enum:
              - GBP
              - EUR
              - USD
      responses:
        '200':
          description: Cash balance response.
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/SingleCurrencyBalance'
                  - $ref: '#/components/schemas/MultiCurrencyBalance'
              examples:
                singleCurrency:
                  summary: Filtered to a single currency
                  value:
                    currency: USD
                    amount: 1234.56
                    amountSettled: 1000
                    asOf: '2025-10-03T10:00:00Z'
                allCurrencies:
                  summary: All currencies
                  value:
                    balances:
                      - currency: USD
                        amount: 1234.56
                        amountSettled: 1000
                      - currency: EUR
                        amount: 890.12
                        amountSettled: 850
                      - currency: GBP
                        amount: 0
                        amountSettled: 0
                    asOf: '2025-10-03T10:00:00Z'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
components:
  parameters:
    ExternalUserId:
      name: x-user-id
      in: header
      description: >
        The bank's unique identifier for the acting customer. Must match the
        user associated with the

        bearer token.
      required: true
      schema:
        type: string
        example: bank-user-12345
  schemas:
    SingleCurrencyBalance:
      type: object
      required:
        - currency
        - amount
        - amountSettled
        - asOf
      properties:
        currency:
          type: string
          description: ISO 4217 currency code.
          example: USD
          enum:
            - GBP
            - EUR
            - USD
        amount:
          type: number
          description: Available cash amount as a number
          example: 1234.56
          minimum: 0
        amountSettled:
          type: number
          description: >-
            Settled cash amount as a number; funds that have cleared and count
            toward withdrawable balance
          example: 1000
        asOf:
          type: string
          format: date-time
          description: Timestamp when the balance was calculated.
          example: '2025-10-03T10:00:00Z'
    MultiCurrencyBalance:
      type: object
      required:
        - balances
        - asOf
      properties:
        balances:
          type: array
          description: Array of cash balances by currency.
          items:
            type: object
            required:
              - currency
              - amount
              - amountSettled
            properties:
              currency:
                type: string
                description: ISO 4217 currency code.
                example: USD
                enum:
                  - GBP
                  - EUR
                  - USD
              amount:
                type: number
                description: Available cash amount as a number
                example: 1234.56
                minimum: 0
              amountSettled:
                type: number
                description: >-
                  Settled cash amount as a number; funds that have cleared and
                  count toward withdrawable balance
                example: 1000
        asOf:
          type: string
          format: date-time
          description: Timestamp when the balances were calculated.
          example: '2025-10-03T10:00:00Z'
    Error:
      type: object
      required:
        - message
        - code
      properties:
        message:
          type: string
          description: Human-readable error message.
          example: Invalid currency code provided
        code:
          type: string
          description: Machine-readable error code.
          example: INVALID_CURRENCY
  responses:
    BadRequestError:
      description: Bad request – invalid parameters or malformed request.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            message: Invalid currency code provided
            code: INVALID_CURRENCY
    UnauthorizedError:
      description: Unauthorized – missing or invalid bearer token.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            message: Authentication required
            code: UNAUTHORIZED
    ForbiddenError:
      description: Forbidden – valid credentials but insufficient permissions.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            message: Access denied
            code: FORBIDDEN
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >
        OAuth 2.0 bearer token issued by Wealthyhood. Include this token in the
        `Authorization` header

        as `Bearer <token>`.

````