# Liquidity Analytics

Track user liquidity positions, portfolio value, yield performance, and LP token holdings across AMM pools.

> ⚠️ **Indexer Notice**: Kadindexer's DeFi queries are currently configured to index and parse event patterns emitted by SushiSwap modules. Data from other DEX implementations requires custom event pattern configuration. Contact toni@hackachain.io to discuss indexing additional protocols.


## liquidityPositions: User Portfolio

Query all liquidity positions for a specific wallet address with sorting and filtering options.


```graphql
query UserLiquidityPositions(
  $walletAddress: String!
  $orderBy: LiquidityPositionOrderBy
  $first: Int
) {
  liquidityPositions(
    walletAddress: $walletAddress
    orderBy: $orderBy
    first: $first
  ) {
    edges {
      node {
        id
        pairId
        liquidity
        valueUsd
        apr24h
        walletAddress
        pair {
          id
          address
          token0 {
            name
            address
          }
          token1 {
            name
            address
          }
          reserve0
          reserve1
          tvlUsd
          volume24hUsd
        }
        createdAt
        updatedAt
      }
    }
    totalCount
  }
}
```

**Variables**


```json
{
  "walletAddress": "k:e23d2dcc79f5a10e0d0f8210cbaa89e505157f84bff7176f1367a43469bb6bad",
  "orderBy": "VALUE_USD_DESC",
  "first": 20
}
```

**Response**


