Getting Started with SwapKit

SwapKit is a comprehensive SDK that unifies blockchain interactions across 20+ chains. This guide will walk you through installation, setup, and building your first cross-chain application.

Prerequisites

Before starting, ensure you have:

Node.js 18+ or Bun installed
Basic knowledge of JavaScript/TypeScript
A code editor (VS Code recommended)

Installation

bun add @swapkit/sdk

pnpm add @swapkit/sdk

npm install @swapkit/sdk

yarn add @swapkit/sdk

Basic Setup

1. Import and Initialize SwapKit

// @noErrorValidation

import { createSwapKit } from "@swapkit/sdk";

const swapKit = createSwapKit();

Try SwapKit Now

Jump into a live environment and experiment with SwapKit right away

Official Playgrounds

Online IDEs

StackBlitz

Instant dev environment

CodeSandbox

Collaborative coding

2. Configure SwapKit (Optional)

For production applications, you’ll want to add your own API keys and custom settings. See our Configuration Guide for detailed setup:

// @noErrorValidation

import { createSwapKit } from "@swapkit/sdk";

const swapKit = createSwapKit({
  config: {
    apiKeys: {
      walletConnectProjectId: "your-project-id",
      blockchair: "your-blockchair-key",
      swapKit: "your-swapkit-key",
    },
    rpcUrls: {
      ETH: "https://eth-mainnet.g.alchemy.com/v2/your-key",
      AVAX: "https://api.avax.network/ext/bc/C/rpc",
    },
  },
});

Core Concepts

SwapKit has several fundamental concepts you should understand. For a detailed explanation, see our Core Concepts guide.

1. Chains

SwapKit supports 20+ blockchain networks with a unified Chain identifier system:

// @noErrorValidation

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

const ethereum = Chain.Ethereum;
const bitcoin = Chain.Bitcoin;
const cosmos = Chain.Cosmos;
const thorchain = Chain.THORChain;

2. AssetValue

AssetValue is SwapKit’s way of representing amounts of any asset:

// @noErrorValidation

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

const eth = AssetValue.from({ asset: "ETH.ETH", value: 1 });
const btc = AssetValue.from({ asset: "BTC.BTC", value: 0.1 });

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

3. Wallets

SwapKit supports 20+ wallet types:

// @noErrorValidation

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

const metamask = WalletOption.METAMASK;
const keplr = WalletOption.KEPLR;

const ledger = WalletOption.LEDGER;

const keystore = WalletOption.KEYSTORE;

Common Use Cases

Connect a Wallet

// @noErrorValidation

import { createSwapKit, Chain, WalletOption } from "@swapkit/sdk";

const swapKit = createSwapKit();

await swapKit.connectKeystore(
  [Chain.Ethereum, Chain.Bitcoin],
  "your twelve word mnemonic phrase here"
);

await swapKit.connectEVMWallet([Chain.Ethereum], WalletOption.METAMASK);

await swapKit.connectKeplr([Chain.Cosmos, Chain.THORChain]);

await swapKit.connectCosmostation([Chain.Cosmos, Chain.THORChain]);

const wallets = swapKit.getAllWallets();

Get Wallet Balances

// @noErrorValidation

import { createSwapKit, Chain } from "@swapkit/sdk";

const swapKit = createSwapKit();

const ethBalance = await swapKit.getBalance(Chain.Ethereum);
const btcBalance = await swapKit.getBalance(Chain.Bitcoin);

const freshBalance = await swapKit.getBalance(Chain.Ethereum, true);

const walletWithBalance = await swapKit.getWalletWithBalance(Chain.Ethereum);
console.log(`Address: ${walletWithBalance.address}`);
console.log(`Balance: ${walletWithBalance.balance}`);

Perform a Swap

Use the SwapKit API to get quotes and execute swaps:

// @noErrorValidation

import { createSwapKit, Chain, FeeOption, SwapKitApi } from "@swapkit/sdk";

const swapKit = createSwapKit();

const quoteParams = {
  sellAsset: "ETH.ETH",
  sellAmount: "1000000000000000000",
  buyAsset: "BTC.BTC",
  sourceAddress: swapKit.getAddress(Chain.Ethereum),
  destinationAddress: swapKit.getAddress(Chain.Bitcoin),
  slippage: 3,
};

const { routes } = await SwapKitApi.getSwapQuote(quoteParams);

const bestRoute = routes[0];
console.log(`Expected output: ${bestRoute.expectedBuyAmount}`);
console.log(`Fees:`, bestRoute.fee);

