# 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)
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://documentation.kodiak.finance/developers/panda/subgraph/entity-reference.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.