Uniswap v4 Subgraph

Query Uniswap v4 onchain-indexed data through The Graph decentralized network GraphQL API. Hosted service endpoints are deprecated; use the gateway URL with a Studio API key.

For expanded query examples and entity field tables, read references/v4-queries.md.

API Overview

• Protocol: GraphQL over HTTPS (POST)
• Mainnet explorer: DiYPVdygkfjDWhbxGSqAQxwBKmfKnkWQojqeM2rkLb3G
• GraphQL endpoint template:

https://gateway.thegraph.com/api/<THEGRAPHAPIKEY>/subgraphs/id/DiYPVdygkfjDWhbxGSqAQxwBKmfKnkWQojqeM2rkLb3G

• Auth: API key from The Graph Studio
• Schema / code: Uniswap/v4-subgraph
• Docs: v4 Queries, v4 Query Examples, Subgraphs Overview

Auth setup

export THEGRAPH_API_KEY="..."
# key from https://thegraph.com/studio/apikeys/

Never hardcode the key. Prefer $THEGRAPHAPIKEY from the environment.

Reliability note

Public explorer links and gateway IDs in Uniswap docs are example community deployments, not guaranteed official Uniswap Labs production indexers. Before relying on data: confirm the deployment is actively indexed, schema matches expectations, and chain/contracts align. For production, prefer deploying from the official v4-subgraph repo.

Key Differences from v3

• Query global metrics from poolManager, not factory.
• Pool id is a bytes32 hash of the pool key (tokens, fee, tick spacing,

hooks) — not a deployed pool contract address.

• Pool entities include hooks (hook contract address, if any).
• Positions track subscriptions, unsubscriptions, and transfers (not the

v3 mint/burn/collect position model).

PoolManager IDs

Ethereum mainnet (and docs examples) use:

0x000000000004444c5dc75cb358380d2e3de08a90

Other chains use different PoolManager addresses. Resolve them from v4 Deployments or networks.json in the subgraph repo. Always lowercase hex IDs in queries when the deployment expects checksum-insensitive IDs.

Known deployments by chain

The Graph Explorer / Uniswap docs only surface the Ethereum mainnet id directly — for anything else you're on your own. These additional ids were cross-referenced across three independent third-party integrations (ParaSwap paraswap-dex-lib, DefiLlama DefiLlama-Adapters, and salviega/streams-contracts) as of Jul 2026. Treat as community-sourced, not Uniswap Labs-confirmed — re-verify indexing status before relying on them in production (see Reliability note above).

Chains without a public v4 subgraph

• World Chain — Uniswap indexes v4 there on a private Goldsky

deployment (GOLDSKYWORLDCHAINV4ID, per Uniswap/routing-api source), not on The Graph decentralized network. No public subgraph id exists to query here — use GeckoTerminal (network world-chain, see coingecko-and-coinmarketcap-apis) for pool/TVL data on this chain instead of guessing at an id.

• Gnosis — Uniswap v4 is not deployed at all (only earlier versions

elsewhere); nothing to query on any indexer.

If a chain you need isn't in the table above, don't guess an id from a single source — cross-check at least two independent integrations (search GitHub for gateway.thegraph.com/api/subgraphs/id or thegraph.com/api/subgraphs/id near the chain name) before trusting one repo, since a single project can carry a stale or wrong id.

Core Entities

Common Queries

Protocol metrics

{
  poolManager(id: "0x000000000004444c5dc75cb358380d2e3de08a90") {
    poolCount
    txCount
    totalVolumeUSD
    totalVolumeETH
    totalValueLockedUSD
  }
}

Pool state

{
  pool(id: "0x21c67e77068de97969ba93d4aab21826d33ca12bb9f565d8496e8fda8a82ca27") {
    token0 { symbol id decimals }
    token1 { symbol id decimals }
    feeTier
    liquidity
    sqrtPrice
    tick
    hooks
    volumeUSD
    totalValueLockedUSD
  }
}

Most liquid pools

{
  pools(first: 100, orderBy: liquidity, orderDirection: desc) {
    id
    token0 { symbol }
    token1 { symbol }
    feeTier
    liquidity
    volumeUSD
    hooks
  }
}

Recent swaps in a pool

{
  swaps(
    first: 20
    orderBy: timestamp
    orderDirection: desc
    where: { pool: "0x21c67e77068de97969ba93d4aab21826d33ca12bb9f565d8496e8fda8a82ca27" }
  ) {
    sender
    origin
    amount0
    amount1
    amountUSD
    timestamp
  }
}

Token aggregates