const txHash = await swapKit.swap({
  route: bestRoute,
  feeOptionKey: FeeOption.Fast,
});

console.log(`Swap transaction: ${txHash}`);

🚀 Your First Cross-Chain Swap

Follow this interactive tutorial to perform your first swap with SwapKit

Try in Playground

Step 1 of 4

Install and Initialize SwapKit

Set up SwapKit in your project with the required dependencies

Code Example

bun add @swapkit/sdk

import { createSwapKit } from '@swapkit/sdk';

const swapKit = createSwapKit({
config: {
  apiKeys: {
    swapKit: 'your-api-key-here'
  }
}
});

Action Required

Install SwapKit and create your instance

Tips & Best Practices

Get your API key from https://api.swapkit.dev for enhanced features
The SDK works without API keys for basic functionality
Consider using environment variables for API keys in production

Connect Your Wallet

Connect a wallet to access blockchain functionality

Code Example


await swapKit.connectEVMWallet([Chain.Ethereum]);

await swapKit.connectKeystore(
[Chain.Ethereum, Chain.Bitcoin],
'your twelve word mnemonic phrase'
);

const ethAddress = swapKit.getAddress(Chain.Ethereum);
console.log('Connected:', ethAddress);

Action Required

Connect your preferred wallet type

Tips & Best Practices

Different wallet types support different chains
Hardware wallets provide enhanced security
Always verify addresses before sending transactions

Get a Swap Quote

Fetch quotes from multiple DEX aggregators to find the best rate

Code Example

import { SwapKitApi } from '@swapkit/sdk';

const quoteResponse = await SwapKitApi.getSwapQuote({
sellAsset: 'ETH.ETH',
buyAsset: 'BTC.BTC',
sellAmount: '0.1',
sourceAddress: swapKit.getAddress(Chain.Ethereum),
destinationAddress: swapKit.getAddress(Chain.Bitcoin),
slippage: 1
});

const bestRoute = quoteResponse.data.routes[0];
console.log('Expected output:', bestRoute.expectedBuyAmount);

Action Required

Fetch swap quotes from the API

Tips & Best Practices

Compare multiple routes for the best rate
Consider transaction fees in your calculations
Slippage tolerance affects the final amount received

Execute the Swap

Perform the cross-chain swap using the selected route

Code Example

import { FeeOption } from '@swapkit/sdk';

const txHash = await swapKit.swap({
route: bestRoute,
feeOptionKey: FeeOption.Fast
});

console.log('Transaction hash:', txHash);

const txUrl = swapKit.getExplorerTxUrl({
chain: Chain.Ethereum,
txHash
});

Action Required

Execute your first cross-chain swap

Tips & Best Practices

Save the transaction hash for tracking
Cross-chain swaps may take several minutes to complete
Use block explorers to monitor transaction status

Send Transactions

// @noErrorValidation

import { createSwapKit, AssetValue, FeeOption, Chain } from "@swapkit/sdk";

const swapKit = createSwapKit();

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

const txHash = await swapKit.transfer({
  assetValue: ethAmount,
  recipient: "0x742d35Cc6634C0532925a3b844Bc9e7595f6E321",
  memo: "Payment for services",
  feeOptionKey: FeeOption.Fast,
});

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

const btcTxHash = await swapKit.transfer({
  assetValue: btcAmount,
  recipient: "bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh",
  feeOptionKey: FeeOption.Average,
});

const xrpAmount = AssetValue.from({ asset: "XRP.XRP", value: "10" });

const xrpTxHash = await swapKit.transfer({
  assetValue: xrpAmount,
  recipient: "rBaaxNpAKxELKXkJpSCCJQTkQMTYrcPQPv",
  memo: "Invoice #12345",
  feeOptionKey: FeeOption.Fast,
});

Advanced Usage

Using Core + Plugins (Modular Approach)

For smaller bundle sizes, use only the components you need:

// @noErrorValidation

import {
  SwapKit,
  ThorchainPlugin,
  keystoreWallet,
  ledgerWallet,
} from "@swapkit/sdk";

const swapKit = SwapKit({
  plugins: {
    ...ThorchainPlugin,
  },
  wallets: {
    ...keystoreWallet,
    ...ledgerWallet,
  },
});

Direct Toolbox Usage

For low-level blockchain operations:

// @noErrorValidation

import { getToolbox, Chain } from "@swapkit/sdk";

