Choosing a liquidity range

This page helps you choose the price range for a liquidity position before you open one.

Concentrated liquidity on Shield

Shield uses Uniswap v3’s concentrated-liquidity math. Your range determines the asset mix and liquidity your deposit supports, and your active liquidity earns a share of the trading fees charged. Shield’s supported price limits differ from Uniswap v3’s. Your bounds must fit those limits and the pool’s permitted price increments, so check the resulting range before you submit. Full Range selects the widest supported range for that pool. Check the pool’s current fee when choosing where to provide liquidity. That fee can change, and your earnings depend on the fees actually charged and the share allocated to liquidity providers. See LP fee entitlements.

High level liquidity flow

The following diagram illustrates how a market maker starting with no liquidity position can create and manage a liquidity position

Mint opens a position. Increase, decrease, and collect keep its ID; rebalance creates a new ID. To close, decrease all liquidity, collect all owed balances, confirm zero liquidity and owed balances, then burn.

In the app

Before you startYou’ll need: Shield Wallet connected to Shield Swap, and a pool open under Pools.

Check the pool before choosing

The chart tabs Price, Volume, Liquidity, and Depth show recent price movement and where other positions sit. The Oracle panel below shows the TWAP (the time-weighted average price), the LP Fees earned in the pool over the selected window, and Last Trade. The pool’s fee percentage appears under its name in the Pools list and in Switch pair on the Trade page.

Choose a range

In the panel on the right, keep New Position selected and enter an amount for one asset.
Keep Full Range for the pool’s widest supported range, or select Custom.
With Custom selected, choose a preset or set the range by hand:
- Stable sets a narrow band, about 2 percent either side of the current price.
- Wide sets a broad band, from 50 percent below the current price to 100 percent above it.
- Lower sets a band from 50 percent below the current price up to the current price.
- Upper sets a band from the current price up to 100 percent above it.
- Drag the handles on the chart, or enter prices in Min and Max.
Check Min and Max. Each shows the price and its distance from the current price as a percentage.

The chart shows where liquidity in the pool sits, with your range highlighted and the current price marked. The second amount updates when the range changes, because a different range needs a different mix of the two assets.Continue with Minting a position to open the position.

Troubleshooting

What you see	Why it happens	What to do
The current price is outside your range. The position will be 100% in one token and won’t earn fees until the price moves back into the range.	You chose Lower, Upper, or a custom range that does not include the current price.	Widen the range to include the current price, or continue if you intend to wait for the price to reach the range.
Min and Max show very small and very large numbers after you select Custom	The app opened the custom chart at the full-range bounds.	Select a preset or drag the handles. The fields update to the prices you choose.

Next steps

Minting a position to open a position with the range you chose.
Rebalancing positions to move an existing position to a new range.

Set a liquidity range

Prerequisites: Your authenticated mainnet client for Typescript, dex for Python, or CLI profile from Setup.Start by finding pools for USDCx and ETH, then select one by its full pool key. A pair can have multiple pools. Keep the selected key when you preview the range and mint. Run the three steps in your language in order; discovery and selection do not require a funded account.In step 2, replace the quoted POOL_KEY with a key printed in step 1, including its field suffix. Check the token IDs before choosing. In the Typescript range preview, supply AMOUNT0_BASE_UNITS and AMOUNT1_BASE_UNITS as bigint budgets in each token’s native base units. Step 2 shows the token order and decimals for those amounts.Use the pool’s stored tick spacing when choosing bounds; the current trading fee can change without changing that spacing. Both ticks must be multiples of the spacing. The Typescript preview and CLI plan report the aligned bounds, and the Python example uses the slot’s range helper. See Price, ticks, and square-root price and Liquidity formulas for Shield’s numeric conventions and limits.

Typescript
Python
CLI

Step 1: Discover pools

Change the two symbols to find a different pair. Match both token IDs in either order.

const [assetA, assetB] = await Promise.all([
  client.tokenData("USDCx"),
  client.tokenData("ETH"),
])
const page = await client.api.getPools({ limit: 50, offset: 0 })
const pools = page.data.filter(pool =>
  (pool.token0 === assetA.id && pool.token1 === assetB.id) ||
  (pool.token0 === assetB.id && pool.token1 === assetA.id),
)
if (!pools.length) throw new Error("No matching pools in this page")
console.table(pools.map(pool => ({
  poolKey: pool.key, token0: pool.token0, token1: pool.token1,
})))

