Pools
Uniswap v4 pools on Ethereum (1), Arbitrum One (42161), Avalanche C-Chain (43114), Robinhood Chain (4663), Arc (5042), HyperEVM (999), MegaETH (4326), Zora (7777777), Celo (42220), Ink (57073), Tempo (4217), Polygon (137) and Unichain (130), ranked by TVL, 24h volume, 24h fees, fee APR or age.
GET /v1/pools — 2 units
curl -s "https://api.tickwise.xyz/v1/pools?chainId=1&sort=tvl&limit=25" \
-H "KC-APIKey: $TICKWISE_API_KEY"Query parameters
| Parameter | Default | Meaning |
|---|---|---|
| chainId | all chains | 1, 42161, 43114, 4663, 5042, 999, 4326, 7777777, 42220, 57073, 4217, 137 or 130 — GET /v1/chains is the live list. Omitting it merges every enabled chain into one ranking. |
| protocol | uniswap-v4 | The only value served; anything else is a 400. |
| sort | tvl | tvl, volume, fees, fee_apr or age. Descending except age, which is oldest first. There is no direction parameter. |
| page | 1 | 1-based. |
| limit | 20 | 1–100. |
| minTvlUsd | 0 | Floor on pool TVL. |
| includeRisky | false | Admits pools whose tokens have no corroborated on-chain market. |
| search | — | Case-insensitive substring over either token symbol, either token address, or the pool id. Up to 64 characters. It is a lookup, not a filter: the spam-token exclusion is skipped while searching, so a pool you name stays findable. |
Response
A pools array and the same pagination envelope the positions list uses. Each row carries rank, poolId, chainId, protocol, both token snapshots, fee, isDynamicFee, tickSpacing, currentTick, sqrtPriceX96, liquidity, createdAtTimestamp, a metrics group (tvlUsd, volumeUsd24h, volumeUsd7d, feesUsd24h, feesUsd7d, feeApr, txCount, currentPrice), metricsAsOf, pricing, and two counts the underlying subgraph does not provide: positionsCount (open positions) and holdersCount (distinct owners). The same rules apply to total here: it is a floor when totalCapped is true, so page with hasMore.
The two counts are computed separately from the pool rows. For a very large pool they can still be in progress when the response is built. Those pools then carry null for both counts, and the list response adds "countsPending": true. Read null as “not known yet”, not as zero. A later request returns the numbers.
risk labels a row we would not rank, present only when it applies. risk.flags lists why: symbol-spoof (a token uses a major token’s symbol, such as USDT, at another contract), phishing-symbol (a token’s symbol carries a link or “visit”), excluded-token (a token is on our exclusion list: a security scan marked it unsafe or fake, or it has no real market) and risky-pool (the pool’s value cannot be relied on; these are the pools includeRisky=false hides). The ranked list already leaves such pools out, so the field mostly appears on search results and pool detail, which keep a pool you name. Ignore flag values you do not recognise.
hooks and customAccounting describe a pool’s v4 hook, and are present only on a pool that has one. hooks is the hook contract address, lower case; a pool without a hook carries neither field. customAccounting is true when the hook’s address sets one of the four returns-delta permissions, which let a hook take or redirect value that the pool’s swap and liquidity events do not show. It is read from the address alone and says nothing about intent. On such a pool the volume, LP fees and TVL are what moved through the pool’s own liquidity and are not affected, but what the hook itself takes is in none of them, and a position’s deposited, withdrawn and collected amounts can exceed what its owner actually paid or received. A dynamic-fee pool keeps isDynamicFee: true and carries these fields as well. A pool gains the fields the next time pool sync revisits it after this was released.
Two more flags, each present only when it applies. In all-chains mode (no chainId), a chain whose data is temporarily unavailable is left out rather than failing the whole request: the response adds "partial": true and "missingChains": […], the rows are the other chains’ merged order, total counts only those chains, and the request is not charged. Data older than the usual 45-second freshness is only ever served flagged: it carries "stale": true and dataAsOf, the time it was current. That happens when the database is too slow to answer (the last page we served comes back instead), when the database replica it was read from is running behind, and on a very deep page whose position in the list was counted more than 45 seconds ago. There is no page cap. Paging forward from one page to the next is cheap; the first visit to a very deep page can answer 503 with Retry-After while it is still being reached, and the retry continues from where that request got to.
feeApr is clamped at ±100,000% on the way out. The upstream v4 subgraph’s feesUSD is known to produce values in the hundreds of thousands of percent on thin pools; clamping at read time keeps a stale document from dominating a fee_apr ranking. A value sitting exactly on the cap should be read as “not trustworthy”, not as a measurement.
GET /v1/pools/{chainId}/{protocol}/{poolId} — 1 unit
One pool, in the same shape as a list row plus its counts. poolId is validated before anything else happens: a v4 pool id is 0x plus 64 hex characters, a v3 pool address 0x plus 40. Anything else is a 400 with {"error":"Invalid poolId"}, rejected here rather than fanned out to a metered upstream.
curl -s "https://api.tickwise.xyz/v1/pools/1/uniswap-v4/0x…64hex" \
-H "KC-APIKey: $TICKWISE_API_KEY"Ids are matched lowercased, so case in the path does not matter. A pool that exists on the other chain is a 404 here.
Like the list, a pool older than the 45-second freshness — its holder counts kept past their freshness, a database replica running behind, or the last copy served because the database was too slow — carries "stale": true and dataAsOf, the time it was current.
GET /v1/pools/{chainId}/{protocol}/{poolId}/charts — 10 units
?range=30d|60d|90d|180d|all, defaulting to 30d; an unrecognised value falls back to 30d rather than erroring.
curl -s "https://api.tickwise.xyz/v1/pools/1/uniswap-v4/0x…64hex/charts?range=90d" \
-H "KC-APIKey: $TICKWISE_API_KEY"Carries poolPrice (daily OHLC), poolOverview, liquidityDistribution (the tick histogram, with no position range marked — that is the difference from the position variant), poolSeries (volume, TVL, fees, fee APR) and poolOverviewCurrent, which is null when the pool has no day data. A range is counted back from the pool’s newest day of data, not from today; all is the last 365 days.
Each poolPrice point also carries tick: the pool’s tick after its last indexed event of that UTC day, an integer in the same units as a position’s tickLower and tickUpper, so a position was in range at a day’s close when tickLower <= tick < tickUpper. It is null, not 0, when the indexer has no valid tick for that day. A day with no pool activity has no point, so a gap is not a day out of range: the previous point’s tick still holds. One tick per day says nothing about moves within the day.
When an input could not be loaded for this response, the response adds "partial": true and missing, the inputs left out: any of poolState, poolDayData and ticks. Without poolDayData the price, overview and series sections are empty, and without ticks the histogram is, so read an empty series alongside partial as “not loaded”, not as “no activity”. poolState is the exception: without it the histogram is still returned, but liquidityDistribution.currentTick is 0 and its price0, price1, amount0 and amount1 assume 18 decimals for both tokens and a tick spacing of 60, so ignore liquidityDistribution whenever missing includes poolState. Neither flag is present on a complete response, and a partial response is not charged.
As on positions, poolOverview.divergence is always empty: the upstream schema does not carry it, and the key exists so it can be filled later without breaking clients. This route is the expensive one — see units and limits.
How fresh pool data is
Pool figures (price, tick, liquidity, TVL, volume and fees) come from the periodic pool sync, so they are as old as the last sync, which can be hours. Every pool carries asOf.statsAt: a time the stored figures are known to be at least as fresh as. It is the later of the pool's own updatedAt (the last time sync wrote the row; an unchanged pool is not rewritten for up to about a day) and the start of the last complete sync of that chain. If that sync skipped any pools, only updatedAt is used, so the time can only be too old, never too new. It is null when nothing is known.
volumeUsd24h, feesUsd24h and feeApr cover the 24 complete hours ending at the pool's metricsAsOf: the top of an hour in the indexer's time, not the wall clock, so the window trails now by up to an hour plus the indexer's own lag. Fees are what the LPs earned, each swap at its own fee. volumeUsd7d and feesUsd7d are the indexer's 7 newest UTC days, today's partial day included. metricsAsOf is null when not known.
Smaller responses
The list, detail and charts routes accept the same two optional parameters as the positions routes. Without them nothing changes: view=full is the default and is the response documented above. A shaped response costs the same units, and partial, missing, countsPending, stale, dataAsOf, risk and hooks are always returned. Nothing is converted or rounded.
view=compact— a curated default set.fields=a,b.c— dotted paths of the full response. On its own it returns exactly those paths plusrank,poolId,chainIdandprotocol; withview=compactit adds them to the compact set. An unknown path is a 400. Any full-response path can be named, so a field left out of compact is one request away. (On charts,fieldsselects exactly those paths, and leaves series in their full shape.)
What compact leaves out of a pool row: the raw reserves metrics.tvlToken0 and tvlToken1, the lifetime totals metrics.volumeUsdTotal and feesUsdTotal, the write time updatedAt and sqrtPriceX96. A pool row has no duplicated fields, so this is a curated default rather than a de-duplication, and the detail keeps sqrtPriceX96 and updatedAt. positionsCount and holdersCount stay, including their null while counts are still being computed.
Compact charts: every series is a column sharing one t axis (zip a column with t to get the points back); poolSeries.volume, tvl and fees are left out when they are exactly poolOverview’s (feeApr stays); poolOverview.price0/price1 when identical to poolPrice; the empty divergence; and each tick’s price1 (1 / price0). Liquidity bins are windowed to 200 around the current tick (ticksLimit, max 1,000); tickFrom / tickTo return an inclusive tick range instead, and liquidityDistribution.ticksTotal and tickWindow say what was returned. Each bin inside the window equals the full response’s bin.
curl -s "https://api.tickwise.xyz/v1/pools?chainId=1&view=compact&limit=100" -H "KC-APIKey: $TICKWISE_API_KEY"
curl -s "https://api.tickwise.xyz/v1/pools/1/uniswap-v4/$POOL_ID/charts?range=all&view=compact" -H "KC-APIKey: $TICKWISE_API_KEY"