Polymarket Subgraph Schema Reference: orderbook-subgraph schema.graphql

Complete reference for polymarket-subgraph orderbook-subgraph schema.graphql. This comprehensive 2026 guide documents all GraphQL types, fields, relationships, and schema definitions for querying historical Polymarket data from The Graph network. Understanding the schema is essential for building analytics tools, backtesting systems, and historical research applications.

The Polymarket subgraph schema defines the structure of all historical on-chain data indexed from Polymarket smart contracts. This schema reference serves as the definitive guide to available types, fields, and relationships, enabling developers to construct efficient GraphQL queries for trades, positions, orderbooks, and market activity. High search volume: "polymarket subgraph schema", "orderbook-subgraph schema.graphql" - developers frequently search for schema documentation. Professional developers use analytics platforms like PolyTrack Pro which provides pre-built historical analytics without requiring deep subgraph schema knowledge.

Subgraph Schema Overview

The Polymarket subgraph schema on The Graph network exposes historical on-chain data via GraphQL. The schema is organized into logical entities representing trades, positions, orders, tokens, accounts, and markets. All data is indexed from blockchain transactions and organized for efficient querying.

Schema Endpoints

• • Goldsky Hosted: https://api.goldsky.com/api/public/project_cl6mb8i9h0003e201j6li0diw/subgraphs/orderbook-subgraph/0.0.1/gn
• • The Graph Hosted: https://api.thegraph.com/subgraphs/name/polymarket/orderbook-subgraph
• • Schema File: https://github.com/polymarket/orderbook-subgraph/blob/main/schema.graphql

Core Entity Types

Trade Type

Represents a single trade execution on Polymarket. Trades are indexed from on-chain fill events.

type Trade {
  id: ID!                    # Unique trade identifier (transaction hash + log index)
  timestamp: BigInt!         # Block timestamp when trade occurred
  blockNumber: BigInt!       # Block number of trade transaction
  transactionHash: Bytes!    # Transaction hash containing this trade
  
  # Trade Details
  price: BigDecimal!         # Execution price (0.0 - 1.0)
  amount: BigDecimal!        # Trade size in shares
  value: BigDecimal!         # Total value in USDC
  
  # Relationships
  token: Token!              # Token that was traded
  trader: Account!            # Account that executed the trade
  maker: Account             # Maker account (if applicable)
  taker: Account             # Taker account (if applicable)
  
  # Order Information
  orderHash: Bytes           # Hash of the order that was filled
  side: String!              # "BUY" or "SELL"
  isMaker: Boolean!          # Whether trader was maker (true) or taker (false)
  
  # Fee Information
  feeAmount: BigDecimal      # Fee paid in USDC
  feeRate: BigDecimal        # Fee rate (e.g., 0.003 for 0.3%)
}

Position Type

Represents a user's position in a specific token. Positions are calculated from trade history.

type Position {
  id: ID!                    # Unique position ID (account + token)
  token: Token!               # Token for this position
  account: Account!          # Account holding the position
  
  # Position Details
  shares: BigDecimal!        # Current number of shares held
  avgPrice: BigDecimal!      # Average entry price
  totalCost: BigDecimal!    # Total cost basis
  realizedPnl: BigDecimal   # Realized profit/loss (if position closed)
  
  # Timestamps
  firstTrade: BigInt!        # Timestamp of first trade
  lastTrade: BigInt          # Timestamp of most recent trade
  
  # Trade Count
  tradeCount: BigInt!        # Number of trades for this position
}

Order Type

Represents an order placed on the orderbook. Includes both active and filled/cancelled orders.

type Order {
  id: ID!                    # Unique order ID (order hash)
  hash: Bytes!               # Order hash (EIP-712 signature)
  
  # Order Details
  token: Token!              # Token being traded
  maker: Account!            # Account that placed the order
  side: String!              # "BUY" or "SELL"
  price: BigDecimal!         # Limit price
  size: BigDecimal!          # Order size in shares
  
  # Order Status
  status: String!            # "OPEN", "FILLED", "CANCELLED", "EXPIRED"
  filledAmount: BigDecimal   # Amount filled (if partially filled)
  
  # Timestamps
  createdAt: BigInt!         # Block timestamp when order created
  filledAt: BigInt           # Block timestamp when order filled
  cancelledAt: BigInt        # Block timestamp when order cancelled
  expiresAt: BigInt          # Expiration timestamp (for GTD orders)
  
  # Order Type
  orderType: String!         # "GTC", "GTD", "IOC", "FOK"
}

Token Type

Represents a Polymarket token (outcome share) for a specific market condition.

type Token {
  id: ID!                    # Token ID (contract address)
  tokenId: String!           # Token identifier string
  
  # Market Information
  conditionId: String!        # Market condition ID
  outcome: String!            # Outcome name (e.g., "YES", "NO", "UP", "DOWN")
  
  # Price Information
  price: BigDecimal          # Current price (from latest trade)
  lastPrice: BigDecimal      # Last traded price
  
  # Volume Statistics
  totalVolume: BigDecimal!   # Total volume traded
  totalTrades: BigInt!       # Total number of trades
  totalValue: BigDecimal!   # Total value traded in USDC
  
  # Relationships
  trades: [Trade!]!          # All trades for this token
  positions: [Position!]!    # All positions in this token
  orders: [Order!]!         # All orders for this token
}

Account Type

Represents a wallet address that has interacted with Polymarket.

