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

# Get lifetime earnings of KVault users

> Get the lifetime earnings of up to 100 wallets in one Kamino Earn Vault, across every position each wallet opened and closed. Earnings are tokens withdrawn minus tokens deposited plus the value of the open position, net of vault fees and withdrawal penalties, so they can be negative. Every value is measured at the latest vault snapshot (`asOf`), taken every 15 minutes; deposits and withdrawals after it are not counted yet. Wallets without vault activity return zeros. Returns 503 when the vault has no snapshot from the last 24 hours. Private (authorized) API access only, please add a basic auth header to your request.



## OpenAPI

````yaml /kamino-api.json post /kvaults/vaults/{pubkey}/users/lifetime-earnings
openapi: 3.1.0
info:
  version: 1.0.0
  title: Kamino Public API
  description: >
    The Kamino API provides a comprehensive way to interact with Kamino without
    reading directly from the blockchain.


    The API also provides the ability to fetch data that might not be available
    from just reading the chain.


    The API is rate-limited for unauthenticated users. If you feel you need to
    make more requests or run into rate-limit issues, please reach out.
servers:
  - url: https://api.kamino.finance
security: []
paths:
  /kvaults/vaults/{pubkey}/users/lifetime-earnings:
    post:
      tags:
        - Kamino Earn Vaults
      summary: Get lifetime earnings of KVault users
      description: >-
        Get the lifetime earnings of up to 100 wallets in one Kamino Earn Vault,
        across every position each wallet opened and closed. Earnings are tokens
        withdrawn minus tokens deposited plus the value of the open position,
        net of vault fees and withdrawal penalties, so they can be negative.
        Every value is measured at the latest vault snapshot (`asOf`), taken
        every 15 minutes; deposits and withdrawals after it are not counted yet.
        Wallets without vault activity return zeros. Returns 503 when the vault
        has no snapshot from the last 24 hours. Private (authorized) API access
        only, please add a basic auth header to your request.
      parameters:
        - schema:
            $ref: '#/components/schemas/AddressBase58'
          required: true
          description: Valid base58-encoded address
          name: pubkey
          in: path
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/KvaultLifetimeEarningsBody'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/KvaultLifetimeEarningsResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: High-level error message describing the failure
                    example: Invalid query params
                  details:
                    type: array
                    items:
                      type: object
                      additionalProperties: {}
                    description: >-
                      Detailed validation issues (present only for validation
                      errors)
                required:
                  - error
                description: Bad request response (400)
                example:
                  error: Invalid query request
                  details:
                    - code: invalid_union
                      errors:
                        - - code: custom
                            path: []
                            message: Invalid date string
                        - - expected: number
                            code: invalid_type
                            path: []
                            message: 'Invalid input: expected number, received string'
                      path:
                        - start
                      message: Invalid input
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: Error message describing why it was not authorized
                    example: >-
                      Not authorized for this request. Please include the basic
                      auth headers.
                required:
                  - error
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                type: object
                properties:
                  metadata:
                    type: string
                    description: Error message describing why it was not found
                    example: Account could not be found
                required:
                  - metadata
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: Service Unavailable
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                required:
                  - error
components:
  schemas:
    AddressBase58:
      type: string
      description: Valid base58-encoded address
      example: VEG1EMtttdHunMbSza8uoms1R18VXmYSph2bBpHcSJd
    KvaultLifetimeEarningsBody:
      type: object
      properties:
        owners:
          type: array
          items:
            $ref: '#/components/schemas/AddressBase58'
          minItems: 1
          maxItems: 100
          description: Wallets to report, 1 to 100 unique addresses
      required:
        - owners
      additionalProperties: false
    KvaultLifetimeEarningsResponse:
      type: object
      properties:
        vault:
          allOf:
            - $ref: '#/components/schemas/AddressBase58'
            - description: Kamino Earn Vault address
        tokenMint:
          allOf:
            - $ref: '#/components/schemas/AddressBase58'
            - description: Mint of the vault token
        asOf:
          allOf:
            - $ref: '#/components/schemas/SnapshotDateTime'
            - description: Timestamp of the vault snapshot every value is measured at
        tokenPrice:
          allOf:
            - $ref: '#/components/schemas/Decimal'
            - description: USD price of the vault token at the snapshot
        tokensPerShare:
          allOf:
            - $ref: '#/components/schemas/Decimal'
            - description: Vault tokens per share at the snapshot
        owners:
          type: array
          items:
            $ref: '#/components/schemas/KvaultOwnerLifetimeEarnings'
          description: One entry per requested wallet, in request order
      required:
        - vault
        - tokenMint
        - asOf
        - tokenPrice
        - tokensPerShare
        - owners
    Error:
      type: object
      properties:
        error:
          type: string
          description: Error message for internal server failure
          example: An internal error occurred
      required:
        - error
      description: Internal server error response (500)
      example:
        error: An internal error occurred
    SnapshotDateTime:
      type: string
      format: date-time
      description: Timestamp when the snapshot was created (ISO 8601 format)
      example: '2025-03-01T12:00:00.000Z'
    Decimal:
      type: string
      description: Decimal value represented as string
      example: '1234.56789'
    KvaultOwnerLifetimeEarnings:
      type: object
      properties:
        owner:
          allOf:
            - $ref: '#/components/schemas/AddressBase58'
            - description: Wallet address, as requested
        lifetimeEarned:
          allOf:
            - $ref: '#/components/schemas/Decimal'
            - description: >-
                Earnings in vault token units over every position the wallet
                held, net of vault fees and withdrawal penalties. Can be
                negative.
        lifetimeEarnedUsd:
          allOf:
            - $ref: '#/components/schemas/Decimal'
            - description: lifetimeEarned valued at the token price of the snapshot
        deposited:
          allOf:
            - $ref: '#/components/schemas/Decimal'
            - description: Tokens the wallet deposited into the vault up to the snapshot
        withdrawn:
          allOf:
            - $ref: '#/components/schemas/Decimal'
            - description: Tokens the wallet received from the vault up to the snapshot
        currentShares:
          allOf:
            - $ref: '#/components/schemas/Decimal'
            - description: >-
                Shares held at the snapshot, in the wallet and staked in the
                vault farm
        currentAmount:
          allOf:
            - $ref: '#/components/schemas/Decimal'
            - description: currentShares valued in vault tokens at the snapshot
        reconciled:
          type: boolean
          description: >-
            True when the deposits and withdrawals the API indexed explain
            currentShares. False otherwise, usually because of a share transfer
            between wallets, which can put lifetimeEarned off by the interest on
            the transferred shares, or because the wallet deposited or withdrew
            while the snapshot was being taken, which clears at a later
            snapshot.
      required:
        - owner
        - lifetimeEarned
        - lifetimeEarnedUsd
        - deposited
        - withdrawn
        - currentShares
        - currentAmount
        - reconciled

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.