WDK Core API Reference

Class	Description	Methods
WDK	Main class for managing wallets across multiple blockchains. Orchestrates wallet managers and protocols.	Constructor, Methods
IWalletAccount	Base writable wallet account interface from `@tetherto/wdk-wallet`.	Methods
IWalletAccountWithProtocols	Extended wallet account interface that supports protocol registration and access. Extends `IWalletAccount`.	Methods

WDK

The main class for managing wallets across multiple blockchains. This class serves as an orchestrator that allows you to register different wallet managers and protocols, providing a unified interface for multi-chain operations.

Constructor

new WDK(seed)

Parameters:

seed (string | Uint8Array): BIP-39 mnemonic seed phrase or seed bytes

Example:

Initialize WDK

import WDK from '@tetherto/wdk'

// With seed phrase
const wdk = new WDK('abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon about')

// With seed bytes
const seedBytes = new Uint8Array([...])
const wdk2 = new WDK(seedBytes)

Methods

Method	Description	Returns	Throws
`registerWallet(blockchain, wallet, config)`	Registers a new wallet manager for a blockchain	`WDK`	-
`registerProtocol(blockchain, label, protocol, config)`	Registers a protocol globally for a blockchain	`WDK`	-
`registerMiddleware(blockchain, middleware)`	Registers middleware for account decoration	`WDK`	-
`getAccount(blockchain, index?)`	Returns a wallet account for a blockchain and index	`Promise<IWalletAccountWithProtocols>`	If wallet not registered
`getAccountByPath(blockchain, path)`	Returns a wallet account for a blockchain and derivation path	`Promise<IWalletAccountWithProtocols>`	If wallet not registered
`getFeeRates()`	Returns current fee rates	`Promise<FeeRates>`	-
`dispose(blockchains?)`	Disposes all registered wallets, or only the named blockchains, and clears their sensitive data	`void`	-

`registerWallet(blockchain, wallet, config)`

Registers a new wallet manager for a specific blockchain.

Type Parameters:

W: typeof WalletManager - A class that extends the @tetherto/wdk-wallet's WalletManager class

Parameters:

blockchain (string): The name of the blockchain (e.g., "ethereum", "ton", "bitcoin")
wallet (W): The wallet manager class
config (ConstructorParameters<W>[1]): The configuration object for the wallet

Returns: WDK - The wdk manager instance (supports method chaining)

Example:

import WDK from '@tetherto/wdk'
import WalletManagerEvm from '@tetherto/wdk-wallet-evm'
import WalletManagerTon from '@tetherto/wdk-wallet-ton'

const wdk = new WDK(seedPhrase)

// Register EVM wallet
wdk.registerWallet('ethereum', WalletManagerEvm, {
  provider: 'https://eth.drpc.org'
})

// Register TON wallet
wdk.registerWallet('ton', WalletManagerTon, {
  tonApiKey: 'YOUR_TON_API_KEY',
  tonApiEndpoint: 'https://tonapi.io'
})

// Method chaining
const wdk2 = new WDK(seedPhrase)
  .registerWallet('ethereum', WalletManagerEvm, ethereumWalletConfig)
  .registerWallet('ton', WalletManagerTon, tonWalletConfig)

`registerProtocol(blockchain, label, protocol, config)`

Registers a protocol globally for all accounts of a specific blockchain.

Type Parameters:

P: typeof SwapProtocol | typeof BridgeProtocol | typeof LendingProtocol - A class that extends one of the @tetherto/wdk-wallet/protocol's classes

Parameters:

blockchain (string): The name of the blockchain
label (string): Unique label for the protocol (must be unique per blockchain and protocol type)
protocol (P): The protocol class
config (ConstructorParameters<P>[1]): The protocol configuration

Returns: WDK - The wdk manager instance (supports method chaining)

Example:

import veloraProtocolEvm from '@tetherto/wdk-protocol-swap-velora-evm'
import Usdt0ProtocolEvm from '@tetherto/wdk-protocol-bridge-usdt0-evm'

// Register swap protocol for Ethereum
wdk.registerProtocol('ethereum', 'velora', veloraProtocolEvm, {
  apiKey: 'YOUR_velora_API_KEY'
})

// Register bridge protocol for Ethereum
wdk.registerProtocol('ethereum', 'usdt0', Usdt0ProtocolEvm)

// Method chaining
const wdk2 = new WDK(seedPhrase)
  .registerWallet('ethereum', WalletManagerEvm, ethereumWalletConfig)
  .registerProtocol('ethereum', 'velora', veloraProtocolEvm, veloraProtocolConfig)

