# Liquidity and positions

> What the liquidity family indexes — events, pools, positions, the health score, range planning — and how the numbers are made.

Source: https://getchord.xyz/docs/concepts/liquidity/

The `/v1/lp/*` family is Chord's LP agent: the data a liquidity provider needs before, during and after a position, on Arc, Robinhood Chain and Monad.

## What is indexed

- **Events** — every `Mint` / `Burn` / `Collect` on V2 pairs, V3 pools and V4 pools (`ModifyLiquidity`), with the sender resolved through position managers to the wallet, and the dollars that entered or left the pool where the pool has an anchor side (USDC, EURC on Arc; WETH, USDG on 4663). V4 amounts are computed from `liquidityDelta` and the pool's price at that block, because the log does not carry them.
- **Pools** — hourly volume, trades and price per pool from the swap tape, TVL from the chain (or a market-data fallback, named in `tvlSrc`), and the pool's fee tier. Fees are `volume × fee tier`; `feeTvlPct` is fees ÷ TVL for the window; `aprPct` is the 24-hour figure × 365, a full-range yardstick and not a promise.
- **Positions** — every position NFT from the Uniswap V3 position manager and the V4 PositionManager on each chain: dollars in and out, fees collected, and for open positions the live value, uncollected fees (V3), whether it is in range, the distance to the nearest edge, and PnL on the liquidity leg.
- **Providers** — the leaderboard: win rate on closed positions, fees, expected value per position, average age, invested and monthly profit, and the last seven days.

## The health score

Every pool has a 0–100 score from six parts: traders (real wallets, not printing), TVL, yield sanity (fee/TVL a pool can honestly sustain), LP flow (net adds versus removes), age, and penalties. `reasons` names what cost points — "the launcher holds 100 % of the liquidity added", "fee/TVL over 10 %/day: volume is being printed". `/lp/token/{address}/pools` ranks a token's pools by it.

## Suspect pools

A pool is `suspect` when its numbers cannot be honest: 24-hour turnover above 300× TVL, above 50× with fewer than 25 traders, dust TVL under six-figure volume, fewer than five wallets printing over $10k, or a hooked V4 pool with dust TVL (a launchpad curve where the hook holds the real reserves). Suspect pools are hidden from `/lp/pools` unless `flagged=1`, and never chosen as "best yield". The rule was measured against a launch fleet printing $100k a day through $2.5k pools with three wallets, and against a real market-maker pool turning 48× a day with thousands of traders — turnover alone cannot split them; traders can.

## Launch facts

On Arc most tokens are born through a launcher. `/lp/pools/{pool}` and `/lp/token/{address}/pools` say who launched the pool, how much of the liquidity ever added the launcher supplied (`launcherSharePct`), and when it last pulled and how much. A pool whose launcher holds all the liquidity and has started removing it is a different risk from one with fifty providers.

## Planning a range

`/lp/plan` derives three ranges from the token's own hourly and daily volatility (tight, balanced, wide), reports the share of the last seven days the price stayed inside each, and backtests each on Chord's candles against holding: fees at the pool's real tier and the position's share of liquidity, impermanent loss, how many times the price left the range, and the net versus hold. `/lp/simulate` runs one explicit range. Under two days of candles the answer says `young: true` — the bands are a launch's noise, not a distribution.

## Minting

`/lp/pools/{pool}` returns `mint`: the position manager to call, the pool key (tokens, fee, tick spacing, hooks), Permit2, and whether `currency0` is native. It is what the Chord app uses to add liquidity from the browser (V3 through the NPM, V4 through PositionManager + Permit2). Chord does not build the mint calldata for you; the pool key is the input to the Uniswap SDK.

## Alerts

`POST /lp/watch` turns on alerts for a wallet's positions — out of range, fees past a bar, a watched pool draining — in the app and, through a one-hour Telegram deep link, in a chat. `GET /lp/watch` is the inbox.