Class Coin

The Coin class provides functionality to manage and inspect coin types, retrieve metadata and prices, and convert balances with respect to coin decimals. It can be instantiated with or without a specific coinType for convenience.

Example


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

const coin = afSdk.Coin("0x2::sui::SUI");

const metadata = await coin.getCoinMetadata(); // fetch metadata for SUI coin

Hierarchy (View Summary)

Caller
- Coin

Constructors

constructor

new Coin(
    coinType?: string | undefined,
    config?: CallerConfig,
    api?: AftermathApi,
): Coin
Creates a new instance of Coin.
Parameters
- coinType: string | undefined = undefined
  The coin's type string (e.g., "0x2::sui::SUI"). If omitted, methods that require a type will need it passed in manually.
- Optionalconfig: CallerConfig
  Optional caller configuration (network, access token).
- Optionalapi: AftermathApi
  An optional AftermathApi instance for coin-specific API calls.
Returns Coin
Overrides Caller.constructor
- Defined in packages/coin/coin.ts:115

Properties

`Optional` `Readonly`api

api?: AftermathApi

An optional AftermathApi instance for coin-specific API calls.

`Readonly`coinType

coinType: string | undefined = undefined

The coin's type string (e.g., "0x2::sui::SUI"). If omitted, methods that require a type will need it passed in manually.

`Readonly`coinTypePackageName

coinTypePackageName: string

The Move package name portion of this coin type, e.g. the middle "module" from "0x2::sui::SUI". Will be empty if no coinType is provided.

`Readonly`coinTypeSymbol

coinTypeSymbol: string

The final part of the coin type (the "symbol" or short name) from "0x2::sui::SUI". Will be empty if no coinType is provided.

config

config: CallerConfig

The mutable configuration used for subsequent requests.

`Readonly`innerCoinType

innerCoinType: string

If the coin type includes a generic argument (like Coin<0x...>), this is extracted. Else empty. E.g. "0x5::coin::Coin<0x2::sui::SUI>" => "0x2::sui::SUI".

metadata

metadata: CoinMetadaWithInfo | undefined

An optional cached coin metadata object retrieved by getCoinMetadata.

priceInfo

priceInfo: CoinPriceInfo | undefined

An optional cached price info object retrieved by getPrice.

`Static` `Readonly`constants

constants: {
    coinObjectType: string;
    defaultCoinDecimals: { evm: number; sui: number; svm: number };
    maxCoinDecimals: number;
    suiCoinDecimals: number;
    suiCoinType: string;
} = ...

Static configuration and defaults for Sui coin types, including the standard SUI coin type, default decimals, and coin object type path.

Type Declaration

coinObjectType: string

The canonical coin object type path for Sui's Move module, used in verifying coin objects.
defaultCoinDecimals: { evm: number; sui: number; svm: number }

Default decimals for various blockchains or ecosystems. For instance, "sui" => 9, "evm" => 18, etc.
maxCoinDecimals: number

The maximum number of decimals
suiCoinDecimals: number

The default number of decimals for SUI (9).
suiCoinType: string

The canonical coin type string for SUI.

Methods

getCoinMetadata

getCoinMetadata(
coin?: string,
abortSignal?: AbortSignal,
): Promise<CoinMetadaWithInfo>
Fetches the metadata (name, symbol, decimals) for this coin type or a provided one, caching it if already requested.
Parameters
- Optionalcoin: string
  Optionally override the constructor coinType.
- OptionalabortSignal: AbortSignal
Returns Promise<CoinMetadaWithInfo>
The CoinMetadaWithInfo object containing metadata and optional external references.
Throws
If neither constructor nor argument coinType is available.
Example
```
const metadata = await coin.getCoinMetadata("0x2::sui::SUI");
console.log(metadata.name, metadata.symbol, metadata.decimals);
```
- Defined in packages/coin/coin.ts:185

getCoinMetadatas

getCoinMetadatas(
inputs: { coins: string[] },
abortSignal?: AbortSignal,
): Promise<CoinMetadaWithInfo[]>
Fetches metadata for multiple coins at once, returning an array in the same order as the coin types requested.
Parameters
- inputs: { coins: string[] }
  An object with coins, an array of coin types.