```json
{
  "data": {
    "liquidityPositions": {
      "edges": [
        {
          "node": {
            "id": "17",
            "pairId": "n_bd19ba92f0449d4422e620740759c9e94cacdb37.sushi-exchange-coin:n_e309f0fa7cf3a13f93a8da5325cdad32790d2070.heron",
            "liquidity": "554304.805390613745",
            "valueUsd": null,
            "apr24h": 0.00068209,
            "walletAddress": "k:e23d2dcc79f5a10e0d0f8210cbaa89e505157f84bff7176f1367a43469bb6bad",
            "pair": {
              "id": "n_bd19ba92f0449d4422e620740759c9e94cacdb37.sushi-exchange-coin:n_e309f0fa7cf3a13f93a8da5325cdad32790d2070.heron",
              "address": "n_bd19ba92f0449d4422e620740759c9e94cacdb37.sushi-exchange",
              "token0": {
                "name": "coin",
                "address": "coin"
              },
              "token1": {
                "name": "heron",
                "address": "n_e309f0fa7cf3a13f93a8da5325cdad32790d2070.heron"
              },
              "reserve0": "12770.504435455846",
              "reserve1": "38074537.408709260683",
              "tvlUsd": 8617.61238464,
              "volume24hUsd": 5.35193683
            },
            "createdAt": "2025-09-06T15:45:01.207Z",
            "updatedAt": "2025-09-06T15:45:01.207Z"
          }
        },
        {
          "node": {
            "id": "20",
            "pairId": "n_bd19ba92f0449d4422e620740759c9e94cacdb37.sushi-exchange-coin:n_518dfea5f0d2abe95cbcd8956eb97f3238e274a9.AZUKI",
            "liquidity": "229283.219025423190",
            "valueUsd": null,
            "apr24h": 0.00033067,
            "walletAddress": "k:e23d2dcc79f5a10e0d0f8210cbaa89e505157f84bff7176f1367a43469bb6bad",
            "pair": {
              "id": "n_bd19ba92f0449d4422e620740759c9e94cacdb37.sushi-exchange-coin:n_518dfea5f0d2abe95cbcd8956eb97f3238e274a9.AZUKI",
              "address": "n_bd19ba92f0449d4422e620740759c9e94cacdb37.sushi-exchange",
              "token0": {
                "name": "coin",
                "address": "coin"
              },
              "token1": {
                "name": "AZUKI",
                "address": "n_518dfea5f0d2abe95cbcd8956eb97f3238e274a9.AZUKI"
              },
              "reserve0": "9797.032670542943",
              "reserve1": "5388913.746947418574",
              "tvlUsd": 6688.70476706,
              "volume24hUsd": 2.01381383
            },
            "createdAt": "2025-09-07T14:37:01.481Z",
            "updatedAt": "2025-09-07T14:37:01.481Z"
          }
        },
        {
          "node": {
            "id": "39",
            "pairId": "n_bd19ba92f0449d4422e620740759c9e94cacdb37.sushi-exchange-coin:free.kishu-ken",
            "liquidity": "349012893.743629442691",
            "valueUsd": null,
            "apr24h": 0.01672196,
            "walletAddress": "k:e23d2dcc79f5a10e0d0f8210cbaa89e505157f84bff7176f1367a43469bb6bad",
            "pair": {
              "id": "n_bd19ba92f0449d4422e620740759c9e94cacdb37.sushi-exchange-coin:free.kishu-ken",
              "address": "n_bd19ba92f0449d4422e620740759c9e94cacdb37.sushi-exchange",
              "token0": {
                "name": "coin",
                "address": "coin"
              },
              "token1": {
                "name": "kishu-ken",
                "address": "free.kishu-ken"
              },
              "reserve0": "9030.850560907996",
              "reserve1": "13495122135779.406220200723",
              "tvlUsd": 6564.39033188,
              "volume24hUsd": 99.94534988
            },
            "createdAt": "2025-09-10T20:35:02.695Z",
            "updatedAt": "2025-09-10T20:35:02.695Z"
          }
        },
        {
          "node": {
            "id": "43",
            "pairId": "n_bd19ba92f0449d4422e620740759c9e94cacdb37.sushi-exchange-coin:free.crankk01",
            "liquidity": "104605.495987491060",
            "valueUsd": null,
            "apr24h": 0.00028899,
            "walletAddress": "k:e23d2dcc79f5a10e0d0f8210cbaa89e505157f84bff7176f1367a43469bb6bad",
            "pair": {
              "id": "n_bd19ba92f0449d4422e620740759c9e94cacdb37.sushi-exchange-coin:free.crankk01",
              "address": "n_bd19ba92f0449d4422e620740759c9e94cacdb37.sushi-exchange",
              "token0": {
                "name": "coin",
                "address": "coin"
              },
              "token1": {
                "name": "crankk01",
                "address": "free.crankk01"
              },
              "reserve0": "8694.320210810076",
              "reserve1": "1259338.187456126080",
              "tvlUsd": 5998.24006345,
              "volume24hUsd": 1.578285
            },
            "createdAt": "2025-09-11T16:19:02.924Z",
            "updatedAt": "2025-09-11T16:19:02.924Z"
          }
        },
        {
          "node": {
            "id": "19",
            "pairId": "n_bd19ba92f0449d4422e620740759c9e94cacdb37.sushi-exchange-coin:n_582fed11af00dc626812cd7890bb88e72067f28c.bro",
            "liquidity": "137.937247052802",
            "valueUsd": 6375.20886898,
            "apr24h": 0.00119638,
            "walletAddress": "k:e23d2dcc79f5a10e0d0f8210cbaa89e505157f84bff7176f1367a43469bb6bad",
            "pair": {
              "id": "n_bd19ba92f0449d4422e620740759c9e94cacdb37.sushi-exchange-coin:n_582fed11af00dc626812cd7890bb88e72067f28c.bro",
              "address": "n_bd19ba92f0449d4422e620740759c9e94cacdb37.sushi-exchange",
              "token0": {
                "name": "coin",
                "address": "coin"
              },
              "token1": {
                "name": "bro",
                "address": "n_582fed11af00dc626812cd7890bb88e72067f28c.bro"
              },
              "reserve0": "9443.561218055584",
              "reserve1": "2.020456010431",
              "tvlUsd": 6375.20886898,
              "volume24hUsd": 6.9445588
            },
            "createdAt": "2025-09-06T20:33:01.236Z",
            "updatedAt": "2025-09-06T20:33:01.236Z"
          }
        },
        {
          "node": {
            "id": "51",
            "pairId": "n_bd19ba92f0449d4422e620740759c9e94cacdb37.sushi-exchange-coin:n_625e9938ae84bdb7d190f14fc283c7a6dfc15d58.ktoshi",
            "liquidity": "24392621.834300937294",
            "valueUsd": 6043.364826229999,
            "apr24h": 0.00303869,
            "walletAddress": "k:e23d2dcc79f5a10e0d0f8210cbaa89e505157f84bff7176f1367a43469bb6bad",
            "pair": {
              "id": "n_bd19ba92f0449d4422e620740759c9e94cacdb37.sushi-exchange-coin:n_625e9938ae84bdb7d190f14fc283c7a6dfc15d58.ktoshi",
              "address": "n_bd19ba92f0449d4422e620740759c9e94cacdb37.sushi-exchange",
              "token0": {
                "name": "coin",
                "address": "coin"
              },
              "token1": {
                "name": "ktoshi",
                "address": "n_625e9938ae84bdb7d190f14fc283c7a6dfc15d58.ktoshi"
              },
              "reserve0": "9042.615232763131",
              "reserve1": "65909930206.367753557787417",
              "tvlUsd": 6043.36482623,
              "volume24hUsd": 16.72036646
            },
            "createdAt": "2025-09-12T21:49:20.131Z",
            "updatedAt": "2025-09-12T21:49:20.131Z"
          }
        }
      ],
      "totalCount": 6
    }
  }
}
```

