hydric-liquidity-pools-indexer-user

name: hydric-liquidity-pools-indexer-user
description: Comprehensive guide for interacting with the Hydric Liquidity Pools Indexer (Envio/HyperIndex). Use this skill when you need to (1) Query real-time Liquidity Pool data like TVL, Volume, Fees, or Yields/APY, (2) Fetch cross-chain token metadata and prices, (3) Aggregate protocol data (Uniswap, etc.), (4) Retrieve historical time-series data for generic analytics, or (5) Understand the specific 'tracked' vs 'untracked' value safety rules of the indexer.

Liquidity Pools Indexer Overview

The Hydric Liquidity Pools Indexer is a high-performance indexer built on Envio HyperIndex. It aggregates liquidity data across multiple blockchains into a unified Postgres database, accessible via a Hasura-style GraphQL API.

Endpoint: The indexer endpoint is typically provided in the environment variables (e.g., INDEXER_URL).
Schema: The schema is available at https://github.com/hydric-org/liquidity-pools-indexer/blob/main/schema.graphql.

Core Entities & Schema

The schema is strongly typed. The primary entry points are:

1. Pool

Represents a text-book liquidity pool (e.g., Uniswap V3 USDC/ETH).

• Key Fields: id, chainId, poolAddress, totalValueLockedUsd, token0, token1, protocol.
• Stats: totalStats24h, totalStats7d, totalStats30d, totalStats90d (pre-calculated rolling windows).
• Type-Specific Data: v3PoolData, v4PoolData, algebraPoolData, slipstreamPoolData.

2. SingleChainToken

Represents a token deployed on a specific blockchain.

• Key Fields: id, tokenAddress, symbol, name, decimals.
• Metrics: trackedUsdPrice, trackedTotalValuePooledUsd (Liquidity), trackedSwapVolumeUsd.
• Search: normalizedSymbol, normalizedName (for fuzzy matching).

3. PoolHistoricalData

Time-series snapshots for charting.

• Granularity: interval (e.g., DAILY, HOURLY).
• Fields: timestampAtStart, trackedTotalValueLockedUsdAtStart, accumulatedVolume, accumulatedFees.

IDs & Network Reference

Global ID Format:
Entities follow a strict globally unique ID pattern: <chainId>-<lowercase_address>.

• Example: USDC on Ethereum -> 1-0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48
• Rule: Always lowercase addresses when constructing IDs manually.

Supported Chain IDs:

• Ethereum: 1
• Base: 8453
• Scroll: 534352
• Polygon: 137
• Monad: 143
• Unichain: 130

Data Handling & Best Practices

1. "Tracked" vs "Untracked" Values

The indexer computes values raw (Untracked) and with safety filters (Tracked).

• ⚠️ Untracked: totalValueLockedUsd. Computed simply as balance * price. Vulnerable to fake tokens or bad price manipulation.
• ✅ Tracked: trackedTotalValueLockedUsd. ALWAYS PREFER THIS. It uses filtered prices and whitelisted tokens to ensure the TVL is real.

2. Normalized Search

For search functionality, never query only symbol directly, use normalizedSymbol, normalizedName, symbol and name to ensure maximum coverage.

• Use: normalizedSymbol and normalizedName.
• Why: Handles "USD₮" -> "USDT" conversion and ignores emojis/special chars.
• Pattern: where: { normalizedSymbol: { _ilike: "%USDT%" } }

3. Numbers are Strings

CRITICAL: All financial values (TVL, Volume, Prices) are returned as Strings in GraphQL to preserve BigInt/Decimal precision.

• Action: Use Number() or BigInt() parsing in your code after fetching.

Specific Entity Patterns

Querying Different Pool Types (Polymorphism)

Pools can be V3, V4, Algebra, etc. Request the specific nested object to get type-specific data.

query GetPoolsWithMetadata {
  Pool(limit: 10) {
    id
    poolType # e.g., "V3", "ALGEBRA", "SLIPSTREAM"
    # Request all possible internal data structures
    v3PoolData {
      tickSpacing
      sqrtPriceX96
    }
    algebraPoolData {
      communityFeePercentage
      plugin
    }
    v4PoolData {
      hooks
      stateView
    }
  }
}

Retrieving Token Prices & Liquidity

Use the SingleChainToken entity to get pricing.

query GetTokenPricing {
  SingleChainToken(where: { symbol: { _eq: "WETH" } }) {
    id
    chainId
    trackedUsdPrice # Current price in USD
    trackedTotalValuePooledUsd # Total liquidity across all indexed pools
  }
}

Example Queries (Copy & Paste)

1. Top Pools by TVL (The Standard Leaderboard)

query GetTopPools {
  Pool(
    limit: 20
    offset: 0
    order_by: { trackedTotalValueLockedUsd: desc }
    where: { trackedTotalValueLockedUsd: { _gt: "10000" } } # Dust filter
  ) {
    id
    poolAddress
    chainId
    trackedTotalValueLockedUsd
    currentFeeTierPercentage
    token0 {
      symbol
      decimals
    }
    token1 {
      symbol
      decimals
    }
    protocol {
      name
      logo
    }
    totalStats24h {
      yearlyYield
      swapVolumeUsd
      feesUsd
    }
  }
}

2. Search Tokens Fuzzy

query SearchTokens($search: String!) {
  SingleChainToken(
    limit: 10
    where: {
      _or: [
        { normalizedSymbol: { _ilike: $search } }
        { normalizedName: { _ilike: $search } }
      ]
    }
    order_by: { trackedTotalValuePooledUsd: desc }
  ) {
    id
    name
    symbol
    tokenAddress
    chainId
    logoUrl # Note: This might need to be constructed client-side as per skill context
  }
}

3. Historical Chart Data (Daily Volume/TVL)

query GetPoolHistory($poolId: String!) {
  PoolHistoricalData(
    limit: 90
    order_by: { timestampAtStart: asc }
    where: { poolId: { _eq: $poolId }, interval: { _eq: DAILY } }
  ) {
    timestampAtStart
    trackedTotalValueLockedUsdAtStart
    accumulatedVolume
    accumulatedFees
    open
    high
    low
    close
  }
}