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.

<!-- markdownlint-disable-next-line MD028 -->

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

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

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 safety

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:

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

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.