`registerMiddleware(blockchain, middleware)`

Registers middleware for account decoration and enhanced functionality.

Parameters:

blockchain (string): The name of the blockchain
middleware (<A extends IWalletAccount>(account: A) => Promise<A | void>): Middleware function called when deriving accounts

Returns: WDK - The wdk manager instance (supports method chaining)

Example:

// Simple logging middleware
wdk.registerMiddleware('ethereum', async (account) => {
  console.log('New account:', await account.getAddress())
})

// Failover cascade middleware
import { getFailoverCascadeMiddleware } from '@tetherto/wdk-wrapper-failover-cascade'

wdk.registerMiddleware('ethereum', getFailoverCascadeMiddleware({
  fallbackOptions: {
    retries: 3,
    delay: 1000
  }
}))

// Method chaining
const wdk2 = new WDK(seedPhrase)
  .registerWallet('ethereum', WalletManagerEvm, ethereumWalletConfig)
  .registerMiddleware('ethereum', async (account) => {
    console.log('New account:', await account.getAddress())
  })

`getAccount(blockchain, index?)`

Returns a wallet account for a specific blockchain and index using BIP-44 derivation.

Parameters:

blockchain (string): The name of the blockchain (e.g., "ethereum")
index (number, optional): The index of the account to get (default: 0)

Returns: Promise<IWalletAccountWithProtocols> - The wallet account with protocol support

Throws: Error if no wallet has been registered for the given blockchain

Example:

Get Account

// Get first account (index 0)
const account = await wdk.getAccount('ethereum', 0)

// Get second account (index 1)
const account1 = await wdk.getAccount('ethereum', 1)

// Default index (0)
const defaultAccount = await wdk.getAccount('ethereum')

// This will throw an error if no wallet registered for 'tron'
try {
  const tronAccount = await wdk.getAccount('tron', 0)
} catch (error) {
  console.error('No wallet registered for tron blockchain')
}

`getAccountByPath(blockchain, path)`

Returns a wallet account for a specific blockchain and BIP-44 derivation path.

Parameters:

blockchain (string): The name of the blockchain (e.g., "ethereum")
path (string): The derivation path (e.g., "0'/0/0")

Returns: Promise<IWalletAccountWithProtocols> - The wallet account with protocol support

Throws: Error if no wallet has been registered for the given blockchain

Example:

Get Account by Path

// Full path: m/44'/60'/0'/0/1
const account = await wdk.getAccountByPath('ethereum', "0'/0/1")

// Different derivation path
const customAccount = await wdk.getAccountByPath('ton', "1'/2/3")

`getFeeRates()`

Returns current fee rates for all registered blockchains.

Returns: Promise<FeeRates> - The fee rates in base units

Example:

Get Fee Rates

const feeRates = await wdk.getFeeRates()
console.log('Fee rates:', feeRates)

`dispose(blockchains?)`

Disposes all registered wallets when called without arguments, or only the wallets for the named blockchains when you pass a string array.

Parameters:

blockchains (string[], optional): The blockchain identifiers to dispose. Omit this parameter to dispose every registered wallet.

Example:

Dispose WDK

// Clean up all sensitive data
wdk.dispose()

// Dispose only one registered wallet
wdk.dispose(['ethereum'])

Static Methods

Method	Description	Returns
`getRandomSeedPhrase(wordCount?)`	Returns a random BIP-39 seed phrase (12 or 24 words)	`string`
`isValidSeedPhrase(seedPhrase)`	Checks if a seed phrase is valid	`boolean`

`getRandomSeedPhrase(wordCount?)`

Returns a random BIP-39 seed phrase. Supports both 12-word (128-bit entropy) and 24-word (256-bit entropy) seed phrases.

Parameters:

wordCount (12 | 24, optional): The number of words in the seed phrase. Defaults to 12.

Returns: string - The seed phrase

Example:

Generate Random Seed

// Generate 12-word seed phrase (default)
const seedPhrase12 = WDK.getRandomSeedPhrase()
console.log('Generated 12-word seed:', seedPhrase12)
// Output: "abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon about"

// Generate 24-word seed phrase (higher security)
const seedPhrase24 = WDK.getRandomSeedPhrase(24)
console.log('Generated 24-word seed:', seedPhrase24)
// Output: "abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon art"

`isValidSeedPhrase(seedPhrase)`

