Endpoints

Positions

Uniswap v4 liquidity positions 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). Every filter and sort the dashboard uses is on the same endpoint — there is no reduced public subset.

GET /v1/positions — 2 units

A ranked, filtered, paginated page of positions.

bash
curl -s "https://api.tickwise.xyz/v1/positions?chainId=1&sort=apr&limit=25" \
  -H "KC-APIKey: $TICKWISE_API_KEY"

Query parameters

Everything is optional. The defaults are not neutral — they are the visibility filters that keep spam and dust out of a ranking — so read the last three rows before concluding a position is missing.

ParameterDefaultMeaning
chainIdall chains1, 42161, 43114, 4663, 5042, 999, 4326, 7777777, 42220, 57073, 4217, 137 or 130 — GET /v1/chains is the live list. Omitting it means every enabled chain, merged into one ranking — not Ethereum. An unregistered id is a 400.
protocoluniswap-v4The only value served. uniswap-v3 is a 400 — see coverage.
sortaprOne of apr, fee_apr, roi, pnl, underlying_value, age, nft_id_asc, nft_id_desc. Direction is part of the key, not a separate parameter: everything is descending except nft_id_asc. age orders by creation time, newest first, on every status — closed rows are not ordered by how long they were held.
page11-based.
limit201–100. A larger value is a 400 rather than a silent clamp.
statusopen onlyactive, inactive or all — open, closed, or both. Unset behaves as active, because the older activeOnly flag it supersedes defaults to true; pass status=all to see closed positions.
rangeallin or out restricts to positions whose range currently contains the pool tick, or does not.
owner—A 0x-prefixed 40-hex EVM address, matched case-insensitively. Anything else is a 400 with a message naming the format.
poolId—Every position in one pool.
positionId—Exact match on a single id — the tokenId for an ERC-721 protocol. The other filters still apply, so a known id can still return nothing if it fails them.
minValueUsd0Floor on current underlying value.
minPoolTvl1000Floor on the pool’s TVL. Not zero — this is the one default that silently hides real positions in small pools.
includeRiskyfalseAdmits positions whose token has no corroborated on-chain market. Off by default because a ranking full of issuer-seeded spam pools is worthless.

Response

A positions array and a pagination object. Each row carries rank, identity (positionId, tokenId, chainId, protocol, owner, poolId), both token snapshots, the range (tickLower, tickUpper, currentTick, tickSpacing, fee, liquidity, isActive), and four nested groups: amounts (token-denominated deposits, withdrawals, collected and uncollected fees, gas), metrics (apr, feeApr, roi, pnlUsd, underlyingValueUsd, pendingFeesUsd, feesSource, feesMeasuredAt, ageSeconds, inRange), poolStats and pricing.

risk labels a position 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 (its pool’s value cannot be relied on). Lists leave positions in excluded tokens out, so excluded-token appears on a positionId lookup and on position detail. Ignore flag values you do not recognise.

hooks and customAccounting describe the position’s pool hook, and are present only when that pool has a v4 hook. hooks is the hook contract address, lower case. 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; the fee and value figures on such a position are not provably complete. They come from the pool, so a position whose pool the pool sync has not revisited yet lacks them. Both are on list rows and on detail.

metrics.feesSource says where the uncollected-fee figure came from. It applies to pendingFeesUsd and to the uncollected token amounts in amounts. Open positions are re-read on-chain by a recurring pass, and earlier when the indexer sees a position change, when it is newly indexed, or when its detail is requested. A position not written since the field was added can lack it; read a missing value as unmeasured.

feesSourceMeaning
onchainRead from the chain’s pool state at or after the position’s last liquidity change, which is the last event that settles fees.
indexerNo longer returned. It labelled the indexer’s own fee reading, which the indexer no longer produces: the figure now comes from the on-chain reading alone, and a position without one is unmeasured. The value stays in the list so a client that switches over every feesSource keeps working; a position not written since the change can still carry it until its next write.
settledThe position holds no liquidity. The change that emptied it paid out every fee owed and nothing accrues afterwards, so 0 is exact. Closed positions are not re-read.
unmeasuredNo on-chain reading at or after the last liquidity change. The figure is a placeholder 0, not a measurement: treat it as unknown. The dashboard shows it as Pending.

metrics.feesMeasuredAt is the ISO time of the on-chain reading behind the figure. It is null or absent unless feesSource is onchain, and can be null on an onchain figure read before the field was added. A re-read that finds no material change is not always written back, so the timestamp can be older than the most recent check. It dates the fee figure only; the response-level dataAsOf below dates the read of the stored data.

Every position row and detail carries asOf, which dates each kind of data on its own instead of one combined time: asOf.priceAt is when the position was last valued against token prices, asOf.liquidityAt is when its tick range and liquidity were last verified against the indexer, and asOf.feesAt is when its uncollected fees were last read on-chain (the same time as metrics.feesMeasuredAt). A value is null when it is unknown, never estimated. asOf.priceAt and asOf.liquidityAt move with the position refresh, so they are not a promise of minute-level freshness; check the value against your own tolerance before relying on it.

