> ## 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 LP positions

> Your liquidity positions: what they hold, what they cost, what they paid.

Only the first of those is on chain. A position reports its liquidity and
its range; it does not report the amounts that opened it or what has already
been collected. Those come from recorded events, and where there are none
`cost_basis.source` is `unavailable` and the PnL fields are null rather than
guessed — an invented cost basis would make every number derived from it
wrong in the same direction.

`hold_value_usd` is what the deposited amounts would be worth if they had
simply been held. The gap between that and `value_usd` is impermanent loss,
and it is the number that decides whether the fees were worth it.

`needs_rebalance` and `rebalance_reasons` say what the API would look at, not
what it will do: rebalancing realizes the loss, pays gas twice and a swap,
and puts the position back at risk from a new price.



## OpenAPI

````yaml /v2/combined_spec.json get /v2/risk_yield/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/risk_yield/positions:
    get:
      tags:
        - Risk Yield
      summary: List LP positions
      description: >-
        Your liquidity positions: what they hold, what they cost, what they
        paid.


        Only the first of those is on chain. A position reports its liquidity
        and

        its range; it does not report the amounts that opened it or what has
        already

        been collected. Those come from recorded events, and where there are
        none

        `cost_basis.source` is `unavailable` and the PnL fields are null rather
        than

        guessed — an invented cost basis would make every number derived from it

        wrong in the same direction.


        `hold_value_usd` is what the deposited amounts would be worth if they
        had

        simply been held. The gap between that and `value_usd` is impermanent
        loss,

        and it is the number that decides whether the fees were worth it.


        `needs_rebalance` and `rebalance_reasons` say what the API would look
        at, not

        what it will do: rebalancing realizes the loss, pays gas twice and a
        swap,

        and puts the position back at risk from a new price.
      operationId: v2_risk_yield_positions
      parameters:
        - name: chain
          in: query
          required: true
          schema:
            type: string
            enum:
              - robinhood
            title: Chain
            default: robinhood
        - name: owner
          in: query
          required: true
          schema:
            type: string
            title: Owner
            default: '0x06A9aF046187895AcFc7258450B15397CAc67400'
          description: The wallet that owns the Risk Yield Account.
        - name: dex_version
          in: query
          required: false
          schema:
            anyOf:
              - $ref: '#/components/schemas/DexVersion'
              - type: 'null'
            title: Dex Version
        - name: include_closed
          in: query
          required: false
          schema:
            type: boolean
            default: false
            title: Include Closed
          description: >-
            Include positions with no liquidity and nothing owed. Off by
            default: a closed position is history, not a holding.
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RiskYieldPositionsResponse'
        '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.risk_yield.risk_yield_positions(chain=models.V2RiskYieldPositionsChain.ROBINHOOD, owner="0x06A9aF046187895AcFc7258450B15397CAc67400", include_closed=False)

                # 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.riskYield.riskYieldPositions({
                chain: "robinhood",
                owner: "0x06A9aF046187895AcFc7258450B15397CAc67400",
                includeClosed: false,
              });

              console.log(result);
            }

            run();
