Kamino Kamino Earn User API

openapi: 3.0.0
info:
  version: 1.0.0
  title: Kamino Public Airdrop Kamino Earn User 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
tags:
- name: Kamino Earn User
paths:
  /kvaults/users/{pubkey}/transactions:
    get:
      summary: Get user KVault transactions
      description: Get all Kamino Earn Vault transactions for a given user
      tags:
      - Kamino Earn User
      parameters:
      - schema:
          allOf:
          - $ref: '#/components/schemas/AddressBase58'
          - description: Valid base58-encoded address of the user wallet
            example: AxqtG9SHDkZTLSWg81Sp7VqAzQpRqXtR9ziJ3VQAS8As
        required: true
        description: Valid base58-encoded address of the user wallet
        name: pubkey
        in: path
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/KVaultInstruction'
        '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:
                        nullable: true
                    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
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /kvaults/users/{pubkey}/positions:
    get:
      summary: Get all user KVault positions
      description: Get a list of user positions for each Kamino Earn Vault the user has currently deposited into. Returns staked and unstaked shares.
      tags:
      - Kamino Earn User
      parameters:
      - schema:
          allOf:
          - $ref: '#/components/schemas/AddressBase58'
          - description: Valid base58-encoded address of the user wallet
            example: AxqtG9SHDkZTLSWg81Sp7VqAzQpRqXtR9ziJ3VQAS8As
        required: true
        description: Valid base58-encoded address of the user wallet
        name: pubkey
        in: path
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/VaultStateArray'
                - items:
                    type: object
                    properties:
                      vaultAddress:
                        allOf:
                        - $ref: '#/components/schemas/AddressBase58'
                        - description: Address of the Kamino Earn Vault
                      stakedShares:
                        allOf:
                        - $ref: '#/components/schemas/Decimal'
                        - description: The number of Kamino Earn Vault shares staked in a farm
                      unstakedShares:
                        allOf:
                        - $ref: '#/components/schemas/Decimal'
                        - description: The number of Kamino Earn Vault shares held in the user wallet
                      totalShares:
                        allOf:
                        - $ref: '#/components/schemas/Decimal'
                        - description: The total number of Kamino Earn Vault shares both held and staked by the user
                    required:
                    - vaultAddress
                    - stakedShares
                    - unstakedShares
                    - totalShares
        '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:
                        nullable: true
                    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
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /kvaults/users/{userPubkey}/positions/{vaultPubkey}:
    get:
      summary: Get user position for a specific KVault
      description: Get a single user position for a Kamino Earn Vault the user currently has currently deposited into. Returns staked and unstaked shares.
      tags:
      - Kamino Earn User
      parameters:
      - schema:
          allOf:
          - $ref: '#/components/schemas/AddressBase58'
          - description: Valid base58-encoded address of the vault
            example: HDsayqAsDWy3QvANGqh2yNraqcD8Fnjgh73Mhb3WRS5E
        required: true
        description: Valid base58-encoded address of the vault
        name: vaultPubkey
        in: path
      - schema:
          allOf:
          - $ref: '#/components/schemas/AddressBase58'
          - description: Valid base58-encoded address of the user wallet
            example: AxqtG9SHDkZTLSWg81Sp7VqAzQpRqXtR9ziJ3VQAS8As
        required: true
        description: Valid base58-encoded address of the user wallet
        name: userPubkey
        in: path
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  vaultAddress:
                    allOf:
                    - $ref: '#/components/schemas/AddressBase58'
                    - description: Address of the Kamino Earn Vault
                  stakedShares:
                    allOf:
                    - $ref: '#/components/schemas/Decimal'
                    - description: The number of Kamino Earn Vault shares staked in a farm
                  unstakedShares:
                    allOf:
                    - $ref: '#/components/schemas/Decimal'
                    - description: The number of Kamino Earn Vault shares held in the user wallet
                  totalShares:
                    allOf:
                    - $ref: '#/components/schemas/Decimal'
                    - description: The total number of Kamino Earn Vault shares both held and staked by the user
                required:
                - vaultAddress
                - stakedShares
                - unstakedShares
                - totalShares
        '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:
                        nullable: true
                    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
        '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'
  /kvaults/users/{pubkey}/metrics/history:
    get:
      summary: Get historical user metrics for all KVault positions
      description: Get historical timeseries of total usd/sol/interest/apy for all user Kamino Earn Vault positions
      tags:
      - Kamino Earn User
      parameters:
      - schema:
          allOf:
          - $ref: '#/components/schemas/AddressBase58'
          - description: Valid base58-encoded address of the user wallet
            example: AxqtG9SHDkZTLSWg81Sp7VqAzQpRqXtR9ziJ3VQAS8As
        required: true
        description: Valid base58-encoded address of the user wallet
        name: pubkey
        in: path
      - schema:
          anyOf:
          - type: string
          - type: number
          default: '1970-01-01T00:00:00.000Z'
          description: Start date of the range (defaults to Unix epoch). Accepts ISO string or epoch in ms.
          examples:
          - '1970-01-01T00:00:00.000Z'
          - 0
        required: false
        description: Start date of the range (defaults to Unix epoch). Accepts ISO string or epoch in ms.
        name: start
        in: query
      - schema:
          anyOf:
          - type: string
          - type: number
          description: End date of the range (defaults to current time). Accepts ISO string or epoch in ms.
          examples:
          - '2025-01-01T00:00:00.000Z'
          - 1735689600000
        required: false
        description: End date of the range (defaults to current time). Accepts ISO string or epoch in ms.
        name: end
        in: query
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/UserKVaultTotal'
        '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:
                        nullable: true
                    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
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /kvaults/users/{userPubkey}/vaults/{vaultPubkey}/metrics/history:
    get:
      summary: Get historical user metrics for a single KVault
      description: Get historical timeseries of total usd/sol/interest/apy for a single user Kamino Earn Vault position
      tags:
      - Kamino Earn User
      parameters:
      - schema:
          allOf:
          - $ref: '#/components/schemas/AddressBase58'
          - description: Valid base58-encoded address of the vault
            example: HDsayqAsDWy3QvANGqh2yNraqcD8Fnjgh73Mhb3WRS5E
        required: true
        description: Valid base58-encoded address of the vault
        name: vaultPubkey
        in: path
      - schema:
          allOf:
          - $ref: '#/components/schemas/AddressBase58'
          - description: Valid base58-encoded address of the user wallet
            example: AxqtG9SHDkZTLSWg81Sp7VqAzQpRqXtR9ziJ3VQAS8As
        required: true
        description: Valid base58-encoded address of the user wallet
        name: userPubkey
        in: path
      - schema:
          anyOf:
          - type: string
          - type: number
          default: '1970-01-01T00:00:00.000Z'
          description: Start date of the range (defaults to Unix epoch). Accepts ISO string or epoch in ms.
          examples:
          - '1970-01-01T00:00:00.000Z'
          - 0
        required: false
        description: Start date of the range (defaults to Unix epoch). Accepts ISO string or epoch in ms.
        name: start
        in: query
      - schema:
          anyOf:
          - type: string
          - type: number
          description: End date of the range (defaults to current time). Accepts ISO string or epoch in ms.
          examples:
          - '2025-01-01T00:00:00.000Z'
          - 1735689600000
        required: false
        description: End date of the range (defaults to current time). Accepts ISO string or epoch in ms.
        name: end
        in: query
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/UserKvaultMetrics'
        '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:
                        nullable: true
                    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
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /kvaults/users/{userPubkey}/vaults/{vaultPubkey}/pnl:
    get:
      summary: Get user KVault PnL
      description: Get current PnL and cost basis of user vault position
      tags:
      - Kamino Earn User
      parameters:
      - schema:
          allOf:
          - $ref: '#/components/schemas/AddressBase58'
          - description: Valid base58-encoded address of the vault
            example: HDsayqAsDWy3QvANGqh2yNraqcD8Fnjgh73Mhb3WRS5E
        required: true
        description: Valid base58-encoded address of the vault
        name: vaultPubkey
        in: path
      - schema:
          allOf:
          - $ref: '#/components/schemas/AddressBase58'
          - description: Valid base58-encoded address of the user wallet
            example: AxqtG9SHDkZTLSWg81Sp7VqAzQpRqXtR9ziJ3VQAS8As
        required: true
        description: Valid base58-encoded address of the user wallet
        name: userPubkey
        in: path
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/KvaultPnl'
        '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:
                        nullable: true
                    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
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /kvaults/users/{userPubkey}/vaults/{vaultPubkey}/pnl/history:
    get:
      summary: Get user KVault PnL history
      description: Get PnL and cost basis history of user vault position
      tags:
      - Kamino Earn User
      parameters:
      - schema:
          allOf:
          - $ref: '#/components/schemas/AddressBase58'
          - description: Valid base58-encoded address of the vault
            example: HDsayqAsDWy3QvANGqh2yNraqcD8Fnjgh73Mhb3WRS5E
        required: true
        description: Valid base58-encoded address of the vault
        name: vaultPubkey
        in: path
      - schema:
          allOf:
          - $ref: '#/components/schemas/AddressBase58'
          - description: Valid base58-encoded address of the user wallet
            example: AxqtG9SHDkZTLSWg81Sp7VqAzQpRqXtR9ziJ3VQAS8As
        required: true
        description: Valid base58-encoded address of the user wallet
        name: userPubkey
        in: path
      - schema:
          anyOf:
          - type: string
          - type: number
          description: Date input (ISO 8601 string or epoch in ms)
          examples:
          - '2024-01-01T00:00:00.000Z'
          - 1704067200000
        required: false
        description: Date input (ISO 8601 string or epoch in ms)
        name: start
        in: query
      - schema:
          anyOf:
          - type: string
          - type: number
          description: Date input (ISO 8601 string or epoch in ms)
          examples:
          - '2024-01-01T00:00:00.000Z'
          - 1704067200000
        required: false
        description: Date input (ISO 8601 string or epoch in ms)
        name: end
        in: query
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  history:
                    type: array
                    items:
                      $ref: '#/components/schemas/KvaultPnlTimeseriesValue'
                  totalPnl:
                    $ref: '#/components/schemas/KvaultMultiValue'
                  totalCostBasis:
                    $ref: '#/components/schemas/KvaultMultiValue'
                required:
                - history
                - totalPnl
                - totalCostBasis
        '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:
                        nullable: true
                    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
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /kvaults/users/{pubkey}/rewards:
    get:
      summary: Get season user rewards
      description: Get user season points rewards for each Kamino Earn Vault which the user has invested in
      tags:
      - Kamino Earn User
      parameters:
      - schema:
          $ref: '#/components/schemas/AddressBase58'
        required: true
        description: Valid base58-encoded address
        name: pubkey
        in: path
      - schema:
          type: string
          description: Points source identifier
          example: Season1
          examples:
          - Season1
          - Season2
          - Season3
          - Season4
        required: false
        description: Points source identifier
        name: source
        in: query
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/KvaultUserRewardMetrics'
        '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:
                        nullable: true
                    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
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    AddressBase58:
      type: string
      description: Valid base58-encoded address
      example: VEG1EMtttdHunMbSza8uoms1R18VXmYSph2bBpHcSJd
    KvaultUserRewardMetrics:
      type: array
      items:
        $ref: '#/components/schemas/KvaultUserRewardMetric'
      description: List of kvault user reward metrics
    KvaultPnlTimeseriesValue:
      type: object
      properties:
        timestamp:
          type: number
          description: Unix timestamp in milliseconds
        type:
          anyOf:
          - type: string
            enum:
            - buy
          - type: string
            enum:
            - sell
          - type: string
            enum:
            - mark-to-market
        position:
          allOf:
          - $ref: '#/components/schemas/Decimal'
          - description: Current position value
        quantity:
          allOf:
          - $ref: '#/components/schemas/Decimal'
          - description: Quantity involved in transaction
        tokenPrice:
          allOf:
          - $ref: '#/components/schemas/KvaultMultiValue'
          - description: Token price snapshot
        sharePrice:
          allOf:
          - $ref: '#/components/schemas/KvaultMultiValue'
          - description: Share price snapshot
        costBasis:
          allOf:
          - $ref: '#/components/schemas/KvaultMultiValue'
          - description: Cost basis for position
        realizedPnl:
          allOf:
          - $ref: '#/components/schemas/KvaultMultiValue'
          - description: Realized profit/loss
        pnl:
          allOf:
          - $ref: '#/components/schemas/KvaultMultiValue'
          - description: Total profit/loss
        positionValue:
          allOf:
          - $ref: '#/components/schemas/KvaultMultiValue'
          - description: Value of the position
        investment:
          allOf:
          - $ref: '#/components/schemas/KvaultMultiValue'
          - description: Total invested value
      required:
      - timestamp
      - type
      - position
      - quantity
      - tokenPrice
      - sharePrice
      - costBasis
      - realizedPnl
      - pnl
      - positionValue
      - investment
    UserKVaultTotal:
      type: object
      properties:
        createdOn:
          allOf:
          - $ref: '#/components/schemas/SnapshotDateTime'
          - description: Timestamp when the snapshot was created (ISO 8601 format)
            example: '2025-03-01T12:00:00.000Z'
        usdAmount:
          allOf:
          - $ref: '#/components/schemas/Decimal'
          - description: User's total amount across all vaults in USD
        solAmount:
          allOf:
          - $ref: '#/components/schemas/Decimal'
          - description: User's total amount across all vaults in SOL
        weightedApy:
          allOf:
          - $ref: '#/components/schemas/Apy'
          - description: Weighted average APY across all vaults in decimal format
            example: '0.2'
        cumulativeInterestEarnedUsd:
          allOf:
          - $ref: '#/components/schemas/Decimal'
          - description: Total interest earned in USD across all vaults
        cumulativeInterestEarnedSol:
          allOf:
          - $ref: '#/components/schemas/Decimal'
          - description: Total interest earned in SOL across all vaults
        interestEarnedPerSecondUsd:
          allOf:
          - $ref: '#/components/schemas/Decimal'
          - description: Interest earned per second at that specific moment in USD
        interestEarnedPerSecondSol:
          allOf:
          - $ref: '#/components/schemas/Decimal'
          - description: Interest earned per second at that specific moment in SOL
      required:
      - createdOn
      - usdAmount
      - solAmount
      - weightedApy
      - cumulativeInterestEarnedUsd
      - cumulativeInterestEarnedSol
      - interestEarnedPerSecondUsd
      - interestEarnedPerSecondSol
    Decimal:
      type: string
      description: Decimal value represented as string
      example: '1234.56789'
    The vault state object:
      type: object
      properties:
        vaultAdminAuthority:
          allOf:
          - $ref: '#/components/schemas/AddressBase58'
          - description: Public key of the vault admin authority
        baseVaultAuthority:
          allOf:
          - $ref: '#/components/schemas/AddressBase58'
          - description: Public key of the base vault authority
        baseVaultAuthorityBump:
          type: number
          description: Bump seed for the base vault authority
        tokenMint:
          allOf:
          - $ref: '#/components/schemas/AddressBase58'
          - description: Public key of the token mint
        tokenMintDecimals:
          type: number
          description: Decimals of the token mint
        tokenVault:
          allOf:
          - $ref: '#/components/schemas/AddressBase58'
          - description: Public key of the token vault
        tokenProgram:
          allOf:
          - $ref: '#/components/schemas/AddressBase58'
          - description: Public key of the token program
        sharesMint:
          allOf:
          - $ref: '#/components/schemas/AddressBase58'
          - description: Public key of the shares mint
        sharesMintDecimals:
          type: number
          description: Decimals of the shares mint
        tokenAvailable:
          allOf:
          - $ref: '#/components/schemas/Decimal'
          - description: Amount of tokens available in the vault
        sharesIssued:
          allOf:
          - $ref: '#/components/schemas/Decimal'
          - description: Total shares issued by the vault
        availableCrankFunds:
          allOf:
          - $ref: '#/components/schemas/Decimal'
          - description: Available crank funds in the vault
        performanceFeeBps:
          type: number
          description: Performance fee in basis points
        managementF

# --- truncated at 32 KB (45 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/kamino/refs/heads/main/openapi/kamino-kamino-earn-user-api-openapi.yml