Class Pools

Provides high-level pool reads, transaction requests, fee helpers, and pool discovery for Aftermath AMMs.

API methods return decoded bigint amounts in coin or LP smallest units. Transaction methods return unsigned Transaction objects. Network failures are normalized as AftermathTransportError by the shared caller.

Example

const afSdk = await Aftermath.create({ network: "MAINNET" });

const pools = afSdk.Pools();

// Fetch a single pool
const pool = await pools.getPool({ objectId: "0x<poolId>" });

// Fetch multiple pools
const poolArray = await pools.getPools({ objectIds: ["0x<id1>", "0x<id2>"] });

Hierarchy (View Summary)

Caller
- Pools

Constructors

constructor

new Pools(config?: CallerConfig, api?: AftermathApi): Pools
Creates a pool client without making a network request.

Supply api when transaction methods must select coins or configure referral transactions. Read methods can use config alone.
Parameters
- Optionalconfig: CallerConfig
  Optional API host, network, and access-token configuration.
- Optionalapi: AftermathApi
  Optional provider used by transaction builders and DAO-fee commands.
Returns Pools
Overrides Caller.constructor
- Defined in packages/pools/pools.ts:157

Properties

`Optional` `Readonly`api

api?: AftermathApi

Optional provider used by transaction builders and DAO-fee commands.

config

config: CallerConfig

The mutable configuration used for subsequent requests.

`Static` `Readonly`constants

constants: {
    bounds: {
        maxCoinsInPool: number;
        maxDaoFee: number;
        maxSwapFee: number;
        maxTradePercentageOfPoolBalance: number;
        maxWeight: number;
        maxWithdrawPercentageOfPoolBalance: number;
        minDaoFee: number;
        minSwapFee: number;
        minWeight: number;
    };
    defaults: { lpCoinDecimals: number };
    feePercentages: {
        devWallet: number;
        insuranceFund: number;
        totalProtocol: number;
        treasury: number;
    };
    referralPercentages: { discount: number; rebate: number };
} = ...

Protocol fee fractions, referral settings, safety bounds, and defaults used by the high-level pool helpers.

Type Declaration

bounds: {
    maxCoinsInPool: number;
    maxDaoFee: number;
    maxSwapFee: number;
    maxTradePercentageOfPoolBalance: number;
    maxWeight: number;
    maxWithdrawPercentageOfPoolBalance: number;
    minDaoFee: number;
    minSwapFee: number;
    minWeight: number;
}

Decimal safety bounds enforced by local estimates and pool creation validation.
- maxCoinsInPool: number
  
  Maximum number of distinct coins allowed in a single pool.
- maxDaoFee: number
- maxSwapFee: number
- maxTradePercentageOfPoolBalance: number
  
  Maximum decimal fraction of a pool balance accepted for one trade.
- maxWeight: number
- maxWithdrawPercentageOfPoolBalance: number
  
  Maximum decimal fraction of a pool balance accepted for one withdrawal.
- minDaoFee: number
  
  Minimum and maximum decimal DAO fees. The range is 0% to 100%.
- minSwapFee: number
  
  Minimum and maximum decimal swap fees. The range is 0.0001 to 0.1, or 0.01% to 10%.
- minWeight: number
  
  Minimum and maximum decimal coin weights. The range is 1% to 99%.
defaults: { lpCoinDecimals: number }

Defaults used when a caller does not supply an explicit value.
- lpCoinDecimals: number
  
  Default LP coin decimal precision.
feePercentages: {
    devWallet: number;
    insuranceFund: number;
    totalProtocol: number;
    treasury: number;
}

Protocol fee fractions. totalProtocol is taken from a trade and the other fields describe its allocation.
- devWallet: number
  
  The fraction of totalProtocol allocated to the dev wallet.
- insuranceFund: number
  
  The fraction of totalProtocol allocated to the insurance fund.
- totalProtocol: number
  
  The total decimal fraction charged by the protocol. 0.00005 is 0.005%.
- treasury: number
  
  The fraction of totalProtocol allocated to the treasury.
referralPercentages: { discount: number; rebate: number }

Referral fractions applied to the treasury allocation. The static fee helper uses discount; referral transaction builders register the referrer separately.
- discount: number
  
  The fraction of the treasury allocation used as a user fee discount.
- rebate: number
  
  The configured fraction of the treasury allocation reserved as a referrer rebate.

Methods

getAllPools