This reads up to 50 pools. Check page.pagination and increase offset to inspect later pages if your pool is absent.

Step 2: Select a pool

const poolKey = "POOL_KEY"
const pool = pools.find(pool => pool.key === poolKey)
if (!pool) throw new Error("Selected pool is not in the matching results")
const [token0, token1] = await Promise.all([
  client.tokenData(pool.token0),
  client.tokenData(pool.token1),
])
const slot = await client.getSlot({ poolKey: pool.key })
if (!slot) throw new Error("Selected pool has no initialized slot")

console.log("selected pool:", pool.key)
console.table([
  { side: "token0", id: token0.id, symbol: token0.symbol, decimals: token0.decimals },
  { side: "token1", id: token1.id, symbol: token1.symbol, decimals: token1.decimals },
])
console.log("tick spacing:", slot.tick_spacing)
console.log("active liquidity:", slot.liquidity.toString())

The output identifies the selected pool and its token order. Active liquidity is in liquidity units, not token amounts or a dollar value. An initialized pool can have zero active liquidity.

Step 3: Set a liquidity range

previewMint accepts either a width around the current price or explicit ticks, aligns the result to the pool’s spacing, and reports whether the range includes the current price. Nothing is spent.

const preview = await client.previewMint({
  poolKey: pool.key,
  amount0Desired: AMOUNT0_BASE_UNITS,
  amount1Desired: AMOUNT1_BASE_UNITS,
  rangePercent: 5, // 5 percent either side of the current price
})

console.log(preview.tickLower, preview.tickUpper, preview.tickCurrent, preview.inRange)

To set exact bounds, pass tickLower and tickUpper instead of rangePercent. preview.inRange is false when the current tick is outside the range. See Minting a position for the full preview-then-mint sequence, using the same pool key.

Step 1: Discover pools

Change the two symbols to find a different pair. Match both token IDs in either order.

asset_a = dex.api.get_token("USDCx")
asset_b = dex.api.get_token("ETH")
pools = [
    pool for pool in dex.api.get_pools()
    if {pool.token0, pool.token1} == {asset_a.address, asset_b.address}
]
if not pools:
    raise ValueError("No matching pools in this page")
for pool in pools:
    print(f"{pool.key}: token0={pool.token0}, token1={pool.token1}")

get_pools() reads the API’s default page. For a complete list, use the paginated pool endpoint.

Step 2: Select a pool

pool_key = "POOL_KEY"
pool = next((pool for pool in pools if pool.key == pool_key), None)
if pool is None:
    raise ValueError("Selected pool is not in the matching results")
tokens_by_id = {token.address: token for token in dex.api.get_tokens()}
token0 = tokens_by_id[pool.token0]
token1 = tokens_by_id[pool.token1]
slot = dex.get_slot(pool.key)

print(f"selected pool: {pool.key}")
print(f"token0: {token0.symbol}, ID {token0.address}, decimals {token0.decimals}")
print(f"token1: {token1.symbol}, ID {token1.address}, decimals {token1.decimals}")
print(f"tick spacing: {slot.tick_spacing}")
print(f"active liquidity: {slot.liquidity}")

The output identifies the selected pool and its token order. Active liquidity is in liquidity units, not token amounts or a dollar value. An initialized pool can have zero active liquidity. get_slot() raises an error for an unknown or uninitialized pool.

Step 3: Set a liquidity range

The Python SDK aligns a symmetric range for you from the pool’s slot. For an asymmetric range, align the ticks yourself to slot.tick_spacing.

slot = dex.get_slot(pool.key)
tick_lower, tick_upper = slot.tick_range(10)  # 10 spacings either side of the current tick
in_range = tick_lower <= slot.tick < tick_upper
print(tick_lower, tick_upper, slot.tick, in_range)

The output shows the lower tick, upper tick, current tick, and whether the range includes it. slot.tick_spacing is the pool’s spacing. The Python SDK has no mint preview; to see the amounts a range consumes before minting, use the CLI plan or the Typescript preview.

Step 1: Discover pools

shield-swap pools --token USDCx --limit 50 --network mainnet --json

