# Entity Reference ### Overview The Panda Protocol subgraph defines several core entities that model the protocol's data. Each entity represents a specific aspect of the protocol's state and behavior. ### Core Entities #### PandaPool Represents an individual Panda liquidity pool. Each pool manages a pair of tokens and tracks trading activity. ```graphql type PandaPool @entity { id: ID! # Pool contract address baseToken: Token! # The base currency token pandaToken: Token! # The Panda token being traded price: BigDecimal! # Current token price volumeUSD: BigDecimal! # Total USD volume marketCapBase: BigDecimal! # Market cap in base currency terms marketCapUSD: BigDecimal! # Market cap in USD termes swapsCount: BigInt! # Total number of swaps lastSwapTimestamp: BigInt! # Last swap timestamp graduated: Boolean! # Graduation status raised: BigDecimal! # amount of tokens raised tokensInPool: BigDecimal! # Total token in the pool pandaReserve: BigDecimal! # Panda token reserve baseReserve: BigDecimal! # Base token reserve startPrice: BigDecimal! # Initial token price } ``` **Common Queries** ```graphql # Get active pools with high volume { pandaPools( where: { graduated: false, volumeUSD_gt: "100000" }, orderBy: volumeUSD, orderDirection: desc ) { id price volumeUSD swapsCount } } # Get pool reserves { pandaPool(id: "0x...") { pandaReserve baseReserve tokensInPool } } ``` #### Token Tracks both Panda and base tokens in the protocol. ```graphql type Token @entity { id: ID! # Token contract address name: String! # Token name symbol: String! # Token symbol decimals: BigInt! # Token decimals totalSupply: BigDecimal! # Total supply isPandaToken: Boolean! # Token type identifier pools: [PandaPool!]! # Associated pools holders: [Holder!]! # Token holders holdersCount: BigInt! # Number of holders lastSwapTimestamp: BigInt! # Last swap timestamp createdAtTimestamp: BigInt! # Creation timestamp } ``` **Example Queries** ```graphql # Get token details with holder metrics { token(id: "0x...") { symbol totalSupply holdersCount holders(first: 10, orderBy: balance, orderDirection: desc) { balance sharePercentage } } } ``` #### PandaPoolSwap Records individual swap transactions within pools. ```graphql type PandaPoolSwap @entity(immutable: true) { id: ID! # Unique swap identifier pool: PandaPool! # Reference to pool timestamp: BigInt! # Swap timestamp amountPandaIn: BigDecimal! # Panda tokens in amountPandaOut: BigDecimal! # Panda tokens out amountBaseIn: BigDecimal! # Base tokens in amountBaseOut: BigDecimal! # Base tokens out from: Bytes! # Sender address to: Bytes! # Recipient address tx: String! # Transaction hash origin: String! # Transaction origin volumeUSD: BigDecimal! # Volume in USD averagePrice: BigDecimal! # Average execution price } ``` **Querying Swaps** ```graphql # Get recent swaps for a pool { pandaPoolSwaps( where: { pool: "0x..." } orderBy: timestamp orderDirection: desc first: 100 ) { timestamp amountPandaIn amountPandaOut volumeUSD averagePrice } } ``` #### PriceSnapshot Time-based price aggregation for historical analysis. ```graphql type PriceSnapshot @entity { id: ID! timestamp: BigInt! open: BigDecimal! close: BigDecimal! high: BigDecimal! low: BigDecimal! volume: BigDecimal! pool: PandaPool! timeframe: PriceSnapshotTimeframe! } enum PriceSnapshotTimeframe { SECOND10 MINUTE MINUTE5 MINUTE15 HOUR HOUR3 DAY } ``` **Historical Data Queries** ```graphql # Get hourly price data { priceSnapshots( where: { pool: "0x...", timeframe: HOUR } orderBy: timestamp orderDirection: desc first: 24 ) { timestamp open high low close volume } } ``` ### Entity Relationships #### Primary Relationships #### Key Points * Each `PandaPool` has exactly two `Token` entities (base and Panda) * `PriceSnapshot` entities are created for specific timeframes * `Holder` entities track token ownership * `PandaPoolSwap` entities are immutable records ### Best Practices #### Querying Efficiently 1. **Use Specific Fields** ```graphql # Good { pandaPools { id price } } # Avoid { pandaPools { ...allFields # Fetching unnecessary data } } ``` 2. **Pagination** ```graphql # Use skip/first for large datasets { pandaPoolSwaps( skip: 100, first: 100, orderBy: timestamp, orderDirection: desc ) { id timestamp } } ``` 3. **Field Selection** * Request only needed fields * Use fragments for common field sets * Consider query complexity #### Error Handling 1. **Entity Not Found** ```graphql # Handle null responses { pandaPool(id: "0x...") { id # Will be null if not found price } } ``` 2. **Invalid Queries** * Validate entity existence * Check field value ranges * Handle pagination edges ### Next Steps Continue to: * Queries Documentation for advanced query patterns * Advanced Usage for optimization techniques ### Support Need help with entities? * Check Known Issues * Join our [Developer Discord](https://discord.gg/pandaprotocol)