getAllPools(abortSignal?: AbortSignal): Promise<Pool[]>
Fetches every pool recognized by the Aftermath API.
Parameters
- OptionalabortSignal: AbortSignal
  Optional caller-owned cancellation signal.
Returns Promise<Pool[]>
A promise for all decoded Pool instances.
Throws
AftermathTransportError when the API request or response fails.
Example
```
const allPools = await pools.getAllPools();
console.log(allPools.map(p => p.pool.name));
```
- Defined in packages/pools/pools.ts:244

getCreatePoolTransaction

getCreatePoolTransaction(inputs: ApiCreatePoolBody): Promise<Transaction>
Builds an unsigned transaction that creates a new pool on chain.

The API serializes nested bigint deposits with an n suffix, and the caller must supply a creation capability and initial coin balances. This method does not sign, submit, or serialize the returned Transaction.
Parameters
- inputs: ApiCreatePoolBody
  Pool type, metadata, coin configuration, capability, and fee settings.
Returns Promise<Transaction>
A promise for the unsigned pool-creation Transaction.
Throws
AftermathTransportError when the API cannot build or decode the transaction.
Example
```
const createPoolTx = await pools.getCreatePoolTransaction({
  walletAddress: "0x<address>",
  lpCoinType: "0x<lpCoin>",
  lpCoinMetadata: {
    name: "MyPool LP",
    symbol: "MYPLP"
  },
  coinsInfo: [
    {
      coinType: "0x<coinA>",
      weight: 0.5,
      decimals: 9,
      tradeFeeIn: 0.003,
      initialDeposit: 1_000_000_000n
    },
    // ...
  ],
  poolName: "My Weighted Pool",
  createPoolCapId: "0x<capId>",
  respectDecimals: true,
});
```
- Defined in packages/pools/pools.ts:330

getInteractionEvents

getInteractionEvents(
inputs: ApiIndexerEventsBody & { walletAddress: string },
): Promise<IndexerEventsWithCursor<PoolDepositEvent | PoolWithdrawEvent>>
Fetches a wallet's deposit and withdrawal events across pools.
Parameters
- inputs: ApiIndexerEventsBody & { walletAddress: string }
  Wallet address and optional indexer pagination fields.
Returns Promise<IndexerEventsWithCursor<PoolDepositEvent | PoolWithdrawEvent>>
A promise for paginated PoolDepositEvent and PoolWithdrawEvent values.
Throws
AftermathTransportError when the indexer request or response fails.
Example
```
const userEvents = await pools.getInteractionEvents({
  walletAddress: "0x...",
  limit: 10,
});
console.log(userEvents.events, userEvents.nextCursor);
```
- Defined in packages/pools/pools.ts:533

getOwnedDaoFeePoolOwnerCaps

getOwnedDaoFeePoolOwnerCaps(
inputs: ApiPoolsOwnedDaoFeePoolOwnerCapsBody,
): Promise<DaoFeePoolOwnerCapObject[]>
Fetches DAO fee owner capabilities owned by a wallet.

Each returned capability identifies a DAO fee pool whose fee or recipient the wallet can update. DAO-fee package addresses must be configured.
Parameters
- inputs: ApiPoolsOwnedDaoFeePoolOwnerCapsBody
  The wallet address to inspect.
Returns Promise<DaoFeePoolOwnerCapObject[]>
A promise for the owned DAO fee capability objects.
Throws
Error when DAO-fee addresses are not configured.
Example
```
const daoCaps = await pools.getOwnedDaoFeePoolOwnerCaps({
  walletAddress: "0x<address>"
});
console.log(daoCaps);
```
- Defined in packages/pools/pools.ts:507

getOwnedLpCoins

getOwnedLpCoins(inputs: { walletAddress: string }): Promise<PoolLpInfo[]>
Fetches the LP coin balances owned by a wallet across pools.
Parameters
- inputs: { walletAddress: string }
  The wallet address to inspect.
Returns Promise<PoolLpInfo[]>
A promise for LP coin types, pool IDs, and smallest-unit balances.
Throws
AftermathTransportError when the API request or response fails.
Example
```
const lpCoins = await pools.getOwnedLpCoins({ walletAddress: "0x<address>" });
console.log(lpCoins);
```
- Defined in packages/pools/pools.ts:262

getPool

getPool(inputs: { objectId: string }, abortSignal?: AbortSignal): Promise<Pool>
Fetches one pool by its on-chain object ID and wraps it in Pool.
Parameters
- inputs: { objectId: string }
  The pool object ID to read.