const address = "bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh";
const btcToolbox = getToolbox(Chain.Bitcoin);

const isValid = btcToolbox.validateAddress(address);

const balance = await btcToolbox.getBalance(address);

Custom Plugin Development

Create your own plugin to extend SwapKit:

// @noErrorValidation

import { SwapKit } from "@swapkit/sdk";

const MyCustomPlugin = {
  myCustomMethod: async (params: any) => {
    return { success: true };
  },

  getCustomData: async () => {
    console.log("Fetching custom data");
    return { data: "custom-data" };
  },
};

const swapKit = SwapKit({
  plugins: {
    ...MyCustomPlugin,
  },
});

await swapKit.myCustomMethod({ customParam: "value" });
await swapKit.getCustomData();

Error Handling

SwapKit uses typed errors for better debugging:

// @noErrorValidation

import { createSwapKit, SwapKitError, FeeOption } from "@swapkit/sdk";

const swapKit = createSwapKit();

try {
  const route = {
    sellAsset: "ETH.ETH",
    buyAsset: "BTC.BTC",
    expectedBuyAmount: "0.001",
  };
  await swapKit.swap({
    route,
    feeOptionKey: FeeOption.Fast,
  });
} catch (error) {
  if (error instanceof SwapKitError) {
    console.error("SwapKit Error:", error.message);

    console.error("Full error:", error);
  } else {
    console.error("Unexpected error:", error);
  }
}

Next Steps

Now that you understand the basics, here’s your recommended learning path:

📚 Essential Foundation (Complete First)

Core Concepts

Master AssetValue, error handling, and TypeScript types that power every SwapKit operation. Learn Core Concepts →

Configuration

Set up API keys, RPC URLs, and customize settings for your production environment. Configure SwapKit →

⚡ Essential Actions (Build Your First App)

Connect Wallets

Deep dive into wallet integration across 20+ supported wallets and chains. Wallet Integration →

Send Transactions

Handle transfers, fee estimation, and transaction tracking across all chains. Transaction Guide →

Perform Swaps

Implement cross-chain swaps with quote fetching and execution. Swap Implementation →

🌐 Chain-Specific Integration

EVM Chains

Ethereum, Arbitrum, Polygon, and other EVM-compatible networks. EVM Integration →

Bitcoin Family

Bitcoin, Litecoin, Dogecoin, and other UTXO-based chains. Bitcoin Integration →

Other Networks

Solana, Cosmos, Ripple, and specialized blockchain integrations. All Chains →

🚀 Production & Advanced Topics

Best Practices

Production deployment, security, performance, and error handling. Production Guide →

THORChain Features

Leverage THORChain’s native liquidity and advanced DeFi features. THORChain Guide →

Advanced Features

Multi-chain operations, synthetic assets, and enterprise features. Advanced Guide →

🔧 Extend & Customize SwapKit

Framework Integration

Use SwapKit with Next.js, Vite, React Native, and other frameworks. Framework Guides →

Custom Plugins

Create plugins for new protocols and extend SwapKit’s capabilities. Plugin Development →

Custom Wallets

Build wallet adapters for new providers and specialized use cases. Wallet Development →

🆕 What’s New in v4

If you’re upgrading from v3 or want to explore the latest features:

What’s New in v4 - Runtime configuration, improved architecture, and new features
Migration Guide - Complete upgrade guide from v3 to v4

Need Help?

💬 Join our Discord for community support
🐛 Report issues on GitHub
📚 Browse the API Reference for detailed documentation

Happy building with SwapKit! 🚀

Getting Started with SwapKit

Prerequisites

Installation

Basic Setup

1. Import and Initialize SwapKit

Try SwapKit Now

Official Playgrounds

Online IDEs

2. Configure SwapKit (Optional)

Core Concepts

1. Chains

2. AssetValue

3. Wallets

Common Use Cases

Connect a Wallet

Get Wallet Balances

Perform a Swap

🚀 Your First Cross-Chain Swap

Install and Initialize SwapKit

Connect Your Wallet

Get a Swap Quote

Execute the Swap

Congratulations!

Send Transactions

Advanced Usage

Using Core + Plugins (Modular Approach)

Direct Toolbox Usage

Custom Plugin Development

Error Handling

Next Steps

📚 Essential Foundation (Complete First)

⚡ Essential Actions (Build Your First App)

🌐 Chain-Specific Integration

🚀 Production & Advanced Topics

🔧 Extend & Customize SwapKit

🆕 What’s New in v4

Need Help?