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

bun add @swapkit/sdk

pnpm

pnpm add @swapkit/sdk

npm

npm install @swapkit/sdk

yarn

yarn add @swapkit/sdk

Basic Setup

1. Import and Initialize SwapKit

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

// Create a SwapKit instance with default configuration
const swapKit = createSwapKit();

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', // Get from cloud.walletconnect.com
      blockchair: 'your-blockchair-key',         // Get from blockchair.com/api
      swapKit: 'your-swapkit-key',               // Get from api.swapkit.dev
    },
    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';

// Examples of supported chains
const ethereum = Chain.Ethereum;   // "ETH"
const bitcoin = Chain.Bitcoin;     // "BTC"
const cosmos = Chain.Cosmos;       // "GAIA"
const thorchain = Chain.THORChain; // "THOR"

2. AssetValue

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

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

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

// Tokens include the contract address
const usdc = AssetValue.from({
  asset: 'ETH.USDC-0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48',
  value: 1000
}); // 1000 USDC on Ethereum

3. Wallets

SwapKit supports 20+ wallet types:

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

// Browser extension wallets
const metamask = WalletOption.METAMASK;
const keplr = WalletOption.KEPLR;

// Hardware wallets
const ledger = WalletOption.LEDGER;

// Software wallets
const keystore = WalletOption.KEYSTORE;

Common Use Cases

Connect a Wallet

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

const swapKit = createSwapKit();

// Connect Keystore wallet (mnemonic phrase)
await swapKit.connectKeystore(
  [Chain.Ethereum, Chain.Bitcoin],
  'your twelve word mnemonic phrase here'
);

// Connect MetaMask (EVM chains only)
await swapKit.connectEVMWallet([Chain.Ethereum], WalletOption.METAMASK);

// Connect Keplr (Cosmos chains)
await swapKit.connectKeplr([Chain.Cosmos, Chain.THORChain]);

// Connect Cosmostation (Cosmos chains)
await swapKit.connectCosmostation([Chain.Cosmos, Chain.THORChain]);

// Get all connected wallets
const wallets = swapKit.getAllWallets();

Get Wallet Balances

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

const swapKit = createSwapKit();

// Get balance for a specific chain
const ethBalance = await swapKit.getBalance(Chain.Ethereum);
const btcBalance = await swapKit.getBalance(Chain.Bitcoin);

// Force refresh balance (bypass cache)
const freshBalance = await swapKit.getBalance(Chain.Ethereum, true);

// Get wallet with balance
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();

// Step 1: Get a quote
const quoteParams = {
  sellAsset: 'ETH.ETH',
  sellAmount: '1000000000000000000', // 1 ETH in wei
  buyAsset: 'BTC.BTC',
  sourceAddress: swapKit.getAddress(Chain.Ethereum),
  destinationAddress: swapKit.getAddress(Chain.Bitcoin),
  slippage: 3, // 3% slippage tolerance
};

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

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

// Step 3: Execute the swap
const txHash = await swapKit.swap({
  route: bestRoute,
  feeOptionKey: FeeOption.Fast
});

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

Send Transactions

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

const swapKit = createSwapKit();

// Simple ETH transfer
const ethAmount = AssetValue.from({ asset: 'ETH.ETH', value: '0.1' });

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

// Bitcoin transfer with custom fee
const btcAmount = AssetValue.from({ asset: 'BTC.BTC', value: '0.001' });

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

// Ripple (XRP) transfer
const xrpAmount = AssetValue.from({ asset: 'XRP.XRP', value: '10' });

const xrpTxHash = await swapKit.transfer({
  assetValue: xrpAmount,
  recipient: 'rBaaxNpAKxELKXkJpSCCJQTkQMTYrcPQPv',
  memo: 'Invoice #12345', // Optional destination tag or memo
  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) => {
    // Your custom logic here
    return { success: true };
  },

  // Add custom functionality
  getCustomData: async () => {
    console.log('Fetching custom data');
    return { data: 'custom-data' };
  }
};

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

// Use your custom method
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 {
  // Example: attempting a swap with a route object
  const route = {
    sellAsset: 'ETH.ETH',
    buyAsset: 'BTC.BTC',
    expectedBuyAmount: '0.001',
    // ... other route properties
  };
  await swapKit.swap({
    route,
    feeOptionKey: FeeOption.Fast
  });
} catch (error) {
  if (error instanceof SwapKitError) {
    console.error('SwapKit Error:', error.message);
    // Error may have additional properties
    console.error('Full error:', error);
  } else {
    console.error('Unexpected error:', error);
  }
}

Next Steps

Now that you understand the basics:

Essential Reading

1. Core Concepts - Master AssetValue, error handling, and types
2. Configuration - Set up API keys and customize settings
3. API Reference - Explore all available API methods

Build Your Application

1. Connect Wallets - Deep dive into wallet integration
2. Perform Swaps - Implement cross-chain swaps
3. Send Transactions - Handle transfers and tracking

Advanced Topics

1. THORChain Features - Liquidity, and THORNames
2. Advanced Features - Multi-chain ops and synthetics
3. Toolbox Usage - Direct blockchain operations

Extend SwapKit

1. Create Custom Plugin - Add new protocols
2. Create Custom Wallet - Integrate new wallets
3. Framework Integration - Use with Next.js, Vite, etc.

Need Help?

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

---

Happy building with SwapKit! 🚀