Skip to content
SwapDK is a powerful suite of tools for building blockchain applications.

Core Concepts

Before diving into SwapDK’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

Section titled “AssetValue”

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

Creating AssetValue

Section titled “Creating AssetValue”
// @noErrorValidation
import { AssetValue } from "@swapdk/sdk";


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


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

Asset Notation

Section titled “Asset Notation”

SwapDK 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

Section titled “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

Section titled “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

Section titled “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

Section titled “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

Section titled “SwapKitNumber”

SwapKitNumber provides utilities for safe numeric operations with BigInt support:

// @noErrorValidation
import { SwapKitNumber } from "@swapdk/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

Section titled “Chain Types”

SwapDK uses consistent chain identifiers across the entire SDK:

// @noErrorValidation
import { Chain } from "@swapdk/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

Section titled “Error Handling”

SwapDK uses a typed error system for better debugging:

SwapKitError

Section titled “SwapKitError”

The base error class with additional context:

// @noErrorValidation
import { SwapKitError } from "@swapdk/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

Section titled “Common Error Codes”

SwapDK 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

Section titled “Error Context”

Errors include helpful context:

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










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

Wallet Types

Section titled “Wallet Types”

SwapDK supports various wallet types through the WalletOption enum:

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


WalletOption.METAMASK;
WalletOption.LEDGER;
WalletOption.TREZOR;
WalletOption.WALLETCONNECT;
WalletOption.KEYSTORE;

Fee Options

Section titled “Fee Options”

Control transaction fees with the FeeOption enum:

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


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


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

Provider Types

Section titled “Provider Types”

SwapDK integrates with multiple swap providers:

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


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

Best Practices

Section titled “Best Practices”

1. Always Use AssetValue for Amounts

Section titled “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

Section titled “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

Section titled “3. Compare Assets Safely”
// @noErrorValidation


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


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

4. Format for Display

Section titled “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

Section titled “Next Steps”

Now that you understand SwapDK’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 SwapDK →

⚡ Essential Actions

Learn the core functionality every SwapDK 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 SwapDK API with detailed method documentation. API Reference →

Learning Path Recommendations

Section titled “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.