Class: Positions

Handles position management operations for liquidity positions.

Constructors

Constructor

new Positions(
   gatewayBaseUrl, 
   dexContractBasePath, 
   bundlerService, 
   poolService, 
   httpClient, 
   options?): Positions;

Parameters

Parameter	Type
`gatewayBaseUrl`	`string`
`dexContractBasePath`	`string`
`bundlerService`	`Bundler`
`poolService`	`Pools`
`httpClient`	`HttpClient`
`options?`	{ `walletAddress?`: `string`; }
`options.walletAddress?`	`string`

Returns

Positions

Methods

addLiquidityByPrice()

addLiquidityByPrice(args): Promise<PendingTransaction>;

Creates a new position or adds liquidity to a position, using a specified price range. Note that this method automatically converts your minPrice and maxPrice to ticks, rounding down if necessary.

Parameters

Parameter	Type	Description
`args`	{ `amount0Desired`: `NumericAmount`; `amount0Min`: `NumericAmount`; `amount1Desired`: `NumericAmount`; `amount1Min`: `NumericAmount`; `fee`: `number`; `maxPrice`: `PriceIn`; `minPrice`: `PriceIn`; `positionId`: `string`; `tickSpacing`: `number`; `token0`: \| `string` \| `GalaChainTokenClassKey`; `token1`: \| `string` \| `GalaChainTokenClassKey`; `walletAddress?`: `string`; }	Parameters for adding liquidity.
`args.amount0Desired`	`NumericAmount`	Desired (also maximum) amount of token0 to add.
`args.amount0Min`	`NumericAmount`	Minimum amount of token0 to add (slippage protection).
`args.amount1Desired`	`NumericAmount`	Desired (also maximum) amount of token1 to add.
`args.amount1Min`	`NumericAmount`	Minimum amount of token1 to add (slippage protection).
`args.fee`	`number`	The pool fee tier.
`args.maxPrice`	`PriceIn`	The maximum price for the position range.
`args.minPrice`	`PriceIn`	The minimum price for the position range.
`args.positionId`	`string`	The position identifier. This should be an empty string if you are creating a new position.
`args.tickSpacing`	`number`	The tick spacing for the pool.
`args.token0`	\| `string` \| `GalaChainTokenClassKey`	The first token in the pair.
`args.token1`	\| `string` \| `GalaChainTokenClassKey`	The second token in the pair.
`args.walletAddress?`	`string`	The wallet address adding liquidity.

Returns

Promise<PendingTransaction>

Pending transaction.

Example

const result = await gSwap.positions.addLiquidityByPrice({
  walletAddress: 'eth|123...abc',
  positionId: '',
  token0: 'GALA|Unit|none|none',
  token1: 'GUSDC|Unit|none|none',
  fee: 500,
  tickSpacing: 10,
  minPrice: '0.45',
  maxPrice: '0.55',
  amount0Desired: '100',
  amount1Desired: '50',
  amount0Min: '95',
  amount1Min: '47.5'
});
console.log('Liquidity added with price range:', result);

addLiquidityByTicks()

addLiquidityByTicks(args): Promise<PendingTransaction>;

Creates a new position or adds liquidity to a position, using a specific tick range. Consider using addLiquidityByPrice() instead unless you want to use ticks directly.

Parameters

Parameter	Type	Description
`args`	{ `amount0Desired`: `NumericAmount`; `amount0Min`: `NumericAmount`; `amount1Desired`: `NumericAmount`; `amount1Min`: `NumericAmount`; `fee`: `FEE_TIER`; `positionId`: `string`; `tickLower`: `number`; `tickUpper`: `number`; `token0`: \| `string` \| `GalaChainTokenClassKey`; `token1`: \| `string` \| `GalaChainTokenClassKey`; `walletAddress?`: `string`; }	Parameters for adding liquidity.
`args.amount0Desired`	`NumericAmount`	Desired (also maximum) amount of token0 to add.
`args.amount0Min`	`NumericAmount`	Minimum amount of token0 to add (slippage protection).
`args.amount1Desired`	`NumericAmount`	Desired (also maximum) amount of token1 to add.
`args.amount1Min`	`NumericAmount`	Minimum amount of token1 to add (slippage protection).
`args.fee`	`FEE_TIER`	The pool fee tier.
`args.positionId`	`string`	The position identifier. If you're creating a new position, this should be an empty string.
`args.tickLower`	`number`	The lower tick of the position range.
`args.tickUpper`	`number`	The upper tick of the position range.
`args.token0`	\| `string` \| `GalaChainTokenClassKey`	The first token in the pair.
`args.token1`	\| `string` \| `GalaChainTokenClassKey`	The second token in the pair.
`args.walletAddress?`	`string`	The wallet address adding liquidity.

Returns

Promise<PendingTransaction>

Pending transaction.

Example

const result = await gSwap.positions.addLiquidityByTicks({
  walletAddress: 'eth|123...abc',
  positionId: '',
  token0: 'GALA|Unit|none|none',
  token1: 'GUSDC|Unit|none|none',
  fee: 500,
  tickSpacing: 10,
  tickLower: -6000,
  tickUpper: 6000,
  amount0Desired: '100',
  amount1Desired: '50',
  amount0Min: '95',
  amount1Min: '47.5'
});
console.log('Liquidity added:', result);

