> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dune.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Spot Liquidity Feed

> Real-time onchain pool liquidity over WebSocket: per-block LP adds, removes and limit orders, and a ±2% order book for each touched pool on 12 EVM chains and Solana.

The Spot Liquidity feed streams pre-trade liquidity for onchain pools. For each block, it sends every liquidity event (add, remove, limit order) and a bounded order book for each pool that the block changed. The feed is real time only. It has no history table.

For connection, resume and latency, see the [Market Data Feeds overview](https://docs.dune.com/market-data-feeds/overview.md).

| | |
| - | - |
| Chains | Arbitrum, Arc, Avalanche C-Chain, Base, BNB Chain, Ethereum, HyperEVM, Monad, Optimism, Polygon, Robinhood Chain, X Layer, Solana |
| EVM endpoint | `wss://api.dune.com/api/feed/dex/liquidity/evm/{chain_id}` |
| Solana endpoint | `wss://api.dune.com/api/feed/dex/liquidity/svm/1` |
| Format | `dex-liquidity.json.v1` |

## Venues

The feed covers concentrated-liquidity and bin pools. This is the complete list of `venue` labels:

| Chain type | `venue` |
| - | - |
| EVM | `uniswap_v3`, `uniswap_v4`, `pancakeswap_v3`, `pancakeswap_infinity_cl`, `pancakeswap_infinity_bin`, `aerodrome_slipstream`, `ramses_v3`, `solidly_v3`, `algebra_v1`, `algebra_v1_9`, `algebra_integral`, `lfj_lb_v2_0`, `lfj_lb_v2_1` (LFJ Liquidity Book v2.1 and v2.2) |
| Solana | `orca_whirlpool`, `raydium_clmm`, `pancakeswap_clmm`, `byreal_clmm`, `meteora_dlmm` |

Constant-product pools, such as Uniswap V2, are not in this feed.

## How the book is built

An AMM pool has no resting orders, but its liquidity sits at known prices. Dune reads each pool's state at the end of the block and writes it as a price ladder.

* Levels are 10 basis points (bps) wide and go out to ±2% of the mid price. There are at most 20 levels on each side, nearest the mid first. Empty levels are not sent.
* Bucket edges are fixed post-fee prices: level `k` (1 to 20) has `price = mid_price × (1 − 0.001 × k)` on the bid side and `mid_price × (1 + 0.001 × k)` on the ask side.
* The fee decides which pool liquidity fills each bucket. Selling base into the pool at pool price `p` fills at `p × (1 − fee)`, and buying base fills at `p ÷ (1 − fee)`. A level's `size_base` is the base amount that fills at post-fee prices inside its bucket.
* `best_bid` and `best_ask` are the post-fee price of the first unit on each side, with the size of the first level.
* Each pool has its own book. Books are not combined across pools or venues. One instrument code can cover several pools (fee tiers); use `pool` or `pool_id` to tell them apart.
* EVM state is read at the block hash. Solana state is read at the slot. A correction rebuilds the same book.
* A book is sent only when a block changes the pool. No new book does not mean the pool is empty. Keep the last book of each pool.

## Message envelope

| Field | Type | Description |
| - | - | - |
| `schema_version` | string | `dex-liquidity.json.v1` |
| `sequence_number` | string | Resume cursor |
| `chain` | object | `{id, type}`, `type` is `evm` or `svm` |
| `block_number` | integer | EVM block number or Solana slot |
| `block_hash` | string | Absent only on a Solana retraction |
| `block_timestamp` | string | RFC 3339, microseconds, UTC |
| `op` | string | `insert` or `update` (lowercase in this feed) |
| `incarnation_version` | integer | Increases with each correction |
| `liquidity_events` | array | See [Liquidity event](#liquidity-event) |
| `books` | array | One book for each pool the block touched. See [Book](#book). |
| `block_notification_time` | string | When the block was first observed, if known |

Optional fields are omitted when absent, never `null`. Raw token amounts are decimal strings in the token's smallest unit. Prices, sizes, fees and USD values are JSON numbers. Prices are quote per base, decimal-adjusted.

## Liquidity event

| Field | Description |
| - | - |
| `event_id` | Unique id. The key for corrections. |
| `tx` | `{hash, from, to, index, source_kind, source_index}`. `source_kind` is `log` on EVM and `instruction` on Solana. |
| `pool` or `pool_id` | Exactly one is present. `pool_id` is for keyed venues (Uniswap V4, PancakeSwap Infinity). |
| `venue` | One of the labels in [Venues](#venues) |
| `instrument_code` | Instrument code, when resolved |
| `base`, `quote` | Token addresses or mints |
| `action` | `add` or `remove` |
| `mechanism` | `range` (tick range), `bins` (discrete bins) or `limit_order` |
| `side` | `bid`, `ask` or `both`. For a limit order, selling base is `ask` and selling quote is `bid`. |
| `price_lower`, `price_upper` | Range bounds before fees |
| `native_lower`, `native_upper` | Ticks or bin ids, inclusive |
| `base_amount_raw`, `quote_amount_raw` | Token amounts added or removed |
| `liquidity_delta_raw` | For `range` only: the change in liquidity |
| `provider` | Owner of the liquidity, when known |
| `position_id` | The venue's position id, when it has one |
| `value` | `{usd, price_source, stale_usd_price}`. Absent when the event is `unpriced`. |
| `condition_flags` | `unpriced`, `stale_usd_price` |

## Book

| Field | Description |
| - | - |
| `pool` or `pool_id`, `venue`, `instrument_code`, `base`, `quote` | As on events |
| `mid_price` | End-of-block mid, quote per base, before fees |
| `bid_fee_rate`, `ask_fee_rate` | Fee as a fraction of input |
| `bids`, `asks` | `[{price, size_base}]`, as described in [How the book is built](#how-the-book-is-built) |
| `best_bid`, `best_ask` | `{price, size_base}`. Absent when that side is empty. |
| `depth_usd_bid`, `depth_usd_ask` | USD depth of each side. Absent when the book is `unpriced`. |
| `flags` | `unpriced`, `stale_usd_price`, `fee_approximate` |

`fee_approximate` marks pools whose fee can change with each swap. The book uses the fee stored at the block. This applies to Uniswap V4 and PancakeSwap Infinity dynamic fees, Algebra adaptive and plugin fees, LFJ Liquidity Book variable fees, Meteora DLMM, and Orca, Raydium and Byreal dynamic-fee pools.

## Corrections

* Events are keyed by `event_id`. Books are keyed by `(pool or pool_id, block_number)`.
* Every block sends one message, even when both lists are empty.
* An `update` replaces all events and books you hold for that `(chain, block_number)`. Delete the held items that are not in the message.
* A pool's current book is the held book with the highest `block_number`. Keep older books for the reorg window, so that a correction can fall back to an earlier book.
* **Solana retraction:** when a slot's block is gone, the message is an empty `update` with no `block_hash`.

## Example

EVM, a Uniswap V4 add with the pool's book:

```json theme={null}
{
  "schema_version": "dex-liquidity.json.v1",
  "sequence_number": "99",
  "chain": { "id": 1, "type": "evm" },
  "block_number": 26299910,
  "block_hash": "0xabababababababababababababababababababababababababababababababab",
  "block_timestamp": "2026-10-29T15:29:31.000000Z",
  "op": "insert",
  "incarnation_version": 0,
  "liquidity_events": [
    {
      "tx": {
        "hash": "0x4d4d4d4d4d4d4d4d4d4d4d4d4d4d4d4d4d4d4d4d4d4d4d4d4d4d4d4d4d4d4d4d",
        "from": "0x1111111111111111111111111111111111111111",
        "to": "0x2222222222222222222222222222222222222222",
        "index": 7,
        "source_kind": "log",
        "source_index": 1020
      },
      "event_id": "1-26299910-7-log-1020-0",
      "pool_id": "0xcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcd",
      "venue": "uniswap_v4",
      "instrument_code": "WETH-USDC.UNIV4.ETH",
      "base": "0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2",
      "quote": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
      "action": "add",
      "mechanism": "range",
      "side": "both",
      "price_lower": 2300.5,
      "price_upper": 2400.25,
      "native_lower": 197320,
      "native_upper": 199830,
      "base_amount_raw": "1729999999567175515",
      "quote_amount_raw": "3546222310",
      "liquidity_delta_raw": "1291216586791917",
      "provider": "0xc3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3c3",
      "position_id": "1043512",
      "value": { "usd": 7610.5, "price_source": "chainlink", "stale_usd_price": false },
      "condition_flags": []
    }
  ],
  "books": [
    {
      "pool_id": "0xcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcd",
      "venue": "uniswap_v4",
      "instrument_code": "WETH-USDC.UNIV4.ETH",
      "base": "0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2",
      "quote": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
      "mid_price": 2348.77984084116,
      "bid_fee_rate": 0.0005,
      "ask_fee_rate": 0.0005,
      "bids": [
        { "price": 2346.4310610003, "size_base": 13.186741380247083 },
        { "price": 2344.0822811595, "size_base": 26.428971998798044 }
      ],
      "asks": [{ "price": 2351.128620682, "size_base": 13.203971568 }],
      "best_bid": { "price": 2347.605451, "size_base": 13.186741380247083 },
      "best_ask": { "price": 2349.954818, "size_base": 13.203971568 },
      "depth_usd_bid": 92838.0,
      "depth_usd_ask": 31043.0,
      "flags": ["fee_approximate"]
    }
  ],
  "block_notification_time": "2026-10-29T15:29:32.000000Z"
}
```

Hashes and addresses with repeated characters in this example are placeholders.

## Limits

* The book shows depth within ±2% of the mid only. It is not a quote for a larger trade.
* A book does not include gas, MEV or routing costs.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.