tetherto/wdk

Tether WDK

Multi-chain wallet SDK. All modules share common interfaces from @tetherto/wdk-wallet.

Documentation

Official Docs: https://docs.wallet.tether.io

URL Fetching Workflow

When working with WDK tasks, follow this workflow to access documentation:

Identify relevant URLs - Based on the task, determine which module documentation pages are needed (see Module Documentation Links below) Attempt to fetch - Try web_fetch on the URL directly If fetch fails - Search for the exact URL:

web_search("https://docs.wallet.tether.io/sdk/wallet-modules/wallet-spark/usage") This makes the URL appear in search results, which unlocks fetching.

Fetch after search - Now web_fetch will work on that URL

Example workflow: Task: Build a Spark wallet app

1. Relevant URLs identified:

   • https://docs.wallet.tether.io/sdk/wallet-modules/wallet-spark/usage
   • https://docs.wallet.tether.io/sdk/wallet-modules/wallet-spark/configuration

2. web_fetch("https://docs.wallet.tether.io/sdk/wallet-modules/wallet-spark/usage") → If permission error, proceed to step 3

3. web_search("https://docs.wallet.tether.io/sdk/wallet-modules/wallet-spark/usage") → URL now appears in results

4. web_fetch("https://docs.wallet.tether.io/sdk/wallet-modules/wallet-spark/usage") → Success - full page content retrieved

For each module, documentation is organized into subpages:

/usage - Example usage and patterns /configuration - Configuration options and settings /api-reference - Complete API documentation

Architecture

@tetherto/wdk-core          # Orchestrator - registers wallets + protocols
    ├── @tetherto/wdk-wallet    # Base classes (WalletManager, IWalletAccount)
    │   ├── wdk-wallet-btc      # Bitcoin (BIP-84, SegWit)
    │   ├── wdk-wallet-evm      # Ethereum & EVM chains
    │   ├── wdk-wallet-evm-erc-4337  # EVM with Account Abstraction
    │   ├── wdk-wallet-solana   # Solana
    │   ├── wdk-wallet-spark    # Spark/Lightning
    │   ├── wdk-wallet-ton      # TON
    │   ├── wdk-wallet-ton-gasless   # TON gasless
    │   ├── wdk-wallet-tron     # TRON
    │   └── wdk-wallet-tron-gasfree  # TRON gas-free
    └── Protocol Modules
        ├── wdk-protocol-swap-velora-evm   # DEX swaps on EVM
        ├── wdk-protocol-bridge-usdt0-evm  # Cross-chain USDT0 bridge
        └── wdk-protocol-lending-aave-evm  # Aave V3 lending

Quick Start

Docs: https://docs.wallet.tether.io/sdk/get-started

With WDK Core (Multi-chain)

import WDK from '@tetherto/wdk'
import WalletManagerEvm from '@tetherto/wdk-wallet-evm'
import WalletManagerBtc from '@tetherto/wdk-wallet-btc'

const wdk = new WDK(seedPhrase)
  .registerWallet('ethereum', WalletManagerEvm, { provider: 'https://eth.drpc.org' })
  .registerWallet('bitcoin', WalletManagerBtc, { host: 'electrum.blockstream.info', port: 50001 })

const ethAccount = await wdk.getAccount('ethereum', 0)
const btcAccount = await wdk.getAccount('bitcoin', 0)

Single Chain (Direct)

import WalletManagerBtc from '@tetherto/wdk-wallet-btc'

const wallet = new WalletManagerBtc(seedPhrase, {
  host: 'electrum.blockstream.info',
  port: 50001,
  network: 'bitcoin'
})
const account = await wallet.getAccount(0)

Common Interface (All Wallets)

All wallet accounts implement IWalletAccount:

| Method | Returns | Description | |--------|---------|-------------| | getAddress() | Promise<string> | Account address | | getBalance() | Promise<bigint> | Native token balance (base units) | | getTokenBalance(addr) | Promise<bigint> | Token balance | | sendTransaction({to, value}) | Promise<{hash, fee}> | Send native tokens | | quoteSendTransaction({to, value}) | Promise<{fee}> | Estimate tx fee | | transfer({token, recipient, amount}) | Promise<{hash, fee}> | Transfer tokens | | quoteTransfer(opts) | Promise<{fee}> | Estimate transfer fee | | sign(message) | Promise<string> | Sign message | | verify(message, signature) | Promise<boolean> | Verify signature | | dispose() | void | Clear private keys from memory |

Properties: index, path, keyPair (⚠️ sensitive)

Module Documentation Links

Core Module

| Resource | URL | |----------|-----| | Overview | https://docs.wallet.tether.io/sdk/core-module | | Usage | https://docs.wallet.tether.io/sdk/core-module/usage | | Configuration | https://docs.wallet.tether.io/sdk/core-module/configuration | | API Reference | https://docs.wallet.tether.io/sdk/core-module/api-reference |

Wallet Modules

| Module | Docs | |--------|------| | Bitcoin | https://docs.wallet.tether.io/sdk/wallet-modules/wallet-btc | | EVM | https://docs.wallet.tether.io/sdk/wallet-modules/wallet-evm | | EVM ERC-4337 | https://docs.wallet.tether.io/sdk/wallet-modules/wallet-evm-erc-4337 | | Solana | https://docs.wallet.tether.io/sdk/wallet-modules/wallet-solana | | Spark | https://docs.wallet.tether.io/sdk/wallet-modules/wallet-spark | | TON | https://docs.wallet.tether.io/sdk/wallet-modules/wallet-ton | | TON Gasless | https://docs.wallet.tether.io/sdk/wallet-modules/wallet-ton-gasless | | TRON | https://docs.wallet.tether.io/sdk/wallet-modules/wallet-tron | | TRON Gasfree | https://docs.wallet.tether.io/sdk/wallet-modules/wallet-tron-gasfree |

