liquidity-planner

Liquidity Position Planning

Plan and generate deep links for creating liquidity positions on Uniswap v2, v3, and v4.

Runtime Compatibility: This skill uses AskUserQuestion for interactive prompts. If AskUserQuestion is 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:

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": 

For missing token pair:

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, or an equivalent conversational confirmation where that tool is unavailable.

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:

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:

For thin liquidity pools, present a warning:

Step 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:

Response fields to use:

Get current prices with DexScreener:

Compare fee tiers (if APY data available):

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):

For stablecoin pairs (USDC/USDT, DAI/USDC):

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:

Fee tier guidelines:

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:

IMPORTANT: URL Encoding

Only encode the double quotes (" → %22) in JSON values. Do NOT encode braces {} or colons :.

priceRangeState JSON structure:

For full range:

For custom range:

depositState JSON structure:

Note: Use TOKEN0 for currencyA, TOKEN1 for currencyB.

fee JSON structure:

Tick spacing by fee:

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:

After displaying the summary, open the URL in the browser:

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:

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 ,.

Decodes to:

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.