PoolSide Documentation
PoolSide is a personal Uniswap V3 liquidity position dashboard that connects to your Ethereum wallet, reads your LP positions on-chain, and tracks your fee earnings over time using daily snapshots stored locally on the server.
How PoolSide Works
ArchitecturePoolSide runs a local Python server that queries the Uniswap V3 subgraph and the Ethereum blockchain via public APIs. When you hit Refresh, the server fetches your live position data, calculates USD values using CoinGecko prices, converts them to your local currency via live FX rates, and returns everything to the browser.
PoolSide is snapshot-based. It does not stream live data continuously. Each Refresh call fetches a new point-in-time snapshot. Historical data is built up by running Refresh periodically — once or several times per day. The more snapshots you have, the more accurate the history and averages will be.
Data Source
Uniswap V3 Subgraph
Position details, tick ranges, and liquidity amounts are fetched from The Graph's Uniswap V3 subgraph — the same data source used by app.uniswap.org.
Pricing
CoinGecko + On-Chain
Token prices come from the CoinGecko public API. Unclaimed fees are calculated by simulating the Uniswap V3 fee math directly from the blockchain.
Storage
Local CSV Files
Each Refresh appends a row to a CSV file per pool/position. These files are the backbone of the History page and all historical calculations.
FX Rate
Live Exchange Rates
USD↔local currency conversion uses live rates from multiple providers (open.er-api.com, frankfurter.app). If one fails, the next is tried automatically.
Dashboard
OverviewThe Dashboard is your at-a-glance command centre. It shows a snapshot of your portfolio right now, aggregated across all open positions.
| Card | What it shows |
|---|---|
| Today's Fees Earned | Fees accrued since midnight (local time). Calculated by comparing the latest unclaimed fee snapshot against the first snapshot of the day, accounting for any collect transactions in between. The 🔄 button forces a fresh on-chain recalculation for just this value. |
| Total Unclaimed | The total unclaimed fees sitting in all your open LP positions right now — not yet collected to your wallet. This is the live value from the Uniswap contracts. |
| Total Position Value | The combined market value of the tokens locked in all your active LP positions at current prices. Click the 👁 button to blur/hide this number for privacy. The delta badge shows how much this has changed since the last Refresh. |
| Open Positions | Count of active LP NFTs with non-zero liquidity. Closed or burned positions are not counted. |
Pool Ranking Row — Below the top cards, each of your pools gets a ranked card showing today's fees earned in that pool and the average APR since you opened it. The 🏆 card is your best-performing pool for the day.
| Stat Card | What it shows |
|---|---|
| 24hr Projection | An extrapolation of today's current fee rate to a full 24 hours. Based on hours elapsed today ÷ fees earned so far × 24. Less than 30 minutes of data shows "—" since early projections are unreliable. |
| Collected Today (on-chain) | The total value of fee-collect transactions that hit the blockchain today, fetched live from Etherscan. This does NOT include unclaimed fees — only fees you have explicitly collected to your wallet. |
| Yesterday's Fees Earned | The total fees earned yesterday, calculated from the History snapshots using the same delta formula as Today's Fees. Useful as a benchmark for today's performance. |
| Total Earnings This Month | Sum of all daily fee earnings in the current calendar month, read from the History snapshot data. The 👁 button hides this for privacy. |
The delta badges (e.g.,
+42 kr) next to values like Total Unclaimed show the change between the current Refresh and the previous one. They help you see at a glance whether things are moving up or down in real time.Open Positions
LP ManagementEvery active Uniswap V3 LP position you hold is shown here as an individual card. You can search by pair name, token ID, or pool address, and filter by range status.
Each position card shows:
| Field | Description |
|---|---|
| Pair + Version | The trading pair (e.g. WETH/SOL) and the fee tier (e.g. 0.30%). The token ID is shown as #1199114. |
| In Range / Out of Range | Green = the current price is within your tick range — you're earning fees right now. Red = price is outside your range — you're not earning, and you may want to rebalance. |
| Range Bar | A visual slider showing where the current price tick sits relative to your Min and Max ticks. The percentages show the current token ratio in the position. |
| Position Value | Total USD market value of the two tokens currently locked in this LP position at spot prices. |
| Unclaimed Fees | Fees earned but not yet collected — still inside the position. Shown in both USD and local currency. |
| Token Breakdown (Unclaimed) | How many of each token make up the unclaimed fees, with individual USD values. |
| Token Breakdown (Position) | How many of each token are currently in the LP position, with individual USD values. |
| Pool Address | A link to the pool contract on Etherscan. |
| My APY | Your personal APY for this pool, calculated from the historical snapshot data. This is your actual earned-fees-to-position-value ratio annualised. |
| Pool APY | The pool's overall APY based on the last 7 days of on-chain fee and TVL data from the Uniswap subgraph. |
Clicking anywhere on a position card opens the Pool Info detail page for that specific position, where you can see the full historical chart, daily APR, and manually override values.
The ⋯ menu (three dots) on each position card gives you quick actions:
Action
Collect Fees
Initiates a fee collect transaction via your connected wallet (MetaMask / Rabby). This moves unclaimed fees from the LP position to your wallet.
Action
View on Uniswap
Opens the official Uniswap app directly on this position's detail page, where you can also add/remove liquidity.
Action
Remove Liquidity
Opens the Uniswap app at the withdraw page for this position. Full or partial liquidity removal is handled by Uniswap's UI.
History
Snapshot LogThe History page shows a daily log of your portfolio across time, broken down month by month. Each row represents one calendar day, built from the CSV snapshot files that the server writes each time you Refresh.
Snapshot-based, not continuous. If you did not run Refresh on a given day, that day will have no data (shown as a gap). Fees are calculated as the difference between consecutive unclaimed-fee snapshots, not by watching every block. The more consistently you refresh, the more complete your history.
The top summary bar shows stats for the selected month or year: total fees, average fees per day, projected month total, average APR across all positions, latest position size, and position delta.
Column Reference
| Column | Type | Description |
|---|---|---|
| Day | read-only | The calendar date of the snapshot. Rows highlighted in a lighter colour indicate today. |
| Fees Earned | computed | Calculated automatically: today_unclaimed + collected_today − yesterday_unclaimed. This is the net new fees generated on this day. Negative values can occur on days with large price swings (impermanent loss effect on the unclaimed calculation) or after a large collect. |
| Unclaimed Fees | ✏ editable | The total unclaimed fees in all positions at the time of the snapshot. You can click the cell and override this value if the automatic reading was wrong (e.g. fetched during a price spike or with stale data). Overrides are saved to the CSV file immediately. |
| Position Size | ✏ editable | The combined market value of all tokens in all LP positions at snapshot time. Click to override if the value was clearly wrong. Position size is used to calculate APR. |
| Position Delta | computed | The change in position value compared to the previous day, in both absolute and percentage terms. Green = portfolio grew, red = it shrank. This reflects both price movement (impermanent loss/gain) and any deposits or withdrawals you made. |
| APR (%) | computed | The annualised fee return for this specific day: (fees_earned / position_size) × 365 × 100. This is your actual daily fee APR, not a projection. |
| Collected | ✏ editable | Fees you explicitly collected to your wallet on this day, in local currency. This is auto-populated from on-chain data when available, but you can also enter it manually. The value is used to ensure fees-earned calculations remain correct on collect days. |
| Note | ✏ editable | A free-text field for your own notes — e.g. "added liquidity", "rebalanced WETH/RPL", or anything you want to remember about that day. |
| ↺ (Reset) | action | The red circular arrow button reverts any manual overrides on that row, restoring the values from the original snapshot data. |
When to override values: If a snapshot was taken during a period of extreme market volatility, or if the subgraph returned stale data, the Unclaimed Fees and Position Size values can be unreliable. Overriding with a value you know was correct (from Uniswap app or Etherscan at that time) gives you a cleaner historical record and more accurate APR calculations.
The Year view aggregates the entire year, one row per day. The Jan, Feb… month tabs filter to that specific month and show the same data at the same granularity.
Transactions
On-Chain ActivityThe Transactions view shows your wallet's recent on-chain activity on Ethereum Mainnet, fetched live from Etherscan. It focuses on LP-related transactions but shows all activity for the selected date.
| Column | Description |
|---|---|
| Transaction Hash | The unique hash of the transaction on Ethereum. Clicking it opens Etherscan in a new tab. |
| Method | The contract method called. collect = fee collection from an LP position. multicall = a bundle of multiple operations in one transaction. |
| Block | The Ethereum block number where the transaction was included. Clicking it opens that block on Etherscan. |
| Age | Time elapsed since the transaction was confirmed (e.g. "6h 26m ago"). |
| From / To | The sender and recipient addresses. Your wallet is highlighted in orange. |
| Value | The raw ETH value transferred in the transaction (most LP operations send 0 ETH). |
| Txn Fee | The gas fee paid for this transaction, in ETH. |
| Details ▶ | Click to expand the row and see the ERC-20 token transfers inside the transaction, with amounts and USD values. This is especially useful for collect transactions to see exactly which tokens and amounts were received. |
The date selector at the top lets you browse transactions from past dates. The Today (live) option fetches the latest data directly from Etherscan. The total collected value shown in green is automatically calculated from any
collect method calls on that day.Pool Info Page
Per-Pool DetailWhen you click on a position card in Open Positions, it opens a dedicated detail page for that specific pool/position. This page is similar to the History page but scoped to a single pool.
Historical Chart
Daily Fees + Position
A chart showing daily fees earned and position value over time for this specific pool, so you can spot trends and out-of-range periods.
Snapshot Table
Same edit features
The same editable table as History — override Unclaimed, Position Size, Collected, and Note. All edits are saved immediately to the per-pool CSV file.
Navigation
← Dashboard
The back button returns to the main dashboard. The URL includes the pool address and token ID so you can bookmark a specific position.
If you hold multiple token IDs in the same pool (e.g. two WETH/RPL positions with different tick ranges), the Pool Info page aggregates all of them. Each position gets its own column in the snapshot table, and fees are summed for the pool-level view.
Settings
Preferences| Setting | Description |
|---|---|
| Theme | Changes the colour accent of the entire dashboard. Options: Default (purple), Pink, Light, Red, Orange, Green, Yellow. The chosen theme is persisted in localStorage and applies to all pages including History and Pool Info. |
| Primary Currency | Replaces all USD dollar ($) values throughout the app. Set to USD by default. Changing to EUR, GBP, etc. converts all primary values using live exchange rates fetched from open.er-api.com. The FX rate is displayed in the header. |
| Secondary Currency | Replaces all NOK (kr) values throughout the app. Internally all calculations use NOK as the base, and the secondary currency is applied as a display conversion. Set to NOK by default. |
| Wallet / Connect | Connect a MetaMask or Rabby browser extension wallet to enable fee collection directly from the dashboard. Alternatively, append ?wallet=0x… to the URL to watch any read-only address without connecting an extension. |
Key Concepts
ReferenceUniswap V3
Concentrated Liquidity
Unlike V2, V3 lets you set a specific price range (ticks) where your liquidity is active. You only earn fees when the price is inside your range — but when it is, your capital efficiency is much higher.
Ticks
Price Range Boundaries
Tick numbers encode price boundaries on a log scale. The Min and Max ticks shown on each position card define the exact price range where your liquidity is deployed.
APR vs APY
Annualised Returns
PoolSide shows APR (simple annual rate, no compounding). Your actual return depends heavily on how often you collect and reinvest fees, and whether the price stays in range.
Impermanent Loss
Position Delta Risk
When token prices move, the ratio of your two tokens shifts to maintain the constant-product formula. Negative Position Delta days reflect this — your position value declined more than fees earned.
Fee Tiers
0.01% / 0.05% / 0.30% / 1%
Uniswap V3 pools come in four fee tiers. Higher-fee pools pay more per trade but tend to have less volume. The fee tier is shown on each position as a badge (e.g.
0.30%).NFT Positions
ERC-721 Token IDs
Each Uniswap V3 LP position is minted as a unique NFT. The token ID (e.g.
#1199114) is how PoolSide identifies each position. Closed positions (burned NFTs) are not shown.