Toolbox Usage

SwapKit toolboxes provide low-level blockchain operations for all supported chains. While the main SwapKit SDK handles most operations automatically, toolboxes give you direct access to chain-specific functionality when you need fine-grained control.

When to Use Toolboxes

Use toolboxes when you need:

• Direct control over transaction building
• Custom signing logic
• Read-only operations without full SDK
• Minimal bundle size (import only what you need)
• Integration with existing wallet infrastructure

For most use cases, the main SDK is recommended as it handles configuration, wallet connections, and provides a unified interface.

Available Toolboxes

SwapKit provides specialized toolboxes for different blockchain ecosystems:

• EVM Toolbox: For Ethereum, BSC, Arbitrum, Avalanche, Polygon, Optimism, Base, etc.
• UTXO Toolbox: For Bitcoin, Bitcoin Cash, Litecoin, Dogecoin, Dash, Zcash
• Cosmos Toolbox: For ATOM, THORChain, Maya, Kujira, etc.
• Solana Toolbox: For Solana blockchain
• Substrate Toolbox: For Polkadot, Chainflip, etc.
• Radix Toolbox: For Radix ecosystem
• Ripple Toolbox: For XRP Ledger
• NEAR Toolbox: For NEAR Protocol

Each toolbox can be imported individually, which is preferred for frontend applications to minimize bundle size.

Importing Toolboxes

Before using toolboxes, make sure you understand Core Concepts like Chain identifiers and AssetValue.

You can initialize a toolbox either by importing specific toolbox methods like getEvmToolbox or getUtxoToolbox or by common toolbox method getToolbox.

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

const ethToolbox = await getEvmToolbox(Chain.Ethereum);
const btcToolbox = await getUtxoToolbox(Chain.Bitcoin);

or

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

const ethToolbox = await getToolbox(Chain.Ethereum);
const btcToolbox = await getToolbox(Chain.Bitcoin);

EVM Toolbox

Importing and Initializing

import { Chain, getEvmToolbox, getProvider } from "@swapkit/sdk";
import { ethers } from "ethers";

// Get a toolbox for a specific EVM chain
const ethereumToolbox = await getEvmToolbox(Chain.Ethereum);

const provider = await getProvider(Chain.Ethereum);
// With a signer (for transactions)
const signer = new ethers.Wallet("your-private-key-here", provider);
const signingToolbox = await getEvmToolbox(Chain.Ethereum, {
  // You can provide a custom provider & signer
  // provider: getProvider(Chain.Ethereum),
  signer,
});

Common Methods

Address Validation

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

// Validate an Ethereum address | true or false
const isValidAddress = evmValidateAddress({
  address: "0x742d35Cc6634C0532925a3b844Bc454e4438f44e",
});

Token Transfers

// @noErrorValidation
import { AssetValue, Chain, FeeOption, getEvmToolbox, getProvider } from "@swapkit/sdk";
import { ethers } from "ethers";

async function transferTokens() {
  // Create a signer
  const provider = await getProvider(Chain.Ethereum);
  const signer = new ethers.Wallet("your-private-key", provider);

  // Create a toolbox with signer
  const ethToolbox = await getEvmToolbox(Chain.Ethereum, {
    provider,
    signer
  });

  // ERC20 token transfer (USDC)
  const tokenAmount = AssetValue.from({
    chain: Chain.Ethereum,
    symbol: "USDC",
    address: "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48", // USDC contract
    value: "10", // 10 USDC
  });

  // Transfer the tokens
  const txHash = await ethToolbox.transfer({
    assetValue: tokenAmount,
    recipient: "0x742d35Cc6634C0532925a3b844Bc454e4438f44e",
    from: signer.address,
    feeOptionKey: FeeOption.Fast,
  });

  return txHash;
}

Smart Contract Interactions

// @noErrorValidation
import { Chain, erc20ABI, getEvmToolbox, getProvider } from "@swapkit/sdk";
import { ethers } from "ethers";