Each wallet module has /usage, /configuration, and /api-reference subpages.

Protocol Modules

| Module | Docs | |--------|------| | Swap (Velora EVM) | https://docs.wallet.tether.io/sdk/swap-modules/swap-velora-evm | | Bridge (USDT0 EVM) | https://docs.wallet.tether.io/sdk/bridge-modules/bridge-usdt0-evm | | Lending (Aave EVM) | https://docs.wallet.tether.io/sdk/lending-modules/lending-aave-evm |

Each protocol module has /usage, /configuration, and /api-reference subpages.

UI Kits & Examples

| Resource | URL | |----------|-----| | React Native UI Kit | https://docs.wallet.tether.io/ui-kits/react-native-ui-kit/get-started | | Theming | https://docs.wallet.tether.io/ui-kits/react-native-ui-kit/theming | | UI Kit API Reference | https://docs.wallet.tether.io/ui-kits/react-native-ui-kit/api-reference | | React Native Starter | https://docs.wallet.tether.io/examples-and-starters/react-native-starter |

Chain-Specific Notes

Bitcoin

• BIP-84 (Native SegWit only, bc1... addresses)
• Uses Electrum servers, fees in sat/vB
• No token support (getTokenBalance, transfer throw)
• getTransfers({direction, limit, skip}) for history

EVM

• BIP-44 (m/44'/60'), EIP-1559 fee model
• Supports ERC20 via transfer()
• Fee rates: normal = base×1.1, fast = base×2.0

ERC-4337 (Account Abstraction)

• Gasless via UserOperations + Paymaster
• Fees paid in paymaster token (e.g., USDT)
• getPaymasterTokenBalance() for fee balance
• Batch transactions: sendTransaction([tx1, tx2])

Solana

• BIP-44 (m/44'/501'), Ed25519
• Fees in lamports (1 SOL = 1B lamports)
• SPL tokens via transfer()

Spark

• Bitcoin L2 with Lightning support
• Zero fees for Spark txs
• getSingleUseDepositAddress(), claimDeposit(txId)
• createLightningInvoice({value, memo}), payLightningInvoice({invoice, maxFeeSats})
• withdraw({to, value}) for L1 withdrawal

TON

• BIP-44 (m/44'/607'), Ed25519
• Fees in nanotons (1 TON = 1B nanotons)
• Jettons via transfer()

TRON

• BIP-44 (m/44'/195'), secp256k1
• Fees in sun (1 TRX = 1M sun)
• TRC20 via transfer()
• Energy + bandwidth costs

Gasless Variants

• TON Gasless: Requires tonApiClient, paymasterToken config
• TRON Gasfree: Requires gasFreeProvider, gasFreeApiKey, serviceProvider, verifyingContract
• Both: sendTransaction() not supported, use transfer() only

Protocol Quick Reference

Swap (DEX)

// EVM (Velora)
const velora = new VeloraProtocolEvm(evmAccount, { swapMaxFee: 200000000000000n })
await velora.swap({ tokenIn: '0x...', tokenOut: '0x...', tokenInAmount: 1000000n })

Bridge

const bridge = new Usdt0ProtocolEvm(evmAccount, { bridgeMaxFee: 1000000000000000n })
await bridge.bridge({
  targetChain: 'arbitrum',
  recipient: '0x...',
  token: '0x...',  // USDT0
  amount: 1000000n
})

Lending (Aave)

const aave = new AaveProtocolEvm(evmAccount)
await aave.supply({ token: '0x...', amount: 1000000n })
await aave.borrow({ token: '0x...', amount: 500000n })
await aave.repay({ token: '0x...', amount: 500000n })
await aave.withdraw({ token: '0x...', amount: 1000000n })
const data = await aave.getAccountData()  // healthFactor, ltv, etc.

Common Patterns

Fee Estimation Before Send

const quote = await account.quoteSendTransaction({ to, value })
if (quote.fee > maxAcceptableFee) throw new Error('Fee too high')
const result = await account.sendTransaction({ to, value })

Cleanup

try {
  // ... wallet operations
} finally {
  account.dispose()
  wallet.dispose()
}

Read-Only Account

const readOnly = await account.toReadOnlyAccount()
// Can query balances, estimate fees, but cannot sign

Package Versions

ALWAYS fetch the latest version from npm before adding any package to package.json:

npm view <package-name> version

Example workflow:

# Before writing package.json, check each package you need:
npm view @tetherto/wdk-core version
npm view @tetherto/wdk-wallet-btc version
npm view @tetherto/wdk-wallet-evm version
# ... for every @tetherto package you're using

Never hardcode or guess versions. Always verify against npm first.

Browser Compatibility

WDK uses sodium-universal for secure memory handling which requires Node.js. For browser/React apps:

1. Add node polyfills (vite-plugin-node-polyfills or similar)
2. Create a shim for sodium if dispose() errors occur:

// sodium-shim.js - No-op for browser
export function sodium_memzero() {}
export default { sodium_memzero }

3. Alias in bundler config:

resolve: {
  alias: {
    'sodium-universal': './src/sodium-shim.js'
  }
}