- OptionalabortSignal: AbortSignal
Returns Promise<CoinMetadaWithInfo[]>
An array of CoinMetadaWithInfo with length matching coins.
Example
```
const metas = await coin.getCoinMetadatas({
  coins: ["0x2::sui::SUI", "0x<custom::TOKEN>"]
});
console.log(metas[0].symbol, metas[1].symbol);
```
- Defined in packages/coin/coin.ts:221

getCoinsToDecimals

getCoinsToDecimals(
inputs: { coins: string[] },
abortSignal?: AbortSignal,
): Promise<CoinsToDecimals>
Retrieves the decimals for multiple coins by calling the Aftermath API for metadata and extracting the decimals property.
Parameters
- inputs: { coins: string[] }
  An object containing an array of coin types.
- OptionalabortSignal: AbortSignal
Returns Promise<CoinsToDecimals>
An object mapping each coin type to a numeric decimal count.
Example
```
const decimals = await coin.getCoinsToDecimals({ coins: ["0x2::sui::SUI", "0x<...>"] });
console.log(decimals); // { "0x2::sui::SUI": 9, "0x<...>": 6 }
```
- Defined in packages/coin/coin.ts:156

getPrice

getPrice(coin?: string, abortSignal?: AbortSignal): Promise<CoinPriceInfo>
Retrieves price information (including current price and 24h change) for this coin or a provided coin. If already fetched, it returns the cached data.
Parameters
- Optionalcoin: string
  Optionally override the constructor coinType.
- OptionalabortSignal: AbortSignal
Returns Promise<CoinPriceInfo>
A CoinPriceInfo with price and priceChange24HoursPercentage.
Throws
If no valid coin type is present.
Example
```
const priceInfo = await coin.getPrice("0x2::sui::SUI");
console.log(priceInfo.price, priceInfo.priceChange24HoursPercentage);
```
- Defined in packages/coin/coin.ts:257

getVerifiedCoins

getVerifiedCoins(): Promise<string[]>
Fetches a list of "verified" coin types from the Aftermath backend. Verified coins typically pass certain safety or liquidity checks.

Returns Promise<string[]>
An array of CoinType strings that are considered verified.
Example
```
const verified = await coin.getVerifiedCoins();
console.log(verified); // e.g. ["0x2::sui::SUI", "0x...::MYCOIN", ...]
```
- Defined in packages/coin/coin.ts:305

setCoinMetadata

setCoinMetadata(metadata: CoinMetadaWithInfo): void
Manually sets the metadata in this Coin instance, storing it in this.metadata.
Parameters
- metadata: CoinMetadaWithInfo
  A CoinMetadaWithInfo object to cache in this instance.
Returns void
- Defined in packages/coin/coin.ts:239

setPriceInfo

setPriceInfo(priceInfo: CoinPriceInfo): void
Manually sets the price info in this Coin instance, storing it in this.priceInfo.
Parameters
- priceInfo: CoinPriceInfo
  A CoinPriceInfo object to cache in this instance.
Returns void
- Defined in packages/coin/coin.ts:289

`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`balanceWithDecimals

balanceWithDecimals(amount: number | bigint, decimals: number): number
Scales a raw bigint or numeric amount down by decimals to get a display-friendly float. For example, 1500000000n with decimals = 9 => 1.5.
Parameters
- amount: number | bigint
  The raw on-chain amount as bigint or number.
- decimals: number
  Number of decimal places for this coin.
Returns number
The resulting float as an easily readable balance.
- Defined in packages/coin/coin.ts:536

`Static`balanceWithDecimalsUsd

balanceWithDecimalsUsd(
    amount: number | bigint,
    decimals: number,
    price: number,
): number
Scales a raw amount down by decimals and multiplies by a price in USD, returning a final USD value. E.g., 1500000000n, decimals=9, price=2.0 => 3.0.
Parameters
- amount: number | bigint
  The raw balance as bigint or number.
- decimals: number
  The coin decimals.
- price: number
  The coin's price in USD.
Returns number
The computed float in USD.
- Defined in packages/coin/coin.ts:553