type Account {
  id: ID!                    # Account address (wallet address)
  address: Bytes!            # Ethereum/Polygon address
  
  # Trading Statistics
  totalTrades: BigInt!       # Total number of trades
  totalVolume: BigDecimal!   # Total trading volume
  totalValue: BigDecimal!    # Total value traded
  
  # P&L Statistics
  totalPnl: BigDecimal       # Total profit/loss across all positions
  realizedPnl: BigDecimal    # Realized profit/loss
  unrealizedPnl: BigDecimal  # Unrealized profit/loss
  
  # Relationships
  trades: [Trade!]!          # All trades by this account
  positions: [Position!]!   # All positions held by this account
  orders: [Order!]!         # All orders placed by this account
  
  # Timestamps
  firstTrade: BigInt        # Timestamp of first trade
  lastTrade: BigInt         # Timestamp of most recent trade
}

See What Whales Are Trading Right Now

Get instant alerts when top traders make moves. Track P&L, win rates, and copy winning strategies.

Free forever. No credit card required.

Scalar Types

The schema uses custom scalar types for blockchain-specific data:

Query Root Type

The Query type defines all available queries in the schema:

type Query {
  # Trade Queries
  trades(
    where: Trade_filter
    orderBy: Trade_orderBy
    orderDirection: OrderDirection
    first: Int
    skip: Int
  ): [Trade!]!
  trade(id: ID!): Trade
  
  # Position Queries
  positions(
    where: Position_filter
    orderBy: Position_orderBy
    orderDirection: OrderDirection
    first: Int
    skip: Int
  ): [Position!]!
  position(id: ID!): Position
  
  # Order Queries
  orders(
    where: Order_filter
    orderBy: Order_orderBy
    orderDirection: OrderDirection
    first: Int
    skip: Int
  ): [Order!]!
  order(id: ID!): Order
  
  # Token Queries
  tokens(
    where: Token_filter
    orderBy: Token_orderBy
    orderDirection: OrderDirection
    first: Int
    skip: Int
  ): [Token!]!
  token(id: ID!): Token
  
  # Account Queries
  accounts(
    where: Account_filter
    orderBy: Account_orderBy
    orderDirection: OrderDirection
    first: Int
    skip: Int
  ): [Account!]!
  account(id: ID!): Account
}

Filter Types

Filter types allow you to query specific subsets of data. Common filter fields:

Trade_filter

input Trade_filter {
  id: ID
  id_not: ID
  id_in: [ID!]
  id_not_in: [ID!]
  
  timestamp: BigInt
  timestamp_gt: BigInt
  timestamp_gte: BigInt
  timestamp_lt: BigInt
  timestamp_lte: BigInt
  
  price: BigDecimal
  price_gt: BigDecimal
  price_gte: BigDecimal
  price_lt: BigDecimal
  price_lte: BigDecimal
  
  token: String
  token_not: String
  token_in: [String!]
  
  trader: String
  trader_not: String
  
  side: String
  side_not: String
  
  isMaker: Boolean
}

Position_filter

input Position_filter {
  id: ID
  token: String
  account: String
  shares: BigDecimal
  shares_gt: BigDecimal
  shares_gte: BigDecimal
  shares_lt: BigDecimal
  shares_lte: BigDecimal
  avgPrice: BigDecimal
  avgPrice_gt: BigDecimal
  avgPrice_gte: BigDecimal
}

OrderBy Enums

OrderBy enums define available sorting fields for each type:

enum Trade_orderBy {
  id
  timestamp
  blockNumber
  price
  amount
  value
  token
  trader
  maker
  taker
}

enum Position_orderBy {
  id
  token
  account
  shares
  avgPrice
  totalCost
  realizedPnl
  firstTrade
  lastTrade
}

enum Order_orderBy {
  id
  hash
  token
  maker
  price
  size
  status
  createdAt
  filledAt
  cancelledAt
}

enum OrderDirection {
  asc
  desc
}

Schema Relationships

Understanding relationships between types is crucial for efficient queries:

Best Practices for Schema Queries

• • Use Filters: Always filter results to reduce query size and improve performance
• • Limit Results: Use first parameter to limit result sets
• • Pagination: Use skip for pagination instead of fetching all data
• • Order Results: Use orderBy and orderDirection for predictable sorting
• • Selective Fields: Only query fields you need to reduce response size
• • Indexed Fields: Filter on indexed fields (id, timestamp, token, account) for better performance
• • Avoid Deep Nesting: Limit nested relationship queries to prevent timeout

Schema Location and Resources

• • Official Schema: https://github.com/polymarket/orderbook-subgraph/blob/main/schema.graphql
• • Subgraph Explorer: https://thegraph.com/explorer/subgraphs/polymarket/orderbook-subgraph
• • GraphQL Playground: Use endpoint URL in GraphQL playground for interactive schema exploration
• • Documentation: See Polymarket Subgraph Queries Guide for query examples

Conclusion

The Polymarket subgraph schema provides comprehensive access to historical on-chain data through well-defined GraphQL types. Understanding the schema structure, relationships, and available filters is essential for building efficient queries. Always use filters, limit results, and query only necessary fields for optimal performance.

For production applications requiring historical analytics, consider using enterprise platforms like PolyTrack Pro which provides pre-built historical analytics and eliminates the need for custom subgraph query development.

Related Resources

• • Polymarket Subgraph Queries: Complete GraphQL Guide
• • gamma-api.polymarket.com Complete Guide: GraphQL & REST API Reference
• • Polymarket API JavaScript Tutorial: Complete Node.js Guide