Back to Details

hydric-liquidity-pools-indexer-user

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

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.
hydric流动性池索引器是基于Envio HyperIndex构建的高性能索引器。它将多条区块链上的流动性数据聚合到统一的Postgres数据库中，可通过Hasura风格的GraphQL API访问。
端点：索引器端点通常在环境变量中提供（例如
INDEXER_URL
）。 Schema：Schema可在https://github.com/hydric-org/liquidity-pools-indexer/blob/main/schema.graphql获取。

Core Entities & Schema

核心实体与Schema

The schema is strongly typed. The primary entry points are:
该Schema为强类型。主要入口点如下：

1. 
Pool

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
    .
代表标准的流动性池（例如Uniswap V3 USDC/ETH）。
  • 关键字段：
    id
    、
    chainId
    、
    poolAddress
    、
    totalValueLockedUsd
    、
    token0
    、
    token1
    、
    protocol
    。
  • 统计数据：
    totalStats24h
    、
    totalStats7d
    、
    totalStats30d
    、
    totalStats90d
    （预计算的滚动窗口数据）。
  • 特定类型数据：
    v3PoolData
    、
    v4PoolData
    、
    algebraPoolData
    、
    slipstreamPoolData
    。

2. 
SingleChainToken

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
    (Representations of the token symbol and name without special characters, for example 
    USD₮
    -> 
    USDT
    ).
代表部署在特定区块链上的代币。
  • 关键字段：
    id
    、
    tokenAddress
    、
    symbol
    、
    name
    、
    decimals
    。
  • 指标：
    trackedUsdPrice
    、
    trackedTotalValuePooledUsd
    （流动性）、
    trackedSwapVolumeUsd
    。
  • 搜索：
    normalizedSymbol
    、
    normalizedName
    （去除特殊字符的代币符号和名称，例如
    USD₮
    -> 
    USDT
    ）。

3. 
PoolHistoricalData

3. 
PoolHistoricalData

Time-series snapshots for charting.
  • Granularity: 
    interval
    (e.g., 
    DAILY
    , 
    HOURLY
    ).
  • Key Fields (Not limited to these): 
    timestampAtStart
    , 
    trackedTotalValueLockedUsdAtStart
    , 
    intervalSwapVolumeUsd
    , 
    intervalFeesUsd
    , 
    intervalLiquidityInflowUsd
    .
用于图表展示的时间序列快照。
  • 粒度：
    interval
    （例如
    DAILY
    、
    HOURLY
    ）。
  • 关键字段（不限于以下）：
    timestampAtStart
    、
    trackedTotalValueLockedUsdAtStart
    、
    intervalSwapVolumeUsd
    、
    intervalFeesUsd
    、
    intervalLiquidityInflowUsd
    。

IDs & Network Reference

ID与网络参考

Global ID Format: Entities follow a strict globally unique ID pattern: 
<chainId>-<lowercase_address>
.
  • Example: USDC on Ethereum -> 
    1-0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48
  • Rule: all addresses are lowercase.
Supported Chain IDs:
You can find the supported chain IDs in this file: https://github.com/hydric-org/liquidity-pools-indexer/blob/7586588dcc9b507ca647f498c7ab8af5fefd4eef/src/core/network/indexer-network.ts#L5-L13
in the 
IndexerNetwork
enum will be all chain IDs that the lastest version of the indexer currently supports
全局ID格式: 实体遵循严格的全局唯一ID模式：
<chainId>-<小写地址>
。
  • 示例：以太坊上的USDC -> 
    1-0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48
  • 规则：所有地址均为小写。
支持的链ID:
你可以在以下文件中找到支持的链ID：https://github.com/hydric-org/liquidity-pools-indexer/blob/7586588dcc9b507ca647f498c7ab8af5fefd4eef/src/core/network/indexer-network.ts#L5-L13 
IndexerNetwork
枚举中包含了当前最新版本索引器支持的所有链ID

Data Handling & Best Practices

数据处理与最佳实践

1. "Tracked" vs "Untracked" Values

1. "Tracked"与"Untracked"值

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.
索引器会计算原始值（Untracked）和经过安全过滤的值（Tracked）。
  • ⚠️ Untracked：
    totalValueLockedUsd
    。仅通过
    balance * price
    计算，容易受到虚假代币或恶意价格操纵的影响。
  • ✅ Tracked：
    trackedTotalValueLockedUsd
    。优先使用此值。它使用过滤后的价格和白名单代币来确保TVL真实有效。

2. Normalized Search

2. 标准化搜索

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. Attention: Emojis will keep their emojis (not removed or converted).
  • Pattern: 
    where: { normalizedSymbol: { _ilike: "%USDT%" } }
对于搜索功能，切勿仅直接查询
symbol
，请使用
normalizedSymbol
、
normalizedName
、
symbol
和
name
以确保覆盖范围最大化。
  • 推荐使用：
    normalizedSymbol
    和
    normalizedName
    。
  • 原因：可处理类似"USD₮" -> "USDT"的转换。注意：表情符号会保留（不会被移除或转换）。
  • 查询示例：
    where: { normalizedSymbol: { _ilike: "%USDT%" } }