async function interactWithContract() {
  // Create a signer
  const provider = await getProvider(Chain.Ethereum);
  const signer = new ethers.Wallet("your-private-key", provider);

  // Create a toolbox with signer
  const ethToolbox = await getEvmToolbox(Chain.Ethereum, {
    provider,
    signer
  });

  // USDC contract address
  const contractAddress = "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48";

  // Read-only call (no signer needed)
  const tokenName = await ethToolbox.call<string>({
    contractAddress,
    abi: erc20ABI,
    funcName: "name",
  });

  // Get balance
  const balance = await ethToolbox.call<number>({
    contractAddress,
    abi: erc20ABI,
    funcName: "balanceOf",
    funcParams: [signer.address],
  });

  // Get decimals
  const decimals = await ethToolbox.call<number>({
    contractAddress,
    abi: erc20ABI,
    funcName: "decimals",
  });

  // Format the balance
  const formattedBalance = ethers.formatUnits(balance, decimals);

  // Contract write operation (requires signer)
  const transferResult = await ethToolbox.call<string>({
    contractAddress,
    abi: erc20ABI,
    funcName: "transfer",
    funcParams: [
      "0x742d35Cc6634C0532925a3b844Bc454e4438f44e",
      ethers.parseUnits("1.0", decimals),
    ],
  });

  return {
    name: tokenName,
    balance: formattedBalance,
    transferTx: transferResult,
  };
}

Fee Estimation

// @noErrorValidation
import { Chain, FeeOption, getEvmToolbox } from "@swapkit/sdk";
import { ethers } from "ethers";

async function estimateFees() {
  const ethToolbox = await getEvmToolbox(Chain.Ethereum);

  // Transaction to estimate
  const transaction = {
    to: "0x742d35Cc6634C0532925a3b844Bc454e4438f44e",
    from: "0x8C8D7C46219D9205f056f28Fee5950aD564d7465",
    value: ethers.parseEther("0.01"),
    data: "0x",
    chain: Chain.Ethereum as const,
  };

  // Estimate with different fee options
  const fastFee = await ethToolbox.estimateTransactionFee({
    ...transaction,
    feeOption: FeeOption.Fast,
  });

  const averageFee = await ethToolbox.estimateTransactionFee({
    ...transaction,
    feeOption: FeeOption.Average,
  });

  return {
    fast: fastFee.toString(),
    average: averageFee.toString(),
  };
}

UTXO Toolbox

Importing and Initializing

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

// Initialize the Bitcoin toolbox
async function setupBitcoinToolbox() {
  const btcToolbox = await getUtxoToolbox(Chain.Bitcoin);
  return btcToolbox;
}

Key Generation and Address Management

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

async function bitcoinKeysAndAddresses() {
  const btcToolbox = await getUtxoToolbox(Chain.Bitcoin);

  // Create keys from a mnemonic phrase
  const keys = await btcToolbox.createKeysForPath({
    phrase: "your twelve word mnemonic phrase here ...",
    derivationPath: "m/84'/0'/0'/0/0", // BIP84 for native segwit
  });

  // Get address from keys
  const address = btcToolbox.getAddressFromKeys(keys);

  // Validate an address
  const isValid = btcToolbox.validateAddress("bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf5mdq");

  return { address, isValid };
}

Building and Signing Transactions

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

async function createBitcoinTransaction() {
  const btcToolbox = await getUtxoToolbox(Chain.Bitcoin);

  // Create keys from a mnemonic phrase
  const keys = await btcToolbox.createKeysForPath({
    phrase: "your twelve word mnemonic phrase here ...",
    derivationPath: "m/84'/0'/0'/0/0",
  });

  const fromAddress = btcToolbox.getAddressFromKeys(keys);

  // Create a function to sign transactions
  async function signTransaction({ builder, utxos }: { builder: any, utxos: any[] }) {
    utxos.forEach((utxo, index) => {
      builder.sign(index, keys);
    });
    return builder.build();
  }

  // Get fee rates based on desired confirmation speed
  const feeRate = (await btcToolbox.getFeeRates()).average

  // Build a transaction
  const { psbt: builder, utxos } = await btcToolbox.buildTx({
    recipient: "bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf5mdq",
    feeRate,
    assetValue: AssetValue.from({ chain: Chain.Bitcoin, value: "0.0001" }),
    sender: fromAddress,
    memo: "Test transaction",
  });

  // Sign the transaction
  const signedTx = await signTransaction({ builder, utxos });

  // Get the raw transaction hex
  const txHex = signedTx.toHex();

  // To broadcast (send) the transaction:
  // const txHash = await btcToolbox.broadcastTransaction(txHex);

  return {
    txHex,
    // Once broadcast: txHash
  };
}