Checks if a seed phrase is valid according to BIP-39 standards.

Parameters:

seedPhrase (string): The seed phrase to validate

Returns: boolean - True if the seed phrase is valid

Example:

Validate Seed Phrase

const isValid = WDK.isValidSeedPhrase('abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon about')
console.log('Seed phrase valid:', isValid) // true

const isInvalid = WDK.isValidSeedPhrase('invalid seed phrase')
console.log('Seed phrase valid:', isInvalid) // false

IWalletAccount

Base writable wallet account interface exposed by @tetherto/wdk-wallet. Blockchain modules implement this interface and may narrow the transaction type accepted by signTransaction() and sendTransaction().

Methods

Method	Description	Returns	Throws
`getAddress()`	Returns the account address	`Promise<string>`	-
`sign(message)`	Signs a message with the account private key	`Promise<string>`	-
`signTransaction(tx)`	Signs a transaction without broadcasting it	`Promise<unknown>`	If the transaction is invalid for the module
`verify(message, signature)`	Verifies a message signature	`Promise<boolean>`	-
`sendTransaction(tx)`	Signs, broadcasts, and returns the transaction result	`Promise<TransactionResult>`	If provider access or broadcast fails
`transfer(options)`	Transfers a token where supported by the module	`Promise<TransferResult>`	If the module does not support token transfers
`toReadOnlyAccount()`	Returns a read-only account copy	`Promise<IWalletAccountReadOnly>`	-
`dispose()`	Clears sensitive account material from memory	`void`	-

`signTransaction(tx)`

Signs a transaction with the account private key and returns the signed transaction payload without broadcasting it. Use this when your app needs offline signing, external transaction submission, or a separate review step before broadcast.

Parameters:

tx (Transaction): Module-specific transaction object. For example, EVM accounts accept EvmTransaction, and Bitcoin accounts accept BtcTransaction.

Returns: Promise<unknown> - The signed transaction payload. Wallet modules may narrow this return type, such as a hex string for EVM and Bitcoin transactions.

Example:

Sign Without Broadcasting

const account = await wdk.getAccount('ethereum', 0)

const signedTransaction = await account.signTransaction({
  to: '0x71C7656EC7ab88b098defB751B7401B5f6d8976F',
  value: 1000000000000000n
})

console.log('Signed transaction:', signedTransaction)

IWalletAccountWithProtocols

Extended wallet account interface that supports protocol registration and access. Extends IWalletAccount from @tetherto/wdk-wallet.

Methods

Method	Description	Returns	Throws
`registerProtocol(label, protocol, config)`	Registers a protocol for this specific account	`IWalletAccountWithProtocols`	-
`getSwapProtocol(label)`	Returns the swap protocol with the given label	`ISwapProtocol`	If protocol not found
`getBridgeProtocol(label)`	Returns the bridge protocol with the given label	`IBridgeProtocol`	If protocol not found
`getLendingProtocol(label)`	Returns the lending protocol with the given label	`ILendingProtocol`	If protocol not found

`registerProtocol(label, protocol, config)`

Registers a new protocol for this specific account.

Type Parameters:

P: typeof SwapProtocol | typeof BridgeProtocol | typeof LendingProtocol - A class that extends one of the @tetherto/wdk-wallet/protocol's classes

Parameters:

label (string): Unique label for the protocol (must be unique per account and protocol type)
protocol (P): The protocol class
config (ConstructorParameters<P>[1]): The protocol configuration

Returns: IWalletAccountWithProtocols - The account instance (supports method chaining)

Example:

import Usdt0ProtocolEvm from '@tetherto/wdk-protocol-bridge-usdt0-evm'

const account = await wdk.getAccount('ethereum', 0)

// Register protocol for this specific account
account.registerProtocol('usdt0', Usdt0ProtocolEvm, {
  apiKey: 'YOUR_API_KEY'
})

// Method chaining
const account2 = await wdk.getAccount('ethereum', 1)
  .registerProtocol('usdt0', Usdt0ProtocolEvm, usdt0ProtocolConfig)

`getSwapProtocol(label)`

Returns the swap protocol with the given label.

Parameters:

label (string): The protocol label

Returns: ISwapProtocol - The swap protocol instance

Throws: Error if no swap protocol with the given label has been registered

Example:

Get Swap Protocol

import veloraProtocolEvm from '@tetherto/wdk-protocol-swap-velora-evm'

// Register swap protocol
account.registerProtocol('velora', veloraProtocolEvm, veloraProtocolConfig)

