Manage liquidity with the TypeScript SDK

A Shield Swap position has public economic state and a PositionNFT record. The record authorizes position changes. Its token ID remains stable while replacement records are issued through the position lifecycle.

Preview a position

Choose a pool and read balances for both tokens. previewMint aligns the range to tick spacing, calculates the supported liquidity, and reports the token amounts the position would consume.

const { data: pools } = await client.api.getPools({ limit: 20 })
const market = pools.find((pool) => pool.token0_info && pool.token1_info)
if (!market) throw new Error("no pool with token metadata")

const balances = await client.getBalances({
  tokens: [market.token0, market.token1],
})

const preview = await client.previewMint({
  poolKey: market.key,
  amount0Desired: (balances[market.token0]?.private ?? 0n) / 10n,
  amount1Desired: (balances[market.token1]?.private ?? 0n) / 10n,
  rangePercent: 5,
})

if (preview.liquidity === 0n) {
  throw new Error("deposit is too small for this range")
}

You can pass tickLower and tickUpper together instead of rangePercent. preview.inRange tells you whether the position will earn fees at the current tick. State can move between preview and finalization, so set minimum amounts when the application needs tighter deposit protection.

Mint

Resolve token programs, then use the aligned range and consumed amounts returned by the preview.

const token0 = await client.tokenData(market.token0)
const token1 = await client.tokenData(market.token1)
if (!token0.ammTokenProgram || !token1.ammTokenProgram) {
  throw new Error("pool token program is missing")
}

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

const minted = await client.mint({
  poolKey: market.key,
  tickLower: preview.tickLower,
  tickUpper: preview.tickUpper,
  amount0Desired: preview.amount0,
  amount1Desired: preview.amount1,
  recipient: account.address,
  withdrawal: account.address,
  imports,
})

if (!minted.positionTokenId) {
  throw new Error("position token ID is not available yet")
}

const positionTokenId = minted.positionTokenId

recipient receives the PositionNFT and controls the position. withdrawal receives every later collect payout. The withdrawal address is fixed at mint and cannot be changed. Confirm both addresses before submission. They may be different from each other and from the transaction signer. Mint creates the first PositionNFT. Store its token ID and wait for the new record before offering another position action.

Find owned positions

const positions = await client.getOwnedPositions()

const position = await client.getOwnedPosition({
  positionTokenId,
})

Mapping state may appear before the replacement record reaches the scanner. Poll for the expected record after each accepted action.

Increase liquidity

An increase spends the current position record and both token records. It keeps the same position token ID and issues an updated PositionNFT.

await client.increaseLiquidity({
  poolKey: market.key,
  positionTokenId,
  amount0Desired: 100_000n,
  amount1Desired: 200_000n,
  imports,
})

The tick range and withdrawal address do not change. A local-key client can select records through its scanner. A wallet client must supply its position and token record requests.

Decrease and collect

decreaseLiquidity moves principal and accrued fees into the position’s owed balances. It does not transfer token records to the LP.

await client.decreaseLiquidity({
  poolKey: market.key,
  positionTokenId,
  liquidityToRemove: 500_000n,
})

await client.collect({
  poolKey: market.key,
  positionTokenId,
  amount0Requested: 100_000n,
  amount1Requested: 200_000n,
  imports,
})

Collect sends token records to the immutable withdrawal address stored in the PositionNFT. It has no recipient parameter. Increase, decrease, and collect each consume the current position record and issue a replacement, so wait for that replacement before the next action.

Close the position

Burn succeeds after liquidity and both owed balances reach zero.

await client.burn({
  poolKey: market.key,
  positionTokenId,
})

The closing order is:

Decrease all remaining liquidity.
Collect all owed token amounts.
Confirm the latest replacement PositionNFT is available.
Burn the empty position.

Burn consumes the final record and removes the public position. It does not issue a replacement. See Liquidity provider workflow, minting a position, and collecting and burning for the contract-level behavior.

Start

Build

Trade

Provide liquidity

Manage liquidity with the TypeScript SDK

Preview a position

Mint

Find owned positions

Increase liquidity

Decrease and collect

Close the position

​Preview a position

​Mint

​Find owned positions

​Increase liquidity

​Decrease and collect

​Close the position

Preview a position

Mint

Find owned positions

Increase liquidity

Decrease and collect

Close the position