- OptionalabortSignal: AbortSignal
  Optional caller-owned cancellation signal.
Returns Promise<Pool>
A promise for a Pool backed by the decoded API object.
Throws
AftermathTransportError for HTTP, network, abort, timeout, or decode failures.
Example
```
const pool = await pools.getPool({ objectId: "0x<poolId>" });
console.log(pool.pool.lpCoinType, pool.pool.name);
```
- Defined in packages/pools/pools.ts:186

getPoolObjectIdForLpCoinType

getPoolObjectIdForLpCoinType(
inputs: { lpCoinType: string },
abortSignal?: AbortSignal,
): Promise<(string | undefined)[]>
Resolves one LP coin type through the batch pool-ID endpoint.

The response is an array with one entry, which can be undefined when the type is not registered. Use getPoolObjectIdsForLpCoinTypes for several types.
Parameters
- inputs: { lpCoinType: string }
  The LP coin type to resolve.
- OptionalabortSignal: AbortSignal
  Optional caller-owned cancellation signal.
Returns Promise<(string | undefined)[]>
A promise for a one-entry (ObjectId | undefined)[] result.
Throws
AftermathTransportError when the API request or response fails.
Example
```
const poolId = await pools.getPoolObjectIdForLpCoinType({
  lpCoinType: "0x<lpCoinType>"
});
console.log(poolId);
```
- Defined in packages/pools/pools.ts:358

getPoolObjectIdsForLpCoinTypes

getPoolObjectIdsForLpCoinTypes(
inputs: ApiPoolObjectIdForLpCoinTypeBody,
abortSignal?: AbortSignal,
): Promise<(string | undefined)[]>
Resolves LP coin types to pool object IDs.

The response preserves input order and uses undefined for an LP type with no associated pool.
Parameters
- inputs: ApiPoolObjectIdForLpCoinTypeBody
  LP coin types to resolve.
- OptionalabortSignal: AbortSignal
  Optional caller-owned cancellation signal.
Returns Promise<(string | undefined)[]>
A promise for one result per input type.
Throws
AftermathTransportError when the API request or response fails.
Example
```
const poolIds = await pools.getPoolObjectIdsForLpCoinTypes({
  lpCoinTypes: ["0x<lpCoinA>", "0x<lpCoinB>"]
});
console.log(poolIds);
```
- Defined in packages/pools/pools.ts:389

getPools

getPools(
inputs: { objectIds: string[] },
abortSignal?: AbortSignal,
): Promise<Pool[]>
Fetches multiple pools by object ID and wraps the returned objects in Pool.
Parameters
- inputs: { objectIds: string[] }
  The pool object IDs to read.
- OptionalabortSignal: AbortSignal
  Optional caller-owned cancellation signal.
Returns Promise<Pool[]>
A promise for pools in the API response order.
Throws
AftermathTransportError for the batch request or response failures.
Example
```
const poolArray = await pools.getPools({ objectIds: ["0x<id1>", "0x<id2>"] });
console.log(poolArray.length);
```
- Defined in packages/pools/pools.ts:212

getPoolsStats

getPoolsStats(
inputs: ApiPoolsStatsBody,
abortSignal?: AbortSignal,
): Promise<PoolStats[]>
Fetches analytics for a selected set of pools.
Parameters
- inputs: ApiPoolsStatsBody
  Pool object IDs to include, in the requested order.
- OptionalabortSignal: AbortSignal
  Optional caller-owned cancellation signal.
Returns Promise<PoolStats[]>
A promise for the corresponding PoolStats values.
Throws
AftermathTransportError when the API request or response fails.
Example
```
const stats = await pools.getPoolsStats({ poolIds: ["0x<id1>", "0x<id2>"] });
console.log(stats[0].volume, stats[1].tvl);
```
- Defined in packages/pools/pools.ts:465

getPoolSummaries

getPoolSummaries(
inputs?: ApiPoolsSummaryBody,
abortSignal?: AbortSignal,
): Promise<PoolSummary[]>
Fetches pool objects and analytics in one API response.

Omit poolIds to request every pool summary.
Parameters
- Optionalinputs: ApiPoolsSummaryBody
  Optional pool IDs to include.
- OptionalabortSignal: AbortSignal
  Optional caller-owned cancellation signal.
Returns Promise<PoolSummary[]>
A promise for pool objects paired with current PoolStats.

Throws
AftermathTransportError when the API request or response fails.
- Defined in packages/pools/pools.ts:482

getPublishLpCoinTransaction