3. Numbers with decimals are returned as Strings

3. 带小数的数值以字符串形式返回

CRITICAL: All financial values (TVL, Volume, Prices) that have decimals are returned as Strings in GraphQL to preserve decimal precision and maximum accuracy.
  • Action: Use 
    Number()
    , 
    BigInt()
    (or equivalent) parsing in your code after fetching.
重要提示：所有带小数的财务值（TVL、交易量、价格）在GraphQL中均以字符串形式返回，以保留小数精度和最高准确性。
  • 处理方式：在获取数据后，在代码中使用
    Number()
    、
    BigInt()
    （或等效方法）进行解析。

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.
graphql
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
    }
    slipstreamPoolData {
      hooks
      stateView
    }
  }
}
Reminder: You can find all the possible nested objects in the schema.graphql at the 
Pool
type
池可以是V3、V4、Algebra等类型。请求特定的嵌套对象以获取该类型的专属数据。
graphql
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
    }
    slipstreamPoolData {
      hooks
      stateView
    }
  }
}
提示：你可以在schema.graphql的
Pool
类型中找到所有可能的嵌套对象。

Retrieving Token Prices & Liquidity

检索代币价格与流动性

Use the 
SingleChainToken
entity to get pricing.
graphql
query GetTokenPricing {
  SingleChainToken(where: { symbol: { _eq: "WETH" } }) {
    id
    chainId
    trackedUsdPrice # Current price in USD with safety checks
    usdPrice # Current price in USD without safety checks (pure pools values)
  }
}
使用
SingleChainToken
实体获取价格数据。
graphql
query GetTokenPricing {
  SingleChainToken(where: { symbol: { _eq: "WETH" } }) {
    id
    chainId
    trackedUsdPrice # Current price in USD with safety checks
    usdPrice # Current price in USD without safety checks (pure pools values)
  }
}

Wrapped native and native data interoperability

包装原生代币与原生代币的数据互操作性

Wrapped native and native (represented by the zero address) share the same metrics and data, but maintain their own distinct metadata.
Synchronization: Any update to a token's data (e.g., 
usdPrice
, 
trackedUsdPrice
, 
swapVolumeUsd
, 
totalValuePooledUsd
, etc.) on one entity is automatically mirrored to its companion. Metadata fields (
name
, 
symbol
, 
decimals
, 
tokenAddress
) are never synchronized.
Example: WETH and ETH will always have identical pricing and volume stats, but will have different IDs, symbols, and names.
包装原生代币和原生代币（用零地址表示）共享相同的指标和数据，但各自保留独立的元数据。
同步机制：当其中一个实体的代币数据（如
usdPrice
、
trackedUsdPrice
、
swapVolumeUsd
、
totalValuePooledUsd
等）更新时，会自动同步到对应的另一个实体。元数据字段（
name
、
symbol
、
decimals
、
tokenAddress
）不会被同步。
示例：WETH和ETH的价格和交易量统计始终保持一致，但它们的ID、符号和名称不同。

Example Queries (Copy & Paste)

示例查询（可直接复制使用）

1. Top Pools by TVL (The Standard Leaderboard)

1. 按TVL排序的顶级池（标准排行榜）

graphql
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
    }
  }
}
graphql
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

2. 模糊搜索代币

graphql
query SearchTokens($search: String!) {
  SingleChainToken(
    limit: 10
    where: {
      _or: [
        { normalizedSymbol: { _ilike: $search } }
        { normalizedName: { _ilike: $search } }
      ]
    }
    order_by: { trackedTotalValuePooledUsd: desc }
  ) {
    id
    name
    symbol
    tokenAddress
    chainId
  }
}
graphql
query SearchTokens($search: String!) {
  SingleChainToken(
    limit: 10
    where: {
      _or: [
        { normalizedSymbol: { _ilike: $search } }
        { normalizedName: { _ilike: $search } }
      ]
    }
    order_by: { trackedTotalValuePooledUsd: desc }
  ) {
    id
    name
    symbol
    tokenAddress
    chainId
  }
}

3. Historical Chart Data (Daily Volume/TVL)

3. 历史图表数据（每日交易量/TVL）

graphql
query GetPoolHistory($poolId: String!) {
  PoolHistoricalData(
    limit: 90
    order_by: { timestampAtStart: asc }
    where: { pool_id: { _eq: $poolId }, interval: { _eq: DAILY } }
  ) {
    timestampAtStart
    trackedTotalValueLockedUsdAtStart
    intervalSwapVolumeUsd
  }
}
graphql
query GetPoolHistory($poolId: String!) {
  PoolHistoricalData(
    limit: 90
    order_by: { timestampAtStart: asc }
    where: { pool_id: { _eq: $poolId }, interval: { _eq: DAILY } }
  ) {
    timestampAtStart
    trackedTotalValueLockedUsdAtStart
    intervalSwapVolumeUsd
  }
}