// Get swap protocol
const velora = account.getSwapProtocol('velora')

// Use the protocol
const swapResult = await velora.swap({
  tokenIn: '0x...',
  tokenOut: '0x...',
  tokenInAmount: 1000000n
})

// This will throw an error
// try {
//   const uniswap = account.getSwapProtocol('uniswap')
// } catch (error) {
//   console.error('No swap protocol with label "uniswap" found')
// }

`getBridgeProtocol(label)`

Returns the bridge protocol with the given label.

Parameters:

label (string): The protocol label

Returns: IBridgeProtocol - The bridge protocol instance

Throws: Error if no bridge protocol with the given label has been registered

Example:

Get Bridge Protocol

import Usdt0ProtocolEvm from '@tetherto/wdk-protocol-bridge-usdt0-evm'

// Register bridge protocol
account.registerProtocol('usdt0', Usdt0ProtocolEvm)

// Get bridge protocol
const usdt0 = account.getBridgeProtocol('usdt0')

// Use the protocol
await account.approve({
  token: '0x...',
  spender: '0x...', // OFT or bridge spender address
  amount: 1000000n
})

const bridgeResult = await usdt0.bridge({
  targetChain: 'arbitrum',
  recipient: '0x...',
  token: '0x...',
  amount: 1000000n,
  oftContractAddress: '0x...' // Same address used as approval spender
})

`getLendingProtocol(label)`

Returns the lending protocol with the given label.

Parameters:

label (string): The protocol label

Returns: ILendingProtocol - The lending protocol instance

Throws: Error if no lending protocol with the given label has been registered

Example:

Get Lending Protocol

import AaveProtocolEvm from '@tetherto/wdk-protocol-lending-aave-evm'

// Register lending protocol
account.registerProtocol('aave', AaveProtocolEvm, aaveProtocolConfig)

// Get lending protocol
const aave = account.getLendingProtocol('aave')

// Use the protocol
const supplyResult = await aave.supply({
  token: '0x...',
  amount: 1000000n
})

Complete Example

Complete WDK Flow

import WDK from '@tetherto/wdk'
import WalletManagerEvm from '@tetherto/wdk-wallet-evm'
import WalletManagerTon from '@tetherto/wdk-wallet-ton'
import veloraProtocolEvm from '@tetherto/wdk-protocol-swap-velora-evm'
import Usdt0ProtocolEvm from '@tetherto/wdk-protocol-bridge-usdt0-evm'

// Initialize WDK Manager
const wdk = new WDK(seedPhrase)
  .registerWallet('ethereum', WalletManagerEvm, {
    provider: 'https://eth.drpc.org'
  })
  .registerWallet('ton', WalletManagerTon, {
    tonApiKey: 'YOUR_TON_API_KEY',
    tonApiEndpoint: 'https://tonapi.io'
  })
  .registerProtocol('ethereum', 'velora', veloraProtocolEvm, {
    apiKey: 'YOUR_velora_API_KEY'
  })
  .registerProtocol('ethereum', 'usdt0', Usdt0ProtocolEvm)

// Get accounts
const accountEth = await wdk.getAccount('ethereum', 3)
const accountTon = await wdk.getAccountByPath('ton', "1'/2/3")

// Use wallet account methods
const { hash, fee } = await accountEth.sendTransaction({
  to: '0x...',
  value: 1000000000000000000n // 1 ETH
})

// Use protocols
const velora = accountEth.getSwapProtocol('velora')
const swapResult = await velora.swap(swapOptions)

const usdt0 = accountEth.getBridgeProtocol('usdt0')
// bridgeOptions.oftContractAddress is the source-chain bridge spender.
await accountEth.approve({
  token: bridgeOptions.token,
  spender: bridgeOptions.oftContractAddress,
  amount: bridgeOptions.amount
})
const bridgeResult = await usdt0.bridge(bridgeOptions)

// Clean up
wdk.dispose()

Types

FeeRates

Type: FeeRates

interface FeeRates {
  [blockchain: string]: {
    normal: number;
    fast: number;
  };
}

Middleware Function

Type: MiddlewareFunction

type MiddlewareFunction = <A extends IWalletAccount>(
  account: A
) => Promise<A | void>;

Protocol Types

Types: Protocol Interfaces

// Swap Protocol
interface ISwapProtocol {
  swap(options: SwapOptions): Promise<SwapResult>;
}

// Bridge Protocol
interface IBridgeProtocol {
  bridge(options: BridgeOptions): Promise<BridgeResult>;
}

