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

# List earn positions

> List all Earn positions for a given owner with PnL tracking.

Returns position data including current balance, cost basis, and profit and loss.
Use this endpoint to display portfolio performance, track yields over time, or build
position management interfaces.

Positions are tracked across all venue types (vaults and Aave markets). Each
position includes the venue address, deposited amount, and performance metrics.



## OpenAPI

````yaml /v2/combined_spec.json get /v2/earn/positions
openapi: 3.1.0
info:
  title: Compass API
  description: Compass Labs DeFi API
  version: 0.0.1
servers:
  - url: https://api.compasslabs.ai
    description: Production server
security:
  - ApiKeyAuth: []
paths:
  /v2/earn/positions:
    get:
      tags:
        - Earn
      summary: List earn positions
      description: >-
        List all Earn positions for a given owner with PnL tracking.


        Returns position data including current balance, cost basis, and profit
        and loss.

        Use this endpoint to display portfolio performance, track yields over
        time, or build

        position management interfaces.


        Positions are tracked across all venue types (vaults and Aave markets).
        Each

        position includes the venue address, deposited amount, and performance
        metrics.
      operationId: v2_earn_positions
      parameters:
        - name: chain
          in: query
          required: true
          schema:
            type: string
            enum:
              - arbitrum
              - base
              - ethereum
              - tempo
            title: Chain
            default: base
        - name: owner
          in: query
          required: true
          schema:
            type: string
            title: Owner
            default: '0x06A9aF046187895AcFc7258450B15397CAc67400'
          description: The address of the owner of the earn account to get positions for.
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EarnPositionsResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      x-codeSamples:
        - lang: python
          label: Python (SDK)
          source: |-
            from compass_api_sdk import CompassAPI, models


            with CompassAPI(
                api_key_auth="<YOUR_API_KEY_HERE>",
            ) as compass_api:

                res = compass_api.earn.earn_positions(chain=models.V2EarnPositionsChain.BASE, owner="0x06A9aF046187895AcFc7258450B15397CAc67400")

                # Handle response
                print(res)
        - lang: typescript
          label: Typescript (SDK)
          source: |-
            import { CompassApiSDK } from "@compass-labs/api-sdk";

            const compassApiSDK = new CompassApiSDK({
              apiKeyAuth: "<YOUR_API_KEY_HERE>",
            });

            async function run() {
              const result = await compassApiSDK.earn.earnPositions({
                chain: "base",
                owner: "0x06A9aF046187895AcFc7258450B15397CAc67400",
              });

              console.log(result);
            }

            run();
