Now liveThe Skillselion MCP - thousands of ranked skills, loaded into your agent mid-task. No install.Get it →
uniswap avatar

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-planner

Add your badge

Show developers this skill is listed on Skillselion. Paste this into your README.

Listed on Skillselion
Installs901
repo stars222
Security audit2 / 3 scanners passed
Last updatedAugust 4, 2026
Repositoryuniswap/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

SKILL.mdMarkdownGitHub ↗

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:

ParameterRequiredDefaultExample
Token AYes-ETH, USDC, address
Token BYes-USDC, WBTC, address
AmountYes-1 ETH, $1000
ChainNoEthereumBase, Arbitrum
VersionNoV3v2, v3, v4
Fee TierNoAuto0.05%, 0.3%, 1%
Price RangeNoSuggestFull 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 RangeAssessmentRecommendation
> $1MDeep liquiditySafe for most position sizes
$100K - $1MModerateSuitable for positions up to ~$10K
$10K - $100KThinWarn user about slippage risk, suggest smaller positions
< $10KVery thinWarn 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 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:

FieldUse For
apyShow expected yield
tvlUsdAssess pool depth
volumeUsd1dEstimate fee earnings
volumeUsd7dCheck 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:

FeeTick SpacingBest For
0.01% (100)1Stablecoin pairs
0.05% (500)10Correlated pairs (ETH/stETH)
0.30% (3000)60Most pairs (default)
1.00% (10000)200Exotic/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:

ParameterDescriptionFormat
chainNetwork nameethereum, base, etc.
currencyAFirst tokenAddress or NATIVE
currencyBSecond tokenAddress or NATIVE
priceRangeStateRange configurationJSON (encode quotes only)
depositStateDeposit amountsJSON (encode quotes only)
feeFee tier configurationJSON (encode quotes only)
hookv4 hook address (optional)Address or undefined
stepFlow step1 (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:

FeeTick 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&currencyB=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.

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

Backend & APIsagentsautomation

This week in AI coding

Five minutes, every Monday - the tools, releases and tactics for developers.

unsubscribe anytime.