Core Concepts

Before diving into SwapKit’s features, it’s essential to understand its core concepts. These building blocks are used throughout the SDK and understanding them will make your development experience much smoother.

AssetValue

AssetValue is SwapKit’s primary way of representing amounts of any asset across all supported chains. It handles decimal precision, formatting, and arithmetic operations automatically.

Creating AssetValue

// @noErrorValidation
import { AssetValue } from "@swapkit/sdk";

const oneEth = AssetValue.from({
  asset: "ETH.ETH",
  value: 1,
});

const oneEthInWei = AssetValue.from({
  asset: "ETH.ETH",
  value: "1000000000000000000",
  fromBaseDecimal: true,
});

Asset Notation

SwapKit uses a consistent format for identifying assets:

// @noErrorValidation

"ETH.ETH";
"BTC.BTC";
"AVAX.AVAX";

"ETH.USDC-0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48";
"AVAX.USDC-0xB97EF9Ef8734C71904D8002F8b6Bc66Dd9c48a6E";

"ETH/ETH";
"BTC/BTC";

Arithmetic Operations

AssetValue provides safe arithmetic operations:

// @noErrorValidation
const amount1 = AssetValue.from({ asset: "ETH.ETH", value: 1.5 });
const amount2 = AssetValue.from({ asset: "ETH.ETH", value: 0.5 });

const sum = amount1.add(amount2);

const difference = amount1.sub(amount2);

const doubled = amount1.mul(2);

const halved = amount1.div(2);

Comparisons

Compare AssetValue instances safely:

// @noErrorValidation
const amount1 = AssetValue.from({ asset: "BTC.BTC", value: 1 });
const amount2 = AssetValue.from({ asset: "BTC.BTC", value: 0.5 });

amount1.gt(amount2);
amount1.gte(amount2);
amount1.lt(amount2);
amount1.lte(amount2);
amount1.eq(amount2);

Formatting

Format values for display:

// @noErrorValidation
const btcAmount = AssetValue.from({ asset: "BTC.BTC", value: 0.00123456 });

btcAmount.toSignificant(4);

btcAmount.toCurrency("USD", 45000);

const largeAmount = AssetValue.from({ asset: "ETH.ETH", value: 1234567 });
largeAmount.toAbbreviation();

btcAmount.getValue("string");
btcAmount.getBaseValue("string");

Type Checks

Check asset properties:

// @noErrorValidation
const ethAmount = AssetValue.from({ asset: "ETH.ETH", value: 1 });
const usdcAmount = AssetValue.from({
  asset: "ETH.USDC-0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
  value: 100,
});
const synthEth = AssetValue.from({ asset: "ETH/ETH", value: 1 });

ethAmount.isGasAsset();
usdcAmount.isGasAsset();
synthEth.isSynthetic();

SwapKitNumber

SwapKitNumber provides utilities for safe numeric operations with BigInt support:

// @noErrorValidation
import { SwapKitNumber } from "@swapkit/sdk";

const num1 = new SwapKitNumber(123.456);
const num2 = new SwapKitNumber("789.012");
const num3 = new SwapKitNumber({ value: 100, decimal: 18 });

const sum = num1.add(num2);
const product = num1.mul(num2);

num1.toSignificant(4);
num1.toFixed(2);

Chain Types

SwapKit uses consistent chain identifiers across the entire SDK:

// @noErrorValidation
import { Chain } from "@swapkit/sdk";

Chain.Ethereum;
Chain.Avalanche;
Chain.BinanceSmartChain;
Chain.Polygon;
Chain.Arbitrum;
Chain.Optimism;
Chain.Base;

Chain.Bitcoin;
Chain.BitcoinCash;
Chain.Litecoin;
Chain.Dogecoin;
Chain.Dash;
Chain.Zcash;

Chain.Cosmos;
Chain.THORChain;
Chain.Maya;
Chain.Kujira;

Chain.Solana;
Chain.Polkadot;
Chain.Chainflip;
Chain.Radix;
Chain.Ripple;

Error Handling

SwapKit uses a typed error system for better debugging:

SwapKitError

The base error class with additional context:

// @noErrorValidation
import { SwapKitError } from "@swapkit/sdk";

