Increasing liquidity

This page helps you add funds to a position you already hold, in the Shield Swap app or with the Typescript SDK, Python SDK, or CLI.

How an increase works

An increase adds liquidity at your position’s existing range and keeps its ID. The added liquidity can earn fees after confirmation while the range is active. To change the range, use Rebalancing. As with minting a position, any deposited amount the range does not use stays with the position for you to collect. Fees you have already earned also remain collectible; adding liquidity does not reinvest them. See Collecting and burning.

In the app

Before you startYou’ll need: Shield Wallet connected to Shield Swap, an open position, and a confidential balance of the pool’s assets. See Fund.

Add funds

Open Pools, then select the pool. Under Your Positions, select Manage in the position’s row, then Increase. The panel on the right switches to Increase with Position loaded showing the position’s ID and range.
Enter an amount for either asset. The app fills in the other amount for the position’s range and the current price.
Select Increase Liquidity.
In Review liquidity increase, check both deposit amounts, the position ID, and the Selected price range. Select Confirm.
In the Transaction request in Shield Wallet, check that the request is from swap.shield.fi and that the amounts match, then select Confirm.

The app shows a progress circle, then confirms the increase. The position’s amounts under Your Positions update, and Recent Activity lists an Increase row.

Troubleshooting

What you see	Why it happens	What to do
Enter Amounts stays on the button	No amount has been entered yet.	Enter an amount for one asset.
The second amount is larger than your Private Balance for that asset	The position’s range needs more of that asset than you hold for the amount you entered.	Lower the first amount, or move more of the second asset into your confidential balance.
The Increase option is missing from Manage	The position has no liquidity (it was fully decreased), or it is frozen.	A fully decreased position cannot be increased. Open a new position instead.

Next steps

Decreasing liquidity to remove funds from the position.
Collecting and burning to collect the fees it has earned.

Find the position and add funds

Prerequisites: Your authenticated mainnet client for Typescript, dex for Python, or CLI profile from Setup, an existing position, and a confidential balance of both pool assets.Amounts are base-unit integers; use each token’s decimals to display them.Replace POSITION_TOKEN_ID with the ID of the position you intend to change. Define the confirmation helper for your SDK before running these examples.

Typescript
Python
CLI

Step 1: Find the position

Positions are discovered from the records your account holds, so this needs the scanner. There is no chain index of an account’s positions.

const positions = await client.getOwnedPositions()
const position = positions.find((p) => p.positionTokenId === POSITION_TOKEN_ID)
if (!position?.state) throw new Error("position not ready or not owned by this account")

const [token0, token1] = await Promise.all([
  client.tokenData(position.token0Id),
  client.tokenData(position.token1Id),
])

Each entry carries positionTokenId, poolKey, tickLower, tickUpper, withdrawal, and a state with the live liquidity, amount0, amount1, and uncollectedFees0 and uncollectedFees1. Name the position by positionTokenId whenever the account holds more than one in the same pool.

Step 2: Increase

The range is read from the position; only the amounts are new.

const imports = await client.resolveDexImports({
  tokenPrograms: [token0.ammTokenProgram!, token1.ammTokenProgram!],
})

const result = await client.increaseLiquidity({
  poolKey: position.poolKey,
  positionTokenId: position.positionTokenId,
  amount0Desired: AMOUNT0_BASE_UNITS,
  amount1Desired: AMOUNT1_BASE_UNITS,
  imports,
})

console.log(`submitted ${result.transactionId}`)
const increased = await waitForPosition(
  result.transactionId, position.positionTokenId, position.record.tag,
)
console.log(`confirmed: liquidity ${increased.state.liquidity}`)

Replace AMOUNT0_BASE_UNITS and AMOUNT1_BASE_UNITS with base-unit bigint budgets for the pool’s token0 and token1. The call spends the current position record and issues a replacement with the same positionTokenId; wait for the scanner to serve the new record before the next operation on this position.

Step 1: Find the position

position = dex.get_owned_position(POSITION_TOKEN_ID)
if position is None or position.state is None:
    raise ValueError("position not ready or not owned by this account")

