> For the complete documentation index, see [llms.txt](https://docs.ferra.ag/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.ferra.ag/integration/dlmm/typescript-sdk/utilities-and-reference/bin-mathematics.md).

# Bin Mathematics

## What are Bins?

Think of bins as **price buckets** that hold liquidity. Each bin represents a specific price point where tokens can be traded. Instead of spreading liquidity across a continuous range, DLMM splits it into these discrete bins.

#### **Key characteristics:**

* Each bin has a unique ID
* Bins contain reserves of both tokens (X and Y)
* Only one bin is "active" for trading at any time
* Price moves by jumping between adjacent bins

#### How Bin IDs Work

Bin IDs are 24-bit integers that directly map to price levels:

```
Bin ID 8388608 (2^23) = Price of 1.0 (X/Y = 1)
Bin ID > 8388608 = Price > 1.0
Bin ID < 8388608 = Price < 1.0
```

**Important concepts:**

* **Active Bin**: The current trading bin where swaps occur
* **Bin Step**: The price difference between adjacent bins (in basis points)
* **Bin Range**: A sequence of bins where you can place liquidity

#### Example

For a USDC/USDT pair with 1 basis point bin step:

* Bin 8388608: 1 USDC = 1.0000 USDT
* Bin 8388609: 1 USDC = 1.0001 USDT
* Bin 8388610: 1 USDC = 1.0002 USDT

This discretization enables gas-efficient trading and precise liquidity placement at exact price points.

## Bin ID Calculations

Find the appropriate bin ID for any target price using the reverse price formula.

#### The Reverse Formula

To calculate bin ID from a target price:

```
binId = log(price) / log(1 + binStep/10000) + 8388608
```

Where:

* `price`: Target price (X/Y ratio)
* `binStep`: The step size in basis points
* `8388608`: The reference bin where price = 1.0 for example
* Result must be rounded to nearest integer

#### Quick Examples

**Finding bin IDs for common prices:**

```typescript
// With 10 basis point bin step
price: 1.0000 → binId = 8388608
price: 1.0050 → binId = 8388613 (5 bins above)
price: 0.9950 → binId = 8388603 (5 bins below)

// With 100 basis point bin step  
price: 1.1000 → binId = 8388618 (10 bins above)
price: 0.9000 → binId = 8388597 (11 bins below)
```

#### Code Implementation

```typescript
function getBinIdFromPrice(
  targetPrice: number, 
  binStep: number
): number {
  const base = 1 + binStep / 10000;
  const rawBinId = Math.log(targetPrice) / Math.log(base) + 8388608;
  
  // Round to nearest bin
  return Math.round(rawBinId);
}

// Example: Place liquidity at $3.00 for SUI/USDC
const binId = getBinIdFromPrice(3.0, 20);
// Result: binId = 8394879
```

#### Rounding Considerations

* **Round**: For finding nearest tradeable bin
* **Floor**: For conservative sell orders
* **Ceil**: For conservative buy orders

```typescript
// Different rounding strategies
const exact = 8388612.7;
Math.round(exact); // 8388613 - nearest bin
Math.floor(exact); // 8388612 - lower price
Math.ceil(exact);  // 8388613 - higher price
```

## Bin step guides

Choose the optimal bin step for your trading pair based on asset volatility, trading patterns, and capital efficiency needs.

#### What is Bin Step?

Bin step defines the **price increment** between adjacent bins in basis points (bps):

* 1 bps = 0.01% price difference
* Range: 1 to 10,000 bps
* Affects price granularity and capital efficiency

#### Choosing Your Bin Step

#### Stable Pairs (1-10 bps)

**Best for:** USDC/USDT, wBTC/BTC, haSUI/SUI

```
1 bps → 0.01% increments → Finest granularity
5 bps → 0.05% increments → Good for most stables
```

#### Blue-chip Pairs (10-50 bps)

**Best for:** SUI/USDC, DEEP/USDC, WAL/USDC

```
20 bps → 0.20% increments → Popular choice
50 bps → 0.50% increments → Wider but efficient
```

#### Volatile Pairs (50-200 bps)

**Best for:** MEME/USDC, New tokens, Low liquidity pairs

```
100 bps → 1.00% increments → Handles volatility well
200 bps → 2.00% increments → Maximum capital efficiency
```

#### Trade-offs

| Bin Step             | Pros                                                                                         | Cons                                                                                      |
| -------------------- | -------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
| **Small** (1-10 bps) | <p>• Minimal slippage</p><p>• Precise pricing</p><p>• Better for limit orders</p>            | <p>• Liquidity spread thin</p><p>• More bins needed</p><p>• Higher gas on rebalancing</p> |
| **Large** (100+ bps) | <p>• Concentrated liquidity</p><p>• Fewer bins to manage</p><p>• Lower rebalancing costs</p> | <p>• Higher slippage</p><p>• Larger price jumps</p><p>• Less precise entries</p>          |

#### Quick Reference

```typescript
// Recommended bin steps by pair type
const binStepGuide = {
  stablecoin: 1,      // USDC/USDT
  correlated: 5,      // haSUI/SUI  
  bluechip: 20,       // SUI/USDC
  volatile: 100,      // MEME/USDC
  exotic: 200         // New launches
};
```

#### Practical Example

For SUI/USDC with 20 bps bin step:

* Bin 8388608: $3.00
* Bin 8388609: $3.01 (0.3% higher)
* Bin 8388610: $3.02 (0.6% higher)

This provides good balance between capital efficiency and price precision.