getPublishLpCoinTransaction(inputs: ApiPublishLpCoinBody): Promise<Transaction>
Builds an unsigned transaction that publishes the compiled LP coin package.

The transaction transfers the resulting upgrade capability to walletAddress. It is not signed, submitted, or serialized by this method.
Parameters
- inputs: ApiPublishLpCoinBody
  Publisher address and compiled LP coin decimal precision.
Returns Promise<Transaction>
A promise for the unsigned publish Transaction.
Throws
Error when the provider lacks the compiled package for the requested decimals.
Example
```
const publishTx = await pools.getPublishLpCoinTransaction({
  walletAddress: "0x<address>",
  lpCoinDecimals: 9
});
```
- Defined in packages/pools/pools.ts:290

getTotalVolume24hrs

getTotalVolume24hrs(): Promise<number>
Fetches the protocol-wide 24-hour pool volume.

Returns Promise<number>
A promise for the numeric API value. This method does not convert its unit.
Throws
AftermathTransportError when the API request or response fails.
Example
```
const totalVol24 = await pools.getTotalVolume24hrs();
console.log("Protocol-wide 24h volume:", totalVol24);
```
- Defined in packages/pools/pools.ts:430

getTVL

getTVL(inputs?: { poolIds?: string[] }): Promise<number>
Fetches total value locked across all pools or a selected pool set.
Parameters
- Optionalinputs: { poolIds?: string[] }
  Optional pool IDs. Omit the argument for protocol-wide TVL.
Returns Promise<number>
A promise for the numeric API TVL value. This method does not convert its unit.
Throws
AftermathTransportError when the API request or response fails.
Example
```
const allTvl = await pools.getTVL();
const subsetTvl = await pools.getTVL({ poolIds: ["0x<id1>", "0x<id2>"] });
```
- Defined in packages/pools/pools.ts:447

isLpCoinType

isLpCoinType(
inputs: { lpCoinType: string },
abortSignal?: AbortSignal,
): Promise<boolean>
Checks whether an LP coin type maps to a registered pool.

This performs the same API read as getPoolObjectIdForLpCoinType and does not validate the coin type from its string shape alone.
Parameters
- inputs: { lpCoinType: string }
  The LP coin type to resolve.
- OptionalabortSignal: AbortSignal
  Optional caller-owned cancellation signal.
Returns Promise<boolean>
A promise for true when the API returns a pool ID.

Throws
AftermathTransportError when the API request or response fails.
- Defined in packages/pools/pools.ts:410

`Static`apiBaseUrlForNetwork

apiBaseUrlForNetwork(network: SuiNetwork): string
Returns the canonical Aftermath API host for a Sui network.

To target a custom or local host, pass baseUrl in CallerConfig to the constructor instead.
Parameters
- network: SuiNetwork
  The Sui network whose host to return.
Returns string
The network's HTTPS or local HTTP API host.
Inherited from Caller.apiBaseUrlForNetwork
- Defined in general/utils/caller.ts:151

`Static`defaultFullnodeUrl

defaultFullnodeUrl(network: SuiNetwork | undefined): string
Returns the canonical Sui fullnode URL for a network.
Parameters
- network: SuiNetwork | undefined
  The network whose fullnode URL to return. undefined defaults to mainnet.
Returns string
The network's fullnode URL.
Inherited from Caller.defaultFullnodeUrl
- Defined in general/utils/caller.ts:162

`Static`displayLpCoinType

displayLpCoinType(lpCoinType: string): string
Formats an Aftermath LP coin type for display.

The method reads the type symbol, removes the AF_LP_ prefix when present, title-cases underscore-separated components, and appends LP. It does not validate the type on chain.
Parameters
- lpCoinType: string
  The fully qualified LP coin type.
Returns string
A display label such as "A B LP".
- Defined in packages/pools/pools.ts:638

`Static`getAmountWithoutProtocolFees

getAmountWithoutProtocolFees(
inputs: { amount: bigint; withReferral?: boolean },
): bigint
Reverses getAmountWithProtocolFees for a smallest-unit amount.

The result is rounded down. With withReferral: true, it uses the same treasury discount as the forward calculation. It does not register a referrer or pay a referral rebate.
Parameters
- inputs: { amount: bigint; withReferral?: boolean }
  The net amount in a coin's smallest unit and optional referral flag.
Returns bigint
The estimated gross amount in the same smallest unit, rounded down.
- Defined in packages/pools/pools.ts:595

`Static`getAmountWithProtocolFees