calculateOptimalPositionSize()

calculateOptimalPositionSize(
   tokenAmount, 
   spotPrice, 
   lowerPrice, 
   upperPrice, 
   tokenDecimals, 
   otherTokenDecimals): BigNumber;

Parameters

Parameter	Type
`tokenAmount`	`NumericAmount`
`spotPrice`	`NumericAmount`
`lowerPrice`	`NumericAmount`
`upperPrice`	`NumericAmount`
`tokenDecimals`	`number`
`otherTokenDecimals`	`number`

Returns

BigNumber

collectPositionFees()

collectPositionFees(args): Promise<PendingTransaction>;

Collects accumulated fees from a liquidity position.

Parameters

Parameter	Type	Description
`args`	{ `amount0Requested`: `NumericAmount`; `amount1Requested`: `NumericAmount`; `fee`: `number`; `positionId`: `string`; `tickLower`: `number`; `tickUpper`: `number`; `token0`: \| `string` \| `GalaChainTokenClassKey`; `token1`: \| `string` \| `GalaChainTokenClassKey`; `walletAddress?`: `string`; }	Parameters for collecting fees.
`args.amount0Requested`	`NumericAmount`	Desired amount of token0 fees to collect.
`args.amount1Requested`	`NumericAmount`	Desired amount of token1 fees to collect.
`args.fee`	`number`	The pool fee tier.
`args.positionId`	`string`	The position identifier.
`args.tickLower`	`number`	The lower tick of the position range.
`args.tickUpper`	`number`	The upper tick of the position range.
`args.token0`	\| `string` \| `GalaChainTokenClassKey`	The first token in the pair.
`args.token1`	\| `string` \| `GalaChainTokenClassKey`	The second token in the pair.
`args.walletAddress?`	`string`	The wallet address collecting fees.

Returns

Promise<PendingTransaction>

Pending transaction.

Example

// Collect all accumulated fees from a position
const result = await gSwap.positions.collectPositionFees({
  walletAddress: 'eth|123...abc',
  positionId: 'position-123',
  token0: 'GALA|Unit|none|none',
  token1: 'GUSDC|Unit|none|none',
  fee: 500,
  tickLower: -6000,
  tickUpper: 6000,
  amount0Requested: '1000000000000000000', // Max fees available
  amount1Requested: '500000000' // Max fees available
});
console.log('Fees collected:', result);

estimateRemoveLiquidity()

estimateRemoveLiquidity(args): Promise<{
  amount0: BigNumber;
  amount1: BigNumber;
}>;

Estimates the token amounts that would be received from removing liquidity from a position.

Parameters

Parameter	Type	Description
`args`	{ `amount`: `NumericAmount`; `fee`: `number`; `ownerAddress`: `string`; `positionId`: `string`; `tickLower`: `number`; `tickUpper`: `number`; `token0`: \| `string` \| `GalaChainTokenClassKey`; `token1`: \| `string` \| `GalaChainTokenClassKey`; }	Parameters for estimating liquidity removal.
`args.amount`	`NumericAmount`	The amount of liquidity to remove.
`args.fee`	`number`	The pool fee tier.
`args.ownerAddress`	`string`	The wallet address that owns the position.
`args.positionId`	`string`	The position identifier.
`args.tickLower`	`number`	The lower tick of the position range.
`args.tickUpper`	`number`	The upper tick of the position range.
`args.token0`	\| `string` \| `GalaChainTokenClassKey`	The first token in the pair.
`args.token1`	\| `string` \| `GalaChainTokenClassKey`	The second token in the pair.

Returns

Promise<{ amount0: BigNumber; amount1: BigNumber; }>

Estimated token amounts that would be received.

Example

const estimation = await gSwap.positions.estimateRemoveLiquidity({
  ownerAddress: 'client|635f048ab243d7eb7f5ba044',
  positionId: '210f8e4dd1bbe1b4af4b977330ee7e4b68bc716f66e39c87a60fff0976ded3ea',
  token0: 'GALA|Unit|none|none',
  token1: 'GUSDT|Unit|none|none',
  fee: 3000,
  tickLower: -41100,
  tickUpper: -40080,
  amount: '1491.973332758921980256'
});
console.log('Estimated tokens:', estimation);

getPosition()

getPosition(ownerAddress, position): Promise<GetPositionResult>;

Gets detailed information about a specific liquidity position.

Parameters

Parameter	Type	Description
`ownerAddress`	`string`	The wallet address that owns the position.
`position`	{ `fee`: `number`; `tickLower`: `number`; `tickUpper`: `number`; `token0ClassKey`: \| `string` \| `GalaChainTokenClassKey`; `token1ClassKey`: \| `string` \| `GalaChainTokenClassKey`; }	Position parameters including tokens, fee, and tick range.
`position.fee`	`number`	The pool fee tier.
`position.tickLower`	`number`	The lower tick of the position range.
`position.tickUpper`	`number`	The upper tick of the position range.
`position.token0ClassKey`	\| `string` \| `GalaChainTokenClassKey`	The first token in the position.
`position.token1ClassKey`	\| `string` \| `GalaChainTokenClassKey`	The second token in the position.