In the pools array, find an entry whose other token is ETH. Each entry includes poolKey, both token IDs, symbols and decimals, tickSpacing, and active liquidity. The filter matches one token; verify both IDs before choosing. The command inspects up to 50 pools before filtering, so increase --limit if needed.

Step 2: Select a pool

Save the chosen poolKey in your shell. Replace the quoted placeholder with its full value from step 1.

export POOL_KEY="POOL_KEY"

--pool uses that exact key. With --pair, the CLI chooses a matching pool automatically and can select a different one.

Step 3: Set a liquidity range

--range-pct sets a width either side of the current price. Without --execute, the plan prints the aligned ticks and the amounts the range consumes, and stops.

shield-swap mint --pool "$POOL_KEY" --amount USDCx:1 \
  --range-pct 5 --network mainnet

The preview reads your funded balance for both tokens. This example caps USDCx at 1 token; the unnamed ETH side uses your available balance as its budget. Add a second --amount ETH:AMOUNT_IN_ETH to set that budget explicitly. The default range width is 5 percent on either side. The CLI has no option for an asymmetric range; use an SDK for that.

How it works on chain

A position is active when the pool’s stored tick satisfies tick_lower <= current_tick < tick_upper. The lower tick is included and the upper tick is excluded.

What backs the liquidity

Current price	Assets backing the position’s liquidity
At or below the lower price bound	Token0 only.
Between the price bounds	A mix of token0 and token1.
At or above the upper price bound	Token1 only.

The amounts come from the current square-root price and the square-root prices at your bounds. Owed balances are separate from this inventory. See Price, ticks, and square-root price.

What happens at a boundary

The contract records the swap step’s LP fee using the active liquidity before crossing. The fee is earned in that step’s input token, in proportion to each active position’s liquidity.
It updates the boundary’s fee-growth-outside values and applies its signed liquidity change for the direction of travel.
It updates the stored tick and nearest-tick pointers. The active ranges for the next step now reflect the crossing.

The crossing completes even when the swap stops exactly at the boundary. Your position can therefore become inactive without the price moving beyond its edge. See LP fee entitlements for fee accounting.

Before you mint

Shield stores initialized ticks in a per-pool linked list. A new boundary needs the initialized tick below it as an insertion hint. Fetch hints close to submission; another accepted transaction can make one stale.Record the reference price, aligned ticks, expected inventory at entry, and your rebalance trigger. The range, liquidity, and fee accounting are public; ownership is confidential. See Public data.

Next steps

Minting a position to open a position with the range you chose.
Rebalancing positions to move an existing position to a new range.

Start

Trade

Provide liquidity

Integration guides

Choosing a liquidity range

Concentrated liquidity on Shield

High level liquidity flow

In the app

Check the pool before choosing

Choose a range

Troubleshooting

Next steps

Set a liquidity range

Step 1: Discover pools

Step 2: Select a pool

Step 3: Set a liquidity range

Step 1: Discover pools

Step 2: Select a pool

Step 3: Set a liquidity range

Step 1: Discover pools

Step 2: Select a pool

Step 3: Set a liquidity range

How it works on chain

What backs the liquidity

What happens at a boundary

Before you mint

Next steps

​Concentrated liquidity on Shield

​High level liquidity flow

​In the app

​Check the pool before choosing

​Choose a range

​Troubleshooting

​Next steps

​Set a liquidity range

​Step 1: Discover pools

​Step 2: Select a pool

​Step 3: Set a liquidity range

​Step 1: Discover pools

​Step 2: Select a pool

​Step 3: Set a liquidity range

​Step 1: Discover pools

​Step 2: Select a pool

​Step 3: Set a liquidity range

​How it works on chain

​What backs the liquidity

​What happens at a boundary

​Before you mint

​Next steps

Concentrated liquidity on Shield

High level liquidity flow

In the app

Check the pool before choosing

Choose a range

Troubleshooting

Next steps

Set a liquidity range

Step 1: Discover pools

Step 2: Select a pool

Step 3: Set a liquidity range

Step 1: Discover pools

Step 2: Select a pool

Step 3: Set a liquidity range

Step 1: Discover pools

Step 2: Select a pool

Step 3: Set a liquidity range

How it works on chain

What backs the liquidity

What happens at a boundary

Before you mint

Next steps