json
"pagination": { "page": 1, "limit": 20, "total": 0, "totalPages": 1, "hasMore": false }

Page with hasMore, not totalPages. hasMore is always exact: each page reads one row past itself. The count behind total runs separately and is cached; when it is not ready within about two seconds, or when it reaches its cap of 25,000, the response carries "totalCapped": true and total / totalPages are a floor: the number of rows that page proves exist, not the size of the result set. Without totalCapped, total is exact, in all-chains mode too (the merge sums each shard’s own count). A loop that stops at totalPages from the first response can stop early. Loop until hasMore is false.

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.

Two fields on metrics exist to stop you reading a gap as a number. priceUnavailable marks a leg that could not be priced from any independent source, and unrealizableLeg marks one valued at zero because the claim exceeds the pool’s real exit liquidity. Neither is the same as a genuine zero.

The rate sorts — apr, fee_apr, roi — exclude closed and no-value positions rather than ranking them on a stale stored rate. pnl does not: realised PnL on a closed position is a real number and belongs in that ranking. With status=inactive, a rate sort is served as pnl, because a closed position has no current rate: ?status=inactive&sort=apr returns closed positions ranked by PnL, not an empty page. With status=active or all, the rate sorts still leave closed and no-value rows out.

GET /v1/positions/{chainId}/{protocol}/{positionId} — 1 unit

One position in full, plus a transactions array the list endpoint does not carry: every mint, burn, collect and transfer with its token amounts, gas and per-transaction USD valuation.

bash
curl -s "https://api.tickwise.xyz/v1/positions/1/uniswap-v4/12345" \
  -H "KC-APIKey: $TICKWISE_API_KEY"

An id that does not exist on that chain and protocol is a 404, not an empty object — and an id from the other chain will 404 here, which is the usual cause.

The transaction list can come back incomplete, and says so rather than looking empty. transactionsDegraded is on every detail response; true means the full list could not be loaded for this response. On its own, the array is empty because the transaction source failed or did not answer in time, which is not the same as a position with no transactions. With it, "transactionsPartial": true means the array holds only the position’s newest transactions (up to 1,000) while the full history loads: ask again a few seconds later. "transactionsTruncated": true means the history is longer than 100,000 transactions and the newest are missing. A degraded answer is not charged. "stale": true with dataAsOf means the position itself was read from a database replica running more than 45 seconds behind.

GET /v1/positions/batch — 1 unit per position

Up to 100 positions of one chain in one request, instead of one call each. Each entry of positions is exactly what the single-position route above returns for that id, with the same view, fields and transactionsLimit.

bash
curl -s "https://api.tickwise.xyz/v1/positions/batch?chainId=1&ids=12345,12346,12347" \
  -H "KC-APIKey: $TICKWISE_API_KEY"
json
{
  "chainId": 1,
  "protocol": "uniswap-v4",
  "positions": [ { "positionId": "12345", … }, { "positionId": "12347", … } ],
  "missing": ["12346"]
}

chainId and ids are required; protocol defaults to uniswap-v4. ids is 1 to 100 position ids, comma-separated (repeating ids= also works). Duplicates are dropped and the rows come back in the order you asked. More than 100 distinct ids, or an id that is not digits, is a 400. An id with no position on that chain is not an error: it is listed in missing.

Billed per position returned: ids in missing and rows with "transactionsDegraded": true are not charged, and X-Units-Charged says what the request cost. See Units and limits.

For speed, pass a fields list without transactions (for example fields=positionId,metrics.underlyingValueUsd,metrics.apr): the transaction lists are then not loaded at all. With transactions, each list is read through the same cache as the single route, and a list not ready in time comes back as its newest page with transactionsPartial, as it would on the single route.

GET /v1/positions/{chainId}/{protocol}/{positionId}/charts — 10 units

Time series for one position. ?range=30d|60d|90d|180d|all, defaulting to 30d; an unrecognised value falls back to 30d rather than erroring, because the alternative is letting a typo fan out unbounded queries against a paid upstream.

bash
curl -s "https://api.tickwise.xyz/v1/positions/1/uniswap-v4/12345/charts?range=90d" \
  -H "KC-APIKey: $TICKWISE_API_KEY"

The response carries poolPrice (daily OHLC plus both token prices), poolOverview (TVL, volume, fees, fees/TVL, both prices), liquidityDistribution (the tick histogram, with this position’s tickLower and tickUpper marked), positionSeries (PnL, asset value, APR, fee APR, divergence loss) and poolOverviewCurrent.

A range is the last 30, 60, 90 or 180 days counted back from the newest data point the series holds, not from today. all starts at the position’s creation.

