Adjusting Position Liquidity

1. Overview of Adjusting Liquidity

The SDK functions for increasing or decreasing liquidity work similarly, enabling you to modify the liquidity of an existing position. You can specify the liquidity directly or provide amounts of token A or token B to increase or decrease liquidity. With these functions, you can:

Increase liquidity to potentially earn more fees as trading volume grows.
Decrease liquidity to reduce exposure or withdraw profits.

2. Getting Started Guide

Once you’ve opened a position in an Orca Whirlpool, you may need to adjust the amount of liquidity you’ve provided to align with market conditions or your strategy. Whether you want to add more liquidity to capture additional fees or withdraw liquidity to reduce exposure or realize profits, the Whirlpools SDK provides functions for both. This guide explains how to use the SDK functions to increase and decrease the liquidity in your position. The SDK also provides quote functions (ex. increaseLiquidityQuoteByInputToken, decreaseLiquidityQuoteByLiquidity) to help estimate the tokenIn/Out from the liquidity operation.

Using Whirlpool Client

Use the Position class from the WhirlpoolClient to fetch and manage your liquidity. Read below for more on the relationship between quote and the transaction.

TypeScript

import { exit } from "node:process";
import { Percentage } from "@orca-so/common-sdk";
import {
	buildWhirlpoolClient,
	increaseLiquidityQuoteByInputToken,
	TokenExtensionUtil,
} from "@orca-so/whirlpools-sdk";
import { PublicKey } from "@solana/web3.js";
import Decimal from "decimal.js";
import { getCtx } from "../utils";

const ctx = getCtx();
const client = buildWhirlpoolClient(ctx);

const whirlpoolAddress = new PublicKey(
	"3KBZiL2g8C7tiJ32hTv5v3KM7aK9htpqTw4cTXz1HvPt",
); // SOL/devUSDC
const positionAddress = new PublicKey(
	"HUy5LwdpfXBmqmDkWbE6CRFKokBX1PKVqujTexCHkBqp",
);

const whirlpool = await client.getPool(whirlpoolAddress);
const whirlpoolData = await ctx.fetcher.getPool(whirlpoolAddress);
const position = await client.getPosition(positionAddress);
const positionData = await ctx.fetcher.getPosition(positionAddress);

if (whirlpoolData == null || positionData === null) {
	console.log("Invalid whirlpool or position");
	exit();
}

const tokenExtensionCtx = await TokenExtensionUtil.buildTokenExtensionContext(
	ctx.fetcher,
	whirlpoolData,
);

const increase_quote = increaseLiquidityQuoteByInputToken(
	whirlpoolData.tokenMintA,
	new Decimal(1),
	positionData.tickLowerIndex,
	positionData.tickUpperIndex,
	Percentage.fromFraction(1, 100),
	whirlpool,
	tokenExtensionCtx,
);

const signature = await (
	await position.increaseLiquidity(increase_quote, true, ctx.wallet.publicKey)
).buildAndExecute();

console.log("Signature: ", signature);

The Manual Way

For each instruction, calculate the following values:

liquidityAmount - The total amount of liquidity you would like to deposit/withdraw into your position.
tokenMax A, B (increase_liquidity) - The maximum amount of token X to add to the position. Note the value here is shifted by the decimal places of the token.
tokenMin A, B (decrease_liquidity) - The minimum amount of token X to withdraw from the position. Note the value here is shifted by the decimal places of the token.

Getting a Quote

The Typescript SDK provides several quote functions to help generate an estimate based on common user input values.

Increase liquidity quote by input token amount

Given a desired amount of input token (A or B), you can use the quote utility function increaseLiquidityQuoteByInputTokenWithParams to calculate the liquidityAmount and other tokenMax value required to deposit the desired amount of token into the position. The quote amount will differ based on the current price (tick) and the desired tick boundaries for the position. The price environment may change from the time of quote to the actual processing of the increase_liquidity ix. Use the slippage tolerance to adjust the quote values to balance your risk of ix failure and total tokens to deposit.

TypeScript

import { exit } from "node:process";
import { Percentage } from "@orca-so/common-sdk";
import {
	buildWhirlpoolClient,
	increaseLiquidityQuoteByInputTokenWithParams,
	TokenExtensionUtil,
} from "@orca-so/whirlpools-sdk";
import { PublicKey } from "@solana/web3.js";
import BN from "bn.js";
import { getCtx } from "../utils";

const ctx = getCtx();
const client = buildWhirlpoolClient(ctx);

const whirlpoolAddress = new PublicKey(
	"3KBZiL2g8C7tiJ32hTv5v3KM7aK9htpqTw4cTXz1HvPt",
); // SOL/devUSDC
const positionAddress = new PublicKey(
	"HUy5LwdpfXBmqmDkWbE6CRFKokBX1PKVqujTexCHkBqp",
);

const whirlpoolData = await ctx.fetcher.getPool(whirlpoolAddress);
const position = await client.getPosition(positionAddress);
const positionData = await ctx.fetcher.getPosition(positionAddress);

if (whirlpoolData == null || positionData === null) {
	console.log("Invalid whirlpool or position");
	exit();
}

const tokenExtensionCtx = await TokenExtensionUtil.buildTokenExtensionContext(
	ctx.fetcher,
	whirlpoolData,
);

