> For the complete documentation index, see [llms.txt](https://docs.kumbaya.xyz/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.kumbaya.xyz/developers/sdks/v3-sdk.md).

# @kumbaya\_xyz/v3-sdk

Concentrated liquidity (V3) primitives - `Pool`, `Position`, `Trade`, tick math, pool address computation.

```bash
npm install @kumbaya_xyz/v3-sdk @kumbaya_xyz/sdk-core
```

## Why this fork exists

The API matches Uniswap's `@uniswap/v3-sdk` 1:1, but this fork ships **chain-aware pool address derivation** for MegaETH. `Pool.getAddress()` and `computePoolAddress()` automatically use Kumbaya's pool init code hash (`0x851d77a4…628a3da7`) when called with `ChainId.MEGAETH` or `ChainId.MEGAETH_TESTNET`.

## Use it when

* Computing pool addresses from a `(tokenA, tokenB, feeTier)` triple
* Building `Pool` and `Position` objects from on-chain reads
* Doing local tick math / price ↔ tick conversions
* Encoding mint/burn calldata via the position manager

## Example: pool address

```ts
import { Pool, FeeAmount } from '@kumbaya_xyz/v3-sdk'
import { Token, ChainId } from '@kumbaya_xyz/sdk-core'

const tokenA = new Token(ChainId.MEGAETH, '0x...', 18, 'A')
const tokenB = new Token(ChainId.MEGAETH, '0x...', 6, 'B')

// Internally calls poolInitCodeHash(ChainId.MEGAETH) which returns the Kumbaya hash.
const poolAddress = Pool.getAddress(tokenA, tokenB, FeeAmount.MEDIUM)
```

## Fee amounts and tick spacing

The fork extends the canonical four V3 fee tiers with three intermediate ones:

```ts
enum FeeAmount {
  LOWEST  = 100,    // 0.01% - tickSpacing 1
  LOW_200 = 200,    // 0.02% - tickSpacing 4   (Kumbaya extension)
  LOW_300 = 300,    // 0.03% - tickSpacing 6   (Kumbaya extension)
  LOW_400 = 400,    // 0.04% - tickSpacing 8   (Kumbaya extension)
  LOW     = 500,    // 0.05% - tickSpacing 10
  MEDIUM  = 3000,   // 0.30% - tickSpacing 60
  HIGH    = 10000,  // 1.00% - tickSpacing 200
}
```

The four canonical tiers (100/500/3000/10000) are the most commonly used. The intermediate tiers exist for fine-grained control on stable-stable or correlated pairs but should be checked for actual on-chain pool existence before relying on them.

## Pool init code hash exports

Both exports exist; **only one returns the right value for MegaETH**:

```ts
import { POOL_INIT_CODE_HASH, poolInitCodeHash } from '@kumbaya_xyz/v3-sdk'
import { ChainId } from '@kumbaya_xyz/sdk-core'

POOL_INIT_CODE_HASH                       // ⚠ deprecated, returns upstream Uniswap hash
poolInitCodeHash(ChainId.MEGAETH)         // ✓ returns Kumbaya hash 0x851d77a4…628a3da7
```

You typically don't need either - `Pool.getAddress()` calls the function internally. See [**Pool Init Code Hash**](/developers/dex-integration/pool-init-code-hash.md) for context.

## Top-level exports

The package re-exports from these modules: `entities`, `utils`, `constants`, `multicall`, `nonfungiblePositionManager`, `payments`, `quoter`, `selfPermit`, `staker`, `swapRouter`. Pull from the package root:

```ts
import {
  Pool, Position, Trade, Route,
  TickMath, NonfungiblePositionManager,
  computePoolAddress, FeeAmount,
} from '@kumbaya_xyz/v3-sdk'
```

For everything not specific to Kumbaya, the upstream [V3 SDK docs](https://docs.uniswap.org/sdk/v3/overview) apply directly. **Do not** reference V2 or V4 SDK docs.