`Static`coinsAndAmountsOverZero

coinsAndAmountsOverZero(
coinAmounts: Record<CoinType, number>,
): { amounts: number[]; coins: string[] }
Given a record of coin types => numeric amounts, filters out those with zero or negative amounts, returning only the positive pairs.
Parameters
- coinAmounts: Record<CoinType, number>
  A record mapping coin types to numeric amounts.
Returns { amounts: number[]; coins: string[] }
An object with coins array and amounts array in matching indexes.
- Defined in packages/coin/coin.ts:412

`Static`coinsAndBalancesOverZero

coinsAndBalancesOverZero(
coinsToBalance: CoinsToBalance,
): { balances: bigint[]; coins: string[] }
Given a record of coin types => bigint balances, filters out those with zero or negative balances, returning only the positive pairs.
Parameters
- coinsToBalance: CoinsToBalance
  A record mapping coin types to bigints.
Returns { balances: bigint[]; coins: string[] }
An object with coins array and balances array in matching indexes.
- Defined in packages/coin/coin.ts:431

`Static`coinSymbolForCoinType

coinSymbolForCoinType(
    inputs: {
        coinSymbolToCoinTypes: CoinSymbolToCoinTypes;
        coinType: string;
    },
): string
| undefined
Looks up a coin's symbol if it is known in a provided coinSymbolToCoinTypes record. For instance, if "SUI" => ["0x2::sui::SUI"], we can find "SUI" from the coin type "0x2::sui::SUI".
Parameters
- inputs: { coinSymbolToCoinTypes: CoinSymbolToCoinTypes; coinType: string }
  An object with coinType and coinSymbolToCoinTypes.
Returns string | undefined
The coin symbol string or undefined if not found.
- Defined in packages/coin/coin.ts:569

`Static`coinTypeFromKeyType

coinTypeFromKeyType(keyType: string): string
If a KeyType string references a type in angle brackets, extracts the type inside. Typically for "0x2::coin::Coin<0x2::mycoin::MYCOIN>" -> "0x2::mycoin::MYCOIN".
Parameters
- keyType: string
  The key type string to parse.
Returns string
The substring inside <...> or the original if no brackets found.
- Defined in packages/coin/coin.ts:374

`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`filterCoinsByMetadata

filterCoinsByMetadata(
    inputs: {
        coinMetadatas: Record<CoinType, CoinMetadata>;
        filter: string;
    },
): string[]
Filters a record of coin metadata by a textual query, matching both the coin type and the metadata's name/symbol fields.
Parameters
- inputs: { coinMetadatas: Record<CoinType, CoinMetadata>; filter: string }
  An object containing filter and a record of coinMetadatas.
Returns string[]
An array of coin types that match the search criteria.
- Defined in packages/coin/coin.ts:489

`Static`filterCoinsByType

filterCoinsByType(inputs: { coinTypes: string[]; filter: string }): string[]
Filters a list of coinTypes by a textual query, matching against both zero-padded and non-padded forms as well as substring checks.
Parameters
- inputs: { coinTypes: string[]; filter: string }
  Contains filter (the search string) and coinTypes.
Returns string[]
An array of coin types that match the filter in either raw or zero-padded form.
Example
```
const filtered = Coin.filterCoinsByType({
  filter: "sui",
  coinTypes: ["0x2::sui::SUI", "0x<...>"]
});
```
- Defined in packages/coin/coin.ts:458

`Static`getCoinTypePackageName

getCoinTypePackageName(coin: string): string
Extracts the Move package name portion from a coin type string. E.g., "0x2::sui::SUI" => "sui".
Parameters
- coin: string
  The coin type string (e.g., "0x2::sui::SUI").
Returns string
The middle segment of the type or empty string if not parseable.
- Defined in packages/coin/coin.ts:324

`Static`getCoinTypeSymbol

getCoinTypeSymbol(coin: string): string
Extracts the final part of the coin type (the symbol or short name). For example, "0x2::sui::SUI" => "SUI".
Parameters
- coin: string
  The coin type string.
Returns string
The extracted symbol or empty string if not found.
- Defined in packages/coin/coin.ts:343