Balance and Fee Management

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

async function getUtxoData() {
  const btcToolbox = await getUtxoToolbox(Chain.Bitcoin);

  // Get balance for an address
  const address = "bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf5mdq";
  const balance = await btcToolbox.getBalance(address);

  // Calculate optimal fee
  const feeRates = await btcToolbox.getFeeRates();

  return { balance, feeRates };
}

Zcash Specific Operations

Zcash requires special handling due to its unique address format and transparent-only support:

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

async function zcashOperations() {
  // Initialize Zcash toolbox
  const zcashToolbox = await getUtxoToolbox(Chain.Zcash, {
    phrase: "abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon about"
  });

  // Generate Zcash transparent address (t1... for mainnet)
  const address = await zcashToolbox.getAddress();
  console.log("Zcash address:", address); // t1...

  // Validate addresses (transparent only)
  const isValid = zcashToolbox.validateAddress("t1XVXWCvpMgBvUaed4XDqWtgQgJSu1Ghz7F");
  console.log("Address valid:", isValid); // true

  // Shielded addresses are rejected
  const shieldedValid = zcashToolbox.validateAddress("zs1z7rejlpsa98s2...");
  console.log("Shielded valid:", shieldedValid); // false + warning

  // Transfer with memo support
  const txHash = await zcashToolbox.transfer({
    recipient: "t1XVXWCvpMgBvUaed4XDqWtgQgJSu1Ghz7F",
    assetValue: AssetValue.from({ chain: Chain.Zcash, value: "0.001" }),
    feeOptionKey: FeeOption.Fast,
    memo: "Payment memo" // Optional memo via OP_RETURN
  });

  // Create keys with custom derivation path
  const keys = await zcashToolbox.createKeysForPath({
    phrase: "abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon about",
    derivationPath: "m/44'/133'/0'/0/0" // Standard Zcash path
  });

  return { address, isValid, txHash, keys };
}

Cosmos Toolbox

Importing and Initializing

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

// Initialize a Cosmos toolbox
function initCosmosToolbox() {
  // For Cosmos Hub (ATOM)
  const cosmosToolbox = getCosmosToolbox(Chain.Cosmos);

  // For THORChain
  const thorchainToolbox = getCosmosToolbox(Chain.THORChain);

  return { cosmosToolbox, thorchainToolbox };
}

Wallet Creation, Signing and Transfers

// @noErrorValidation
import { AssetValue, Chain, FeeOption, getCosmosToolbox, TransferParams } from "@swapkit/sdk";

async function createThorchainWallet() {
  const toolbox = getCosmosToolbox(Chain.THORChain);
  const phrase = "your twelve word mnemonic phrase here";
  const signer = await toolbox.getSigner(phrase);
  const address = await toolbox.getAddressFromMnemonic(phrase);

  return {
    ...toolbox,
    address,
    transfer: (params: TransferParams) =>
      toolbox.transfer({ ...params, from: address, signer }),
    signMessage: async (message: string) => {
      const privateKey = await toolbox.createPrivateKeyFromPhrase(phrase);
      return toolbox.signWithPrivateKey({ privateKey, message });
    },
  };
}

const wallet = await createThorchainWallet();

const tx = await wallet.transfer({
  recipient: "cosmos1abcd1234abcd1234abcd1234abcd1234abcd12",
  assetValue: AssetValue.from({ chain: Chain.THORChain, value: "0.1" }),
  from: wallet.address,
  feeOptionKey: FeeOption.Average,
});

const signedMessage = await wallet.signMessage("Hello, world!");

