/liquidity-planner

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

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

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

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