# Pool Data & TVL

Query liquidity pool reserves, total value locked (TVL), trading volume, and performance metrics for AMM pools on Kadena.

> ⚠️ **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.


## pools: Query All Pools

Retrieve a paginated list of all liquidity pools with sorting and filtering options.


```graphql
query AllPools($orderBy: PoolOrderBy, $first: Int) {
  pools(orderBy: $orderBy, first: $first) {
    edges {
      node {
        id
        address
        token0 {
          name
          address
        }
        token1 {
          name
          address
        }
        reserve0
        reserve1
        totalSupply
        tvlUsd
        tvlChange24h
        volume24hUsd
        volumeChange24h
        apr24h
        transactionCount24h
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
    totalCount
  }
}
```

**Variables**


```json
{
  "orderBy": "TVL_USD_DESC",
  "first": 20
}
```

**Response**


```json
{
  "data": {
    "pools": {
      "edges": [
        {
          "node": {
            "id": "1",
            "address": "kdswap.exchange",
            "token0": {
              "name": "coin",
              "address": "coin"
            },
            "token1": {
              "name": "KDX",
              "address": "kaddex.kdx"
            },
            "reserve0": "125000.50",
            "reserve1": "450000.75",
            "totalSupply": "237500.25",
            "tvlUsd": 850000.50,
            "tvlChange24h": 2.5,
            "volume24hUsd": 125000.00,
            "volumeChange24h": 15.3,
            "apr24h": 45.2,
            "transactionCount24h": 234
          }
        }
      ],
      "pageInfo": {
        "hasNextPage": true,
        "endCursor": "MjA="
      },
      "totalCount": 45
    }
  }
}
```

**Sort Options**

- `TVL_USD_DESC` - Highest TVL first (default)
- `TVL_USD_ASC` - Lowest TVL first
- `VOLUME_24H_DESC` - Highest 24h volume
- `VOLUME_7D_DESC` - Highest 7d volume
- `APR_24H_DESC` - Highest APR
- `TRANSACTION_COUNT_24H_DESC` - Most active pools


**Use Cases**

- DEX pool explorers
- Liquidity analytics dashboards
- Pool discovery interfaces
- TVL tracking and rankings


**Notes**
Prices for TVL and volume calculations are sourced from DIA data and refreshed approximately every 5 minutes. Reserve values are returned as strings to preserve precision. Use `protocolAddress` filter to limit results to specific DEX implementations.

## pool: Query Single Pool

Retrieve detailed information about a specific liquidity pool including reserves, metrics, and historical data.


```graphql
query SinglePool($id: ID!, $timeFrame: TimeFrame) {
  pool(id: $id, timeFrame: $timeFrame) {
    id
    address
    key
    token0 {
      id
      name
      address
      chainId
    }
    token1 {
      id
      name
      address
      chainId
    }
    reserve0
    reserve1
    totalSupply
    tvlUsd
    tvlChange24h
    volume24hUsd
    volumeChange24h
    volume7dUsd
    fees24hUsd
    feesChange24h
    apr24h
    transactionCount24h
    transactionCountChange24h
    createdAt
    updatedAt
    charts(timeFrame: DAY) {
      tvl {
        timestamp
        value
      }
      volume {
        timestamp
        value
      }
      fees {
        timestamp
        value
      }
    }
  }
}
```

**Variables**


```json
{
  "id": "1",
  "timeFrame": "DAY"
}
```

**Response**


```json
{
  "data": {
    "pool": {
      "id": "1",
      "address": "kdswap.exchange",
      "key": "coin-kdx-pair",
      "token0": {
        "id": "coin-0",
        "name": "coin",
        "address": "coin",
        "chainId": "0"
      },
      "token1": {
        "id": "kdx-0",
        "name": "KDX",
        "address": "kaddex.kdx",
        "chainId": "0"
      },
      "reserve0": "125000.50",
      "reserve1": "450000.75",
      "totalSupply": "237500.25",
      "tvlUsd": 850000.50,
      "tvlChange24h": 2.5,
      "volume24hUsd": 125000.00,
      "volumeChange24h": 15.3,
      "volume7dUsd": 750000.00,
      "fees24hUsd": 375.00,
      "feesChange24h": 12.5,
      "apr24h": 45.2,
      "transactionCount24h": 234,
      "transactionCountChange24h": 8.5,
      "createdAt": "2024-01-15T10:00:00Z",
      "updatedAt": "2024-03-15T14:30:00Z",
      "charts": {
        "tvl": [
          {
            "timestamp": "2024-03-15T00:00:00Z",
            "value": "820000.00"
          },
          {
            "timestamp": "2024-03-15T12:00:00Z",
            "value": "850000.50"
          }
        ],
        "volume": [
          {
            "timestamp": "2024-03-15T00:00:00Z",
            "value": "50000.00"
          },
          {
            "timestamp": "2024-03-15T12:00:00Z",
            "value": "75000.00"
          }
        ],
        "fees": [
          {
            "timestamp": "2024-03-15T00:00:00Z",
            "value": "150.00"
          },
          {
            "timestamp": "2024-03-15T12:00:00Z",
            "value": "225.00"
          }
        ]
      }
    }
  }
}
```

**Time Frame Options**

- `DAY` - Last 24 hours
- `WEEK` - Last 7 days
- `MONTH` - Last 30 days
- `YEAR` - Last 365 days
- `ALL` - All available data


**Use Cases**

