Get Pair Bins

Retrieve detailed bin data for a specific trading pair within a given range. This method allows you to inspect liquidity distribution and reserves at each price level.

Prerequisites

Before fetching bin data:

• Have a valid LBPair object from getPair() or getPairs()

• Understand bin ID ranges and price relationships

• Know which bins to inspect (around active bin)

Basic Usage

// First, get the pair
const pair = await sdk.Pair.getPair(pairAddress);

// Fetch bins around the active bin
const activeId = pair.parameters.active_id;
const bins = await sdk.Pair.getPairBins(
  pair, 
  [activeId - 10, activeId + 10]  // 20 bins range
);

// Display bin reserves
bins.forEach((bin, index) => {
  const binId = activeId - 10 + index;
  console.log(`Bin ${binId}:`, {
    reserveX: bin.reserve_x.toString(),
    reserveY: bin.reserve_y.toString()
  });
});

Method Signature

async getPairBins(
  pair: LBPair, 
  binRange: [from: number, to: number]
): Promise<PairBin[]>

Parameters

• pair: The LBPair object to query

• binRange: Tuple of [fromBinId, toBinId] (inclusive start, exclusive end)

Returns

Array of PairBin objects:

interface PairBin {
  reserve_x: bigint;  // Token X reserves in this bin
  reserve_y: bigint;  // Token Y reserves in this bin
}

Understanding Bin Ranges

// Example: Fetch bins for different scenarios

// 1. Around active bin (common for display)
const activeBins = await sdk.Pair.getPairBins(
  pair,
  [pair.parameters.active_id - 5, pair.parameters.active_id + 5]
);

// 2. Above active bin (sell side liquidity)
const sellSide = await sdk.Pair.getPairBins(
  pair,
  [pair.parameters.active_id + 1, pair.parameters.active_id + 20]
);

// 3. Below active bin (buy side liquidity)
const buySide = await sdk.Pair.getPairBins(
  pair,
  [pair.parameters.active_id - 20, pair.parameters.active_id]
);

Practical Examples

Analyze Liquidity Depth

const pair = await sdk.Pair.getPair(pairAddress);
const range = 50; // Check 50 bins each side

const bins = await sdk.Pair.getPairBins(
  pair,
  [pair.parameters.active_id - range, pair.parameters.active_id + range]
);

// Calculate total liquidity in range
let totalX = 0n;
let totalY = 0n;

bins.forEach(bin => {
  totalX += bin.reserve_x;
  totalY += bin.reserve_y;
});

console.log("Liquidity in range:", { totalX, totalY });

Find Liquidity Walls

// Identify bins with concentrated liquidity
const bins = await sdk.Pair.getPairBins(pair, [activeId - 20, activeId + 20]);

const liquidityWalls = bins
  .map((bin, index) => ({
    binId: activeId - 20 + index,
    totalLiquidity: bin.reserve_x + bin.reserve_y
  }))
  .filter(bin => bin.totalLiquidity > WALL_THRESHOLD)
  .sort((a, b) => Number(b.totalLiquidity - a.totalLiquidity));

console.log("Top liquidity concentrations:", liquidityWalls.slice(0, 5));

Display Price Levels

const binStep = Number(pair.binStep);
const bins = await sdk.Pair.getPairBins(pair, [activeId - 5, activeId + 5]);

bins.forEach((bin, index) => {
  const binId = activeId - 5 + index;
  const price = getPriceFromBinId(binId, binStep);
  
  console.log(`Price ${price.toFixed(4)}: X=${bin.reserve_x}, Y=${bin.reserve_y}`);
});

Performance Notes

• Queries use devInspectTransactionBlock (no gas cost)

• Larger ranges take more time to fetch

• Maximum practical range depends on RPC limits

• Consider chunking very large ranges

Common Use Cases

1. Order Book Visualization: Display liquidity at each price level

2. Slippage Calculation: Estimate impact before swaps

3. Liquidity Analysis: Find optimal entry/exit points

4. Market Depth: Assess pair's ability to handle large trades

Related Topics

• Get Pair Reserves - Complete liquidity distribution

• Price Impact - Calculate trade impact

• Add Liquidity Overview - Add to specific bins