components:
  schemas:
    DexVersion:
      type: string
      enum:
        - V3
        - V4
      title: DexVersion
      description: >-
        Which Uniswap deployment a pool belongs to.


        v3 pools hold their own tokens and pay LPs the fee tier. v4 pools live
        in a

        shared PoolManager and may route the fee through a hook, which is where
        the

        launchpad pools' zero LP yield comes from.
    RiskYieldPositionsResponse:
      properties:
        account:
          type: string
          title: Account
        positions:
          items:
            $ref: '#/components/schemas/LpPosition'
          type: array
          title: Positions
        total_value_usd:
          anyOf:
            - type: string
            - type: 'null'
          title: Total Value Usd
        total_unclaimed_fees_usd:
          anyOf:
            - type: string
            - type: 'null'
          title: Total Unclaimed Fees Usd
        total_pnl_usd:
          anyOf:
            - type: string
            - type: 'null'
          title: Total Pnl Usd
        prices_updated_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Prices Updated At
      type: object
      required:
        - account
        - positions
      title: RiskYieldPositionsResponse
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    LpPosition:
      properties:
        token_id:
          type: integer
          title: Token Id
          description: The position NFT's id.
        dex_version:
          $ref: '#/components/schemas/DexVersion'
        pool_id:
          anyOf:
            - type: integer
            - type: 'null'
          title: Pool Id
        pool_address:
          anyOf:
            - type: string
            - type: 'null'
          title: Pool Address
        token0:
          $ref: '#/components/schemas/DexTokenRef'
        token1:
          $ref: '#/components/schemas/DexTokenRef'
        fee_ppm:
          type: integer
          title: Fee Ppm
        range:
          $ref: '#/components/schemas/ResolvedRange'
        liquidity:
          type: string
          title: Liquidity
        current_tick:
          anyOf:
            - type: integer
            - type: 'null'
          title: Current Tick
        current_price:
          anyOf:
            - type: string
            - type: 'null'
          title: Current Price
        in_range:
          type: boolean
          title: In Range
        out_of_range_side:
          anyOf:
            - type: string
            - type: 'null'
          title: Out Of Range Side
          description: '`below` or `above`: which asset the position is now all of.'
        amount0:
          type: string
          title: Amount0
        amount1:
          type: string
          title: Amount1
        value_usd:
          anyOf:
            - type: string
            - type: 'null'
          title: Value Usd
        unclaimed_fees0:
          type: string
          title: Unclaimed Fees0
        unclaimed_fees1:
          type: string
          title: Unclaimed Fees1
        unclaimed_fees_usd:
          anyOf:
            - type: string
            - type: 'null'
          title: Unclaimed Fees Usd
        fees_collected0:
          anyOf:
            - type: string
            - type: 'null'
          title: Fees Collected0
        fees_collected1:
          anyOf:
            - type: string
            - type: 'null'
          title: Fees Collected1
        cost_basis:
          $ref: '#/components/schemas/CostBasis'
        hold_value_usd:
          anyOf:
            - type: string
            - type: 'null'
          title: Hold Value Usd
          description: >-
            What the deposited amounts would be worth had they simply been held.
            The comparison that makes impermanent loss meaningful.
        il_usd:
          anyOf:
            - type: string
            - type: 'null'
          title: Il Usd
        il_pct:
          anyOf:
            - type: string
            - type: 'null'
          title: Il Pct
        fees_earned_usd:
          anyOf:
            - type: string
            - type: 'null'
          title: Fees Earned Usd
          description: Collected plus unclaimed.
        pnl_usd:
          anyOf:
            - type: string
            - type: 'null'
          title: Pnl Usd
          description: Position value plus fees earned, less what it cost to open.
        fee_apr_since_open_pct:
          anyOf:
            - type: string
            - type: 'null'
          title: Fee Apr Since Open Pct
        age_days:
          anyOf:
            - type: string
            - type: 'null'
          title: Age Days
        status:
          $ref: '#/components/schemas/PositionStatus'
        needs_rebalance:
          type: boolean
          title: Needs Rebalance
          default: false
        rebalance_reasons:
          items:
            $ref: '#/components/schemas/RebalanceReason'
          type: array
          title: Rebalance Reasons
        needs_collect:
          type: boolean
          title: Needs Collect
          default: false
        lp_earns_fees:
          type: boolean
          title: Lp Earns Fees
          description: >-
            False when this pool's hook keeps the swap fee. Such a position
            accrues impermanent loss and earns nothing against it.
          default: true
      type: object
      required:
        - token_id
        - dex_version
        - token0
        - token1
        - fee_ppm
        - range
        - liquidity
        - in_range
        - amount0
        - amount1
        - unclaimed_fees0
        - unclaimed_fees1
        - cost_basis
        - status
      title: LpPosition
    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
    DexTokenRef:
      properties:
        address:
          type: string
          title: Address
        symbol:
          anyOf:
            - type: string
            - type: 'null'
          title: Symbol
        name:
          anyOf:
            - type: string
            - type: 'null'
          title: Name
        decimals:
          anyOf:
            - type: integer
            - type: 'null'
          title: Decimals
          description: Null until read on chain; never assume 18 on this chain.
        kind:
          $ref: '#/components/schemas/DexTokenKind'
          default: OTHER
        price_usd:
          anyOf:
            - type: string
            - type: 'null'
          title: Price Usd
        price_source:
          anyOf:
            - $ref: '#/components/schemas/PriceSource'
            - type: 'null'
        price_confidence:
          anyOf:
            - type: string
            - type: 'null'
          title: Price Confidence
          description: 0-1. Below 0.6 the USD figures derived from it are indicative only.
        stock_ticker:
          anyOf:
            - type: string
            - type: 'null'
          title: Stock Ticker
      type: object
      required:
        - address
      title: DexTokenRef
      description: A token as every Risk Yield response describes it.
    ResolvedRange:
      properties:
        tick_lower:
          type: integer
          title: Tick Lower
        tick_upper:
          type: integer
          title: Tick Upper
        price_lower:
          type: string
          title: Price Lower
        price_upper:
          type: string
          title: Price Upper
        width_lower_pct:
          type: string
          title: Width Lower Pct
          description: How far below the current price the lower bound sits.
        width_upper_pct:
          type: string
          title: Width Upper Pct
        is_full_range:
          type: boolean
          title: Is Full Range
      type: object
      required:
        - tick_lower
        - tick_upper
        - price_lower
        - price_upper
        - width_lower_pct
        - width_upper_pct
        - is_full_range
      title: ResolvedRange
      description: >-
        A range after the API has snapped it to the pool's tick spacing.


        Returned because the range you asked for is rarely the range you get:
        ticks

        are discrete, and a 30% band becomes whichever usable ticks bracket it.
    CostBasis:
      properties:
        source:
          $ref: '#/components/schemas/CostBasisSource'
        amount0:
          anyOf:
            - type: string
            - type: 'null'
          title: Amount0
        amount1:
          anyOf:
            - type: string
            - type: 'null'
          title: Amount1
        value_usd:
          anyOf:
            - type: string
            - type: 'null'
          title: Value Usd
        opened_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Opened At
      type: object
      required:
        - source
      title: CostBasis
      description: >-
        What the position cost to open.


        Not readable from the chain: a position reports its liquidity, never the

        amounts that bought it. This comes from recorded events, and when there
        are

        none the PnL fields are null rather than guessed — an invented cost
        basis

        would make every number derived from it quietly wrong.
    PositionStatus:
      type: string
      enum:
        - ACTIVE
        - OUT_OF_RANGE
        - EMPTY
        - CLOSED
      title: PositionStatus
    RebalanceReason:
      type: string
      enum:
        - OUT_OF_RANGE
        - PRICE_DRIFT
        - VOL_REGIME_CHANGE
        - UNCOLLECTED_FEES
        - FEES_NOT_EARNED
        - STALE_DATA
      title: RebalanceReason
    DexTokenKind:
      type: string
      enum:
        - STOCK
        - STABLE
        - NATIVE
        - WRAPPED_NATIVE
        - MAJOR
        - LAUNCHPAD_MEME
        - OTHER
      title: DexTokenKind
    PriceSource:
      type: string
      enum:
        - CHAINLINK
        - RH_REST
        - LLAMA
        - POOL
        - PEG
      title: PriceSource
      description: >-
        Where a USD price came from, best first.


        Returned with every price because they are not equally trustworthy: a

        Chainlink feed is a measurement, a price read off a shallow pool is
        closer

        to a rumour.
    CostBasisSource:
      type: string
      enum:
        - indexed
        - onchain_logs
        - unavailable
      title: CostBasisSource
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: >-
        Your Compass API Key. Get your key
        [here](https://www.compasslabs.ai/dashboard).

````