- Pool detail pages
- TVL and volume charting
- Performance analytics
- APR calculations


**Notes**
Charts data returns time-series points for TVL, volume, and fees. Reserve values use string format for precision. The `key` field provides a stable pool identifier. Use `timeFrame` to control chart data granularity.

## Pool Reserves and Pricing

Calculate token prices and liquidity depth using pool reserves.


```graphql
query PoolReserves($id: ID!) {
  pool(id: $id) {
    id
    token0 {
      name
      address
    }
    token1 {
      name
      address
    }
    reserve0
    reserve1
    totalSupply
  }
}
```

**Variables**


```json
{
  "id": "1"
}
```

**Response**


```json
{
  "data": {
    "pool": {
      "id": "1",
      "token0": {
        "name": "coin",
        "address": "coin"
      },
      "token1": {
        "name": "KDX",
        "address": "kaddex.kdx"
      },
      "reserve0": "125000.50",
      "reserve1": "450000.75",
      "totalSupply": "237500.25"
    }
  }
}
```

**Price Calculations**


```javascript
// Token1 price in Token0
const price1 = reserve0 / reserve1
// 125000.50 / 450000.75 = 0.2777 KDA per KDX

// Token0 price in Token1  
const price0 = reserve1 / reserve0
// 450000.75 / 125000.50 = 3.60 KDX per KDA

// LP token value
const lpValue = (reserve0 * 2) / totalSupply
// Assuming equal value in both tokens
```

**Use Cases**

- Price oracle implementations
- Swap preview calculations
- Liquidity depth analysis
- Slippage estimation


**Notes**
Reserve values are strings to preserve full decimal precision. Convert to numbers for calculations. Prices are derived from constant product formula (x * y = k). Real-time prices may differ from historical snapshots.

## Pool Performance Metrics

Track pool performance including volume, fees, and APR over time.


```graphql
query PoolMetrics($id: ID!) {
  pool(id: $id) {
    id
    address
    tvlUsd
    tvlChange24h
    volume24hUsd
    volumeChange24h
    volume7dUsd
    fees24hUsd
    feesChange24h
    apr24h
    transactionCount24h
    transactionCountChange24h
  }
}
```

**Variables**


```json
{
  "id": "1"
}
```

**Response**


```json
{
  "data": {
    "pool": {
      "id": "1",
      "address": "kdswap.exchange",
      "tvlUsd": 850000.50,
      "tvlChange24h": 2.5,
      "volume24hUsd": 125000.00,
      "volumeChange24h": 15.3,
      "volume7dUsd": 750000.00,
      "fees24hUsd": 375.00,
      "feesChange24h": 12.5,
      "apr24h": 45.2,
      "transactionCount24h": 234,
      "transactionCountChange24h": 8.5
    }
  }
}
```

**Metric Definitions**

- `tvlUsd` - Total Value Locked in USD
- `tvlChange24h` - 24h TVL percentage change
- `volume24hUsd` - 24h trading volume in USD
- `volumeChange24h` - 24h volume percentage change
- `volume7dUsd` - 7d trading volume in USD
- `fees24hUsd` - 24h protocol fees in USD
- `feesChange24h` - 24h fees percentage change
- `apr24h` - 24h annualized percentage rate
- `transactionCount24h` - Number of 24h transactions
- `transactionCountChange24h` - 24h transaction count percentage change


**Use Cases**

- Performance dashboards
- Pool comparison tools
- Yield farming analytics
- Trading activity monitoring


**Notes**
All USD values calculated using DIA price data refreshed every ~5 minutes. APR is derived from recent fees relative to TVL. Percentage changes compare current 24h period to previous 24h period.

## Historical TVL and Volume Charts

Query time-series data for TVL, volume, and fees charting.


```graphql
query PoolCharts($id: ID!, $timeFrame: TimeFrame!) {
  pool(id: $id) {
    id
    charts(timeFrame: $timeFrame) {
      tvl {
        timestamp
        value
      }
      volume {
        timestamp
        value
      }
      fees {
        timestamp
        value
      }
    }
  }
}
```

**Variables**


```json
{
  "id": "1",
  "timeFrame": "WEEK"
}
```

**Response**


```json
{
  "data": {
    "pool": {
      "id": "1",
      "charts": {
        "tvl": [
          {
            "timestamp": "2024-03-08T00:00:00Z",
            "value": "800000.00"
          },
          {
            "timestamp": "2024-03-09T00:00:00Z",
            "value": "810000.00"
          },
          {
            "timestamp": "2024-03-10T00:00:00Z",
            "value": "825000.50"
          },
          {
            "timestamp": "2024-03-15T00:00:00Z",
            "value": "850000.50"
          }
        ],
        "volume": [
          {
            "timestamp": "2024-03-08T00:00:00Z",
            "value": "95000.00"
          },
          {
            "timestamp": "2024-03-15T00:00:00Z",
            "value": "125000.00"
          }
        ],
        "fees": [
          {
            "timestamp": "2024-03-08T00:00:00Z",
            "value": "285.00"
          },
          {
            "timestamp": "2024-03-15T00:00:00Z",
            "value": "375.00"
          }
        ]
      }
    }
  }
}
```

**Use Cases**

- TVL trend visualization
- Volume analysis charts
- Fee revenue tracking
- Performance comparison over time


**Notes**
Data points frequency varies by time frame. Values are in USD. Use for building historical charts and trend analysis. All metrics sourced from on-chain data with DIA pricing.