Understanding Uniswap Subgraph Entities for On-Chain Data Analysis

The Uniswap Subgraph is a powerful tool for indexing and querying blockchain data from the Uniswap protocol. It organizes this complex data into structured entities, which are essential for developers, analysts, and traders to efficiently access on-chain information. This guide provides a comprehensive overview of these core entities, their fields, and how they interconnect to form a complete picture of protocol activity.

What are Subgraph Entities?

In The Graph protocol, an entity defines the schema for a subgraph. It represents a distinct type of data that can be queried, similar to a table in a traditional database. Each entity contains specific fields that store relevant information, creating an organized structure for blockchain data.

Entities in the Uniswap Subgraph use base AssemblyScript types or custom types provided by The Graph's TypeScript library. This structured approach enables efficient data retrieval and analysis across the entire Uniswap ecosystem.

Core Protocol Entities

Uniswap Factory

The Uniswap Factory entity serves as the central aggregation point for protocol-wide statistics. As a singleton entity (only one exists), it provides crucial macro-level insights.

Key fields include:

• pairCount: Total number of trading pairs created
• totalVolumeUSD & totalVolumeETH: All-time trading volume in USD and ETH
• totalLiquidityUSD & totalLiquidityETH: Total liquidity across all pairs
• txCount: Cumulative transaction count across all pairs

Token Entity

The Token entity stores aggregated information for individual tokens across all trading pairs where they appear, providing comprehensive token-level analytics.

Notable fields include:

• symbol, name, and decimals: Basic token identification
• tradeVolume & tradeVolumeUSD: Trading volume metrics
• totalLiquidity: Total token amount provided as liquidity
• derivedETH: Current ETH value of the token

Pair Entity

The Pair entity contains information about specific trading pairs, mirroring the pair smart contract while adding aggregated usage data. This entity is fundamental for understanding market dynamics between two tokens.

Important fields include:

• token0 & token1: References to the paired tokens
• reserve0 & reserve1: Current token reserves in the pool
• reserveUSD: Total liquidity value in USD
• volumeUSD: All-time trading volume in USD
• token0Price & token1Price: Current price ratios

User Entity

The User entity represents any address that provides liquidity to Uniswap pools, enabling tracking of individual user positions and activities.

Primary fields:

• liquidityPositions: Array of user's open liquidity positions
• usdSwapped: Total USD value swapped by the user

LiquidityPosition Entity

This entity stores detailed information about a user's specific liquidity provision within a pair, connecting users to their positions.

Key components:

• user: Reference to the user address
• pair: Reference to the specific trading pair
• liquidityTokenBalance: Amount of LP tokens minted for this position

👉 Explore advanced liquidity analytics

Transaction Entities

Transaction Entity

The Transaction entity captures Ethereum transactions containing Uniswap contract interactions, specifically tracking Mint, Burn, and Swap events.

Core attributes:

• blockNumber & timestamp: Transaction context
• mints, burns, swaps: Arrays of related events

Mint Entity

Mint entities represent liquidity provision events, capturing when users add tokens to pools and receive LP tokens in return.

Essential data points:

• liquidity: Amount of LP tokens minted
• amount0 & amount1: Token amounts provided
• amountUSD: Derived USD value of added liquidity

Burn Entity

Burn entities represent liquidity removal events, tracking when users burn LP tokens to withdraw their underlying assets.

Key information:

• liquidity: Amount of LP tokens burned
• amount0 & amount1: Token amounts withdrawn
• amountUSD: Derived USD value of removed liquidity

Swap Entity

Swap entities capture token exchange events within pairs, providing detailed trade information.

Critical swap data:

• amount0In/amount1In: Input token amounts
• amount0Out/amount1Out: Output token amounts
• amountUSD: Derived USD value of the swap

Bundle Entity

The Bundle entity serves as a global reference store for ETH price in USD, crucial for deriving accurate USD values throughout the subgraph.

Single field:

• ethPrice: Derived USD price of ETH based on stablecoin pairs

Historical Data Entities

The Uniswap Subgraph maintains historical entities grouped into daily buckets, enabling efficient analysis of temporal trends without expensive time-travel queries.

UniswapDayData

This entity tracks protocol-wide metrics aggregated daily, providing a macroscopic view of daily activity.

Key daily metrics:

• dailyVolumeUSD/dailyVolumeETH: Daily trading volume
• totalLiquidityUSD/totalLiquidityETH: Cumulative liquidity up to that day
• mostLiquidTokens: References to the most liquid tokens each day

PairDayData

PairDayData entities track daily metrics for individual trading pairs, enabling historical analysis of specific markets.

Important pair-specific metrics:

• reserve0/reserve1: Daily token reserves
• reserveUSD: Daily liquidity value in USD
• dailyVolumeUSD: Daily trading volume for the pair

TokenDayData

This entity aggregates daily data for individual tokens across all pairs, providing comprehensive token-level historical analytics.

Crucial token metrics:

• dailyVolumeUSD: Daily trading volume in USD
• totalLiquidityUSD: Cumulative liquidity up to that day
• priceUSD: Token price in USD at daily close

Practical Applications of Subgraph Entities

Understanding these entities enables powerful blockchain analytics:

Protocol Analytics: Using Factory and historical entities to track overall protocol growth, liquidity trends, and trading volume patterns.

Token Analysis: Leveraging Token entities to analyze individual token performance, adoption metrics, and trading activity.

Pair Analysis: Utilizing Pair entities to examine specific trading pairs, including liquidity depth, price relationships, and trading volume.

User Activity Tracking: Following User and LiquidityPosition entities to analyze provider behavior, position management, and trading activity.

Historical Research: Employing daily entities to conduct time-series analysis, identify trends, and compare market conditions across different periods.

👉 Access real-time DeFi analytics tools

Frequently Asked Questions

What is the difference between volume and untrackedVolume fields?
Volume fields only track pairs with liquidity above a minimum threshold, ensuring data quality, while untrackedVolume includes all trading activity regardless of liquidity levels. This distinction helps filter out insignificant trading activity while preserving complete data availability.

How frequently is the ETH price updated in the Bundle entity?
The ETH price in the Bundle entity is continuously updated based on weighted averages from stablecoin pairs, providing a real-time reference rate for USD conversions throughout the subgraph.

Why are historical entities important if I can use time-travel queries?
While time-travel queries offer precise historical data, they are computationally expensive and slow. Historical entities provide pre-aggregated daily data that enables efficient analysis of trends and patterns without excessive resource consumption.

How can I track a user's complete activity history?
You can query the User entity to find all liquidity positions, then cross-reference with Transaction, Mint, Burn, and Swap entities to reconstruct complete activity history across all pairs.

What's the relationship between LiquidityPosition and LP token balance?
The LiquidityPosition entity directly tracks a user's LP token balance for a specific pair, while the LP tokens themselves represent ownership share in the pool's liquidity.

How are USD values derived in the subgraph?
USD values are calculated using the ETH price from the Bundle entity, converting native token amounts to USD based on current market rates, ensuring consistent valuation across all entities.

Conclusion

The Uniswap Subgraph entities provide a comprehensive framework for accessing and analyzing protocol data. From real-time trading information to historical trends, these structured entities enable developers, researchers, and analysts to extract valuable insights from the Uniswap ecosystem. By understanding the relationships between Factory, Token, Pair, User, and Transaction entities, along with their historical counterparts, you can build powerful analytics tools, track protocol metrics, and gain deep insights into decentralized finance dynamics.

Whether you're building a dashboard, conducting market research, or developing trading strategies, mastering these entities is essential for effective blockchain data analysis in the Uniswap ecosystem.