Balances and Account Information

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

async function cosmosBalances() {
  const cosmosToolbox = getCosmosToolbox(Chain.Cosmos);

  // Get balance for an address
  const address = "cosmos1abcd1234abcd1234abcd1234abcd1234abcd12";
  const balances = await cosmosToolbox.getBalance(address);

  // Get account information
  const accountInfo = await cosmosToolbox.getAccount(address);

  return { balances, accountInfo };
}

Solana Toolbox

Importing and Initializing

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

// Initialize Solana toolbox
function initSolanaToolbox() {
  const solanaToolbox = getSolanaToolbox();
  return solanaToolbox;
}

Key Management and Addresses

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

async function solanaKeysAndAddresses() {
  const solanaToolbox = getSolanaToolbox();

  // Generate a keypair from a mnemonic phrase
  const keypair = await solanaToolbox.createKeysForPath({
    phrase: "your twelve word mnemonic phrase here",
    derivationPath: "m/44'/501'/0'/0'", // Standard Solana derivation path
  });

  // Get the address from the keypair
  const address = solanaToolbox.getAddressFromKeys(keypair);

  return { address, keypair };
}

Transactions and Transfers

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

async function solanaTransfer() {
  const solanaToolbox = getSolanaToolbox();

  // Generate a keypair from a mnemonic
  const keypair = await solanaToolbox.createKeysForPath({
    phrase: "your twelve word mnemonic phrase here",
    derivationPath: "m/44'/501'/0'/0'",
  });

  // Amount to transfer
  const amount = AssetValue.from({
    chain: Chain.Solana,
    symbol: "SOL",
    value: "0.01", // 0.01 SOL
  });

  // Transfer SOL
  try {
    const txHash = await solanaToolbox.transfer({
      assetValue: amount,
      recipient: "ASfS6nSsF1JW76EBKsHuAj1ypBGZz6uhLSJ5QBUcCJmr",
      fromKeypair: keypair,
      memo: "Transfer from SwapKit",
    });

    return txHash;
  } catch (error) {
    throw error;
  }
}

Substrate Toolbox

Importing and Initializing

// @noErrorValidation
import { Chain, createKeyring, Network, getSubstrateToolbox } from "@swapkit/sdk";

async function initSubstrateToolbox() {
  // Create a keyring with a mnemonic phrase
  const signer = await createKeyring(
    "your twelve word mnemonic phrase here",
    Network[Chain.Polkadot].prefix
  );

  // Get the toolbox with the signer
  const polkadotToolbox = await getSubstrateToolbox(Chain.Polkadot, { signer });

  return { polkadotToolbox, signer };
}

Transactions and Transfers

// @noErrorValidation
import { AssetValue, Chain, createKeyring, Network, getSubstrateToolbox } from "@swapkit/sdk";

async function substrateTransfer() {
  // Create a keyring
  const signer = await createKeyring(
    "your twelve word mnemonic phrase here",
    Network[Chain.Polkadot].prefix
  );

  // Get the toolbox
  const polkadotToolbox = await getSubstrateToolbox(Chain.Polkadot, { signer });

  // Amount to transfer
  const amount = AssetValue.from({
    chain: Chain.Polkadot,
    symbol: "DOT",
    value: "0.1", // 0.1 DOT
  });

  // Recipient address
  const recipient = "15oF4uVJwmo4TdGW7VfQxNLavjCXviqxT9S1MgbjMNHr6Sp5";

  // Transfer DOT
  try {
    const txHash = await polkadotToolbox.transfer({
      assetValue: amount,
      recipient,
      from: signer.address,
    });

    return txHash;
  } catch (error) {
    throw error;
  }
}

Ripple Toolbox

Importing and Initializing

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

// Initialize with a mnemonic phrase
const xrpToolbox = await getRippleToolbox({
  phrase: "your twelve word secret phrase here"
});

// Or initialize as read-only (no signer)
const xrpReadOnlyToolbox = await getRippleToolbox();

Sending XRP Transactions

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

