Amounts & slippage

Amounts are raw bigints

Every amount the SDK accepts or returns is a bigint in the token’s smallest unit, exactly as stored on-chain:

Token	Decimals	`1.5` tokens as bigint
ALPH	18	`1_500_000_000_000_000_000n`
A 6-decimal stablecoin	6	`1_500_000n`

Get decimals from the token list ((await powfi.token.getTokenById(id)).decimals) or from pool state (state.token0Info.decimals). Convert with NumericUtils:

import { NumericUtils } from '@alephium/powfi-sdk'
import Decimal from 'decimal.js'

// human -> raw
const raw = NumericUtils.numericToBigInt(new Decimal('1.5').mul(new Decimal(10).pow(18)))

// raw -> human
NumericUtils.scaleToString(1_500_000_000_000_000_000n, 18) // "1.5"

@alephium/web3 also exports convertAmountWithDecimals and prettifyTokenAmount for the same job.

Never pass JavaScript number values for amounts. 18-decimal amounts overflow Number.MAX_SAFE_INTEGER almost immediately, and the SDK types require bigint.

Basis points

Slippage is expressed in basis points (bps) as a bigint, with BPS = 10_000n:

`slippageBps`	Tolerance
`10n`	0.1%
`50n`	0.5%
`100n`	1%
`500n`	5%

Valid values satisfy 0n <= slippage < 10_000n. Anything else throws.

CPMM: slippage on amounts

CPMM quotes apply slippage to the amount you are not fixing:

// exact-in: minimum you accept to receive
CpmmModule.minimalAmount(amount, slippageBps) // = amount * 10000 / (10000 + slippageBps)

// exact-out: maximum you accept to pay (rounded up)
CpmmModule.maximalAmount(amount, slippageBps) // = ceil(amount * (10000 + slippageBps) / 10000)

computeSwapAmount fills minimalTokenOutAmount (exact-in) or maximalTokenInAmount (exact-out). The other field is undefined.

minimalAmount divides by (1 + s) rather than multiplying by (1 − s). For 0.5% this gives 99.5025% instead of 99.5%: slightly stricter, and it keeps minimalAmount and maximalAmount exact inverses.

For add-liquidity on an existing pool, both desired amounts get minimalAmount applied. On the first deposit into an empty pool no slippage is applied, because the depositor sets the price.

CLMM: slippage on price

CLMM operations turn slippage into a square-root price limit. The swap stops (or the add-liquidity reverts) if the pool price would move past it:

TickUtils.getSqrtPriceX96Bounds(sqrtPriceX96, slippageBps)
// => [ sqrtPriceX96 * sqrt(1 - s), sqrtPriceX96 * sqrt(1 + s) ]

TickUtils.getSqrtPriceLimitX96(sqrtPriceX96, slippageBps, zeroForOne)
// zeroForOne (price goes down) -> lower bound; otherwise -> upper bound
// always strictly beyond the current price and inside [MIN_SQRT_RATIO, MAX_SQRT_RATIO]

So a 1% slippage on a CLMM swap means “the pool price may move by up to 1%”. For a large trade in a thin range, that can still translate to a big difference in output amount. Always check the simulated output against your own minimum.

Price impact

CpmmSwapQuote.priceImpact is a percentage number (for example 0.42 means 0.42%), computed from the reserves before and after the trade. cpmm.swap refuses trades with priceImpact >= 5 (MAX_PRICE_IMPACT).

Fees

Pool	Swap fee	Unit
CPMM	0.3% (`997 / 1000`)	fixed
CLMM	per fee tier: `tradingFee` in the pool config	pips, where `MAX_PIPS = 1_000_000n` (so `3000n` = 0.3%)

Deadlines

CPMM write methods accept ttlMinutes (default 60). The SDK converts it to a millisecond timestamp (Date.now() + ttl), and the router rejects the transaction after that time.

ALPH deposits and dust

Alephium outputs that carry tokens must hold a minimum amount of ALPH (DUST_AMOUNT), and new contracts need MINIMAL_CONTRACT_DEPOSIT. The SDK attaches the right amount of ALPH automatically. For example, a CPMM swap attaches 2–3× DUST_AMOUNT on top of the input, and creating a CPMM pool attaches 1 ALPH as the contract deposit. Budget a little extra ALPH in the sender’s balance for this and for gas.

SDK & API

Core concepts

Modules

Utilities

Guides

Reference

Amounts are raw bigints

Basis points

CPMM: slippage on amounts

CLMM: slippage on price

Price impact

Fees

Deadlines

ALPH deposits and dust

​Amounts are raw bigints

​Basis points

​CPMM: slippage on amounts

​CLMM: slippage on price

​Price impact

​Fees

​Deadlines

​ALPH deposits and dust

Amounts are raw bigints

Basis points

CPMM: slippage on amounts

CLMM: slippage on price

Price impact

Fees

Deadlines

ALPH deposits and dust