A chart can come back incomplete, and says so. When an input could not be loaded for this response, the response adds "partial": true and missing, the inputs left out: any of poolDayData, ticks, token0DayData, token1DayData and transactions. Without poolDayData the price and overview sections are empty, and without ticks the histogram is; without a token’s day data the position series values that token from the pool price instead. For a position with a long history whose full transaction list is still loading, "missing": ["transactions"] comes with positionSeries: null, because the series is a running sum from the first transaction and cannot start from the middle; ask again a few seconds later. transactions is also listed when the history is longer than the 100,000 transactions read, since the series then stops short of the newest flows. Neither flag is present on a complete response, and a partial response is not charged.

Three honest caveats. positionSeries is null when the series cannot be reconstructed, and null is not zero. poolOverview.divergence is always empty — the upstream schema does not carry it, and the key is present only so it can be filled without a breaking change. And this is the most expensive route we serve: it is a multi-query fan-out to an upstream we pay per call for, which is what the unit cost reflects.

Smaller responses

The list, detail and charts routes accept two optional parameters that shape the response. Without them nothing changes: view=full is the default and is the response documented above. A shaped response costs the same units as a full one, and every degradation flag (partial, missing, transactionsDegraded, transactionsPartial, transactionsTruncated, stale, dataAsOf, risk, hooks) is always returned.

  • view=compact — a curated default set. Nothing is converted: large integers stay strings and no value is rounded.
  • fields=a,b.c — dotted paths of the full response. On its own it returns exactly those paths plus identity (rank, positionId, chainId, protocol); with view=compact it adds them to the compact set (on a detail with view=compact the transactions are always compacted, so fields cannot name them: use view=full or the transactions route). A path the full response never carries is a 400, not a silently empty field. Because any full-response path can be named, a field left out of the compact set is always one request away. (On charts, fields selects exactly those paths and leaves series in their full shape.)

What compact leaves out

  • List and detail rows: tokenId (equal to positionId); the six amounts.*Usd strings, each the same figure as a metrics number (depositedUsd, withdrawnUsd, diffUsd, totalGasCostUsd, collectedFeesUsd, pendingFeesUsd); metrics.nominalValueUsd, poolApr, pnlEth, unclaimedRewardsUsd, claimedRewardsUsd; poolStats.tvlUsdUntracked and priceDivergence; each token’s verified. The list also leaves out metrics.usd.* (the vs-USD companion); the detail keeps it, with sqrtPriceX96.
  • Transactions: chainId, protocol, positionId and tokenId when they equal the position’s; amount0PriceUsd / amount1PriceUsd when they equal the position’s token priceUsd; the *PriceUsdUntracked and *HistoricalPriceUsd fields when 0; historicalPricingSource when 'none'; and rawSubgraph. An absent field means that default; a row that carries a different value keeps the field.
  • Charts: every series is a column sharing one t axis (zip a column with t to get the points back; series on a different axis keep their own t); poolOverview.price0/price1 when identical to poolPrice; the always-empty poolOverview.divergence; and each tick’s price1 (1 / price0).

Paging transactions and ticks

A compact detail embeds the newest 50 transactions (transactionsLimit=1..1000 sets it, on either view) and adds transactionsTotal and, when older ones exist, transactionsNextCursor. The rest are on GET /v1/positions/{chainId}/{protocol}/{positionId}/transactions?limit=100&before=<cursor> (1 unit), newest page first, rows oldest to newest inside a page. The cursor is a transactionId, not an offset, so a transaction indexed between two requests cannot duplicate or skip a row. A transactions page carries the same transactionsPartial / transactionsDegraded flags while the history is still loading.

Compact charts return 200 liquidity bins centred on the current tick (ticksLimit, max 1,000). tickFrom and tickTo (inclusive tick indexes) return that range instead, so every bin can be fetched in windows. The response reports liquidityDistribution.ticksTotal and tickWindow, and each bin inside the window is identical to the full response’s bin, activeLiquidity included. The window options also work on view=full when you pass them.

bash
# compact list, then just the fields you need
curl -s "https://api.tickwise.xyz/v1/positions?chainId=1&view=compact&limit=100"   -H "KC-APIKey: $TICKWISE_API_KEY"
curl -s "https://api.tickwise.xyz/v1/positions?chainId=1&fields=owner,metrics.apr,metrics.usd"   -H "KC-APIKey: $TICKWISE_API_KEY"

# compact detail, then the next older page of transactions
curl -s "https://api.tickwise.xyz/v1/positions/1/uniswap-v4/12345?view=compact"   -H "KC-APIKey: $TICKWISE_API_KEY"
curl -s "https://api.tickwise.xyz/v1/positions/1/uniswap-v4/12345/transactions?limit=100&before=$CURSOR"   -H "KC-APIKey: $TICKWISE_API_KEY"

# compact charts, a different window of liquidity bins
curl -s "https://api.tickwise.xyz/v1/positions/1/uniswap-v4/12345/charts?range=all&view=compact&tickFrom=-2000&tickTo=2000"   -H "KC-APIKey: $TICKWISE_API_KEY"

Next

Pools — the same three shapes for pools. Units and limits — why a list costs more than a detail. Errors — every status code and whether retrying helps.