components:
  schemas:
    EarnPositionsResponse:
      properties:
        aave:
          items:
            $ref: '#/components/schemas/AavePosition'
          type: array
          title: Aave
          description: Aave V3 lending positions.
          default: []
          example:
            - balance: '1250.5432100000'
              deposits: []
              pnl:
                current_value: '1250.5432100000'
                realized_pnl: '0.0000000000'
                total_deposited: '1200.0000000000'
                total_pnl: '50.5432100000'
                total_pnl_percent: '4.2119341667'
                unrealized_pnl: '50.5432100000'
              reserve_address: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48'
              reserve_symbol: USDC
              type: AAVE
              withdrawals: []
        vaults:
          items:
            $ref: >-
              #/components/schemas/compass__api_backend__v2__models__earn__read__response__positions__VaultPosition
          type: array
          title: Vaults
          description: ERC-4626 vault positions.
          default: []
          example:
            - balance: '5000.1234560000'
              deposits: []
              pnl:
                current_value: '5000.1234560000'
                realized_pnl: '0.0000000000'
                total_deposited: '4800.0000000000'
                total_pnl: '200.1234560000'
                total_pnl_percent: '4.1692386667'
                unrealized_pnl: '200.1234560000'
              type: VAULT
              underlying_symbol: USDC
              vault_address: '0xBEEF01735c132Ada46AA9aA4c54623cAA92A64CB'
              vault_name: Steakhouse USDC
              withdrawals: []
        pendle_pt:
          items:
            $ref: '#/components/schemas/PendlePTPosition'
          type: array
          title: Pendle Pt
          description: Pendle Principal Token positions.
          default: []
          example:
            - deposits: []
              expiry: 1735689600
              market_address: '0x7d372819240D14fB477f17b964f95F33BeB4c704'
              pnl:
                current_value: '2.5000000000'
                realized_pnl: '0.0000000000'
                total_deposited: '2.4500000000'
                total_pnl: '0.0500000000'
                total_pnl_percent: '2.0408163265'
                unrealized_pnl: '0.0500000000'
              pt_address: '0x7d372819240D14fB477f17b964f95F33BeB4c704'
              pt_balance: '2.5000000000'
              type: PENDLE_PT
              underlying_symbol: weETH
              withdrawals: []
        total_usd_value:
          anyOf:
            - type: string
            - type: 'null'
          title: Total Usd Value
          description: Total USD value of all positions (sum of available values).
      type: object
      title: EarnPositionsResponse
      description: >-
        Grouped positions by protocol.


        This new structure groups positions by protocol type for better
        organization and

        removes the need for a discriminated union in SDK consumers.
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    AavePosition:
      properties:
        type:
          type: string
          const: AAVE
          title: Type
          description: The market type discriminator.
          examples:
            - VAULT
            - AAVE
            - PENDLE_PT
        reserve_address:
          type: string
          title: Reserve Address
          description: The reserve (underlying token) address.
        reserve_symbol:
          type: string
          title: Reserve Symbol
          description: Symbol of the reserve asset (e.g., USDC).
        balance:
          anyOf:
            - type: string
            - type: 'null'
          title: Balance
          description: The user's position value (aToken balance).
        usd_value:
          anyOf:
            - type: string
            - type: 'null'
          title: Usd Value
          description: Position value in USD (null if price unavailable).
        pnl:
          anyOf:
            - $ref: '#/components/schemas/PositionPnL'
            - type: 'null'
          description: PnL metrics for this position.
        deposits:
          items:
            $ref: '#/components/schemas/DepositEvent'
          type: array
          title: Deposits
          description: All deposit events for this position.
          default: []
        withdrawals:
          items:
            $ref: '#/components/schemas/WithdrawalEvent'
          type: array
          title: Withdrawals
          description: All withdrawal events for this position.
          default: []
        apy:
          anyOf:
            - type: string
            - type: 'null'
          title: Apy
          description: Current supply APY (percentage).
      additionalProperties: false
      type: object
      required:
        - type
        - reserve_address
        - reserve_symbol
        - balance
      title: AavePosition
      description: >-
        Aave V3 lending position.


        Note: Unlike the old model, this no longer has vault_address/vault_name
        fields

        as they were nonsensical for Aave positions.
    compass__api_backend__v2__models__earn__read__response__positions__VaultPosition:
      properties:
        type:
          type: string
          const: VAULT
          title: Type
          description: The market type discriminator.
          examples:
            - VAULT
            - AAVE
            - PENDLE_PT
        vault_address:
          type: string
          title: Vault Address
          description: The vault address.
          examples:
            - '0xBEEF01735c132Ada46AA9aA4c54623cAA92A64CB'
        vault_name:
          type: string
          title: Vault Name
          description: Name of the vault token (share token).
        underlying_symbol:
          type: string
          title: Underlying Symbol
          description: Symbol of the underlying token (e.g., USDC).
        underlying_address:
          type: string
          title: Underlying Address
          description: Address of the underlying token.
        balance:
          anyOf:
            - type: string
            - type: 'null'
          title: Balance
          description: The user's position value in underlying token.
        usd_value:
          anyOf:
            - type: string
            - type: 'null'
          title: Usd Value
          description: Position value in USD (null if price unavailable).
        pnl:
          anyOf:
            - $ref: '#/components/schemas/PositionPnL'
            - type: 'null'
          description: PnL metrics for this position.
        deposits:
          items:
            $ref: '#/components/schemas/DepositEvent'
          type: array
          title: Deposits
          description: All deposit events for this position.
          default: []
        withdrawals:
          items:
            $ref: '#/components/schemas/WithdrawalEvent'
          type: array
          title: Withdrawals
          description: All withdrawal events for this position.
          default: []
        apy_7d:
          anyOf:
            - type: string
            - type: 'null'
          title: Apy 7D
          description: 7-day annualized APY (percentage).
        apy_30d:
          anyOf:
            - type: string
            - type: 'null'
          title: Apy 30D
          description: 30-day annualized APY (percentage).
        apy_90d:
          anyOf:
            - type: string
            - type: 'null'
          title: Apy 90D
          description: 90-day annualized APY (percentage).
      additionalProperties: false
      type: object
      required:
        - type
        - vault_address
        - vault_name
        - underlying_symbol
        - underlying_address
        - balance
      title: VaultPosition
      description: ERC-4626 vault position.
    PendlePTPosition:
      properties:
        type:
          type: string
          const: PENDLE_PT
          title: Type
          description: The market type discriminator.
          examples:
            - VAULT
            - AAVE
            - PENDLE_PT
        market_address:
          type: string
          title: Market Address
          description: The Pendle market address.
          examples:
            - '0xAF9D76938E66d0E52C80fbaA35bEd623d9a57eAa'
        pt_address:
          type: string
          title: Pt Address
          description: The PT (Principal Token) contract address.
        underlying_symbol:
          type: string
          title: Underlying Symbol
          description: Symbol of the underlying asset (e.g., rsETH, weETH).
        underlying_address:
          type: string
          title: Underlying Address
          description: Address of the underlying asset (base asset from SY).
        yield_token_address:
          type: string
          title: Yield Token Address
          description: Address of the yield token (e.g., weETH) used for USD pricing.
        pt_balance:
          anyOf:
            - type: string
            - type: 'null'
          title: Pt Balance
          description: The user's PT token balance.
        expiry:
          type: integer
          title: Expiry
          description: Market expiry timestamp (Unix seconds).
        current_pt_to_sy_rate:
          anyOf:
            - type: string
            - type: 'null'
          title: Current Pt To Sy Rate
          description: Current PT-to-SY exchange rate (SY received per PT if sold now).
        usd_value:
          anyOf:
            - type: string
            - type: 'null'
          title: Usd Value
          description: Position value in USD (null if price unavailable).
        pnl:
          anyOf:
            - $ref: '#/components/schemas/PositionPnL'
            - type: 'null'
          description: PnL metrics (in SY terms) for this position.
        deposits:
          items:
            $ref: '#/components/schemas/PendleDepositEvent'
          type: array
          title: Deposits
          description: All buy PT events for this position.
          default: []
        withdrawals:
          items:
            $ref: '#/components/schemas/PendleWithdrawalEvent'
          type: array
          title: Withdrawals
          description: All sell/redeem PT events for this position.
          default: []
        implied_apy:
          anyOf:
            - type: string
            - type: 'null'
          title: Implied Apy
          description: Implied APY (percentage).
      additionalProperties: false
      type: object
      required:
        - type
        - market_address
        - pt_address
        - underlying_symbol
        - underlying_address
        - yield_token_address
        - pt_balance
        - expiry
        - current_pt_to_sy_rate
      title: PendlePTPosition
      description: Pendle Principal Token position.
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError
    PositionPnL:
      properties:
        total_deposited:
          type: string
          title: Total Deposited
          description: Total assets deposited over all time
        current_value:
          type: string
          title: Current Value
          description: Current position value in underlying
        unrealized_pnl:
          type: string
          title: Unrealized Pnl
          description: current_value - cost_basis_remaining
        realized_pnl:
          type: string
          title: Realized Pnl
          description: Sum of profits/losses from all withdrawals
        total_pnl:
          type: string
          title: Total Pnl
          description: unrealized_pnl + realized_pnl
        total_pnl_percent:
          type: string
          title: Total Pnl Percent
          description: (total_pnl / total_deposited) * 100
      additionalProperties: false
      type: object
      required:
        - total_deposited
        - current_value
        - unrealized_pnl
        - realized_pnl
        - total_pnl
        - total_pnl_percent
      title: PositionPnL
      description: >-
        Simplified PnL metrics for API response.


        Historical events (deposits/withdrawals) are now at the position level,
        not inside

        PnL.
    DepositEvent:
      properties:
        block_number:
          type: integer
          title: Block Number
          description: Block number when deposit occurred
        block_timestamp:
          type: string
          format: date-time
          title: Block Timestamp
          description: Timestamp when deposit occurred
        transaction_hash:
          type: string
          title: Transaction Hash
          description: Transaction hash of the deposit
        input_amount:
          type: string
          title: Input Amount
          description: Amount deposited (underlying asset or swap token)
        input_symbol:
          type: string
          title: Input Symbol
          description: Symbol of token deposited
        output_amount:
          type: string
          title: Output Amount
          description: Units received (shares, aTokens, or PT)
        output_symbol:
          type: string
          title: Output Symbol
          description: Symbol of units received
        cost_per_unit:
          type: string
          title: Cost Per Unit
          description: Cost basis per unit at time of deposit
      type: object
      required:
        - block_number
        - block_timestamp
        - transaction_hash
        - input_amount
        - input_symbol
        - output_amount
        - output_symbol
        - cost_per_unit
      title: DepositEvent
      description: |-
        Historical deposit event for position transparency.

        Uses generic input/output format that works across all protocols:
        - Vault: input=underlying, output=shares
        - Aave: input=underlying, output=aTokens
        - Pendle: input=token (varies), output=PT
    WithdrawalEvent:
      properties:
        block_number:
          type: integer
          title: Block Number
          description: Block number when withdrawal occurred
        block_timestamp:
          type: string
          format: date-time
          title: Block Timestamp
          description: Timestamp when withdrawal occurred
        transaction_hash:
          type: string
          title: Transaction Hash
          description: Transaction hash of the withdrawal
        input_amount:
          type: string
          title: Input Amount
          description: Units withdrawn (shares, aTokens, PT)
        input_symbol:
          type: string
          title: Input Symbol
          description: Symbol of units withdrawn
        output_amount:
          type: string
          title: Output Amount
          description: Amount received (underlying or token)
        output_symbol:
          type: string
          title: Output Symbol
          description: Symbol of token received
        realized_pnl:
          type: string
          title: Realized Pnl
          description: 'Profit/loss: output value - cost basis consumed'
      type: object
      required:
        - block_number
        - block_timestamp
        - transaction_hash
        - input_amount
        - input_symbol
        - output_amount
        - output_symbol
        - realized_pnl
      title: WithdrawalEvent
      description: |-
        Historical withdrawal event with realized PnL.

        Uses generic input/output format:
        - Vault: input=shares, output=underlying
        - Aave: input=aTokens, output=underlying
        - Pendle: input=PT, output=token (varies)
    PendleDepositEvent:
      properties:
        block_number:
          type: integer
          title: Block Number
          description: Block number when deposit occurred
        block_timestamp:
          type: string
          format: date-time
          title: Block Timestamp
          description: Timestamp when deposit occurred
        transaction_hash:
          type: string
          title: Transaction Hash
          description: Transaction hash of the deposit
        input_amount:
          type: string
          title: Input Amount
          description: Amount deposited (token spent)
        input_symbol:
          type: string
          title: Input Symbol
          description: Symbol of token deposited
        output_amount:
          type: string
          title: Output Amount
          description: PT tokens received
        output_symbol:
          type: string
          title: Output Symbol
          description: Symbol (PT)
        cost_per_unit:
          type: string
          title: Cost Per Unit
          description: Cost basis per PT at deposit (SY spent per PT acquired)
      type: object
      required:
        - block_number
        - block_timestamp
        - transaction_hash
        - input_amount
        - input_symbol
        - output_amount
        - output_symbol
        - cost_per_unit
      title: PendleDepositEvent
      description: Pendle PT deposit event with cost basis at time of deposit.
    PendleWithdrawalEvent:
      properties:
        block_number:
          type: integer
          title: Block Number
          description: Block number when withdrawal occurred
        block_timestamp:
          type: string
          format: date-time
          title: Block Timestamp
          description: Timestamp when withdrawal occurred
        transaction_hash:
          type: string
          title: Transaction Hash
          description: Transaction hash of the withdrawal
        input_amount:
          type: string
          title: Input Amount
          description: PT tokens sold/redeemed
        input_symbol:
          type: string
          title: Input Symbol
          description: Symbol (PT)
        output_amount:
          type: string
          title: Output Amount
          description: Amount received (SY or token)
        output_symbol:
          type: string
          title: Output Symbol
          description: Symbol of token received
        realized_pnl:
          type: string
          title: Realized Pnl
          description: 'Profit/loss: output value - cost basis consumed'
        cost_per_unit:
          type: string
          title: Cost Per Unit
          description: Cost basis per PT at withdrawal (SY received per PT sold)
      type: object
      required:
        - block_number
        - block_timestamp
        - transaction_hash
        - input_amount
        - input_symbol
        - output_amount
        - output_symbol
        - realized_pnl
        - cost_per_unit
      title: PendleWithdrawalEvent
      description: Pendle PT withdrawal event with cost basis at time of withdrawal.
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: >-
        Your Compass API Key. Get your key
        [here](https://www.compasslabs.ai/dashboard).

````