Get Positions

Retrieve liquidity positions from Ferra pools.

Quick Start

// Get all user positions
const positions = await sdk.Position.getPositionList('0x...')

// Get single position
const position = await sdk.Position.getPositionById('0x...')

Get User Positions

const userAddress = '0x...'

// All positions
const allPositions = await sdk.Position.getPositionList(userAddress)

// Filter by pools
const poolIds = ['0xpool1...', '0xpool2...']
const poolPositions = await sdk.Position.getPositionList(userAddress, poolIds)

// Without display data (faster)
const positions = await sdk.Position.getPositionList(userAddress, [], false)

Get Single Position

const positionId = '0x...'

// With rewards
const position = await sdk.Position.getPositionById(positionId)

// Without rewards (faster)
const position = await sdk.Position.getPositionById(positionId, false)

Position Data

interface Position {
  pos_object_id: string
  owner: string
  pool: string
  
  // Price range
  tick_lower_index: number
  tick_upper_index: number
  liquidity: string
  
  // Tokens
  coin_type_a: string
  coin_type_b: string
  
  // Fees (if calculated)
  fee_owed_a?: string
  fee_owed_b?: string
}

Get Token Amounts

const lowerSqrtPrice = TickMath.tickIndexToSqrtPriceX64(
    position.tick_lower_index
  );
  const upperSqrtPrice = TickMath.tickIndexToSqrtPriceX64(
    position.tick_upper_index
  );
  
  const liquidity = new BN(position.liquidity);
  const slippage = new Percentage(new BN(0), new BN(1000));
  const curSqrtPrice = new BN(pool.current_sqrt_price);
  const coinAmounts = ClmmPoolUtil.getCoinAmountFromLiquidity(
    liquidity,
    curSqrtPrice,
    lowerSqrtPrice,
    upperSqrtPrice,
    true
  );

  const { tokenMaxA, tokenMaxB } = adjustForCoinSlippage(
    coinAmounts,
    slippage,
    false
  );
  
  const amountA = tokenMaxA.toNumber();
  const amountB = tokenMaxB.toNumber();
  
  console.log(amountA, amountB)

Get Position Fees

// Single position
const fees = await sdk.Position.calculateFee({
  pool_id: poolId,
  pos_id: positionId,
  coinTypeA: '0x2::sui::SUI',
  coinTypeB: '0x...::usdc::USDC'
})

console.log('Fees:', fees.feeOwedA, fees.feeOwedB)

// Multiple positions
const positionIds = ['0x1...', '0x2...']
const allFees = await sdk.Position.batchFetchPositionFees(positionIds)

Filter Positions

Active Positions

const activePositions = positions.filter(
  pos => BigInt(pos.liquidity) > 0n
)

In-Range Positions

const pool = await sdk.Pool.getPool(poolId)
const currentTick = pool.current_tick_index

const inRange = positions.filter(pos => 
  pos.tick_lower_index <= currentTick && 
  currentTick < pos.tick_upper_index
)

By Token Pair

const suiUsdc = positions.filter(pos =>
  pos.coin_type_a.includes('sui') && 
  pos.coin_type_b.includes('usdc')
)

Complete Example

// 1. Get all user positions
const userAddress = '0x...'
const positions = await sdk.Position.getPositionList(userAddress)

// 2. Check each position
for (const pos of positions) {
  // Get pool info
  const pool = await sdk.Pool.getPool(pos.pool)
  
  // Check if in range
  const inRange = pos.tick_lower_index <= pool.current_tick_index && 
                  pool.current_tick_index < pos.tick_upper_index
  
  // Calculate fees
  const fees = await sdk.Position.calculateFee({
    pool_id: pos.pool,
    pos_id: pos.pos_object_id,
    coinTypeA: pos.coin_type_a,
    coinTypeB: pos.coin_type_b
  })
  
  console.log({
    position: pos.pos_object_id,
    liquidity: pos.liquidity,
    inRange,
    fees: {
      tokenA: fees.feeOwedA,
      tokenB: fees.feeOwedB
    }
  })
}

Transaction History

const history = await sdk.Position.getPositionTransactionList({
  posId: positionId,
  paginationArgs: { limit: 10 }
})

history.data.forEach(tx => {
  console.log(tx.type, tx.timestamp)
})

Error Handling

try {
  const position = await sdk.Position.getPositionById(posId)
} catch (error) {
  console.log('Position not found')
}