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.

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

# 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.

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

# 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.

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

# 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.

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

# 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

# Good
{
  pandaPools {
    id
    price
  }
}

# Avoid
{
  pandaPools {
    ...allFields # Fetching unnecessary data
  }
}

1. Pagination

# Use skip/first for large datasets
{
  pandaPoolSwaps(
    skip: 100,
    first: 100,
    orderBy: timestamp,
    orderDirection: desc
  ) {
    id
    timestamp
  }
}

1. Field Selection

• Request only needed fields

• Use fragments for common field sets

• Consider query complexity

Error Handling

1. Entity Not Found

# Handle null responses
{
  pandaPool(id: "0x...") {
    id # Will be null if not found
    price
  }
}

1. 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