{"openapi":"3.1.0","info":{"title":"Tickwise API","version":"v1","summary":"Uniswap v4 liquidity positions and pools, ranked and measured.","description":"The client-facing `/v1` API. Send your key in the `KC-APIKey` header on every metered request (never `Authorization`, never a query parameter). Metered routes cost **units**; the two limits — a 60-second burst rate limit per key and a monthly unit quota per account — fail independently with a `429` and a `Retry-After` header. Errors are JSON with an `error` string: branch on the status code, not the message.\n\nA **server** key is rejected (403) on any request that carries an `Origin` header, so the interactive console on the docs site sends calls through a server-side proxy. Call the API from your backend, or use a **browser** key with your origins registered."},"tags":[{"name":"Positions","description":"Liquidity positions: the ranked list, one position, its transactions and time series."},{"name":"Pools","description":"Pools: the ranked list, one pool and its time series."},{"name":"Metadata","description":"Free, keyless: which chains and protocols are served."},{"name":"Account & pricing","description":"Free, keyless: plans, per-route unit costs and corpus size."}],"paths":{"/v1/positions":{"get":{"operationId":"positions.list","tags":["Positions"],"summary":"List positions","description":"A ranked, filtered, paginated page of positions. Every filter and sort the dashboard uses is here. The defaults are visibility filters that keep spam and dust out of a ranking (open positions only, `minPoolTvl=1000`, `includeRisky=false`); to fetch a wallet's complete set pass `status=all&minValueUsd=0&minPoolTvl=0&includeRisky=true`. Page with `pagination.hasMore`, not `totalPages`.\n\nCosts **2 units** per call. Requests we refuse (4xx) and 5xx answers are credited back.","parameters":[{"name":"chainId","in":"query","required":false,"description":"Omit to merge every enabled chain into one ranking (not Ethereum).","schema":{"type":"integer","minimum":1,"enum":[1,999,4217,4326,4663,5042,42161,42220,43114,57073,7777777],"description":"`GET /v1/chains` is the live list. An unregistered id is a 400."}},{"name":"protocol","in":"query","required":false,"description":"The only value served; anything else is a 400.","schema":{"type":"string","enum":["uniswap-v4"],"default":"uniswap-v4"}},{"name":"owner","in":"query","schema":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$"},"description":"Every position held by one wallet (EVM address, case-insensitive)."},{"name":"poolId","in":"query","schema":{"type":"string"},"description":"Every position in one pool."},{"name":"positionId","in":"query","schema":{"type":"string"},"description":"Exact match on one id. The other filters still apply."},{"name":"status","in":"query","schema":{"type":"string","enum":["active","inactive","all"]},"description":"Open, closed, or both. Unset behaves as `active`; pass `all` to see closed positions."},{"name":"sort","in":"query","schema":{"type":"string","enum":["apr","fee_apr","roi","age","pnl","underlying_value","nft_id_asc","nft_id_desc"],"default":"apr"},"description":"Direction is part of the key: everything is descending except `nft_id_asc`. The rate sorts (`apr`, `fee_apr`, `roi`) leave closed and no-value positions out."},{"name":"range","in":"query","schema":{"type":"string","enum":["all","in","out"],"default":"all"},"description":"`in` / `out` restricts to positions whose range currently contains the pool tick, or does not."},{"name":"page","in":"query","schema":{"type":"integer","minimum":1,"default":1},"description":"1-based."},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"description":"1–100. A larger value is a 400, not a silent clamp."},{"name":"minValueUsd","in":"query","schema":{"type":"number","minimum":0,"default":0},"description":"Floor on current underlying value."},{"name":"minPoolTvl","in":"query","schema":{"type":"number","minimum":0,"default":1000},"description":"Floor on the pool's TVL. **Not zero** — the one default that silently hides real positions in small pools."},{"name":"includeRisky","in":"query","schema":{"type":"boolean","default":false},"description":"Admits rows whose token has no corroborated on-chain market. Off by default because a ranking full of issuer-seeded spam is worthless."},{"name":"assetClass","in":"query","schema":{"type":"string","enum":["equity"]},"description":"`equity` restricts to tokenized-equity pools. A chain with none returns zero rows."},{"name":"view","in":"query","schema":{"type":"string","enum":["full","compact"],"default":"full"},"description":"`compact` returns a curated smaller set of fields; `full` is the whole response."},{"name":"fields","in":"query","schema":{"type":"string","maxLength":2000},"description":"Comma-separated dotted paths (at most 60) to return instead of the full row, e.g. `positionId,metrics.apr`. An unknown path is a 400."}],"responses":{"200":{"description":"A page of positions.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-Quota-Limit":{"$ref":"#/components/headers/XQuotaLimit"},"X-Quota-Remaining":{"$ref":"#/components/headers/XQuotaRemaining"},"X-Quota-Reset":{"$ref":"#/components/headers/XQuotaReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PositionList"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/Unavailable"}},"security":[{"ApiKey":[]}],"x-unit-cost":2,"x-route-key":"v1.positions.list"}},"/v1/positions/{chainId}/{protocol}/{positionId}":{"get":{"operationId":"positions.detail","tags":["Positions"],"summary":"Get one position","description":"One position in full, plus a `transactions` array. A position that does not exist on that chain and protocol is a 404. The transaction list says when it is incomplete (`transactionsDegraded`, `transactionsPartial`, `transactionsTruncated`) rather than looking empty.\n\nCosts **1 unit** per call. Requests we refuse (4xx) and 5xx answers are credited back.","parameters":[{"name":"chainId","in":"path","required":true,"schema":{"type":"integer","minimum":1,"enum":[1,999,4217,4326,4663,5042,42161,42220,43114,57073,7777777],"description":"`GET /v1/chains` is the live list. An unregistered id is a 400."}},{"name":"protocol","in":"path","required":true,"schema":{"type":"string","enum":["uniswap-v4"],"default":"uniswap-v4"}},{"name":"positionId","in":"path","required":true,"schema":{"type":"string"},"description":"The tokenId for an ERC-721 protocol. An id from another chain is a 404."},{"name":"view","in":"query","schema":{"type":"string","enum":["full","compact"],"default":"full"},"description":"`compact` returns a curated smaller set of fields; `full` is the whole response."},{"name":"fields","in":"query","schema":{"type":"string","maxLength":2000},"description":"Comma-separated dotted paths (at most 60) to return instead of the full row, e.g. `positionId,metrics.apr`. An unknown path is a 400."},{"name":"transactionsLimit","in":"query","schema":{"type":"integer","minimum":1,"maximum":1000},"description":"Cap on the embedded `transactions` array."}],"responses":{"200":{"description":"One position.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-Quota-Limit":{"$ref":"#/components/headers/XQuotaLimit"},"X-Quota-Remaining":{"$ref":"#/components/headers/XQuotaRemaining"},"X-Quota-Reset":{"$ref":"#/components/headers/XQuotaReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PositionDetail"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/Unavailable"}},"security":[{"ApiKey":[]}],"x-unit-cost":1,"x-route-key":"v1.positions.detail"}},"/v1/positions/{chainId}/{protocol}/{positionId}/transactions":{"get":{"operationId":"positions.transactions","tags":["Positions"],"summary":"Page through a position's transactions","description":"One page of the position's transactions, newest first. Pass `transactionsNextCursor` from the response back as `before` for the next older page.\n\nCosts **1 unit** per call. Requests we refuse (4xx) and 5xx answers are credited back.","parameters":[{"name":"chainId","in":"path","required":true,"schema":{"type":"integer","minimum":1,"enum":[1,999,4217,4326,4663,5042,42161,42220,43114,57073,7777777],"description":"`GET /v1/chains` is the live list. An unregistered id is a 400."}},{"name":"protocol","in":"path","required":true,"schema":{"type":"string","enum":["uniswap-v4"],"default":"uniswap-v4"}},{"name":"positionId","in":"path","required":true,"schema":{"type":"string"},"description":"The tokenId for an ERC-721 protocol. An id from another chain is a 404."},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":1000,"default":50},"description":"1–1000."},{"name":"before","in":"query","schema":{"type":"string","maxLength":200},"description":"A `transactionsNextCursor` from the previous page."},{"name":"view","in":"query","schema":{"type":"string","enum":["full","compact"],"default":"full"},"description":"`compact` returns a curated smaller set of fields; `full` is the whole response."},{"name":"fields","in":"query","schema":{"type":"string","maxLength":2000},"description":"Comma-separated dotted paths (at most 60) to return instead of the full row, e.g. `positionId,metrics.apr`. An unknown path is a 400."}],"responses":{"200":{"description":"One page of transactions.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-Quota-Limit":{"$ref":"#/components/headers/XQuotaLimit"},"X-Quota-Remaining":{"$ref":"#/components/headers/XQuotaRemaining"},"X-Quota-Reset":{"$ref":"#/components/headers/XQuotaReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TransactionsPage"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/Unavailable"}},"security":[{"ApiKey":[]}],"x-unit-cost":1,"x-route-key":"v1.positions.transactions"}},"/v1/positions/{chainId}/{protocol}/{positionId}/charts":{"get":{"operationId":"positions.charts","tags":["Positions"],"summary":"Get a position's time series","description":"Daily pool price (OHLC), pool overview, the liquidity distribution with this position's `tickLower` / `tickUpper` marked, and the position series (PnL, asset value, APR, fee APR, divergence loss). A chart that could not load an input says so with `partial: true`.\n\nCosts **10 units** per call. Requests we refuse (4xx) and 5xx answers are credited back.","parameters":[{"name":"chainId","in":"path","required":true,"schema":{"type":"integer","minimum":1,"enum":[1,999,4217,4326,4663,5042,42161,42220,43114,57073,7777777],"description":"`GET /v1/chains` is the live list. An unregistered id is a 400."}},{"name":"protocol","in":"path","required":true,"schema":{"type":"string","enum":["uniswap-v4"],"default":"uniswap-v4"}},{"name":"positionId","in":"path","required":true,"schema":{"type":"string"},"description":"The tokenId for an ERC-721 protocol. An id from another chain is a 404."},{"name":"range","in":"query","schema":{"type":"string","enum":["30d","60d","90d","180d","all"],"default":"30d"},"description":"Counted back from the newest data point the series holds, not from today. An unrecognised value falls back to `30d` rather than erroring."},{"name":"view","in":"query","schema":{"type":"string","enum":["full","compact"],"default":"full"},"description":"`compact` returns a curated smaller set of fields; `full` is the whole response."},{"name":"fields","in":"query","schema":{"type":"string","maxLength":2000},"description":"Comma-separated dotted paths (at most 60) to return instead of the full row, e.g. `positionId,metrics.apr`. An unknown path is a 400."},{"name":"ticksLimit","in":"query","schema":{"type":"integer","minimum":1,"maximum":1000},"description":"Liquidity bins to return, centred on the current tick."},{"name":"tickFrom","in":"query","schema":{"type":"integer","minimum":-887272,"maximum":887272},"description":"Lowest tick of the liquidity window (inclusive). Must not exceed `tickTo`."},{"name":"tickTo","in":"query","schema":{"type":"integer","minimum":-887272,"maximum":887272},"description":"Highest tick of the liquidity window (inclusive)."}],"responses":{"200":{"description":"Time series for one position.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-Quota-Limit":{"$ref":"#/components/headers/XQuotaLimit"},"X-Quota-Remaining":{"$ref":"#/components/headers/XQuotaRemaining"},"X-Quota-Reset":{"$ref":"#/components/headers/XQuotaReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Charts"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/Unavailable"}},"security":[{"ApiKey":[]}],"x-unit-cost":10,"x-route-key":"v1.positions.charts"}},"/v1/pools":{"get":{"operationId":"pools.list","tags":["Pools"],"summary":"List pools","description":"Top pools, ranked. Page with `pagination.hasMore`, not `totalPages`. `search` is a lookup, not a filter: the spam-token exclusion is skipped while searching.\n\nCosts **2 units** per call. Requests we refuse (4xx) and 5xx answers are credited back.","parameters":[{"name":"chainId","in":"query","required":false,"description":"Omit to merge every enabled chain into one ranking (not Ethereum).","schema":{"type":"integer","minimum":1,"enum":[1,999,4217,4326,4663,5042,42161,42220,43114,57073,7777777],"description":"`GET /v1/chains` is the live list. An unregistered id is a 400."}},{"name":"protocol","in":"query","required":false,"description":"The only value served; anything else is a 400.","schema":{"type":"string","enum":["uniswap-v4"],"default":"uniswap-v4"}},{"name":"sort","in":"query","schema":{"type":"string","enum":["tvl","volume","fees","fee_apr","age"],"default":"tvl"}},{"name":"page","in":"query","schema":{"type":"integer","minimum":1,"default":1},"description":"1-based."},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"description":"1–100. A larger value is a 400, not a silent clamp."},{"name":"minTvlUsd","in":"query","schema":{"type":"number","minimum":0,"default":0}},{"name":"includeRisky","in":"query","schema":{"type":"boolean","default":false},"description":"Admits rows whose token has no corroborated on-chain market. Off by default because a ranking full of issuer-seeded spam is worthless."},{"name":"search","in":"query","schema":{"type":"string","maxLength":66},"description":"Case-insensitive substring over either token symbol, either token address, or the pool id."},{"name":"assetClass","in":"query","schema":{"type":"string","enum":["equity"]},"description":"`equity` restricts to tokenized-equity pools. A chain with none returns zero rows."},{"name":"view","in":"query","schema":{"type":"string","enum":["full","compact"],"default":"full"},"description":"`compact` returns a curated smaller set of fields; `full` is the whole response."},{"name":"fields","in":"query","schema":{"type":"string","maxLength":2000},"description":"Comma-separated dotted paths (at most 60) to return instead of the full row, e.g. `positionId,metrics.apr`. An unknown path is a 400."}],"responses":{"200":{"description":"A page of pools.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-Quota-Limit":{"$ref":"#/components/headers/XQuotaLimit"},"X-Quota-Remaining":{"$ref":"#/components/headers/XQuotaRemaining"},"X-Quota-Reset":{"$ref":"#/components/headers/XQuotaReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PoolList"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/Unavailable"}},"security":[{"ApiKey":[]}],"x-unit-cost":2,"x-route-key":"v1.pools.list"}},"/v1/pools/{chainId}/{protocol}/{poolId}":{"get":{"operationId":"pools.detail","tags":["Pools"],"summary":"Get one pool","description":"One pool, in the same shape as a list row plus its `positionsCount`. A pool that exists on the other chain is a 404.\n\nCosts **1 unit** per call. Requests we refuse (4xx) and 5xx answers are credited back.","parameters":[{"name":"chainId","in":"path","required":true,"schema":{"type":"integer","minimum":1,"enum":[1,999,4217,4326,4663,5042,42161,42220,43114,57073,7777777],"description":"`GET /v1/chains` is the live list. An unregistered id is a 400."}},{"name":"protocol","in":"path","required":true,"schema":{"type":"string","enum":["uniswap-v4"],"default":"uniswap-v4"}},{"name":"poolId","in":"path","required":true,"schema":{"type":"string","pattern":"^0x[0-9a-fA-F]{40}$|^0x[0-9a-fA-F]{64}$"},"description":"`0x` plus 40 hex (a v3 pool address) or 64 hex (a v4 pool id). Anything else is a 400."},{"name":"view","in":"query","schema":{"type":"string","enum":["full","compact"],"default":"full"},"description":"`compact` returns a curated smaller set of fields; `full` is the whole response."},{"name":"fields","in":"query","schema":{"type":"string","maxLength":2000},"description":"Comma-separated dotted paths (at most 60) to return instead of the full row, e.g. `positionId,metrics.apr`. An unknown path is a 400."}],"responses":{"200":{"description":"One pool.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-Quota-Limit":{"$ref":"#/components/headers/XQuotaLimit"},"X-Quota-Remaining":{"$ref":"#/components/headers/XQuotaRemaining"},"X-Quota-Reset":{"$ref":"#/components/headers/XQuotaReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PoolDetail"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/Unavailable"}},"security":[{"ApiKey":[]}],"x-unit-cost":1,"x-route-key":"v1.pools.detail"}},"/v1/pools/{chainId}/{protocol}/{poolId}/charts":{"get":{"operationId":"pools.charts","tags":["Pools"],"summary":"Get a pool's time series","description":"Daily pool price (OHLC), pool overview, the liquidity distribution (no position range marked) and the pool series (volume, TVL, fees, fee APR).\n\nCosts **10 units** per call. Requests we refuse (4xx) and 5xx answers are credited back.","parameters":[{"name":"chainId","in":"path","required":true,"schema":{"type":"integer","minimum":1,"enum":[1,999,4217,4326,4663,5042,42161,42220,43114,57073,7777777],"description":"`GET /v1/chains` is the live list. An unregistered id is a 400."}},{"name":"protocol","in":"path","required":true,"schema":{"type":"string","enum":["uniswap-v4"],"default":"uniswap-v4"}},{"name":"poolId","in":"path","required":true,"schema":{"type":"string","pattern":"^0x[0-9a-fA-F]{40}$|^0x[0-9a-fA-F]{64}$"},"description":"`0x` plus 40 hex (a v3 pool address) or 64 hex (a v4 pool id). Anything else is a 400."},{"name":"range","in":"query","schema":{"type":"string","enum":["30d","60d","90d","180d","all"],"default":"30d"},"description":"Counted back from the newest data point the series holds, not from today. An unrecognised value falls back to `30d` rather than erroring."},{"name":"view","in":"query","schema":{"type":"string","enum":["full","compact"],"default":"full"},"description":"`compact` returns a curated smaller set of fields; `full` is the whole response."},{"name":"fields","in":"query","schema":{"type":"string","maxLength":2000},"description":"Comma-separated dotted paths (at most 60) to return instead of the full row, e.g. `positionId,metrics.apr`. An unknown path is a 400."},{"name":"ticksLimit","in":"query","schema":{"type":"integer","minimum":1,"maximum":1000},"description":"Liquidity bins to return, centred on the current tick."},{"name":"tickFrom","in":"query","schema":{"type":"integer","minimum":-887272,"maximum":887272},"description":"Lowest tick of the liquidity window (inclusive). Must not exceed `tickTo`."},{"name":"tickTo","in":"query","schema":{"type":"integer","minimum":-887272,"maximum":887272},"description":"Highest tick of the liquidity window (inclusive)."}],"responses":{"200":{"description":"Time series for one pool.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/XRateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/XRateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/XRateLimitReset"},"X-Quota-Limit":{"$ref":"#/components/headers/XQuotaLimit"},"X-Quota-Remaining":{"$ref":"#/components/headers/XQuotaRemaining"},"X-Quota-Reset":{"$ref":"#/components/headers/XQuotaReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Charts"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"503":{"$ref":"#/components/responses/Unavailable"}},"security":[{"ApiKey":[]}],"x-unit-cost":10,"x-route-key":"v1.pools.charts"}},"/v1/chains":{"get":{"operationId":"chains","tags":["Metadata"],"summary":"List supported chains","description":"The chains served, each with the protocols live on it. The live source for every valid `chainId`.\n\nFree and unmetered. **No API key needed.**","responses":{"200":{"description":"Supported chains.","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Chain"}}}}}},"security":[],"x-unit-cost":0}},"/v1/protocols":{"get":{"operationId":"protocols","tags":["Metadata"],"summary":"List supported protocols","description":"The protocols served and the chains each one is live on.\n\nFree and unmetered. **No API key needed.**","responses":{"200":{"description":"Supported protocols.","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Protocol"}}}}}},"security":[],"x-unit-cost":0}},"/v1/plans":{"get":{"operationId":"plans","tags":["Account & pricing"],"summary":"List plans","description":"The plans you can buy, with their monthly units, burst limit and prices.\n\nFree and unmetered. **No API key needed.**","responses":{"200":{"description":"Public plans.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlanList"}}}}},"security":[],"x-unit-cost":0}},"/v1/pricing/units":{"get":{"operationId":"pricing.units","tags":["Account & pricing"],"summary":"List unit costs","description":"What each metered route costs in units, live. Read costs from here rather than hard-coding them.\n\nFree and unmetered. **No API key needed.**","responses":{"200":{"description":"Unit cost per route.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnitCostList"}}}}},"security":[],"x-unit-cost":0}},"/v1/stats":{"get":{"operationId":"stats","tags":["Account & pricing"],"summary":"Get corpus size","description":"Headline counts of everything indexed: no visibility filters, unlike the list totals.\n\nFree and unmetered. **No API key needed.**","responses":{"200":{"description":"Corpus statistics.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Stats"}}}}},"security":[],"x-unit-cost":0}}},"components":{"securitySchemes":{"ApiKey":{"type":"apiKey","in":"header","name":"KC-APIKey","description":"Your API key from the portal. A server key must not be sent from a browser."}},"headers":{"XRateLimitLimit":{"description":"Burst limit: requests allowed per 60-second window for this key.","schema":{"type":"integer"}},"XRateLimitRemaining":{"description":"Requests left in the current burst window.","schema":{"type":"integer"}},"XRateLimitReset":{"description":"Seconds until the burst window resets.","schema":{"type":"integer"}},"XQuotaLimit":{"description":"Monthly unit quota for the account.","schema":{"type":"integer"}},"XQuotaRemaining":{"description":"Units left this month.","schema":{"type":"integer"}},"XQuotaReset":{"description":"Seconds until the quota resets (00:00 UTC on the 1st).","schema":{"type":"integer"}}},"responses":{"BadRequest":{"description":"A parameter is malformed or unrecognised. Fix the request; costs no units.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unauthorized":{"description":"The `KC-APIKey` header is missing, unknown, revoked, or the account is suspended.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Forbidden":{"description":"A valid key used where it is not allowed: a server key from a browser (any request with an `Origin` header), or a browser key from an unregistered origin.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"No such position or pool on that chain and protocol. An id from another chain is the usual cause.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"TooManyRequests":{"description":"Burst rate limit or monthly quota. `Retry-After` (seconds) tells you which by how long it is.","headers":{"Retry-After":{"description":"Seconds to wait.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"retryAfterSec":{"type":"integer"}},"additionalProperties":true}}}},"Unavailable":{"description":"A read did not finish in time (often a very deep list page still being reached). Retry after `Retry-After`; costs no units.","headers":{"Retry-After":{"description":"Seconds to wait.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable. Branch on the status code, never on this text."}},"required":["error"],"additionalProperties":true},"Pagination":{"type":"object","properties":{"page":{"type":"integer"},"limit":{"type":"integer"},"total":{"type":["integer","null"],"description":"A floor when `totalCapped` is true."},"totalPages":{"type":["integer","null"]},"hasMore":{"type":"boolean","description":"Always exact. Loop until it is false."},"totalPending":{"type":"boolean","description":"Present only when the count is not ready yet."},"totalCapped":{"type":"boolean","description":"Present only when `total` is a floor (cap 25,000, or not ready in about two seconds)."}},"required":["page","limit","hasMore"],"additionalProperties":true},"Degradation":{"type":"object","properties":{"partial":{"type":"boolean","description":"All-chains mode only: a chain whose data was unavailable is left out, and the request is not charged."},"missingChains":{"type":"array","items":{"type":"integer"}},"stale":{"type":"boolean","description":"Complete but older than the usual 45-second freshness. Billed normally."},"dataAsOf":{"type":"string","format":"date-time","description":"When a `stale` response was current."}},"additionalProperties":true},"Token":{"type":"object","properties":{"address":{"type":"string"},"symbol":{"type":"string"},"decimals":{"type":"integer"},"verified":{"type":"boolean"},"priceUsd":{"type":"number"},"priceConfidence":{"type":"string"},"logoURI":{"type":["string","null"]}},"required":["address","symbol","decimals"],"additionalProperties":true},"Risk":{"type":"object","properties":{"flags":{"type":"array","items":{"type":"string","enum":["symbol-spoof","phishing-symbol","excluded-token","risky-pool"]},"description":"Why we would not rank this row. Ignore values you do not recognise."}},"additionalProperties":true},"Position":{"type":"object","properties":{"rank":{"type":"integer"},"positionId":{"type":"string"},"tokenId":{"type":"string"},"chainId":{"type":"integer"},"protocol":{"type":"string"},"owner":{"type":"string"},"poolId":{"type":"string"},"token0":{"$ref":"#/components/schemas/Token"},"token1":{"$ref":"#/components/schemas/Token"},"fee":{"type":"integer"},"tickSpacing":{"type":"integer"},"tickLower":{"type":"integer"},"tickUpper":{"type":"integer"},"currentTick":{"type":"integer"},"liquidity":{"type":"string"},"isActive":{"type":"boolean"},"createdAtTimestamp":{"type":"integer"},"closedAtTimestamp":{"type":["integer","null"]},"amounts":{"type":"object","properties":{"amount0":{"type":"string"},"amount1":{"type":"string"},"depositedToken0":{"type":"string"},"depositedToken1":{"type":"string"},"withdrawnToken0":{"type":"string"},"withdrawnToken1":{"type":"string"},"totalFeesCollected0":{"type":"string"},"totalFeesCollected1":{"type":"string"},"totalFeesUncollected0":{"type":"string"},"totalFeesUncollected1":{"type":"string"}},"additionalProperties":true},"metrics":{"type":"object","properties":{"apr":{"type":"number"},"feeApr":{"type":"number"},"roi":{"type":"number"},"pnlUsd":{"type":"number","description":"Total profit and loss in USD. When the vs-USD basis was not measured it equals pnlHodl."},"underlyingValueUsd":{"type":"number"},"pendingFeesUsd":{"type":"number"},"investedUsd":{"type":"number"},"ageSeconds":{"type":"integer"},"inRange":{"type":"boolean"},"priceUnavailable":{"type":"boolean","description":"A leg could not be priced from any independent source. Not the same as a genuine zero."},"unrealizableLeg":{"type":"boolean","description":"A leg valued at zero because the claim exceeds the pool's real exit liquidity."},"feesSource":{"type":"string","enum":["onchain","indexer","settled","unmeasured"],"description":"Where the uncollected-fee figure came from. `unmeasured` means a placeholder 0, not a measurement."},"feesMeasuredAt":{"type":["string","null"],"format":"date-time"}},"additionalProperties":true},"poolStats":{"type":"object","properties":{"tvlUsd":{"type":"number"},"volumeUsd":{"type":"number"},"totalFeesUsd":{"type":"number"}},"additionalProperties":true},"pricing":{"type":"object","properties":{"source":{"type":"string"},"usedFallback":{"type":"boolean"},"pricedAt":{"type":"string"}},"additionalProperties":true},"asOf":{"type":"object","properties":{"priceAt":{"type":["string","null"],"format":"date-time"},"liquidityAt":{"type":["string","null"],"format":"date-time"},"feesAt":{"type":["string","null"],"format":"date-time"}},"additionalProperties":true},"risk":{"$ref":"#/components/schemas/Risk"},"hooks":{"type":"string","description":"The pool's v4 hook contract, lower case. Present only when the pool has one."},"customAccounting":{"type":"boolean","description":"True when the hook can take or redirect value the pool events do not show. Fee and value figures are then not provably complete."}},"required":["positionId","chainId","protocol"],"additionalProperties":true},"PositionList":{"allOf":[{"$ref":"#/components/schemas/Degradation"},{"type":"object","properties":{"positions":{"type":"array","items":{"$ref":"#/components/schemas/Position"}},"pagination":{"$ref":"#/components/schemas/Pagination"}},"required":["positions","pagination"],"additionalProperties":true}]},"Transaction":{"type":"object","properties":{"chainId":{"type":"integer"},"protocol":{"type":"string"},"positionId":{"type":"string"},"tokenId":{"type":"string"},"transactionId":{"type":"string"},"txHash":{"type":"string"},"type":{"type":"string"},"timestamp":{"type":"integer"},"amount0":{"type":"string"},"amount1":{"type":"string"},"amount0PriceUsd":{"type":"number"},"amount1PriceUsd":{"type":"number"},"amount0PriceUsdUntracked":{"type":"number"},"amount1PriceUsdUntracked":{"type":"number"},"amount0HistoricalPriceUsd":{"type":"number"},"amount1HistoricalPriceUsd":{"type":"number"},"historicalValueUsd":{"type":"number"},"historicalPricingSource":{"type":"string"},"gasCostEth":{"type":"number"},"gasCostUsd":{"type":"number"},"sender":{"type":"string"},"logIndex":{"type":"integer"}},"additionalProperties":true},"PositionDetail":{"allOf":[{"$ref":"#/components/schemas/Position"},{"type":"object","properties":{"transactions":{"type":"array","items":{"$ref":"#/components/schemas/Transaction"}},"transactionsDegraded":{"type":"boolean","description":"True means the full list could not be loaded for this response. A degraded answer is not charged."},"transactionsPartial":{"type":"boolean","description":"Only the newest transactions (up to 1,000) are here while the full history loads; ask again shortly."},"transactionsTruncated":{"type":"boolean","description":"The history is longer than 100,000 transactions and the newest are missing."},"stale":{"type":"boolean"},"dataAsOf":{"type":"string","format":"date-time"}},"additionalProperties":true}]},"TransactionsPage":{"type":"object","properties":{"chainId":{"type":"integer"},"protocol":{"type":"string"},"positionId":{"type":"string"},"transactions":{"type":"array","items":{"$ref":"#/components/schemas/Transaction"}},"transactionsTotal":{"type":"integer","description":"How many transactions the position has, not how many are on this page."},"transactionsNextCursor":{"type":["string","null"],"description":"Pass as `before` for the next older page. Absent or null on the last page."},"transactionsDegraded":{"type":"boolean","description":"True means the full list could not be loaded for this response. A degraded answer is not charged."},"transactionsPartial":{"type":"boolean","description":"Only the newest transactions (up to 1,000) are here while the full history loads; ask again shortly. Not charged."},"transactionsTruncated":{"type":"boolean","description":"The history is longer than 100,000 transactions and the newest are missing."},"stale":{"type":"boolean","description":"Complete but read from a replica running more than 45 seconds behind. Billed normally."},"dataAsOf":{"type":"string","format":"date-time","description":"When a `stale` response was current."}},"required":["transactions","transactionsDegraded"],"additionalProperties":true},"Pool":{"type":"object","properties":{"rank":{"type":"integer"},"poolId":{"type":"string"},"chainId":{"type":"integer"},"protocol":{"type":"string"},"token0":{"$ref":"#/components/schemas/Token"},"token1":{"$ref":"#/components/schemas/Token"},"fee":{"type":"integer"},"isDynamicFee":{"type":"boolean"},"tickSpacing":{"type":"integer"},"currentTick":{"type":"integer"},"sqrtPriceX96":{"type":"string"},"liquidity":{"type":"string"},"createdAtTimestamp":{"type":"integer"},"metrics":{"type":"object","properties":{"tvlUsd":{"type":"number"},"volumeUsd24h":{"type":"number"},"volumeUsd7d":{"type":"number"},"feesUsd24h":{"type":"number"},"feesUsd7d":{"type":"number"},"feeApr":{"type":"number","description":"Clamped at ±100,000%. A value exactly on the cap means \"not trustworthy\"."},"txCount":{"type":"integer"},"currentPrice":{"type":"number"}},"additionalProperties":true},"pricing":{"type":"object","properties":{"source":{"type":"string"},"usedFallback":{"type":"boolean"}},"additionalProperties":true},"positionsCount":{"type":["integer","null"],"description":"Open positions. `null` means not known yet, not zero."},"holdersCount":{"type":["integer","null"],"description":"Distinct owners. `null` means not known yet, not zero."},"risk":{"$ref":"#/components/schemas/Risk"},"hooks":{"type":"string"},"customAccounting":{"type":"boolean"}},"required":["poolId","chainId","protocol"],"additionalProperties":true},"PoolList":{"allOf":[{"$ref":"#/components/schemas/Degradation"},{"type":"object","properties":{"pools":{"type":"array","items":{"$ref":"#/components/schemas/Pool"}},"pagination":{"$ref":"#/components/schemas/Pagination"},"countsPending":{"type":"boolean","description":"Some pools carry `null` counts while they are computed."}},"required":["pools","pagination"],"additionalProperties":true}]},"PoolDetail":{"$ref":"#/components/schemas/Pool"},"ChartPoint":{"type":"object","properties":{"t":{"type":"integer","description":"Unix seconds, start of the UTC day."},"value":{"type":"number"}},"additionalProperties":true},"Charts":{"type":"object","properties":{"range":{"type":"string","enum":["30d","60d","90d","180d","all"]},"poolPrice":{"type":"array","items":{"type":"object","properties":{"t":{"type":"integer","description":"Unix seconds, start of the UTC day."},"token0Price":{"type":"number"},"token1Price":{"type":"number"},"open":{"type":"number"},"high":{"type":"number"},"low":{"type":"number"},"close":{"type":"number"},"tick":{"type":["integer","null"],"description":"Pool charts only. The tick after the day's last indexed event; null when the indexer has none."}},"additionalProperties":true}},"poolOverview":{"type":"object","properties":{"tvl":{"type":"array","items":{"$ref":"#/components/schemas/ChartPoint"}},"volume":{"type":"array","items":{"$ref":"#/components/schemas/ChartPoint"}},"fees":{"type":"array","items":{"$ref":"#/components/schemas/ChartPoint"}},"feesTvl":{"type":"array","items":{"$ref":"#/components/schemas/ChartPoint"}},"price0":{"type":"array","items":{"$ref":"#/components/schemas/ChartPoint"}},"price1":{"type":"array","items":{"$ref":"#/components/schemas/ChartPoint"}},"divergence":{"type":"array","items":{"$ref":"#/components/schemas/ChartPoint"}}},"additionalProperties":true},"liquidityDistribution":{"type":"object","properties":{"currentTick":{"type":"integer"},"ticksTotal":{"type":"integer","description":"Present when the bins were windowed (`ticksLimit`, `tickFrom`, `tickTo`): how many there were before windowing."},"tickWindow":{"type":"object","properties":{"from":{"type":"integer"},"to":{"type":"integer"}},"additionalProperties":true},"tickLower":{"type":"integer","description":"Position charts only."},"tickUpper":{"type":"integer","description":"Position charts only."},"ticks":{"type":"array","items":{"type":"object","properties":{"tickIdx":{"type":"integer"},"liquidityGross":{"type":"string"},"liquidityNet":{"type":"string"},"activeLiquidity":{"type":"number"},"price0":{"type":"number"},"price1":{"type":"number"},"amount0":{"type":"number"},"amount1":{"type":"number"}},"additionalProperties":true}}},"additionalProperties":true},"positionSeries":{"description":"Position charts only.","oneOf":[{"type":"object","properties":{"pnl":{"type":"array","items":{"$ref":"#/components/schemas/ChartPoint"}},"assetsValue":{"type":"array","items":{"$ref":"#/components/schemas/ChartPoint"}},"apr":{"type":"array","items":{"$ref":"#/components/schemas/ChartPoint"}},"feeApr":{"type":"array","items":{"$ref":"#/components/schemas/ChartPoint"}},"divLoss":{"type":"array","items":{"$ref":"#/components/schemas/ChartPoint"}}},"additionalProperties":true},{"type":"null"}]},"poolSeries":{"type":"object","properties":{"volume":{"type":"array","items":{"$ref":"#/components/schemas/ChartPoint"}},"tvl":{"type":"array","items":{"$ref":"#/components/schemas/ChartPoint"}},"fees":{"type":"array","items":{"$ref":"#/components/schemas/ChartPoint"}},"feeApr":{"type":"array","items":{"$ref":"#/components/schemas/ChartPoint"}}},"additionalProperties":true,"description":"Pool charts only."},"poolOverviewCurrent":{"oneOf":[{"type":"object","properties":{"tvl":{"type":"number"},"volume":{"type":"number"},"fees":{"type":"number"},"feesTvl":{"type":"number"}},"additionalProperties":true},{"type":"null"}]},"partial":{"type":"boolean","description":"An input could not be loaded; the response is incomplete and is not charged."},"missing":{"type":"array","items":{"type":"string"}}},"required":["range"],"additionalProperties":true},"Chain":{"type":"object","properties":{"chainId":{"type":"integer"},"slug":{"type":"string"},"name":{"type":"string"},"shortName":{"type":"string"},"explorerUrl":{"type":"string"},"nativeToken":{"type":"object","properties":{"symbol":{"type":"string"},"address":{"type":"string"},"decimals":{"type":"integer"}},"additionalProperties":true},"wrappedNativeToken":{"type":"object","properties":{"symbol":{"type":"string"},"address":{"type":"string"},"decimals":{"type":"integer"}},"additionalProperties":true},"protocols":{"type":"array","items":{"type":"string"}}},"required":["chainId","slug","name","protocols"],"additionalProperties":true},"Protocol":{"type":"object","properties":{"key":{"type":"string"},"displayName":{"type":"string"},"version":{"type":["string","null"]},"family":{"type":["string","null"]},"chains":{"type":"array","items":{"type":"integer"}},"enabled":{"type":"boolean"}},"required":["key","chains"],"additionalProperties":true},"PlanList":{"type":"object","properties":{"plans":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"features":{"type":"array","items":{"type":"string"}},"monthlyUnits":{"type":"integer"},"rateLimitPerMin":{"type":"integer"},"maxApiKeys":{"type":"integer"},"allowBrowserKeys":{"type":"boolean"},"selfServe":{"type":"boolean"},"prices":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"interval":{"type":"string","enum":["month","year"]},"unitAmountMinor":{"type":"integer"},"currency":{"type":"string"},"displayNote":{"type":"string"}},"additionalProperties":true}}},"additionalProperties":true}}},"required":["plans"],"additionalProperties":true},"UnitCostList":{"type":"object","properties":{"units":{"type":"array","items":{"type":"object","properties":{"routeKey":{"type":"string"},"cost":{"type":"integer"},"description":{"type":"string"}},"additionalProperties":true}}},"required":["units"],"additionalProperties":true},"Stats":{"type":"object","properties":{"pools":{"type":"integer"},"positions":{"type":"integer"},"activePositions":{"type":"integer"},"tvlUsd":{"type":"number"},"indexedTo":{"type":["string","null"]},"byChain":{"type":"array","description":"The same figures per chain and protocol.","items":{"type":"object","properties":{"chainId":{"type":"integer"},"protocol":{"type":"string"},"pools":{"type":"integer"},"positions":{"type":"integer"},"activePositions":{"type":"integer"},"tvlUsd":{"type":"number"},"indexedUpToTimestamp":{"type":["integer","null"],"description":"Indexer head for this shard, epoch seconds."}},"additionalProperties":true}}},"required":["pools","positions"],"additionalProperties":true}}},"servers":[{"url":"https://api.tickwise.xyz","description":"Production"}]}