try {
  await swapKit.swap({ route });
} catch (error) {
  if (error instanceof SwapKitError) {
    console.error("Error:", error.message);
    console.error("Code:", error.code);
    console.error("Details:", error.details);
  }
}

Common Error Codes

SwapKit uses standardized error codes:

// @noErrorValidation

"wallet_not_found";
"wallet_connection_failed";
"wallet_insufficient_funds";

"transaction_failed";
"transaction_rejected";
"transaction_timeout";

"api_request_failed";
"api_rate_limit";
"api_invalid_response";

"invalid_address";
"invalid_amount";
"invalid_chain";

Error Context

Errors include helpful context:

// @noErrorValidation
catch (error) {
  if (error instanceof SwapKitError) {





    console.log('Context:', error.info);
  }
}

Wallet Types

SwapKit supports various wallet types through the WalletOption enum:

// @noErrorValidation
import { WalletOption } from "@swapkit/sdk";

WalletOption.METAMASK;
WalletOption.COINBASE;
WalletOption.OKX;
WalletOption.BITGET;
WalletOption.EXODUS;
WalletOption.KEPLR;
WalletOption.LEAP;
WalletOption.COSMOSTATION;
WalletOption.LEDGER;
WalletOption.TREZOR;
WalletOption.KEEPKEY;
WalletOption.WALLETCONNECT;
WalletOption.KEYSTORE;
WalletOption.POLKADOTJS;
WalletOption.TALISMAN;
WalletOption.PHANTOM;
WalletOption.ONEKEY;
WalletOption.RADIX_MOBILE;
WalletOption.BRAVE;
WalletOption.TRUSTWALLET;
WalletOption.XDEFI;

Fee Options

Control transaction fees with the FeeOption enum:

// @noErrorValidation
import { FeeOption } from "@swapkit/sdk";

FeeOption.Average;
FeeOption.Fast;
FeeOption.Fastest;

await swapKit.transfer({
  assetValue,
  recipient,
  feeOptionKey: FeeOption.Fast,
});

Provider Types

SwapKit integrates with multiple swap providers:

// @noErrorValidation
import { ProviderName } from "@swapkit/sdk";

ProviderName.THORCHAIN;
ProviderName.CHAINFLIP;
ProviderName.ONEINCH;
ProviderName.UNISWAP;
ProviderName.SUSHISWAP;
ProviderName.PANCAKESWAP;

Best Practices

1. Always Use AssetValue for Amounts

// @noErrorValidation

const amount = AssetValue.from({ asset: "ETH.ETH", value: 1 });
await swapKit.transfer({ assetValue: amount, recipient });

await swapKit.transfer({ value: 1, recipient });

2. Handle Decimal Precision

// @noErrorValidation

const usdcAmount = AssetValue.from({
  asset: "ETH.USDC-0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
  value: 100,
});

const weiAmount = AssetValue.from({
  asset: "ETH.ETH",
  value: "1000000000000000000",
  fromBaseDecimal: true,
});

3. Compare Assets Safely

// @noErrorValidation

if (balance.gte(requiredAmount)) {
  await performTransaction();
}

if (Number(balance.getValue()) >= Number(requiredAmount.getValue())) {
  await performTransaction();
}

4. Format for Display

// @noErrorValidation

const btcBalance = AssetValue.from({ asset: "BTC.BTC", value: 0.00123456 });

const displayValue = btcBalance.toSignificant(6);

const usdValue = btcBalance.toCurrency("USD", btcPrice);

Next Steps

Now that you understand SwapKit’s core concepts, you’re ready to build your first application:

🔧 Configuration Setup

Configure API keys, RPC URLs, and production settings for optimal performance. Configure SwapKit →

⚡ Essential Actions

Learn the core functionality every SwapKit application needs to implement. Connect Wallets →

🛠️ Direct Chain Operations

Use toolboxes for low-level blockchain operations and custom integrations. Toolbox Usage →

📚 API Reference

Explore the complete SwapKit API with detailed method documentation. API Reference →

Learning Path Recommendations

For beginners: Start with Essential Actions to learn wallet connections and basic transactions.

For experienced developers: Jump to Advanced Features or explore specific chain integrations.

For production deployments: Review Best Practices and Security Guidelines.