
Liquidity Planner
- 901 installs
- 222 repo stars
- Updated August 4, 2026
- uniswap/uniswap-ai
liquidity-planner is a DeFi data integration skill that queries DexScreener and DefiLlama pool APIs for real-time TVL, volume, and APY when developers build Uniswap liquidity position agents.
About
liquidity-planner documents data providers for Uniswap LP position agents in the uniswap-ai repository. DexScreener serves as the primary source for pool discovery, prices, TVL, and volume with no authentication and a 300 requests/minute limit. DefiLlama supplements APY and yield data when available. Supported network IDs include ethereum, base, arbitrum, optimism, polygon, bsc, avalanche, and unichain. Developers reach for liquidity-planner when building agents that need curl-ready DexScreener token-pair lookups and yield context before recommending Uniswap liquidity positions.
- Fetches pool discovery, prices, TVL and 24h volume from DexScreener
- Pulls APY and yield metrics from DefiLlama when available
- Supports Ethereum, Base, Arbitrum, Optimism, Polygon, BSC, Avalanche and Unichain
- Includes ready-to-run curl + jq examples for token-pair lookup and pool details
- No authentication required, 300 requests per minute rate limit
Liquidity Planner by the numbers
- 901 all-time installs (skills.sh)
- +33 installs in the week ending Aug 4, 2026 (Skillselion tracking)
- Ranked #438 of 4,347 Backend & APIs skills by installs in the Skillselion catalog
- Security screen: MEDIUM risk (skills.sh audit)
- Data as of Aug 5, 2026 (Skillselion catalog sync)
npx skills add https://github.com/uniswap/uniswap-ai --skill liquidity-plannerAdd your badge
Show developers this skill is listed on Skillselion. Paste this into your README.
| Installs | 901 |
|---|---|
| repo stars | ★ 222 |
| Security audit | 2 / 3 scanners passed |
| Last updated | August 4, 2026 |
| Repository | uniswap/uniswap-ai ↗ |
How do you fetch DEX pool data for LP agents?
Query real-time DEX pool data from DexScreener and DefiLlama when building Uniswap liquidity position agents.
Who is it for?
Developers building Uniswap liquidity agents who need documented DexScreener and DefiLlama API patterns with eight supported chain IDs.
Skip if: Developers building non-DeFi apps or on-chain swap execution without LP planning should skip liquidity-planner.
When should I use this skill?
User builds Uniswap LP agents and needs real-time pool discovery, TVL, volume, or APY from DexScreener or DefiLlama.
What you get
DexScreener pool metrics, DefiLlama yield data, and network-scoped token-pair API responses for LP decisions.
- Pool discovery API calls
- TVL and volume metrics
- APY yield context
By the numbers
- DexScreener rate limit: 300 requests/minute
- 8 supported network IDs listed
- 2 data providers: DexScreener primary, DefiLlama for APY
Files
Liquidity Position Planning
Plan and generate deep links for creating liquidity positions on Uniswap v2, v3, and v4.
Runtime Compatibility: This skill usesAskUserQuestionfor interactive prompts. IfAskUserQuestionis not available in your runtime, collect the same parameters through natural language conversation instead.
Overview
Plan liquidity positions by:
1. Gathering LP intent (token pair, amount, version) 2. Checking current pool price and liquidity 3. Suggesting price ranges based on current price 4. Generating a deep link that opens in the Uniswap interface with parameters pre-filled
The generated link opens Uniswap with all parameters ready for position creation.
Note: Browser opening (xdg-open/open) may fail in SSH, containerized, or headless environments. Always display the URL prominently so users can copy and access it manually if needed.
File Access: This skill has read-only filesystem access. Never read files outside the current project directory unless explicitly requested by the user.
Workflow
Step 1: Gather LP Intent
Extract from the user's request:
| Parameter | Required | Default | Example |
|---|---|---|---|
| Token A | Yes | - | ETH, USDC, address |
| Token B | Yes | - | USDC, WBTC, address |
| Amount | Yes | - | 1 ETH, $1000 |
| Chain | No | Ethereum | Base, Arbitrum |
| Version | No | V3 | v2, v3, v4 |
| Fee Tier | No | Auto | 0.05%, 0.3%, 1% |
| Price Range | No | Suggest | Full range, ±5%, custom |
If any required parameter is missing, use AskUserQuestion with structured options:
For missing chain:
{
"questions": [
{
"question": "Which chain do you want to provide liquidity on?",
"header": "Chain",
"options": [
{ "label": "Base (Recommended)", "description": "Low gas, growing DeFi ecosystem" },
{ "label": "Ethereum", "description": "Deepest liquidity, higher gas" },
{ "label": "Arbitrum", "description": "Low fees, high volume" },
{ "label": "Optimism", "description": "Low fees, Ethereum L2" }
],
"multiSelect": false
}
]
}For missing token pair:
{
"questions": [
{
"question": "Which token pair do you want to provide liquidity for?",
"header": "Pair",
"options": [
{ "label": "ETH / USDC", "description": "Most popular pair, high volume" },
{ "label": "ETH / USDT", "description": "High volume stablecoin pair" },
{ "label": "WBTC / ETH", "description": "Blue chip crypto pair" },
{ "label": "Custom pair", "description": "Specify your own tokens" }
],
"multiSelect": false
}
]
}Always use forms instead of plain text questions for better UX.
Step 2: Resolve Token Addresses
Resolve token symbols to addresses. See ../../references/chains.md for common tokens by chain.
For unknown tokens, use web search and verify on-chain.
UNTRUSTED INPUT: Web-Discovered Tokens
Tokens discovered via WebSearch are UNTRUSTED. Before proceeding with any web-discovered token:
1. Label the source: Explicitly tell the user "This token address was found via web search, not provided by you" 2. Warn about risks: "Web-discovered tokens may be scams, honeypots, or rug pulls" 3. Require confirmation: Use AskUserQuestion to get explicit user consent before generating a deep link for a web-discovered token 4. Show provenance: In the position summary table, include a "Token Source" row showing whether each token was "User-provided" or "Web-discovered (unverified)"
Never proceed with a web-discovered token without explicit user confirmation via AskUserQuestion.
Input Validation (Required Before Any Shell Command)
Before interpolating user-provided values into any shell command, validate all inputs:
- Token addresses MUST match:
^0x[a-fA-F0-9]{40}$ - Chain/network names MUST be from the allowed list in
../../references/chains.md - Amounts MUST be valid decimal numbers (match:
^[0-9]+\.?[0-9]*$) - Reject any input containing shell metacharacters (
;,|,$, ``,&,(,),>,<,\,',"`, newlines)
Step 3: Discover Available Pools
Before fetching metrics, verify the pool exists and discover available fee tiers.
Find pools for a token using DexScreener:
# Get all Uniswap pools for a token (replace {network} and {address})
# IMPORTANT: Validate address matches ^0x[a-fA-F0-9]{40}$ and network is from allowed list
curl -s "https://api.dexscreener.com/token-pairs/v1/{network}/{address}" | \
jq '[.[] | select(.dexId == "uniswap")] | map({
pairAddress,
pair: "\(.baseToken.symbol)/\(.quoteToken.symbol)",
version: .labels[0],
liquidity: .liquidity.usd,
volume24h: .volume.h24
})'Network IDs: ethereum, base, arbitrum, optimism, polygon, unichain
From the results, identify:
- Available pools and their addresses (multiple = different fee tiers)
- Pool TVL (
liquidity.usd) to assess liquidity depth - Version (v3 or v4) from
labels[0]
If no Uniswap pools found: The pair may not have an existing pool. Inform the user they would be creating a new pool and setting the initial price.
Step 4: Assess Pool Liquidity
Evaluate if the pool has sufficient liquidity:
| TVL Range | Assessment | Recommendation |
|---|---|---|
| > $1M | Deep liquidity | Safe for most position sizes |
| $100K - $1M | Moderate | Suitable for positions up to ~$10K |
| $10K - $100K | Thin | Warn user about slippage risk, suggest smaller positions |
| < $10K | Very thin | Warn strongly - high IL risk, price impact on entry/exit |
For thin liquidity pools, present a warning:
⚠️ **Low Liquidity Warning**
This pool has only ${tvl} TVL. Consider:
- Your position will be a significant % of the pool
- Entry/exit may move the price against you
- Impermanent loss risk is amplified in thin pools
- You may want to use a wider price range for safetyStep 5: Fetch Pool Metrics
Before suggesting ranges, fetch pool data for informed decisions. See references/data-providers.md for full API details.
Get pool APY and volume with DefiLlama:
# Find Uniswap V3 pools for a token pair
curl -s "https://yields.llama.fi/pools" | jq '[.data[] | select(.project == "uniswap-v3" and .chain == "Ethereum" and (.symbol | test("WETH.*USDC|USDC.*WETH")))]'Response fields to use:
| Field | Use For |
|---|---|
apy | Show expected yield |
tvlUsd | Assess pool depth |
volumeUsd1d | Estimate fee earnings |
volumeUsd7d | Check volume consistency |
Get current prices with DexScreener:
# Get token prices from the pool data (already fetched in Step 3)
curl -s "https://api.dexscreener.com/token-pairs/v1/{network}/{address}" | \
jq '[.[] | select(.dexId == "uniswap")][0] | {
baseTokenPrice: .baseToken.priceUsd,
quoteTokenPrice: .quoteToken.priceUsd
}'Compare fee tiers (if APY data available):
# Find all fee tier variants and compare APY
curl -s "https://yields.llama.fi/pools" | jq '[.data[] | select(.project == "uniswap-v3" and (.symbol | test("WETH.*USDC")))] | map({symbol, tvlUsd, apy, volumeUsd1d})'If APIs are unavailable, fall back to web search for price estimates.
Step 6: Suggest Price Ranges
Based on current price and pair type, present range options using AskUserQuestion.
For major pairs (ETH/USDC, ETH/WBTC):
{
"questions": [
{
"question": "What price range do you want for your position? (Current: ~3,200 USDC/ETH)",
"header": "Range",
"options": [
{
"label": "±10% (Recommended)",
"description": "2,880 - 3,520 USDC. Higher fees, monitor weekly"
},
{ "label": "±20%", "description": "2,560 - 3,840 USDC. Balanced risk/reward" },
{ "label": "±50%", "description": "1,600 - 4,800 USDC. Rarely out of range" },
{ "label": "Full Range", "description": "Never out of range, lower fee efficiency" }
],
"multiSelect": false
}
]
}For stablecoin pairs (USDC/USDT, DAI/USDC):
{
"questions": [
{
"question": "What price range for your stablecoin position?",
"header": "Range",
"options": [
{ "label": "±0.5% (Recommended)", "description": "0.995 - 1.005. Tight range, high fees" },
{ "label": "±1%", "description": "0.99 - 1.01. Standard for stables" },
{ "label": "±2%", "description": "0.98 - 1.02. Safer, lower fees" },
{ "label": "Full Range", "description": "Maximum safety, lowest fees" }
],
"multiSelect": false
}
]
}Recommendation logic:
- Stablecoin pairs (USDC/USDT): Default to ±0.5-1%
- Correlated pairs (ETH/stETH): Default to ±2-5%
- Major pairs (ETH/USDC): Default to ±10-20%
- Volatile pairs: Default to ±30-50% or full range
Step 7: Determine Fee Tier
If multiple fee tiers exist for the pair, let the user choose using pool data from Step 3.
Present fee tier options with APY data:
{
"questions": [
{
"question": "Which fee tier? (Based on current pool data)",
"header": "Fee Tier",
"options": [
{ "label": "0.30% (Recommended)", "description": "TVL: $15M, APY: 12.5%, highest volume" },
{ "label": "0.05%", "description": "TVL: $8M, APY: 8.2%, lower fees per trade" },
{ "label": "1.00%", "description": "TVL: $2M, APY: 18.1%, less competition" }
],
"multiSelect": false
}
]
}Fee tier guidelines:
| Fee | Tick Spacing | Best For |
|---|---|---|
| 0.01% (100) | 1 | Stablecoin pairs |
| 0.05% (500) | 10 | Correlated pairs (ETH/stETH) |
| 0.30% (3000) | 60 | Most pairs (default) |
| 1.00% (10000) | 200 | Exotic/volatile pairs |
v4 Fee Tiers: Dynamic fees possible with hooks. Default to similar V3 tiers.
If pool data shows one tier with significantly higher APY or volume, recommend that tier.
Step 8: Generate Deep Link
Construct the Uniswap position creation URL:
Base URL: https://app.uniswap.org/positions/create
URL Parameters:
| Parameter | Description | Format |
|---|---|---|
chain | Network name | ethereum, base, etc. |
currencyA | First token | Address or NATIVE |
currencyB | Second token | Address or NATIVE |
priceRangeState | Range configuration | JSON (encode quotes only) |
depositState | Deposit amounts | JSON (encode quotes only) |
fee | Fee tier configuration | JSON (encode quotes only) |
hook | v4 hook address (optional) | Address or undefined |
step | Flow step | 1 (for create) |
IMPORTANT: URL Encoding
Only encode the double quotes (" → %22) in JSON values. Do NOT encode braces {} or colons :.
priceRangeState JSON structure:
For full range:
{
"priceInverted": false,
"fullRange": true,
"minPrice": "",
"maxPrice": "",
"initialPrice": "",
"inputMode": "price"
}For custom range:
{
"priceInverted": false,
"fullRange": false,
"minPrice": "2800",
"maxPrice": "3600",
"initialPrice": "",
"inputMode": "price"
}depositState JSON structure:
{ "exactField": "TOKEN0", "exactAmounts": { "TOKEN0": "1.0" } }Note: Use TOKEN0 for currencyA, TOKEN1 for currencyB.
fee JSON structure:
{ "feeAmount": 3000, "tickSpacing": 60, "isDynamic": false }Tick spacing by fee:
| Fee | Tick Spacing |
|---|---|
| 100 (0.01%) | 1 |
| 500 (0.05%) | 10 |
| 3000 (0.30%) | 60 |
| 10000 (1.00%) | 200 |
Step 9: Present Output and Open Browser
Format the response with:
1. Summary of the position parameters 2. Price range visualization (if not full range) 3. Considerations about IL and management 4. Open the browser automatically using system command
Example output format:
## Liquidity Position Summary
| Parameter | Value |
| --------- | ----------------------- |
| Pair | ETH / USDC |
| Chain | Base |
| Version | V3 |
| Fee Tier | 0.30% |
| Deposit | 1 ETH + equivalent USDC |
### Pool Analytics
| Metric | Value |
| ----------- | ------ |
| Current APY | 12.5% |
| 24h Volume | $2.1M |
| 7d Volume | $14.8M |
| Pool TVL | $15.2M |
### Price Range
| Metric | Value |
| ------------- | ------------------- |
| Current Price | ~3,200 USDC per ETH |
| Min Price | 2,800 USDC per ETH |
| Max Price | 3,600 USDC per ETH |
| Range Width | ±12.5% |
### Considerations
- **Impermanent Loss**: If ETH moves outside your range, you'll hold 100% of one asset
- **Rebalancing**: Monitor position and adjust range if price moves significantly
- **Fee Earnings**: Tighter ranges earn more fees but require more active management
- **Gas Costs**: Creating and managing positions costs gas
- **APY Note**: Shown APY is historical and may vary with market conditions
Opening Uniswap in your browser...After displaying the summary, open the URL in the browser:
# Linux - note: only quotes are encoded (%22), not braces or colons
xdg-open "https://app.uniswap.org/positions/create?currencyA=NATIVE¤cyB=0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913&chain=base&fee={%22feeAmount%22:3000,%22tickSpacing%22:60,%22isDynamic%22:false}&priceRangeState={%22priceInverted%22:false,%22fullRange%22:false,%22minPrice%22:%222800%22,%22maxPrice%22:%223600%22,%22initialPrice%22:%22%22,%22inputMode%22:%22price%22}&depositState={%22exactField%22:%22TOKEN0%22,%22exactAmounts%22:{%22TOKEN0%22:%221%22}}&step=1"
# macOS
open "https://app.uniswap.org/positions/create?..."Environment limitations: Browser opening may fail in remote SSH, containerized, or headless environments. If xdg-open/open fails, display the full URL prominently so users can copy and paste it manually:
**[Click here to open in Uniswap](https://app.uniswap.org/positions/create?...)**
Or copy this URL: `https://app.uniswap.org/positions/create?...`Always present the summary and URL so users can review and create the position.
Version Selection
For detailed version comparison (v2/v3/v4 differences, fee tiers, tick spacing), see references/position-types.md.
Quick Guide:
- V2: Full range only, simplest, lowest gas
- V3: Concentrated liquidity, most common choice
- V4: Advanced features with hooks, limited availability
Important Considerations
Impermanent Loss (IL)
Warn users about IL risk:
- IL occurs when token prices diverge from entry price
- Tighter ranges amplify IL but also fee earnings
- Full range minimizes IL but reduces fee efficiency
Position Management
Concentrated liquidity requires active management:
- Monitor if price stays in range
- Rebalance when price approaches range boundaries
- Consider gas costs for position adjustments
Capital Requirements
For V3 positions with custom range:
- Depositing single-sided is possible if current price is outside range
- Within range: both tokens required in ratio determined by price and range
Supported Chains
All Uniswap-supported chains - see references/position-types.md for version availability by chain.
Additional Resources
Reference Files
- `../../references/chains.md` - Chain configuration and token addresses (shared with swap-planner)
- `references/position-types.md` - v2/v3/v4 differences, fee tiers, tick spacing
- `references/data-providers.md` - DexScreener and DefiLlama APIs for pool discovery and yields
URL Encoding
JSON parameters in deep links should have only double quotes encoded (" → %22). Do NOT encode braces {}, colons :, or commas ,.
?priceRangeState={%22fullRange%22:true}Decodes to:
{ "fullRange": true }Why? The Uniswap interface expects JSON-like parameter structure. Full URL encoding of braces and colons breaks parsing. Only quotes need encoding to avoid URL syntax conflicts.
Data Providers Reference
APIs for fetching pool data to inform LP position decisions. Uses two providers:
1. DexScreener - Pool discovery, prices, TVL, volume (primary) 2. DefiLlama - APY/yield data (when available)
DexScreener API (Primary)
No authentication required. 300 requests/minute. Best for pool discovery and real-time metrics.
Network IDs: ethereum, base, arbitrum, optimism, polygon, bsc, avalanche, unichain
Discover Pools for a Token
Use this to find what pools exist for a token pair:
# Find all pools containing a token (e.g., UNI on Base)
curl -s "https://api.dexscreener.com/token-pairs/v1/base/0xc3de830ea07524a0761646a6a4e4be0e114a3c83" | \
jq '[.[] | select(.dexId == "uniswap")] | map({
pairAddress,
baseToken: .baseToken.symbol,
quoteToken: .quoteToken.symbol,
version: .labels[0],
liquidity: .liquidity.usd,
volume24h: .volume.h24,
priceUsd
})'Get Pool Details
# Get specific pool by address
curl -s "https://api.dexscreener.com/latest/dex/pairs/base/0xab365f161dd501473a1ff0d2ef0dce94e7398839" | \
jq '.pairs[0] | {
name: "\(.baseToken.symbol)/\(.quoteToken.symbol)",
version: .labels[0],
liquidity: .liquidity.usd,
volume24h: .volume.h24,
baseTokenPrice: .baseToken.priceUsd,
quoteTokenPrice: .quoteToken.priceUsd,
priceChange24h: .priceChange.h24
}'Search for Token Pair
# Search by token names (filter results by dexId)
curl -s "https://api.dexscreener.com/latest/dex/search?q=ETH%20USDC%20base" | \
jq '[.pairs[] | select(.dexId == "uniswap")] | .[0:5] | map({
pairAddress,
name: "\(.baseToken.symbol)/\(.quoteToken.symbol)",
liquidity: .liquidity.usd,
volume24h: .volume.h24
})'DexScreener Response Fields
| Field | Path | Description |
|---|---|---|
| Pool address | pairAddress | Use for deep links |
| Version | labels[0] | "v3" or "v4" |
| TVL | liquidity.usd | Pool liquidity in USD |
| 24h Volume | volume.h24 | Trading volume |
| Price | priceUsd | Current price |
| Base token price | baseToken.priceUsd | For ratio calculations |
| Quote token price | quoteToken.priceUsd | For ratio calculations |
Important Notes
- Filter by DEX: Results include ALL DEXes. Always filter with
select(.dexId == "uniswap"). - Fee tier not explicit: DexScreener shows version (v3/v4) but not fee tier (0.3%, 1%). Each fee tier has a different pool address - multiple pools for same pair = different fee tiers.
- No 7d volume: Only real-time data up to 24 hours.
DefiLlama Yields API (APY Data)
No authentication required. Best source for Uniswap pool yields, but coverage is limited for less popular pairs.
Find Pool APY
# Find Uniswap V3 pools for a token pair on a specific chain
curl -s "https://yields.llama.fi/pools" | jq '[.data[] | select(
.project == "uniswap-v3" and
.chain == "Base" and
(.symbol | test("WETH.*UNI|UNI.*WETH"; "i"))
)] | map({symbol, apy, apyBase, tvlUsd, volumeUsd1d, volumeUsd7d})'DefiLlama Response Fields
| Field | Description |
|---|---|
apy | Total APY (base + rewards) |
apyBase | APY from trading fees only |
tvlUsd | Total value locked |
volumeUsd1d | 24-hour volume |
volumeUsd7d | 7-day volume |
Chain Names
DefiLlama uses capitalized names: Ethereum, Base, Arbitrum, Optimism, Polygon
Coverage Limitations
DefiLlama often returns empty results for:
- Less popular token pairs
- Newer pools
- Low-TVL pools
When empty, note "APY data unavailable" and rely on DexScreener for other metrics.
Recommended Workflow
Step 1: Discover Pools (DexScreener)
# Find all Uniswap pools for the token
curl -s "https://api.dexscreener.com/token-pairs/v1/{network}/{token_address}" | \
jq '[.[] | select(.dexId == "uniswap")]'From results, identify:
- Available pools and their addresses
- Which has highest liquidity (likely the main fee tier)
- Current prices for range calculations
Step 2: Check APY (DefiLlama)
# Try to get yield data
curl -s "https://yields.llama.fi/pools" | jq '[.data[] | select(
.project == "uniswap-v3" and
.chain == "{Chain}" and
(.symbol | test("{TOKEN_A}.*{TOKEN_B}|{TOKEN_B}.*{TOKEN_A}"; "i"))
)]'If results empty, proceed without APY data.
Step 3: Assess Liquidity
| TVL Range | Assessment | Action |
|---|---|---|
| > $1M | Deep liquidity | Proceed normally |
| $100K - $1M | Moderate | Suitable for most positions |
| $10K - $100K | Thin | Warn user, suggest wider ranges |
| < $10K | Very thin | Strong warning about risks |
Step 4: Calculate Price Range
Use DexScreener prices to calculate range bounds:
# Get current price ratio
BASE_PRICE=$(curl -s "..." | jq -r '.pairs[0].baseToken.priceUsd')
QUOTE_PRICE=$(curl -s "..." | jq -r '.pairs[0].quoteToken.priceUsd')
# Calculate ratio and ±20% bounds with python
python3 -c "
base, quote = $BASE_PRICE, $QUOTE_PRICE
ratio = quote / base
print(f'Current: {ratio:.2f}')
print(f'Min (−20%): {ratio * 0.8:.2f}')
print(f'Max (+20%): {ratio * 1.2:.2f}')
"Example: Complete Pool Research
# 1. Find ETH/UNI pools on Base
curl -s "https://api.dexscreener.com/token-pairs/v1/base/0xc3de830ea07524a0761646a6a4e4be0e114a3c83" | \
jq '[.[] | select(.dexId == "uniswap" and (.quoteToken.symbol == "WETH" or .baseToken.symbol == "WETH"))] | map({
pairAddress,
pair: "\(.baseToken.symbol)/\(.quoteToken.symbol)",
version: .labels[0],
tvl: .liquidity.usd,
volume24h: .volume.h24,
ethPrice: (if .quoteToken.symbol == "WETH" then .quoteToken.priceUsd else .baseToken.priceUsd end),
uniPrice: (if .baseToken.symbol == "UNI" then .baseToken.priceUsd else .quoteToken.priceUsd end)
})'
# 2. Try DefiLlama for APY (may return empty)
curl -s "https://yields.llama.fi/pools" | jq '[.data[] | select(
.project == "uniswap-v3" and
.chain == "Base" and
(.symbol | test("UNI.*WETH|WETH.*UNI|UNI.*ETH|ETH.*UNI"; "i"))
)] | map({symbol, apy, tvlUsd})'Error Handling
| Scenario | Action |
|---|---|
| DexScreener returns no Uniswap pools | Pool may not exist; inform user they'd create a new pool |
| DefiLlama returns empty | Note "APY unavailable"; use DexScreener volume/TVL ratio as proxy |
| Multiple pools found | Present options; highest TVL is usually the primary fee tier |
| API timeout | Retry once, then fall back to web search |
Position Types Reference
Comprehensive reference for Uniswap v2, v3, and v4 liquidity positions.
Version Comparison
| Feature | v2 | v3 | v4 |
|---|---|---|---|
| Liquidity Type | Full Range | Concentrated | Concentrated |
| Price Ranges | No | Yes | Yes |
| Position Representation | ERC-20 LP Token | NFT | NFT |
| Fee Tiers | 0.3% fixed | 0.01%, 0.05%, 0.3%, 1% | Dynamic (with hooks) |
| Hooks Support | No | No | Yes |
| Capital Efficiency | 1x | Up to 4000x | Up to 4000x+ |
| Gas Costs | Low | Medium | Medium |
V2 Positions
V2 Basics
V2 uses the constant product formula (x \* y = k) across the entire price range.
Pros:
- Simple to understand and manage
- No rebalancing needed
- Lower gas costs
- Fungible LP tokens
Cons:
- Capital inefficient (liquidity spread across infinite range)
- Lower fee earnings per dollar deposited
URL Parameters for V2
V2 positions use a different URL structure:
https://app.uniswap.org/add/v2/{tokenA}/{tokenB}Or with the unified interface:
https://app.uniswap.org/positions/create?version=v2¤cyA={}¤cyB={}When to Use V2
- Very long-term, passive positions
- Pairs with extreme volatility where any range would be exceeded
- When gas costs for V3 management exceed benefits
V3 Positions
V3 Basics
V3 allows LPs to concentrate liquidity within custom price ranges, dramatically improving capital efficiency.
Fee Tiers
| Fee | Tick Spacing | Best For | Typical Pairs |
|---|---|---|---|
| 0.01% (100) | 1 | Stablecoins | USDC/USDT, DAI/USDC |
| 0.05% (500) | 10 | Correlated assets | ETH/stETH, WBTC/renBTC |
| 0.30% (3000) | 60 | Most pairs | ETH/USDC, WBTC/ETH |
| 1.00% (10000) | 200 | Exotic pairs | Long-tail tokens |
Tick Math
V3 uses discrete ticks to represent prices. Key concepts:
- Tick: Integer representing a price point
- Tick Spacing: Minimum distance between usable ticks (varies by fee tier)
- Price to Tick:
tick = log(price) / log(1.0001)
Tick ranges by fee tier:
| Fee | Tick Spacing | Min Tick | Max Tick |
|---|---|---|---|
| 100 | 1 | -887272 | 887272 |
| 500 | 10 | -887270 | 887270 |
| 3000 | 60 | -887220 | 887220 |
| 10000 | 200 | -887200 | 887200 |
Price Range Strategies
Full Range:
{
"fullRange": true
}Characteristics:
- Behaves like V2
- Never goes out of range
- Lower capital efficiency
Tight Range (±5%):
{
"fullRange": false,
"minPrice": "3040",
"maxPrice": "3360"
}Characteristics:
- High capital efficiency
- High fee APR
- Requires frequent monitoring
Medium Range (±20%):
{
"fullRange": false,
"minPrice": "2560",
"maxPrice": "3840"
}Characteristics:
- Balanced approach
- Moderate monitoring
- Good for most users
Wide Range (±50%):
{
"fullRange": false,
"minPrice": "1600",
"maxPrice": "4800"
}Characteristics:
- More passive
- Lower concentration benefits
- Less monitoring needed
Position NFT
V3 positions are represented as NFTs (ERC-721):
- Each position has a unique token ID
- NFT contains position metadata (pool, range, liquidity)
- Can be transferred, sold, or used as collateral
v4 Positions
v4 Basics
v4 introduces hooks - custom smart contracts that can execute logic at various points in the pool lifecycle.
Key Differences from v3
1. Hooks: Custom logic for swaps, liquidity changes, etc. 2. Dynamic Fees: Fees can change based on conditions 3. Singleton Contract: All pools in one contract (gas savings) 4. Flash Accounting: More efficient multi-hop swaps
Hook Address Parameter
When creating v4 positions with hooks:
{
"hook": "0x..."
}The hook address determines which v4 pool to use.
v4 Availability
v4 is newer and has limited pool availability. Check if a v4 pool exists before suggesting it.
Chains with v4 support:
- Ethereum Mainnet (limited pools)
- Base (growing)
- Other L2s (expanding)
When to Use v4
- When specific hook functionality is needed
- For advanced use cases (TWAMM, limit orders, etc.)
- When v4 pool has better liquidity than v3
Chain Availability
Version Support by Chain
| Chain | V2 | V3 | V4 |
|---|---|---|---|
| Ethereum | ✅ | ✅ | ✅ |
| Base | ❌ | ✅ | ✅ |
| Arbitrum | ✅ | ✅ | ✅ |
| Optimism | ❌ | ✅ | ✅ |
| Polygon | ✅ | ✅ | 🔜 |
| BNB Chain | ✅ | ✅ | 🔜 |
| Avalanche | ❌ | ✅ | 🔜 |
| Celo | ✅ | ✅ | ❌ |
| Blast | ❌ | ✅ | ✅ |
| Zora | ❌ | ✅ | ✅ |
| World Chain | ❌ | ✅ | ✅ |
| Unichain | ❌ | ✅ | ✅ |
Recommendation by Chain
For most users on most chains: v3 with 0.3% fee tier
For stablecoin LPs: v3 with 0.01% or 0.05% fee tier
For advanced users: v4 if appropriate hook/pool exists
Impermanent Loss by Range
IL increases with range tightness and price movement:
| Price Move | Full Range IL | ±50% Range IL | ±20% Range IL | ±10% Range IL |
|---|---|---|---|---|
| ±10% | 0.11% | 0.22% | 0.55% | 1.10% |
| ±25% | 0.64% | 1.28% | 3.20% | 100%\* |
| ±50% | 2.02% | 4.04% | 100%\* | 100%\* |
\*100% means position is entirely in one asset (out of range)
Deep Link Parameter Reference
IMPORTANT: URL Encoding Rules
Only encode double quotes (" → %22). Do NOT encode braces {}, colons :, or commas ,.
priceRangeState Object
interface PriceRangeState {
priceInverted: boolean; // false for normal price direction
fullRange: boolean; // true for full range, false for custom
minPrice: string; // Min price as string (empty for full range)
maxPrice: string; // Max price as string (empty for full range)
initialPrice: string; // Empty string for existing pools
inputMode: string; // Always "price"
}depositState Object
interface DepositState {
exactField: 'TOKEN0' | 'TOKEN1'; // TOKEN0 = currencyA, TOKEN1 = currencyB
exactAmounts: {
TOKEN0?: string;
TOKEN1?: string;
};
}fee Object
interface FeeData {
feeAmount: number; // Fee in hundredths of a bip (3000 = 0.3%)
tickSpacing: number; // Tick spacing for the fee tier
isDynamic: boolean; // false for V3, can be true for V4
}URL Encoding Examples
Full Range v3 Position (ETH/USDC, 0.3% fee)
https://app.uniswap.org/positions/create
?currencyA=NATIVE
¤cyB=0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48
&chain=ethereum
&fee={%22feeAmount%22:3000,%22tickSpacing%22:60,%22isDynamic%22:false}
&priceRangeState={%22priceInverted%22:false,%22fullRange%22:true,%22minPrice%22:%22%22,%22maxPrice%22:%22%22,%22initialPrice%22:%22%22,%22inputMode%22:%22price%22}
&step=1Custom Range V3 Position (ETH/USDC on Base, ±10% range)
https://app.uniswap.org/positions/create
?currencyA=NATIVE
¤cyB=0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913
&chain=base
&fee={%22feeAmount%22:3000,%22tickSpacing%22:60,%22isDynamic%22:false}
&priceRangeState={%22priceInverted%22:false,%22fullRange%22:false,%22minPrice%22:%222800%22,%22maxPrice%22:%223600%22,%22initialPrice%22:%22%22,%22inputMode%22:%22price%22}
&depositState={%22exactField%22:%22TOKEN0%22,%22exactAmounts%22:{%22TOKEN0%22:%221%22}}
&step=1Stablecoin Position (USDC/USDT, 0.01% fee, tight range)
https://app.uniswap.org/positions/create
?currencyA=0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48
¤cyB=0xdAC17F958D2ee523a2206206994597C13D831ec7
&chain=ethereum
&fee={%22feeAmount%22:100,%22tickSpacing%22:1,%22isDynamic%22:false}
&priceRangeState={%22priceInverted%22:false,%22fullRange%22:false,%22minPrice%22:%220.99%22,%22maxPrice%22:%221.01%22,%22initialPrice%22:%22%22,%22inputMode%22:%22price%22}
&step=1Related skills
How it compares
Use liquidity-planner for documented DexScreener and DefiLlama fetch patterns in Uniswap agents; use generic Web3 skills when you need wallet or contract deployment instead of pool analytics.
FAQ
Which API does liquidity-planner use first for pool data?
liquidity-planner uses DexScreener as the primary provider for pool discovery, prices, TVL, and volume with no authentication and a 300 requests/minute rate limit. DefiLlama supplies APY and yield data when available.
What chains does liquidity-planner support?
liquidity-planner documents DexScreener network IDs for ethereum, base, arbitrum, optimism, polygon, bsc, avalanche, and unichain—eight networks total for token-pair and pool queries.
Is Liquidity Planner safe to install?
skills.sh reports 2 of 3 security scanners passed. Review the Security Audits panel on this page before installing in production.