`Static`getInnerCoinType

getInnerCoinType(coin: string): string
Extracts the inner generic argument of a coin type if present. E.g., "0x2::coin::Coin<0x2::sui::SUI>" => "0x2::sui::SUI".
Parameters
- coin: string
  The coin type with a possible <...> suffix.
Returns string
The inner type or an empty string if not found.
- Defined in packages/coin/coin.ts:364

`Static`isCoinObjectType

isCoinObjectType(objectType: string): boolean
Checks if an object type string is a Coin<...> object from the standard Sui Move module.
Parameters
- objectType: string
  The object type to test.
Returns boolean
true if it matches "0x2::coin::Coin<...>", otherwise false.
- Defined in packages/coin/coin.ts:396

`Static`isSuiCoin

isSuiCoin(coin: string): boolean
Checks if a coin type string corresponds to the canonical SUI coin.
Parameters
- coin: string
  A coin type string.
Returns boolean
true if it matches "0x2::sui::SUI", otherwise false.
- Defined in packages/coin/coin.ts:386

`Static`normalizeBalance

normalizeBalance(balance: number, decimals: number): bigint
Converts a user-friendly decimal number (e.g., 1.5) to a raw on-chain integer representation by scaling with the given coin decimals. For example, 1.5 with decimals = 9 => 1500000000n.
Parameters
- balance: number
  The user-friendly balance as a number.
- decimals: number
  Number of decimal places for this coin.
Returns bigint
A bigint representing the raw on-chain balance.
- Defined in packages/coin/coin.ts:523

Class Coin

Example

Hierarchy (View Summary)

Index

Constructors

Properties

Methods

Constructors

constructor

Parameters

Returns Coin

Properties

Optional Readonlyapi

ReadonlycoinType

ReadonlycoinTypePackageName

ReadonlycoinTypeSymbol

config

ReadonlyinnerCoinType

metadata

priceInfo

Static Readonlyconstants

Type Declaration

coinObjectType: string

defaultCoinDecimals: { evm: number; sui: number; svm: number }

maxCoinDecimals: number

suiCoinDecimals: number

suiCoinType: string

Methods

getCoinMetadata

Parameters

Returns Promise<CoinMetadaWithInfo>

Throws

Example

getCoinMetadatas

Parameters

Returns Promise<CoinMetadaWithInfo[]>

Example

getCoinsToDecimals

Parameters

Returns Promise<CoinsToDecimals>

Example

getPrice

Parameters

Returns Promise<CoinPriceInfo>

Throws

Example

getVerifiedCoins

Returns Promise<string[]>

Example

setCoinMetadata

Parameters

Returns void

setPriceInfo

Parameters

Returns void

StaticapiBaseUrlForNetwork

Parameters

Returns string

StaticbalanceWithDecimals

Parameters

Returns number

StaticbalanceWithDecimalsUsd

Parameters

Returns number

StaticcoinsAndAmountsOverZero

Parameters

Returns { amounts: number[]; coins: string[] }

StaticcoinsAndBalancesOverZero

Parameters

Returns { balances: bigint[]; coins: string[] }

StaticcoinSymbolForCoinType

Parameters

Returns string | undefined

StaticcoinTypeFromKeyType

Parameters

Returns string

StaticdefaultFullnodeUrl

Parameters

Returns string

StaticfilterCoinsByMetadata

`Optional` `Readonly`api

`Readonly`coinType

`Readonly`coinTypePackageName

`Readonly`coinTypeSymbol

`Readonly`innerCoinType

`Static` `Readonly`constants

`Static`apiBaseUrlForNetwork

`Static`balanceWithDecimals

`Static`balanceWithDecimalsUsd

`Static`coinsAndAmountsOverZero

`Static`coinsAndBalancesOverZero

`Static`coinSymbolForCoinType

`Static`coinTypeFromKeyType

`Static`defaultFullnodeUrl

`Static`filterCoinsByMetadata

`Static`filterCoinsByType

`Static`getCoinTypePackageName

`Static`getCoinTypeSymbol

`Static`getInnerCoinType

`Static`isCoinObjectType

`Static`isSuiCoin

`Static`normalizeBalance