**Sort Options**

- `VALUE_USD_DESC` - Highest position value first (default)
- `VALUE_USD_ASC` - Lowest position value first
- `LIQUIDITY_DESC` - Most LP tokens held
- `LIQUIDITY_ASC` - Least LP tokens held
- `APR_DESC` - Highest yield first
- `APR_ASC` - Lowest yield first


**Use Cases**

- Wallet liquidity portfolio views
- DeFi position tracking
- Yield farming dashboards
- Portfolio value aggregation


**Notes**
Liquidity values are LP token amounts as strings for precision. Position values calculated using DIA price data refreshed every ~5 minutes. APR based on 24h fee performance relative to TVL. Total portfolio value is sum of all position valueUsd.

## Position Value Calculation

Track individual position value and share of pool liquidity.


```graphql
query PositionValue($walletAddress: String!, $first: Int) {
  liquidityPositions(walletAddress: $walletAddress, first: $first) {
    edges {
      node {
        id
        liquidity
        valueUsd
        pair {
          id
          reserve0
          reserve1
          totalSupply
          token0 {
            name
          }
          token1 {
            name
          }
        }
      }
    }
    totalCount
  }
}
```

**Variables**


```json
{
  "walletAddress": "k:e23d2dcc79f5a10e0d0f8210cbaa89e505157f84bff7176f1367a43469bb6bad",
  "first": 10
}
```

**Response**


```json
{
  "data": {
    "liquidityPositions": {
      "edges": [
        {
          "node": {
            "id": "17",
            "liquidity": "554304.805390613745",
            "valueUsd": null,
            "pair": {
              "id": "n_bd19ba92f0449d4422e620740759c9e94cacdb37.sushi-exchange-coin:n_e309f0fa7cf3a13f93a8da5325cdad32790d2070.heron",
              "reserve0": "12770.504435455846",
              "reserve1": "38074537.408709260683",
              "totalSupply": "NaN",
              "token0": {
                "name": "coin"
              },
              "token1": {
                "name": "heron"
              }
            }
          }
        },
        {
          "node": {
            "id": "20",
            "liquidity": "229283.219025423190",
            "valueUsd": null,
            "pair": {
              "id": "n_bd19ba92f0449d4422e620740759c9e94cacdb37.sushi-exchange-coin:n_518dfea5f0d2abe95cbcd8956eb97f3238e274a9.AZUKI",
              "reserve0": "9797.032670542943",
              "reserve1": "5388913.746947418574",
              "totalSupply": "NaN",
              "token0": {
                "name": "coin"
              },
              "token1": {
                "name": "AZUKI"
              }
            }
          }
        },
        {
          "node": {
            "id": "39",
            "liquidity": "349012893.743629442691",
            "valueUsd": null,
            "pair": {
              "id": "n_bd19ba92f0449d4422e620740759c9e94cacdb37.sushi-exchange-coin:free.kishu-ken",
              "reserve0": "9030.850560907996",
              "reserve1": "13495122135779.406220200723",
              "totalSupply": "NaN",
              "token0": {
                "name": "coin"
              },
              "token1": {
                "name": "kishu-ken"
              }
            }
          }
        },
        {
          "node": {
            "id": "43",
            "liquidity": "104605.495987491060",
            "valueUsd": null,
            "pair": {
              "id": "n_bd19ba92f0449d4422e620740759c9e94cacdb37.sushi-exchange-coin:free.crankk01",
              "reserve0": "8694.320210810076",
              "reserve1": "1259338.187456126080",
              "totalSupply": "NaN",
              "token0": {
                "name": "coin"
              },
              "token1": {
                "name": "crankk01"
              }
            }
          }
        },
        {
          "node": {
            "id": "19",
            "liquidity": "137.937247052802",
            "valueUsd": 6375.20886898,
            "pair": {
              "id": "n_bd19ba92f0449d4422e620740759c9e94cacdb37.sushi-exchange-coin:n_582fed11af00dc626812cd7890bb88e72067f28c.bro",
              "reserve0": "9443.561218055584",
              "reserve1": "2.020456010431",
              "totalSupply": "137.937247052802",
              "token0": {
                "name": "coin"
              },
              "token1": {
                "name": "bro"
              }
            }
          }
        },
        {
          "node": {
            "id": "51",
            "liquidity": "24392621.834300937294",
            "valueUsd": 6043.364826229999,
            "pair": {
              "id": "n_bd19ba92f0449d4422e620740759c9e94cacdb37.sushi-exchange-coin:n_625e9938ae84bdb7d190f14fc283c7a6dfc15d58.ktoshi",
              "reserve0": "9042.615232763131",
              "reserve1": "65909930206.367753557787417",
              "totalSupply": "24392621.83430094",
              "token0": {
                "name": "coin"
              },
              "token1": {
                "name": "ktoshi"
              }
            }
          }
        }
      ],
      "totalCount": 6
    }
  }
}
```

