Uniswap V3 Pool Lens 🔍

A small, opinionated CLI for poking at Uniswap V3 pools without firing up a subgraph or a notebook.

I use this to answer questions like "what does the liquidity look like around the current tick?", "what's the IL if I LP a [3500, 4500] range and ETH dips 30%?", and "what's the rough fee APR over the last 24h?". It's not a replacement for proper analytics — it's a sanity check that runs in your terminal in under a second.

Install

git clone 
cd univ3-pool-lens
npm install
npm run build
npm link    # optional, makes `lens` available globally

Copy .env.example to .env and set at least one RPC URL.

Quick start

# Pool summary — current tick, price, liquidity
lens pool 0x88e6a0c2ddd26feeb64f039a2c41296fcb3f5640
# WETH / USDC    fee 0.05%
# address       0x88e6…5640
# tick          198543
# price         3742.18 USDC per WETH
# liquidity     12384720394823049823

# IL projection for a [3500, 4500] range
lens range 0x88e6...5640 --lower 196900 --upper 199810

# 24h fee APR estimate
lens fees 0x88e6...5640

# Diff pool state across a window
lens snapshot 0x88e6...5640 --from 21000000 --to 21007200

# Other chains
lens pool 0x... --chain arbitrum
lens pool 0x... --chain base

# JSON output for piping into jq, scripts, dashboards
lens pool 0x... --json | jq '.price'

Architecture

                ┌──────────────────────────────────┐
                │             CLI (cli.ts)         │
                └────────────────┬─────────────────┘
                                 │
         ┌───────────────────────┼───────────────────────┐
         ▼                       ▼                       ▼
   commands/pool.ts        commands/range.ts       commands/fees.ts
         │                       │                       │
         └───────────┬───────────┴───────────┬───────────┘
                     ▼                       ▼
                lens/* (pool, ticks, liquidity, il, fees)
                     │
                     ▼
              chain/provider + util/multicall + util/cache
                     │
                     ▼
                  ethers.js

The lens/* modules know nothing about the CLI or the chain plumbing — they take a provider and an address and return data. Commands handle formatting. This makes the library easy to import into other projects (notebooks, bots, dashboards) without dragging the CLI along.

Subcommands

| Command | What it does | |---------|--------------| | lens pool | Pool immutables, current tick & price, in-range liquidity | | lens range | IL projection + ASCII curve for a [tickLower, tickUpper] position | | lens fees | Fee APR estimate from feeGrowthGlobal deltas over a window | | lens snapshot | Diff between pool state at two block heights |

Run any command with --json for machine-readable output.

Configuration

| Env var | Purpose | |---------|---------| | ETH_RPC_URL | Mainnet JSON-RPC endpoint |