Class: Positions

Manages current-contract concentrated-liquidity positions.

Example

const positions = gSwap.positions;
const mine = await positions.getUserPositions('client|012345678901234567890123');
console.log(mine.length);

Constructors

Constructor

new Positions(gateway, symbols, signer?, walletAddress?, options?): Positions

Parameters

Parameter	Type
gateway	PositionGateway
symbols	PositionSymbols
signer?	GalaChainSigner
walletAddress?	string
options?	PositionsOptions

Returns

Positions

Methods

addLiquidityByPrice()

addLiquidityByPrice(args): Promise<SubmittedTransaction<Position | null>>

Adds liquidity from prices, flooring the lower tick and ceiling the upper tick to fee spacing. The resulting range is therefore no narrower than the requested price interval.

Parameters

Parameter	Type	Description
args	{ amount: NumericAmount; amountIsToken0: boolean; fee: FEE_TIER; maxPrice: PriceIn; minPrice: PriceIn; token0: TokenRef; token1: TokenRef; uniqueKey?: string; }	Pair, fee, price range, deposit amount, and caller-side token index.
args.amount	NumericAmount	-
args.amountIsToken0	boolean	-
args.fee	FEE_TIER	-
args.maxPrice	PriceIn	-
args.minPrice	PriceIn	-
args.token0	TokenRef	-
args.token1	TokenRef	-
args.uniqueKey?	string	The attempt's uniqueKey; default a fresh one (see AddLiquidityArgs.uniqueKey).

Returns

Promise<SubmittedTransaction<Position | null>>

The synchronously submitted transaction.

Example

const tx = await gSwap.positions.addLiquidityByPrice({
  token0: 'GALA', token1: 'GUSDC', fee: 3000,
  minPrice: '0.14', maxPrice: '0.16', amount: '100', amountIsToken0: true,
});

---

addLiquidityByTicks()

addLiquidityByTicks(args): Promise<SubmittedTransaction<Position | null>>

Adds liquidity using an explicit tick range. Exactly one canonical deposit field is emitted.

Parameters

Parameter	Type	Description
args	AddLiquidityArgs	Pair, fee, range, deposit amount, and caller-side token index.

Returns

Promise<SubmittedTransaction<Position | null>>

The synchronously submitted transaction.

Example

const tx = await gSwap.positions.addLiquidityByTicks({
  token0: 'GALA', token1: 'GUSDC', fee: 3000,
  tickLower: -19200, tickUpper: 12000, amount: '100', amountIsToken0: true,
});
await tx.confirm();

---

buildAddLiquidity()

buildAddLiquidity(args): Promise<AddLiquidityDTO>

Builds the AddLiquidity DTO that addLiquidityByTicks would sign, without signing or sending it: to show in an approval popup, or to sign elsewhere. Submit exactly this DTO with submitAddLiquidity. The pure counterpart, with canonical inputs and no resolution, is buildAddLiquidityDto.

Parameters

Parameter	Type
args	AddLiquidityArgs

Returns

Promise<AddLiquidityDTO>

Example

const dto = await gSwap.positions.buildAddLiquidity({
  token0: 'GALA', token1: 'GUSDC', fee: 3000,
  tickLower: -19200, tickUpper: 12000, amount: '100', amountIsToken0: true,
});

---

buildCollectPositionFees()

buildCollectPositionFees(args): Promise<CollectPositionFeesDTO>

Builds the CollectPositionFees DTO that collectPositionFees would sign, without signing or sending it. Submit exactly this DTO with submitCollectPositionFees. The pure counterpart is buildCollectPositionFeesDto.

Parameters

Parameter	Type
args	CollectPositionFeesArgs

Returns

Promise<CollectPositionFeesDTO>

---

buildCreatePool()

buildCreatePool(args): Promise<CreatePoolDTO>

Builds the CreatePool DTO that createPool would sign, without signing or sending it: symbols resolved or proposed, the pair put in canonical order and the price inverted when it was reversed. Submit exactly this DTO with submitCreatePool. The pure counterpart, with canonical inputs, is buildCreatePoolDto.

Parameters

Parameter	Type
args	CreatePoolArgs

Returns

Promise<CreatePoolDTO>

---

buildRemoveLiquidity()

buildRemoveLiquidity(args): Promise<RemoveLiquidityDTO>

Builds the RemoveLiquidity DTO that removeLiquidity would sign, without signing or sending it. Submit exactly this DTO with submitRemoveLiquidity. The pure counterpart is buildRemoveLiquidityDto.