async function sendXRP() {
  const xrpToolbox = await getRippleToolbox({
    phrase: "your twelve word secret phrase here"
  });

  // Get sender address
  const address = await xrpToolbox.getAddress();

  // Create and send transaction
  const txHash = await xrpToolbox.transfer({
    assetValue: AssetValue.from({ chain: Chain.Ripple, value: "10" }), // 10 XRP
    recipient: "rBaaxNpAKxELKXkJpSCCJQTkQMTYrcPQPv",
    memo: "123456", // Optional destination tag
    feeOptionKey: FeeOption.Fast
  });

  return txHash;
}

Balance and Validation

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

async function getRippleData() {
  const xrpToolbox = await getRippleToolbox();

  // Get balance for an address
  const address = "rBaaxNpAKxELKXkJpSCCJQTkQMTYrcPQPv";
  const balance = await xrpToolbox.getBalance(address);

  // Validate XRP address
  const isValid = rippleValidateAddress(address);

  return { balance, isValid };
}

NEAR Toolbox

Importing and Initializing

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

// Initialize with mnemonic phrase (creates implicit account)
const nearToolbox = await getNearToolbox({
  phrase: "your twelve word mnemonic phrase here",
  // Optional: custom derivation path
  derivationPath: [44, 397, 0, 0, 0]
});

// Or with existing signer and account
const nearWithAccount = await getNearToolbox({
  signer: nearSigner,
  accountId: "alice.near"
});

Transfers and Balances

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

async function nearOperations() {
  const nearToolbox = await getNearToolbox({
    phrase: "your twelve word mnemonic phrase here"
  });

  // Get account ID (implicit accounts are hex strings)
  const accountId = nearToolbox.getAddress();

  // Transfer NEAR
  const txHash = await nearToolbox.transfer({
    recipient: "receiver.near",
    assetValue: AssetValue.from({ chain: Chain.Near, value: "1.5" }),
    memo: "Payment"
  });

  // Get balance
  const balance = await nearToolbox.getBalance(accountId);

  return { txHash, balance };
}

Contract Interactions

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

async function nearContracts() {
  const nearToolbox = await getNearToolbox({
    phrase: "your twelve word mnemonic phrase here"
  });

  // Call a view function (read-only)
  const result = await nearToolbox.viewFunction(
    "contract.near",
    "get_value",
    { key: "myKey" }
  );

  // Call a change function
  const txHash = await nearToolbox.callFunction({
    contractId: "contract.near",
    methodName: "set_value",
    args: { key: "myKey", value: "myValue" },
    attachedDeposit: "1000000000000000000000000" // 1 NEAR
  });

  return { result, txHash };
}

Combining Multiple Toolboxes

For complex operations involving multiple chains, you can use multiple toolboxes together:

// @noErrorValidation
import { AssetValue, Chain, getUtxoToolbox, getEvmToolbox } from "@swapkit/sdk";
import { ethers } from "ethers";

async function crossChainOperation() {
  // Initialize Bitcoin toolbox
  const btcToolbox = await getUtxoToolbox(Chain.Bitcoin);

  // Initialize Zcash toolbox (shares UTXO patterns with Bitcoin)
  const zcashToolbox = await getUtxoToolbox(Chain.Zcash);

  // Initialize Ethereum toolbox
  const provider = new ethers.JsonRpcProvider("https://mainnet.infura.io/v3/your-infura-key");
  const signer = new ethers.Wallet("your-eth-private-key", provider);
  const ethToolbox = await getEvmToolbox(Chain.Ethereum, { provider, signer });

  // Get Bitcoin balance
  const btcAddress = "bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf5mdq";
  const btcBalance = await btcToolbox.getBalance(btcAddress);

  // Get Zcash balance (transparent addresses only)
  const zcashAddress = "t1XVXWCvpMgBvUaed4XDqWtgQgJSu1Ghz7F";
  const zcashBalance = await zcashToolbox.getBalance(zcashAddress);

  // Get Ethereum balance
  const ethAddress = signer.address;
  const ethBalance = await ethToolbox.getBalance(ethAddress);

  return { btcBalance, zcashBalance, ethBalance };
}