// Lending Protocol
interface ILendingProtocol {
  supply(options: LendingOptions): Promise<LendingResult>;
  withdraw(options: LendingOptions): Promise<LendingResult>;
  borrow(options: LendingOptions): Promise<LendingResult>;
  repay(options: LendingOptions): Promise<LendingResult>;
}

// Swidge Protocol (unified swap + bridge + route)
interface ISwidgeProtocol extends ISwapProtocol, IBridgeProtocol {
  quoteSwidge(options: SwidgeOptions): Promise<SwidgeQuote>;
  swidge(options: SwidgeOptions, config?: SwidgeProtocolConfig): Promise<SwidgeResult>;
  getSwidgeStatus(id: string, options?: SwidgeStatusOptions): Promise<SwidgeStatusResult>;
  getSupportedChains(): Promise<SwidgeSupportedChain[]>;
  getSupportedTokens(options?: SwidgeSupportedTokensOptions): Promise<SwidgeSupportedToken[]>;
}

Swidge Protocol

SwidgeProtocol is an abstract base class exported from @tetherto/wdk-wallet/protocols for provider packages that implement a single, route-aware surface for same-chain swaps and cross-chain bridges. It implements ISwidgeProtocol, which extends both ISwapProtocol and IBridgeProtocol, so the base class derives swap(), quoteSwap(), bridge(), and quoteBridge() by delegating to swidge() and quoteSwidge(). Provider subclasses implement the abstract methods below.

Method	Description	Returns
`quoteSwidge(options)`	Returns a non-binding quote for a swap/bridge operation	`Promise<SwidgeQuote>`
`swidge(options, config?)`	Executes a swap/bridge operation	`Promise<SwidgeResult>`
`getSwidgeStatus(id, options?)`	Returns the current status of an in-flight operation	`Promise<SwidgeStatusResult>`
`getSupportedChains()`	Returns the chains the provider supports	`Promise<SwidgeSupportedChain[]>`
`getSupportedTokens(options?)`	Returns the tokens the provider supports, optionally route-scoped	`Promise<SwidgeSupportedToken[]>`

The SwidgeOptions input combines common fields (fromToken, toToken, optional toChain, recipient, refundAddress, slippage) with either an exact-in (fromTokenAmount) or exact-out (toTokenAmount) amount. The optional SwidgeProtocolConfig accepts maxNetworkFeeBps and maxProtocolFeeBps to cap acceptable fees.

See the Swidge Protocol Interface page for the full discovery, quote, execution, status, fee, and result shapes.

Type: ISwidgeProtocol Options and Results

type SwidgeProtocolConfig = {
  maxNetworkFeeBps?: number | bigint;
  maxProtocolFeeBps?: number | bigint;
};

type SwidgeOptions = {
  fromToken: string;
  toToken: string;
  toChain?: string | number;     // defaults to the source chain (same-chain swap)
  recipient?: string;
  refundAddress?: string;
  slippage?: number;             // decimal, e.g. 0.01 for 1%
} & (
  | { fromTokenAmount: number | bigint }  // exact-in
  | { toTokenAmount: number | bigint }    // exact-out
);

type SwidgeStatus =
  | 'pending' | 'action-required' | 'completed' | 'failed'
  | 'refund-pending' | 'refunded' | 'cancelled' | 'expired' | 'partial';

GitHub IssuesReport bugs, request features, and get technical help

Open an Issue

Email ContactFor sensitive or private matters, contact our team directly

Send an email

WDK Core API Reference

Table of Contents

WDK

Constructor

Methods

`registerWallet(blockchain, wallet, config)`

`registerProtocol(blockchain, label, protocol, config)`

`registerMiddleware(blockchain, middleware)`

`getAccount(blockchain, index?)`

`getAccountByPath(blockchain, path)`

`getFeeRates()`

`dispose(blockchains?)`

Static Methods

`getRandomSeedPhrase(wordCount?)`

`isValidSeedPhrase(seedPhrase)`

IWalletAccount

Methods

`signTransaction(tx)`

IWalletAccountWithProtocols

Methods

`registerProtocol(label, protocol, config)`

`getSwapProtocol(label)`

`getBridgeProtocol(label)`

`getLendingProtocol(label)`

Complete Example

Types

FeeRates

Middleware Function

Protocol Types

Swidge Protocol

Next Steps

WDK Core Configuration

WDK Core Usage

Wallet Modules

Bridge Modules

Need Help?

On this page