Parameters

Parameter	Type
args	RemoveLiquidityArgs

Returns

Promise<RemoveLiquidityDTO>

---

collectPositionFees()

collectPositionFees(args): Promise<SubmittedTransaction<Position | null>>

Collects all accrued fees for a position; the contract does not support partial collection.

Parameters

Parameter	Type	Description
args	CollectPositionFeesArgs	Pair, fee, and tick range identifying the position.

Returns

Promise<SubmittedTransaction<Position | null>>

The synchronously submitted transaction.

Example

const tx = await gSwap.positions.collectPositionFees({
  token0: 'GALA', token1: 'GUSDC', fee: 3000,
  tickLower: -19200, tickUpper: 12000,
});

---

createPool()

createPool(args): Promise<SubmittedTransaction<Position | null>>

Creates a pool, resolving registered trading symbols. Reversed symbol order inverts the supplied starting price or square-root price.

A token class key carries no symbol, so for a token being proposed into the v2 trading-symbol registry for the first time (no existing pool has registered it yet) the caller MUST pass token0Symbol/token1Symbol (the token class's symbol, from the token list or FetchTokenClasses). The SDK never derives a symbol from the key, and throws a TOKEN_SYMBOL_NOT_REGISTERED error when an unregistered token has none. For an already-registered token a supplied symbol must match the registered one.

Parameters

Parameter	Type	Description
args	CreatePoolArgs	Token class keys or references, fee, exactly one starting price field, and privacy options.

Returns

Promise<SubmittedTransaction<Position | null>>

The synchronously submitted transaction.

Example

const tx = await gSwap.positions.createPool({
  token0: 'GALA|Unit|none|none', token1: 'GUSDC|Unit|none|none', fee: 3000,
  startingPrice: '0.15',
});

---

estimateAddLiquidity()

estimateAddLiquidity(args): Promise<AddLiquidityEstimate>

Estimates the other token amount and resulting liquidity for a deposit.

Parameters

Parameter	Type	Description
args	{ amount: NumericAmount; amountIsToken0: boolean; fee: FEE_TIER; tickLower: number; tickUpper: number; token0: TokenRef; token1: TokenRef; }	Pair, tick range, deposit amount, and the amount's caller-side token index.
args.amount	NumericAmount	-
args.amountIsToken0	boolean	-
args.fee	FEE_TIER	-
args.tickLower	number	-
args.tickUpper	number	-
args.token0	TokenRef	-
args.token1	TokenRef	-

Returns

Promise<AddLiquidityEstimate>

Backend liquidity estimate.

Example

const estimate = await gSwap.positions.estimateAddLiquidity({
  token0: 'GALA', token1: 'GUSDC', fee: 3000,
  tickLower: -19200, tickUpper: 12000, amount: '100', amountIsToken0: true,
});

---

estimateRemoveLiquidity()

estimateRemoveLiquidity(args): Promise<RemoveLiquidityEstimate>

Estimates token amounts released by burning liquidity.

Parameters

Parameter	Type	Description
args	{ fee: FEE_TIER; liquidity: NumericAmount; tickLower: number; tickUpper: number; token0: TokenRef; token1: TokenRef; }	Pair, tick range, fee tier, and liquidity quantity.
args.fee	FEE_TIER	-
args.liquidity	NumericAmount	-
args.tickLower	number	-
args.tickUpper	number	-
args.token0	TokenRef	-
args.token1	TokenRef	-

Returns

Promise<RemoveLiquidityEstimate>

Estimated token0 and token1 quantities.

Example

const estimate = await gSwap.positions.estimateRemoveLiquidity({
  token0: 'GALA', token1: 'GUSDC', fee: 3000,
  tickLower: -19200, tickUpper: 12000, liquidity: '1000',
});

---

getPosition()

getPosition(args, signal?): Promise<Position | null>

Gets one position, normalizing a caller-supplied reversed pair to canonical symbol order. Reversed pairs also invert the price axis, so [lower, upper] becomes [-upper, -lower].

Parameters

Parameter	Type	Description
args	{ fee: FEE_TIER; owner: string; tickLower: number; tickUpper: number; token0: TokenRef; token1: TokenRef; }	Pair, owner, fee, and position tick range.
args.fee	FEE_TIER	-
args.owner	string	-
args.tickLower	number	-
args.tickUpper	number	-
args.token0	TokenRef	-
args.token1	TokenRef	-
signal?	AbortSignal	-

Returns

Promise<Position | null>

The position, or null when the backend returns 404.

Example

const position = await gSwap.positions.getPosition({
  token0: 'GALA', token1: 'GUSDC', owner: 'client|012345678901234567890123',
  fee: 3000, tickLower: -19200, tickUpper: 12000,
});

---

getUserPositions()

getUserPositions(owner): Promise<Position[]>

Gets all current-contract positions owned by an address.

Parameters

Parameter	Type	Description
owner	string	GalaChain owner identity.

Returns

Promise<Position[]>

Enriched positions from the v2 trade backend, token images included. A row that is not a usable position is skipped and reported to onInvalidEntry.

Example

const positions = await gSwap.positions.getUserPositions('client|012345678901234567890123');

---

readPosition()

readPosition(args, signal?): Promise<PositionRead>

Reads one position and classifies the outcome instead of throwing: found with the position (fees included), not_found (the backend's HTTP 404, which it sends only when the chain itself has no such position) or unknown (any other failure, carried as error). Use it to confirm a write: unknown is "no evidence either way", never a confirmed absence.

Only the caller's own abort rethrows. With a pass-through resolver (CanonicalSymbols) the pair and ticks go to the backend exactly as given and the backend orients them.

Parameters

Parameter	Type
args	{ fee: FEE_TIER; owner: string; tickLower: number; tickUpper: number; token0: TokenRef; token1: TokenRef; }
args.fee	FEE_TIER
args.owner	string
args.tickLower	number
args.tickUpper	number
args.token0	TokenRef
args.token1	TokenRef
signal?	AbortSignal

Returns

Promise<PositionRead>

Example

const read = await gSwap.positions.readPosition({
  token0: 'GALA', token1: 'GUSDC', owner: 'client|012345678901234567890123',
  fee: 3000, tickLower: -19200, tickUpper: 12000,
});
if (read.kind === 'found') console.log(read.data.fees0);

---

removeLiquidity()

removeLiquidity(args): Promise<SubmittedTransaction<Position | null>>

Removes liquidity by withdrawing at most one canonical token quantity. Omitting both amounts closes the position and sweeps all accrued fees.

Parameters

Parameter	Type	Description
args	RemoveLiquidityArgs	Pair, fee, range, and optional caller-side withdrawal amount.

Returns

Promise<SubmittedTransaction<Position | null>>

The synchronously submitted transaction.

Example

const tx = await gSwap.positions.removeLiquidity({
  token0: 'GALA', token1: 'GUSDC', fee: 3000,
  tickLower: -19200, tickUpper: 12000,
});

---

submitAddLiquidity()

submitAddLiquidity(dto): Promise<SubmittedTransaction<Position | null>>

Signs and submits a DTO built by buildAddLiquidity or buildAddLiquidityDto; it must be exactly what the builder produces. The returned transaction confirms by proving the position's liquidity grew.

Parameters

Parameter	Type
dto	AddLiquidityDTO

Returns

Promise<SubmittedTransaction<Position | null>>

---

submitCollectPositionFees()

submitCollectPositionFees(dto): Promise<SubmittedTransaction<Position | null>>

Signs and submits a DTO built by buildCollectPositionFees or buildCollectPositionFeesDto; it must be exactly what the builder produces.

Parameters

Parameter	Type
dto	CollectPositionFeesDTO

Returns

Promise<SubmittedTransaction<Position | null>>

---

submitCreatePool()

submitCreatePool(dto): Promise<SubmittedTransaction<Position | null>>

Signs and submits a DTO built by buildCreatePool or buildCreatePoolDto; it must be exactly what the builder produces. The returned transaction confirms by the pool existing, and the cached symbol registry is dropped, since the pool may have registered new symbols.

Parameters

Parameter	Type
dto	CreatePoolDTO

Returns

Promise<SubmittedTransaction<Position | null>>

---

submitRemoveLiquidity()

submitRemoveLiquidity(dto): Promise<SubmittedTransaction<Position | null>>

Signs and submits a DTO built by buildRemoveLiquidity or buildRemoveLiquidityDto; it must be exactly what the builder produces. A DTO with no withdrawal quantity closes the position, and the returned transaction then confirms by proving the position is gone.

Parameters

Parameter	Type
dto	RemoveLiquidityDTO

Returns

Promise<SubmittedTransaction<Position | null>>