Supported Tokens

The SDK exposes route discovery helpers on the swapper instance so you can build token selectors, validate route availability before quoting, and resolve stored token identifiers back into typed token objects.

These helpers reflect two things:

• the chains enabled in your SwapperFactory
• the LPs discovered during await swapper.init()

That means Factory.Tokens gives you the static typed token catalog with a list of supported tokens for the configured chains, while the methods below give you the runtime view of what is currently swappable.

info

Call these helpers after await swapper.init() so LP discovery has already completed. The returned set depends on the currently discovered LPs and the chains you initialized.

Runnable Example

See the complete working example: utils/supportedTokens.ts

Token Object

All token helpers and Factory.Tokens.* return the same Token object, this contains all the information about the token and comes with helpers for checking token equality and serializing the token to its string representation.

Field	Type	Description
chainId	"BITCOIN" | "LIGHTNING" | "STARKNET" | ...	Canonical chain identifier, i.e. SOLANA, STARKNET, CITREA, etc. for Smart chain tokens and BITCOIN or LIGHTNING for Bitcoin tokens
ticker	string	Token symbol used in quotes and UI.
name	string	Full token name.
decimals	number	Raw token precision used for amount parsing.
displayDecimals	number	Optional preferred display precision for UI formatting.
address	string	Smart-chain contract address or mint. For BTC and BTC-LN this is an empty string.
equals(other)	boolean	Checks whether the token equals some other token.
toString()	string	Stable token identifier string that can be passed back into swapper.getToken(...). Smart-chain tokens use <chainId>-<ticker> format.

SCToken and BtcToken are narrowed down types for smart-chain and bitcoin based tokens, respectively. This distinction is used for automatic swap type inference in swap() function and also in other places. Use isSCToken() and isBtcToken() typeguards to narrow down the type of Token to the respective BtcToken and SCToken types.

tip

If you need to persist a token in your database, URL, or form state, prefer token.toString() over manually constructing an identifier string. The returned value is compatible with swapper.getToken(...).

Listing Supported Tokens

Use getSupportedTokens() to get a list of available source and destination tokens. This takes into account the current set of active and discovered LPs and returns tokens for which the LPs advertise support.

import {SwapSide} from "@atomiqlabs/sdk";

const sourceTokens = swapper.getSupportedTokens(SwapSide.INPUT); // Usable as the swap input
const destinationTokens = swapper.getSupportedTokens(SwapSide.OUTPUT); // Usable as the swap output

console.log("Sources:", sourceTokens.map((token) => token.toString()));
console.log("Destinations:", destinationTokens.map((token) => token.toString()));

info

Factory.Tokens may contain more tokens than swapper.getSupportedTokens(...), because a token can exist in the configured chain catalog even when no currently discovered LP offers a route for it.

Getting Valid Counter Tokens

Use getSwapCounterTokens() when the token one side of the swap is already known and you want to constrain the other side.

If the user already selected the input token, pass SwapSide.INPUT to get the valid output tokens:

import {SwapSide} from "@atomiqlabs/sdk";

const outputsFromStrk = swapper.getSwapCounterTokens(
  Tokens.STARKNET.STRK,
  SwapSide.INPUT
);

console.log(outputsFromStrk.map((token) => token.toString()));
// Returns BTC and/or BTC-LN if STRK can currently be swapped out to them

If the user already selected the output token, pass SwapSide.OUTPUT to get the valid input tokens:

import {SwapSide} from "@atomiqlabs/sdk";

const inputsForBtc = swapper.getSwapCounterTokens(
  Tokens.BITCOIN.BTC,
  SwapSide.OUTPUT
);

console.log(inputsForBtc.map((token) => token.toString()));
// Returns various smart-chain tokens that can currently be swapped to BTC

Resolving Tokens from Identifiers

Use getToken() to resolve Token object from strings returned from Token.toString(), raw contract addresses or tickers.

// Bitcoin tokens
const btc = swapper.getToken("BTC");
const btcln = swapper.getToken("BTC-LN");

// Chain-prefixed smart chain tickers
const strk = swapper.getToken("STARKNET-STRK");
const solUsdc = swapper.getToken("SOLANA-USDC");

// Parse based on token contract address
const starknetEth = swapper.getToken(
  "0x049d36570d4e46f48e99674bd3fcc84644ddd6b96f7c741b1562b82f9e004dc7"
);

You can round-trip a token through its string representation:

const token = swapper.getToken("STARKNET-STRK");
const serialized = token.toString(); // "STARKNET-STRK"
const sameToken = swapper.getToken(serialized);

console.log(serialized); // "STARKNET-STRK"
console.log(token.equals(sameToken)); // true

warning

Bare tickers are convenient, but they can be ambiguous in a multichain context:

const token = swapper.getToken("WBTC"); // Can throw if WBTC exists on multiple configured chains
const starknetWbtc = swapper.getToken("STARKNET-WBTC"); // Unambiguous

tip

For compile-time setup prefer the use of a statically typed Factory.Tokens, instead of relying on swapper.getToken(). Using the swapper.getToken() method is useful for resolving tokens during runtime.

Usage in a Token Selector UI

You can use the exposed helper functions to build a route-aware token selector form, which automatically detects which tokens are supported and also which routes are available given an input token is chosen.

import {SwapSide} from "@atomiqlabs/sdk";

// Get tokens supported as a swap input
const supportedSourceTokens = swapper.getSupportedTokens(SwapSide.INPUT);
// You can also filter the tokens based on the chain
const starknetSupportedSourceTokens = supportedSourceTokens
  .filter(token => token.chainId === "STARKNET");

// Check which swap routes are available from a selected source token
function onSourceTokenChange(sourceTokenId: string) {
  // Can also pass `sourceToken: Token` directly as a function argument
  const sourceToken = swapper.getToken(sourceTokenId);
  const supportedDestinationTokens = swapper.getSwapCounterTokens(sourceToken, SwapSide.INPUT);
  ...
}

API Reference

• Swapper - Main SDK client
• getSupportedTokens - Get currently supported inputs or outputs
• getSwapCounterTokens - Get valid counterpart tokens for one side of a route
• getToken - Resolve a token by ticker or address
• SwapSide - Input/output side enum for token helper functions
• Token - Shared token object shape returned by all token helpers
• BtcToken - Bitcoin token specialization
• SCToken - Smart-chain token specialization
• isBtcToken - Bitcoin token type-guard
• isSCToken - Smart-chain token type-guard
• SwapperFactory - Factory for building typed swappers
• TypedTokens - Typed token catalog derived from the configured chains

Next Steps

Creating Quotes

Once you know the source and destination tokens, the next step is requesting a route quote with swapper.swap(...).

Creating Quotes →

---

Swap Types

Inspect the swap protocol used for a given token pair and what capabilities it supports.

Swap Types →

---

Wallet Balance

For source-token selectors and "Max" buttons, pair route discovery with the SDK's fee-aware balance helpers.

Wallet Balance →

---