**Position Calculations**


```javascript
// Pool ownership percentage
const ownership = (liquidity / totalSupply) * 100

// Token amounts owned
const token0Amount = (liquidity / totalSupply) * reserve0

const token1Amount = (liquidity / totalSupply) * reserve1
```

**Use Cases**

- Position value tracking
- Underlying token calculations
- Pool ownership percentage
- Impermanent loss estimation


**Notes**
Position value reflects current market prices via DIA data. Liquidity represents LP token balance. Use reserve and totalSupply to calculate underlying token amounts. Values update every ~5 minutes with price data.

## Yield Performance Analytics

Track APR, fees earned, and yield performance across positions.


```graphql
query YieldAnalytics($walletAddress: String!, $orderBy: LiquidityPositionOrderBy) {
  liquidityPositions(
    walletAddress: $walletAddress
    orderBy: $orderBy
  ) {
    edges {
      node {
        id
        pairId
        liquidity
        valueUsd
        apr24h
        createdAt
      }
    }
    totalCount
  }
}
```

**Variables**


```json
{
  "walletAddress": "k:e23d2dcc79f5a10e0d0f8210cbaa89e505157f84bff7176f1367a43469bb6bad",
  "orderBy": "APR_DESC"
}
```

**Response**


```json
{
  "data": {
    "liquidityPositions": {
      "edges": [
        {
          "node": {
            "id": "39",
            "pairId": "n_bd19ba92f0449d4422e620740759c9e94cacdb37.sushi-exchange-coin:free.kishu-ken",
            "liquidity": "349012893.743629442691",
            "valueUsd": null,
            "apr24h": 0.01672196,
            "createdAt": "2025-09-10T20:35:02.695Z"
          }
        },
        {
          "node": {
            "id": "51",
            "pairId": "n_bd19ba92f0449d4422e620740759c9e94cacdb37.sushi-exchange-coin:n_625e9938ae84bdb7d190f14fc283c7a6dfc15d58.ktoshi",
            "liquidity": "24392621.834300937294",
            "valueUsd": 6043.364826229999,
            "apr24h": 0.00303869,
            "createdAt": "2025-09-12T21:49:20.131Z"
          }
        },
        {
          "node": {
            "id": "19",
            "pairId": "n_bd19ba92f0449d4422e620740759c9e94cacdb37.sushi-exchange-coin:n_582fed11af00dc626812cd7890bb88e72067f28c.bro",
            "liquidity": "137.937247052802",
            "valueUsd": 6375.20886898,
            "apr24h": 0.00119638,
            "createdAt": "2025-09-06T20:33:01.236Z"
          }
        },
        {
          "node": {
            "id": "17",
            "pairId": "n_bd19ba92f0449d4422e620740759c9e94cacdb37.sushi-exchange-coin:n_e309f0fa7cf3a13f93a8da5325cdad32790d2070.heron",
            "liquidity": "554304.805390613745",
            "valueUsd": null,
            "apr24h": 0.00068209,
            "createdAt": "2025-09-06T15:45:01.207Z"
          }
        },
        {
          "node": {
            "id": "20",
            "pairId": "n_bd19ba92f0449d4422e620740759c9e94cacdb37.sushi-exchange-coin:n_518dfea5f0d2abe95cbcd8956eb97f3238e274a9.AZUKI",
            "liquidity": "229283.219025423190",
            "valueUsd": null,
            "apr24h": 0.00033067,
            "createdAt": "2025-09-07T14:37:01.481Z"
          }
        },
        {
          "node": {
            "id": "43",
            "pairId": "n_bd19ba92f0449d4422e620740759c9e94cacdb37.sushi-exchange-coin:free.crankk01",
            "liquidity": "104605.495987491060",
            "valueUsd": null,
            "apr24h": 0.00028899,
            "createdAt": "2025-09-11T16:19:02.924Z"
          }
        }
      ],
      "totalCount": 6
    }
  }
}
```

**Yield Metrics**