getAmountWithProtocolFees(
inputs: { amount: bigint; withReferral?: boolean },
): bigint
Applies the protocol fee to a smallest-unit amount.

The default protocol fee is 0.00005, or 0.005%. With withReferral: true, the helper reduces only the treasury portion by the configured referral discount. It does not register a referrer or calculate the separate referrer rebate. Use a referral-aware transaction builder for that side effect.
Parameters
- inputs: { amount: bigint; withReferral?: boolean }
  The gross amount in a coin's smallest unit and optional referral flag.
Returns bigint
The net amount in the same smallest unit, rounded down.
Example
```
const netAmount = Pools.getAmountWithProtocolFees({ amount: 1_000_000n });
```
- Defined in packages/pools/pools.ts:567

`Static`isPossibleLpCoinType

isPossibleLpCoinType(inputs: { lpCoinType: string }): boolean
Performs a string-shape check for an Aftermath LP coin type.

The check requires three :: segments, an af_lp module segment, and an AF_LP symbol segment. It does not query the API or prove that a pool exists.
Parameters
- inputs: { lpCoinType: string }
  The coin type string to inspect.
Returns boolean
true when the string matches the heuristic pattern.
- Defined in packages/pools/pools.ts:659

`Static`normalizeInvertSlippage

normalizeInvertSlippage(slippage: number): bigint
Converts a decimal slippage tolerance to the fixed-point minimum-result factor.
Parameters
- slippage: number
  A decimal fraction from 0 to 1. 0.01 represents 1%.
Returns bigint
1 - slippage encoded as an on-chain fixed-point bigint.
- Defined in packages/pools/pools.ts:621

Class Pools

Example

Hierarchy (View Summary)

Index

Constructors

Properties

Methods

Constructors

constructor

Parameters

Returns Pools

Properties

Optional Readonlyapi

config

Static Readonlyconstants

Type Declaration

bounds: { maxCoinsInPool: number; maxDaoFee: number; maxSwapFee: number; maxTradePercentageOfPoolBalance: number; maxWeight: number; maxWithdrawPercentageOfPoolBalance: number; minDaoFee: number; minSwapFee: number; minWeight: number;}

maxCoinsInPool: number

maxDaoFee: number

maxSwapFee: number

maxTradePercentageOfPoolBalance: number

maxWeight: number

maxWithdrawPercentageOfPoolBalance: number

minDaoFee: number

minSwapFee: number

minWeight: number

defaults: { lpCoinDecimals: number }

lpCoinDecimals: number

feePercentages: { devWallet: number; insuranceFund: number; totalProtocol: number; treasury: number;}

devWallet: number

insuranceFund: number

totalProtocol: number

treasury: number

referralPercentages: { discount: number; rebate: number }

discount: number

rebate: number

Methods

getAllPools

Parameters

Returns Promise<Pool[]>

Throws

Example

getCreatePoolTransaction

Parameters

Returns Promise<Transaction>

Throws

Example

getInteractionEvents

Parameters

Returns Promise<IndexerEventsWithCursor<PoolDepositEvent | PoolWithdrawEvent>>

Throws

Example

getOwnedDaoFeePoolOwnerCaps

Parameters

Returns Promise<DaoFeePoolOwnerCapObject[]>

Throws

Example

getOwnedLpCoins

Parameters

Returns Promise<PoolLpInfo[]>

Throws

Example

getPool

Parameters

Returns Promise<Pool>

Throws

Example

getPoolObjectIdForLpCoinType

Parameters

Returns Promise<(string | undefined)[]>

Throws

Example

getPoolObjectIdsForLpCoinTypes

Parameters

Returns Promise<(string | undefined)[]>

Throws

Example

getPools

Parameters

Returns Promise<Pool[]>

`Optional` `Readonly`api

`Static` `Readonly`constants

bounds: {
maxCoinsInPool: number;
maxDaoFee: number;
maxSwapFee: number;
maxTradePercentageOfPoolBalance: number;
maxWeight: number;
maxWithdrawPercentageOfPoolBalance: number;
minDaoFee: number;
minSwapFee: number;
minWeight: number;
}

feePercentages: {
devWallet: number;
insuranceFund: number;
totalProtocol: number;
treasury: number;
}

`Static`apiBaseUrlForNetwork

`Static`defaultFullnodeUrl

`Static`displayLpCoinType

`Static`getAmountWithoutProtocolFees

`Static`getAmountWithProtocolFees

`Static`isPossibleLpCoinType

`Static`normalizeInvertSlippage