Subgraph overview
The NFTX subgraph is built on
Envio HyperIndex and indexes Base mainnet (8453)
plus Base Sepolia (84532). Every entity ID is namespaced by chainId (e.g.
8453-0xCollection-42) so the multichain DB keeps rows distinct across both
networks.
The schema lives at Subgraph/schema.graphql. This page is the conceptual
view; Entity reference is the field-level view; and
GraphQL recipes has copy-paste queries.
Liquidity positions on the V4 PoolManager are deliberately not indexed.
The API fetches them on-demand via the Uniswap v4 SDK + Position API,
filtering by the deployed NFTXV4Hook address per chain. See
pool-fees-and-amm for the join.
Relationship diagram
The diagram below shows every entity and the foreign keys / @derivedFrom
edges between them. Collection is the central hub; everything else hangs
off it (or off the protocol-singleton Config).
Reading the diagram
- A double bar (
||) means one on that side. - An
o{means zero-or-many. Most edges areCollection ||--o{ Other. - Entities without a line back to
Collection(FeeOverride,TokenEscrow,LockerManager,AirdropTarget,AmmFeeTaken) are standalone — protocol-wide rows keyed off something other than a collection.
Joining entities
The schema only encodes Hasura/HyperIndex-resolvable edges. A handful of joins are implicit in id construction and must be done client-side:
| You have | You want | Do |
|---|---|---|
A Listing row | Its Collection | Use the explicit collection FK. |
A Listing row | Its ListingActivity history | Filter by (collection_id, tokenId). |
A Collection row | Its PoolFees | Use Collection.poolFees (derived). |
A Collection row | Per-currency pool fees | Resolve currency0/currency1 from Collection.poolKey (V4-sorted address pair). |
A payee address | Their claimable balances | Filter TokenEscrow_filter: { payee: $addr }. |
A recipient address | Available airdrops | Filter AirdropClaim_filter: { recipient: $addr }. |
A Locker.implementation() | The hook config | Read Config (singleton per chainId) — not Collection. |
What we deliberately don’t index
| Source | Why |
|---|---|
| Uniswap V4 LP positions | Read on-demand via Uniswap v4 SDK / Position API (filters by hook address). |
| Token metadata (image, traits) | Lives in the FE’s existing metadata pipeline. |
Wallet balances of CollectionToken | Standard ERC-20 read against the clone address. |
| Failed transactions | HyperIndex only indexes successful event logs. |
If you need any of the above in the FE, do it as a viem readContract /
SDK call, not a subgraph extension.