Returns

Promise<GetPositionResult>

Detailed position information.

Example

const position = await gSwap.positions.getPosition('eth|123...abc', {
  token0ClassKey: 'GALA|Unit|none|none',
  token1ClassKey: 'GUSDC|Unit|none|none',
  fee: 500,
  tickLower: -6000,
  tickUpper: 6000
});
console.log('Position:', position);

getPositionById()

getPositionById(ownerAddress, positionId): Promise<undefined | GetPositionResult>;

Gets detailed information about a liquidity position by its ID.

Parameters

Parameter	Type	Description
`ownerAddress`	`string`	The wallet address that owns the position.
`positionId`	`string`	The unique identifier of the position.

Returns

Promise<undefined | GetPositionResult>

Detailed position information, or undefined if not found.

Example

const position = await gSwap.positions.getPositionById('eth|123...abc', 'position-uuid-123');
if (position) {
  console.log('Position found:', position);
} else {
  console.log('Position not found');
}

getUserPositions()

getUserPositions(
   ownerAddress, 
   limit?, 
   bookmark?): Promise<{
  bookmark: string;
  positions: GetUserPositionsResult[];
}>;

Get all liquidity positions for a specific wallet address.

Parameters

Parameter	Type	Description
`ownerAddress`	`string`	The wallet address to get positions for.
`limit?`	`number`	Maximum number of positions to return.
`bookmark?`	`string`	Pagination bookmark for retrieving additional results. If you call this function and it returns a bookmark that is not an empty string, you can pass that bookmark as this parameter in a subsequent call to fetch the next page.

Returns

Promise<{ bookmark: string; positions: GetUserPositionsResult[]; }>

User positions and pagination bookmark

Example

const positions = await gSwap.positions.getUserPositions('eth|123...abc');
console.log(positions);

removeLiquidity()

removeLiquidity(args): Promise<PendingTransaction>;

Removes liquidity from a position.

Parameters

Parameter	Type	Description
`args`	{ `amount`: `NumericAmount`; `amount0Min?`: `NumericAmount`; `amount1Min?`: `NumericAmount`; `fee`: `number`; `positionId`: `string`; `tickLower`: `number`; `tickUpper`: `number`; `token0`: \| `string` \| `GalaChainTokenClassKey`; `token1`: \| `string` \| `GalaChainTokenClassKey`; `walletAddress?`: `string`; }	Parameters for removing liquidity.
`args.amount`	`NumericAmount`	The amount of liquidity to remove.
`args.amount0Min?`	`NumericAmount`	Minimum amount of token0 to receive (slippage protection, optional).
`args.amount1Min?`	`NumericAmount`	Minimum amount of token1 to receive (slippage protection, optional).
`args.fee`	`number`	The pool fee tier.
`args.positionId`	`string`	The position identifier.
`args.tickLower`	`number`	The lower tick of the position range.
`args.tickUpper`	`number`	The upper tick of the position range.
`args.token0`	\| `string` \| `GalaChainTokenClassKey`	The first token in the pair.
`args.token1`	\| `string` \| `GalaChainTokenClassKey`	The second token in the pair.
`args.walletAddress?`	`string`	The wallet address removing liquidity.

Returns

Promise<PendingTransaction>

Pending transaction.

Example

// Remove 50% of liquidity from a position
const result = await gSwap.positions.removeLiquidity({
  walletAddress: 'eth|123...abc',
  positionId: 'position-123',
  token0: 'GALA|Unit|none|none',
  token1: 'GUSDC|Unit|none|none',
  fee: 500,
  tickLower: -6000,
  tickUpper: 6000,
  amount: '50000000000000000000', // 50% of position liquidity
  amount0Min: '45',
  amount1Min: '22'
});
console.log('Liquidity removed:', result);

Constructors​

Constructor​

Parameters​

Returns​

Methods​

addLiquidityByPrice()​

Parameters​

Returns​

Example​

addLiquidityByTicks()​

Parameters​

Returns​

Example​

calculateOptimalPositionSize()​

Parameters​

Returns​

collectPositionFees()​

Parameters​

Returns​

Example​

estimateRemoveLiquidity()​

Parameters​

Returns​

Example​

getPosition()​

Parameters​

Returns​

Example​

getPositionById()​

Parameters​

Returns​

Example​

getUserPositions()​

Parameters​

Returns​

Example​

removeLiquidity()​

Parameters​

Returns​

Example​

Constructors

Constructor

Parameters

Returns

Methods

addLiquidityByPrice()

Parameters

Returns

Example

addLiquidityByTicks()

Parameters

Returns

Example

calculateOptimalPositionSize()

Parameters

Returns

collectPositionFees()

Parameters

Returns

Example

estimateRemoveLiquidity()

Parameters

Returns

Example

getPosition()

Parameters

Returns

Example

getPositionById()

Parameters

Returns

Example

getUserPositions()

Parameters

Returns

Example

removeLiquidity()

Parameters

Returns

Example