- `apr24h` - 24h annualized percentage rate
- `fees24hUsd` - Pool's 24h fee revenue
- `volume24hUsd` - Pool's 24h trading volume
- `tvlUsd` - Pool's total value locked


**Yield Calculations**


```javascript
// Daily fee share estimate
const ownership = liquidity / pair.totalSupply
const dailyFees = pair.fees24hUsd * ownership

// Annual yield estimate
const annualYield = (apr24h / 100) * valueUsd

// Position earning rate per day
const dailyEarnings = annualYield / 365
```

**Use Cases**

- Yield comparison across positions
- APR-based strategy optimization
- Fee revenue tracking
- High-yield pool discovery


**Notes**
APR calculated from 24h fees extrapolated annually. Actual returns vary based on trading activity and price movements. Higher APR often correlates with higher volatility. Fee distribution proportional to LP token ownership.

## Portfolio Aggregation

Calculate total portfolio value and position distribution.


```graphql
query PortfolioSummary($walletAddress: String!) {
  liquidityPositions(walletAddress: $walletAddress) {
    edges {
      node {
        id
        valueUsd
        apr24h
        pair {
          token0 {
            name
          }
          token1 {
            name
          }
        }
      }
    }
    totalCount
  }
}
```

**Variables**


```json
{
  "walletAddress": "k:abcdef123456789"
}
```

**Response**


```json
{
  "data": {
    "liquidityPositions": {
      "edges": [
        {
          "node": {
            "id": "1",
            "valueUsd": 42500.75,
            "apr24h": 45.2,
            "pair": {
              "token0": {
                "name": "coin"
              },
              "token1": {
                "name": "KDX"
              }
            }
          }
        },
        {
          "node": {
            "id": "2",
            "valueUsd": 18750.50,
            "apr24h": 32.8,
            "pair": {
              "token0": {
                "name": "coin"
              },
              "token1": {
                "name": "FLUX"
              }
            }
          }
        },
        {
          "node": {
            "id": "3",
            "valueUsd": 12000.00,
            "apr24h": 28.5,
            "pair": {
              "token0": {
                "name": "KDX"
              },
              "token1": {
                "name": "FLUX"
              }
            }
          }
        }
      ],
      "totalCount": 3
    }
  }
}
```

**Portfolio Calculations**


```javascript
// Total portfolio value
const totalValue = positions.reduce((sum, pos) => sum + pos.valueUsd, 0)
// 42500.75 + 18750.50 + 12000.00 = 73251.25 USD

// Weighted average APR
const weightedAPR = positions.reduce((sum, pos) => {
  return sum + (pos.apr24h * (pos.valueUsd / totalValue))
}, 0)
// (45.2 * 0.58) + (32.8 * 0.26) + (28.5 * 0.16) = 38.3%

// Position distribution
const distribution = positions.map(pos => ({
  pair: `${pos.pair.token0.name}-${pos.pair.token1.name}`,
  percentage: (pos.valueUsd / totalValue) * 100
}))
```

**Use Cases**

- Portfolio value dashboards
- Asset allocation analysis
- Weighted yield calculations
- Position diversification tracking


**Notes**
Sum all position valueUsd for total portfolio value. Calculate weighted APR based on position size. Track position count via totalCount. Values update with DIA price refreshes every ~5 minutes.

## Position History and Tracking

Monitor position creation dates and value changes over time.


```graphql
query PositionHistory($walletAddress: String!) {
  liquidityPositions(walletAddress: $walletAddress) {
    edges {
      node {
        id
        pairId
        liquidity
        valueUsd
        pair {
          token0 {
            name
          }
          token1 {
            name
          }
        }
        createdAt
        updatedAt
      }
    }
    totalCount
  }
}
```

**Variables**


```json
{
  "walletAddress": "k:abcdef123456789"
}
```

**Response**


```json
{
  "data": {
    "liquidityPositions": {
      "edges": [
        {
          "node": {
            "id": "1",
            "pairId": "coin-kdx-pair",
            "liquidity": "15000.50",
            "valueUsd": 42500.75,
            "pair": {
              "token0": {
                "name": "coin"
              },
              "token1": {
                "name": "KDX"
              }
            },
            "createdAt": "2024-01-15T10:00:00Z",
            "updatedAt": "2024-03-15T14:30:00Z"
          }
        }
      ],
      "totalCount": 1
    }
  }
}
```

**Use Cases**

- Position age tracking
- Entry price analysis
- Historical performance review
- Long-term vs new position comparison


**Notes**
createdAt marks initial liquidity provision. updatedAt reflects last modification. Track position duration for performance analysis. Combine with historical pool data for P&L calculations.