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

# Get Earn Position

> Returns a wallet's position in one Earn vault: share balance, cost basis and realized PnL, plus its open withdrawal requests. Use `openWithdrawalRequests[].onChainRequestAddr` as the `requestId` for claiming or cancelling a queued withdrawal.



## OpenAPI

````yaml post /markets/earn/vaults/positions
openapi: 3.1.0
info:
  title: Loopscale API
  version: 0.1.0
servers:
  - url: https://tars.loopscale.com/v1
    description: Loopscale Production Server
security: []
paths:
  /markets/earn/vaults/positions:
    post:
      tags:
        - earn_data
      summary: Get Earn Position
      description: >-
        Returns a wallet's position in one Earn vault: share balance, cost basis
        and realized PnL, plus its open withdrawal requests. Use
        `openWithdrawalRequests[].onChainRequestAddr` as the `requestId` for
        claiming or cancelling a queued withdrawal.
      operationId: query_get_earn_vault_position
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EarnWalletVaultRequest'
        required: true
      responses:
        '200':
          description: The vault, the wallet's position and its open withdrawal requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EarnVaultPositionResponse'
        '400':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    EarnWalletVaultRequest:
      type: object
      required:
        - address
        - wallet
      properties:
        address:
          type: string
        wallet:
          type: string
    EarnVaultPositionResponse:
      type: object
      required:
        - vault
        - openWithdrawalRequests
      properties:
        openWithdrawalRequests:
          type: array
          items:
            $ref: '#/components/schemas/EarnWithdrawalRequest'
          description: Open withdrawal requests for this user + vault.
        position:
          oneOf:
            - type: 'null'
            - $ref: '#/components/schemas/EarnUserPosition'
              description: User's earn position (share balance, cost basis, realized PnL).
        vault:
          $ref: '#/components/schemas/EarnVaultWithLatestSnapshot'
    ErrorResponse:
      type: object
      description: |-
        Canonical error envelope for every endpoint. The `x-request-id` response
        header carries the correlation id for the failing request.
      required:
        - error
      properties:
        error:
          $ref: '#/components/schemas/ErrorDetails'
          description: error detail
    EarnWithdrawalRequest:
      type: object
      description: Cached Earn withdrawal-request lifecycle state.
      required:
        - onChainRequestAddr
        - earnVaultAddress
        - userWallet
        - sharesRequested
        - sharesFilled
        - sharesClaimed
        - requestedAt
        - status
        - fills
      properties:
        cancelledAt:
          type:
            - string
            - 'null'
          description: cancellation timestamp
        earnVaultAddress:
          type: string
          description: vault address
        fills:
          type: array
          items:
            $ref: '#/components/schemas/EarnWithdrawalFill'
          description: >-
            what the manager has filled so far, one entry per token, from the
            on-chain fills list
        fulfilledAt:
          type:
            - string
            - 'null'
          description: full-fill timestamp
        onChainRequestAddr:
          type: string
          description: withdrawal request PDA
        payoutMint:
          type:
            - string
            - 'null'
          description: >-
            token the user asked to be paid in, from the payout memo in the
            queue txn;

            None means no preference (filler default)
        requestedAt:
          type: string
          description: request creation timestamp
        sharesClaimed:
          type: string
          description: claimed shares
        sharesFilled:
          type: string
          description: filled shares
        sharesRequested:
          type: string
          description: requested shares
        status:
          type: integer
          format: int32
          description: request status enum discriminant
          minimum: 0
        userWallet:
          type: string
          description: user wallet
    EarnUserPosition:
      type: object
      description: Materialized Earn user position cache.
      required:
        - earnVaultAddress
        - userWallet
        - shareBalance
        - costBasisAssets
        - realizedPnlAssets
        - feesPaidAssets
        - lastSyncedSlot
      properties:
        acknowledgedAt:
          type:
            - string
            - 'null'
          description: risk acknowledgment timestamp
        costBasisAssets:
          type: string
          description: current cost basis in deposit-asset units
        earnVaultAddress:
          type: string
          description: vault address
        feesPaidAssets:
          type: string
          description: lifetime fees paid in deposit-asset units
        lastSyncedSlot:
          type: string
          description: latest synchronized slot
        realizedPnlAssets:
          type: string
          description: lifetime realized PnL in deposit-asset units
        shareBalance:
          type: string
          description: current share balance
        userWallet:
          type: string
          description: user wallet
    EarnVaultWithLatestSnapshot:
      allOf:
        - $ref: '#/components/schemas/EarnVault'
          description: Earn vault account (DB projection of the on-chain/provider state).
        - type: object
          properties:
            acceptedAssetMints:
              type: array
              items:
                type: string
              description: >-
                Tokens offered for deposits and payouts: `accepted_asset_mint`
                first, then any

                of the vault's other held tokens it has opted in. Most vaults
                list only the

                accepted asset.
            latestSnapshot:
              oneOf:
                - type: 'null'
                - $ref: '#/components/schemas/EarnVaultSnapshotResponse'
    ErrorDetails:
      type: object
      description: Inner detail of the [`ErrorResponse`] envelope.
      required:
        - code
        - message
      properties:
        code:
          type: integer
          format: int32
          description: HTTP status code, mirrored in the response status line
          example: 400
          minimum: 0
        message:
          type: string
          description: human-readable, client-safe message (sensitive data redacted)
          example: Request could not be processed.
        simulation:
          oneOf:
            - type: 'null'
            - $ref: '#/components/schemas/SimulationDebug'
              description: >-
                Populated on transaction-generation endpoints when the
                build-path

                simulation reverts. Absent on all other error paths.
    EarnWithdrawalFill:
      type: object
      description: One token a withdrawal request was filled with.
      required:
        - mint
        - amount
      properties:
        amount:
          type: string
          description: amount filled in that token's base units, summed across fills
        mint:
          type: string
          description: fill token mint
    EarnVault:
      type: object
      description: Earn managed vault metadata plus cached parsed provider state.
      required:
        - address
        - providerKind
        - shareMint
        - acceptedAssetMint
        - managerAuthority
        - metadataJson
        - status
        - queueEnabled
        - instantEnabled
        - cancelEnabled
        - requiresAcknowledgment
        - parsedAccountJson
        - createdAt
      properties:
        acceptedAssetMint:
          type: string
          description: accepted deposit asset mint
        address:
          type: string
          description: on-chain vault address
        cancelEnabled:
          type: boolean
          description: user cancellation supported
        createdAt:
          type: string
          description: row creation timestamp
        instantEnabled:
          type: boolean
          description: instant withdrawals supported
        lastUpdatedSlot:
          type:
            - string
            - 'null'
          description: latest applied slot
        lastUpdatedTs:
          type:
            - string
            - 'null'
          description: latest applied timestamp
        managerAuthority:
          type: string
          description: curator or manager authority
        metadataJson:
          type: object
          description: off-chain display/product metadata
          additionalProperties: {}
          propertyNames:
            type: string
        parsedAccountJson:
          type: object
          description: cached ParsedEarnVault JSON
          additionalProperties: {}
          propertyNames:
            type: string
        providerKind:
          type: integer
          format: int32
          description: provider enum discriminant
          minimum: 0
        queueEnabled:
          type: boolean
          description: queued withdrawals supported
        requiresAcknowledgment:
          type: boolean
          description: deposit flow acknowledgment required
        shareMint:
          type: string
          description: provider share mint
        status:
          type: integer
          format: int32
          description: vault status enum discriminant
          minimum: 0
    EarnVaultSnapshotResponse:
      type: object
      required:
        - snapshotSlot
        - snapshotTs
        - shareSupply
        - navPerShareE18
        - totalAumAssets
        - pendingWithdrawalsAssets
      properties:
        displayApyBps:
          type:
            - integer
            - 'null'
          format: int32
          description: >-
            Forward-looking base vault APY: share-of-AUM-weighted sum of the

            per-position `display_apy_bps` rows this vault holds. Signed, in
            basis

            points. `null` when Display APY coverage is insufficient.
        headlineApyBps:
          type:
            - integer
            - 'null'
          format: int32
          description: |-
            The APY to show for the vault: `display_apy_bps` plus
            `rewards_apy_bps`, falling back to `realized_return_bps_7d` as the
            base when there is no Display APY. `null` when neither leg is known.
        leverageX100:
          type:
            - integer
            - 'null'
          format: int32
          minimum: 0
        navPerShareE18:
          type: string
        pendingWithdrawalsAssets:
          type: string
        realizedApyBps24h:
          type:
            - integer
            - 'null'
          format: int32
          description: DEPRECATED — use `realizedReturnBps24h`.
        realizedApyBps30d:
          type:
            - integer
            - 'null'
          format: int32
          description: >-
            DEPRECATED — use `realizedReturnBps30d`. Mirrored for one release
            cycle

            to give SDK / FE consumers time to migrate; will be removed in a

            follow-up PR.
        realizedApyBps7d:
          type:
            - integer
            - 'null'
          format: int32
          description: DEPRECATED — use `realizedReturnBps7d`.
        realizedReturnBps24h:
          type:
            - integer
            - 'null'
          format: int32
          description: >-
            Backward-looking NAV-delta return over the trailing 24h, in basis
            points.
        realizedReturnBps30d:
          type:
            - integer
            - 'null'
          format: int32
          description: >-
            Backward-looking NAV-delta return over the trailing 30d, in basis
            points.

            Distinct from `display_apy_bps` (forward-looking, from underlyings).
        realizedReturnBps7d:
          type:
            - integer
            - 'null'
          format: int32
          description: >-
            Backward-looking NAV-delta return over the trailing 7d, in basis
            points.
        rewardsApyBps:
          type:
            - integer
            - 'null'
          format: int32
          description: |-
            Forward-looking rewards APY, in basis points: the rate every active
            emission campaign (Exponent scheduled emissions and Loopscale reward
            campaigns) declares at the snapshot, priced and annualized over AUM.
            Not part of `display_apy_bps`; `headline_apy_bps` adds the two.
        shareSupply:
          type: string
        snapshotSlot:
          type: string
        snapshotTs:
          type: string
        totalAumAssets:
          type: string
        utilizationBps:
          type:
            - integer
            - 'null'
          format: int32
          minimum: 0
    SimulationDebug:
      type: object
      description: >-
        Diagnostics attached to a build-path simulation revert so clients can
        inspect

        the exact txn that would have failed on-chain. Only populated for
        txn-gen

        endpoints; other 4xx/5xx responses omit this field.
      required:
        - decoded
        - logs
      properties:
        decoded:
          type: string
          description: >-
            Human-readable decoded error (Anchor "Error Message: ..." when
            available,

            otherwise the raw program error code or `TransactionError` debug
            form).
        logs:
          type: array
          items:
            type: string
          description: Program logs from the reverting simulation, in order.
        serializedTransaction:
          type:
            - string
            - 'null'
          description: >-
            Base64-encoded, bincode-serialized `VersionedTransaction` that was

            simulated (signatures zeroed for sig-verify-disabled simulation).

            Decode with
            `bincode::deserialize::<VersionedTransaction>(&base64_decode(..))`.

````

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