position.record is the spendable position record. position.state carries the live liquidity, amount0, amount1, and collectible0 and collectible1, or is None when the SDK cannot derive the live state.

Step 2: Increase

Continue with position from step 1. Replace the two amount placeholders with integer base-unit budgets.

result = dex.increase_liquidity(
    pool_key=position.pool_key,
    position_record=position.record,
    amount0_desired=AMOUNT0_BASE_UNITS,
    amount1_desired=AMOUNT1_BASE_UNITS,
).delegate(wait=True)

print(result.transaction_id)
increased = wait_for_position(position.position_token_id, position.record)

Step 1: Find the position

shield-swap positions --network mainnet

Copy the ID of the position you intend to increase and use it as POSITION_TOKEN_ID in step 2.

Step 2: Increase

Review the plan, then submit with --execute:

shield-swap liquidity --position POSITION_TOKEN_ID --increase --percent 10 --network mainnet
shield-swap liquidity --position POSITION_TOKEN_ID --increase --percent 10 --network mainnet --execute

--percent commits that share of your confidential balance of both assets; --amount USDCx:0.5 names one side instead. The plan shows what the range uses, which is never more than the ceiling. A frozen position, or one with no entry in the positions mapping, is rejected before any fee is spent.

How it works on chain

increase_liquidity transfers your desired token0 and token1 amounts into the AMM and adds liquidity at the position’s existing range. Earned fees and any unused deposit stay owed to the position until you collect.

What changes

Item	After a successful increase
Position liquidity	Increased by the liquidity the deposit supports at the current price.
`tokens_owed0` and `tokens_owed1`	Increased by settled fees and each token’s `desired - used` excess. These amounts are not reinvested.
`PositionNFT`	The current record is consumed and replaced. The position ID, pool, range, owner, and withdrawal address stay the same.
Token change records	Hold the input-record amounts above the desired amounts.
Pool active liquidity	Increased only if your range is active.

How liquidity and fees are recorded

The contract calculates the added liquidity and the token amounts used at the current square-root price. Added liquidity must be nonzero, and each used amount must meet its token minimum, in base units.
It updates the boundary ticks and checks the pool’s per-tick liquidity cap.
It settles pending fees using the position’s liquidity before the increase. Those fees and the unused deposit are added to the existing owed balances.
It records the combined liquidity and advances the fee checkpoints. The added liquidity earns only subsequent fee growth.

Fee settlement rounds down to whole base units at each checkpoint. See LP fee entitlements and rounding rules.

After a full decrease

The contract supports adding liquidity to an unburned, fully decreased position. If its boundary ticks were removed, the increase recreates them with fresh fee-growth-outside values. Fetch current insertion hints before submitting; a stale hint rejects the transaction.After acceptance, use the replacement PositionNFT for the next operation on this position.

Next steps

Decreasing liquidity to remove funds from the position.
Collecting and burning to collect fees and close the position.

Start

Trade

Provide liquidity

Integration guides

How an increase works

In the app

Add funds

Troubleshooting

Next steps

Find the position and add funds

Step 1: Find the position

Step 2: Increase

Step 1: Find the position

Step 2: Increase

Step 1: Find the position

Step 2: Increase

How it works on chain

What changes

How liquidity and fees are recorded

After a full decrease

Next steps

​How an increase works

​In the app

​Add funds

​Troubleshooting

​Next steps

​Find the position and add funds

​Step 1: Find the position

​Step 2: Increase

​Step 1: Find the position

​Step 2: Increase

​Step 1: Find the position

​Step 2: Increase

​How it works on chain

​What changes

​How liquidity and fees are recorded

​After a full decrease

​Next steps

How an increase works

In the app

Add funds

Troubleshooting

Next steps

Find the position and add funds

Step 1: Find the position

Step 2: Increase

Step 1: Find the position

Step 2: Increase

Step 1: Find the position

Step 2: Increase

How it works on chain

What changes

How liquidity and fees are recorded

After a full decrease

Next steps