const quote = increaseLiquidityQuoteByInputTokenWithParams({
	tokenMintA: whirlpoolData.tokenMintA,
	tokenMintB: whirlpoolData.tokenMintB,
	tickCurrentIndex: whirlpoolData.tickCurrentIndex,
	sqrtPrice: whirlpoolData.sqrtPrice,
	inputTokenMint: whirlpoolData.tokenMintB,
	inputTokenAmount: new BN(1_000_000), // 1 devUSDC
	tickLowerIndex: positionData.tickLowerIndex,
	tickUpperIndex: positionData.tickUpperIndex,
	slippageTolerance: Percentage.fromFraction(1, 1000),
	tokenExtensionCtx,
});

const signature = await (
	await position.increaseLiquidity(quote, true, ctx.wallet.publicKey)
).buildAndExecute();

console.log("Signature: ", signature);

Decrease liquidity quote by input token amount

Given the liquidity amount, use the decreaseLiquidityQuoteByLiquidityWithParams util function to get an estimate on what’s the minimum token A & B you can expect from the decrease_liquidity instruction call. Like increase_liquidity, use the slippage tolerance to adjust the quote values to balance your risk of ix failure and total tokens to deposit.

TypeScript

import { exit } from "node:process";
import { Percentage } from "@orca-so/common-sdk";
import {
	buildWhirlpoolClient,
	decreaseLiquidityQuoteByLiquidityWithParams,
	TokenExtensionUtil,
} from "@orca-so/whirlpools-sdk";
import { PublicKey } from "@solana/web3.js";
import BN from "bn.js";
import { getCtx } from "../utils";

const ctx = getCtx();
const client = buildWhirlpoolClient(ctx);

const whirlpoolAddress = new PublicKey(
	"3KBZiL2g8C7tiJ32hTv5v3KM7aK9htpqTw4cTXz1HvPt",
); // SOL/devUSDC
const positionAddress = new PublicKey(
	"HUy5LwdpfXBmqmDkWbE6CRFKokBX1PKVqujTexCHkBqp",
);

const whirlpoolData = await ctx.fetcher.getPool(whirlpoolAddress);
const position = await client.getPosition(positionAddress);
const positionData = await ctx.fetcher.getPosition(positionAddress);

if (whirlpoolData == null || positionData === null) {
	console.log("Invalid whirlpool or position");
	exit();
}

const tokenExtensionCtx = await TokenExtensionUtil.buildTokenExtensionContext(
	ctx.fetcher,
	whirlpoolData,
);

// Example: Withdraw 30% of the position
const totalLiquidityInPosition = positionData.liquidity;
const withdrawLiquidityAmount = totalLiquidityInPosition
	.mul(new BN(30))
	.div(new BN(100));

const depositQuote = decreaseLiquidityQuoteByLiquidityWithParams({
	liquidity: withdrawLiquidityAmount,
	sqrtPrice: whirlpoolData.sqrtPrice,
	tickCurrentIndex: whirlpoolData.tickCurrentIndex,
	tickLowerIndex: positionData.tickLowerIndex,
	tickUpperIndex: positionData.tickUpperIndex,
	slippageTolerance: Percentage.fromFraction(1, 100),
	tokenExtensionCtx,
});

const signature = await (
	await position.decreaseLiquidity(depositQuote, true, ctx.wallet.publicKey)
).buildAndExecute();

console.log("Signature: ", signature);

3. Usage example

You are creating a bot to manage investors’ funds and want to optimize returns. Such a bot could rebalance liquidity based on market signals to maintain a specific target price range or to optimize fee collection during periods of high volatility.

4. Next steps

After adjusting liquidity, you can:

Monitor Performance: Track your adjusted position to evaluate its performance and earned fees.
Harvest Rewards: Collect any earned fees and rewards without closing your position.
Make Further Adjustments: Depending on market conditions, continue to adjust liquidity as needed to maximize returns or manage risk.

By using the SDK to adjust liquidity, you gain flexibility in managing your positions and optimizing your liquidity provision strategy.

Common Errors

LiquidityZero (0x177c) - Provided liquidity amount is zero.
LiquidityTooHigh (0x177d) - Provided liquidity exceeds u128::max.
TokenMaxExceeded (0x1781) - The required token to perform this operation exceeds the user defined amount in increase_liquidity.
TokenMinSubceeded (0x1782) - The required token to perform this operation subceeds the user defined amount in decrease_liquidity.
TickNotFound (0x1779) - The provided tick array accounts do not contain the tick specified in the position.
ConstraintRaw (0x7d3) - TokenVault, TokenAccount mints does not match the values in the provided whirlpool.

Getting Started

Architecture

SDKs

Examples

Resources

Reference

1. Overview of Adjusting Liquidity

2. Getting Started Guide

Using Whirlpool Client

The Manual Way

Getting a Quote

Increase liquidity quote by input token amount

Decrease liquidity quote by input token amount

3. Usage example

4. Next steps

Common Errors

​1. Overview of Adjusting Liquidity

​2. Getting Started Guide

​Using Whirlpool Client

​The Manual Way

​Getting a Quote

​Increase liquidity quote by input token amount

​Decrease liquidity quote by input token amount

​3. Usage example

​4. Next steps

​Common Errors

1. Overview of Adjusting Liquidity

2. Getting Started Guide

Using Whirlpool Client

The Manual Way

Getting a Quote

Increase liquidity quote by input token amount

Decrease liquidity quote by input token amount

3. Usage example

4. Next steps

Common Errors