> For the complete documentation index, see [llms.txt](https://docs.bitflow.finance/bitflow-documentation/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.bitflow.finance/bitflow-documentation/developers/current-balance-and-liquidity-valuation.md).

# Current Balance and /liquidity valuation

How App v2 Current Balance (\`/liquidity\`) values DLMM positions after engine absolute bin-share tracking (checkpoint v6 / engine #399).

The Bitflow app **Current Balance** card reads:

```
GET /api/app/v2/users/{address}/liquidity/{pool_id}
```

Retail and market-maker clients can call the same route for a USD and token-amount summary of a wallet's DLMM position.

## Semantics (engine #399+)

For DLMM pools, `/liquidity` **re-values on read** from the user's held bins using:

* Per-bin reserves
* The user's integer shares in that bin
* The bin's **absolute on-chain share supply** (`BinSharesUpdate::Set` on `BinUpdate`, including burn-address / unindexed supply)

That matches Clarity `dlmm_position_amounts` math and the Quote / App **`current-bins`** path. Do **not** assume ownership is `user_shares / sum(indexed holders)` — that understates or skews balances whenever burn or unindexed LPs hold supply.

Wing / out-of-range positions keep per-bin X/Y splits (including `(0, Y)` wings). Pool-wide pro-rata is only a last resort when the user has **no** held-bin rows.

`GET …/positions/{pool_id}/bins` (chart overlay) uses the same absolute bin supply for per-bin USD. Still use **`current-bins`** to size withdraw / add / move transactions (`clean`, `complete`, `tipLag == 0`).

## Pool keys

Prefer the **contract principal** as `pool_id` (same as Quote v2).

`/liquidity` also resolves **short aliases** (for example `dlmm_1`) and case-insensitive pool ids via refdata. Other App v2 routes may still return not-found for an alias — prefer the principal everywhere.

## Derived checkpoint (v6)

Absolute `bin_shares` live in the aggregator's derived checkpoint. Schema **v6** adds that map mid-snap. Integrators do not set `CHECKPOINT_VERSION`; after Bitflow promotes an image that defaults to v6 and rebuilds the derived blob, `/liquidity` and overlay USD align with chain / `current-bins`.

{% hint style="info" %}
Ops cutover (canary Job rebuild → soak → stable promote with matching `CHECKPOINT_VERSION`) is internal. Until a host has finished that cutover, Current Balance on that host can still disagree with chain.
{% endhint %}

## Related

* [HODLMM API Documentation (v2)](/bitflow-documentation/developers/hodlmm-api-documentation-v2.md) — endpoint reference, `current-bins`, sizing rules
* Engine PR: [bitflow-engine#399](https://github.com/BitflowFinance/bitflow-engine/pull/399)