{
  token(id: "0x1f9840a85d5af5bf1d1762f925bdaddc4201f984") {
    symbol
    name
    decimals
    volumeUSD
    poolCount
    totalValueLockedUSD
  }
}

Position by NFT tokenId

{
  position(id: "3") {
    id
    tokenId
    owner
    subscriptions { id }
    unsubscriptions { id }
    transfers { id }
  }
}

Pool daily series

{
  poolDayDatas(
    first: 10
    orderBy: date
    where: {
      pool: "0x21c67e77068de97969ba93d4aab21826d33ca12bb9f565d8496e8fda8a82ca27"
      date_gt: 1735689600
    }
  ) {
    date
    liquidity
    sqrtPrice
    token0Price
    token1Price
    volumeToken0
    volumeToken1
  }
}

Historical (time-travel) at a block

{
  poolManager(
    id: "0x000000000004444c5dc75cb358380d2e3de08a90"
    block: { number: 22451931 }
  ) {
    poolCount
    totalVolumeUSD
  }
}

How to Call (curl)

ENDPOINT="https://gateway.thegraph.com/api/${THEGRAPH_API_KEY}/subgraphs/id/DiYPVdygkfjDWhbxGSqAQxwBKmfKnkWQojqeM2rkLb3G"

curl -s "$ENDPOINT" \
  -H 'Content-Type: application/json' \
  -d '{"query":"{ poolManager(id: \"0x000000000004444c5dc75cb358380d2e3de08a90\") { poolCount txCount totalVolumeUSD } }"}' \
  | jq '.'

Alternate auth style used by some clients:

curl -s "https://gateway.thegraph.com/api/subgraphs/id/DiYPVdygkfjDWhbxGSqAQxwBKmfKnkWQojqeM2rkLb3G" \
  -H "Authorization: Bearer ${THEGRAPH_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{"query":"{ pools(first: 5, orderBy: liquidity, orderDirection: desc) { id liquidity } }"}' \
  | jq '.'

Calling from a browser (CORS)

The gateway (gateway.thegraph.com) responds with access-control-allow-origin: * (confirmed Jul 2026), so fetch() works directly from client-side code — e.g. a static HTML artifact — without a proxy. The API key is then visible to anyone reading the page's source or localStorage; never embed a paid or high-quota key in anything public, and prefer making the key an optional user-supplied input (stored in the visitor's own localStorage) over baking it into shipped code.

Pagination

The Graph caps results at 1000 per request. Use first + skip:

{
  pools(first: 1000, skip: 0, orderBy: liquidity, orderDirection: desc) {
    id
  }
}

Increment skip by 1000 until fewer than 1000 rows return.

Workflow

1. Confirm intent: global metrics, pool state, swaps, token, position, or day data.
2. Ensure $THEGRAPHAPIKEY is set; if missing, ask the user to create one in Studio.
3. Pick the correct subgraph deployment for the chain (mainnet ID above; discover others in The Graph Explorer).
4. Use the chain-correct poolManager id and pool bytes32 ids (not v3 pool addresses).
5. POST GraphQL with curl and parse with jq.
6. If more than 1000 rows are needed, paginate with skip.
7. Present a short snapshot first (counts, top pools, latest swaps), then detail.
8. Treat data as informational; do not give investment advice.

Error Handling

• Missing / invalid API key (401/403): remind user to set THEGRAPHAPIKEY from Studio.
• GraphQL errors array: show message; usually bad field, bad id, or schema mismatch.
• Empty data / null entity: wrong chain deployment, wrong PoolManager id, or unknown pool/token id.
• Timeouts / 429: backoff and retry 1–2 times; avoid tight polling loops.
• Stale or inconsistent TVL: public deployments can lag or disagree with app.uniswap.org; state the source deployment id used.

Presenting Results

• Global: poolCount, txCount, totalVolumeUSD, totalValueLockedUSD.
• Pools: pair symbols, feeTier, liquidity, volumeUSD, hooks.
• Swaps: amounts, amountUSD, timestamp, sender/origin.
• Positions: tokenId, owner, subscription/transfer counts.
• Always cite chain + subgraph id when summarizing.

Out of Scope

This skill does not cover in v1:

• Uniswap v2 / v3 subgraphs (separate deployments)
• Onchain contract calls / SDK swaps (Universal Router, Permit2)
• Private Uniswap Labs indexers used by the official app
• Deploying or maintaining a subgraph (point to the GitHub repo only)

Reference

Expanded examples and entity tables: [references/v4-queries.md](references/v4-queries.md)