WDK logoWDK documentation
StartWalletsDeFi & FiatAI & CLITools

WDK Core Configuration

Configuration options and settings for @tetherto/wdk

Configuration

WDK Manager Configuration

Create WDK Instance
import WDK from '@tetherto/wdk'

const wdk = new WDK(seedPhrase)

The WDK manager accepts a seed phrase or raw BIP-32 seed bytes. Configure wallets, protocols, and middleware through their registration methods. Configure policy timeouts and exclusions on the standalone Policies plugin.

Wallet Registration Configuration

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

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'
  })

Protocol Registration Configuration

Register WDK Protocol
const wdk = new WDK(seedPhrase)
  .registerProtocol('ethereum', 'swap', MySwapProtocol, swapProtocolConfig)

MySwapProtocol is an illustrative class that extends SwapProtocol. Replace it with a provider whose constructor supports the account and provider shape used by your registered wallet.

Core beta.19 and later forward every argument after the protocol class to that provider's constructor after the account. A provider accepting one config object uses the call above; if it requires multiple arguments, pass them separately and in constructor order. The same argument forwarding applies to account-scoped registration. See the registerProtocol() reference.

Configuration Options

Wallet Configuration

Each wallet manager requires its own configuration object when registered. The configuration depends on the specific wallet module being used.

EVM Wallet Configuration

Ethereum WDK Wallet Configuration
const ethereumWalletConfig = {
  provider: 'https://eth.drpc.org', // RPC endpoint
  // Additional EVM-specific configuration options
}

wdk.registerWallet('ethereum', WalletManagerEvm, ethereumWalletConfig)

TON Wallet Configuration

TON WDK Wallet Configuration
const tonWalletConfig = {
  tonClient: {
    secretKey: 'YOUR_TON_API_KEY',
    url: 'https://toncenter.com/api/v2/jsonRPC'
  }
}

wdk.registerWallet('ton', WalletManagerTon, tonWalletConfig)

Protocol Configuration

Protocol constructor arguments depend on the provider. Pass any required arguments after its class in constructor order; a provider can require zero, one, or multiple arguments.

Swap Protocol Configuration

Swap WDK Protocol Configuration
const swapProtocolConfig = {
  swapMaxFee: 200000000000000n
}

wdk.registerProtocol('ethereum', 'swap', MySwapProtocol, swapProtocolConfig)

Middleware Configuration

Middleware runs in registration order on account retrieval, after WDK attaches protocol methods. A non-nullish callback return replaces the account passed to the next callback and the caller.

Middleware WDK Protocol Configuration
// Simple logging middleware
wdk.registerMiddleware('ethereum', async (account, { blockchain }) => {
  console.log('Accessed account:', blockchain, await account.getAddress())
})

Environment Variables

For production applications, consider using environment variables for sensitive configuration:

WDK environment variables Configuration
const wdk = new WDK(process.env.SEED_PHRASE)
  .registerWallet('ethereum', WalletManagerEvm, {
    provider: process.env.ETHEREUM_RPC_URL
  })
  .registerProtocol('ethereum', 'swap', MySwapProtocol, swapProtocolConfig)

Configuration Validation

Registration does not validate every downstream module configuration:

  • Wallet Registration: WDK constructs the wallet manager during registration, so wallet-constructor validation errors surface immediately. Registering a second wallet under the same blockchain throws.
  • Protocol Registration: Global registration stores a supported protocol class and config for later construction. Reusing the same blockchain, protocol type, and label replaces the previous global registration. Provider-constructor and config errors surface when an account retrieves the protocol.
  • Middleware Registration: WDK stores the middleware for later account decoration. Errors thrown by the middleware surface when an account is retrieved.

In JavaScript, a protocol class that does not extend a supported WDK protocol base class is ignored rather than rejected. Keep protocol classes typed, use distinct labels, and test retrieval during application startup. A global registration shadows an account-scoped provider with the same type and label.

Core beta.20 also defers account-scoped protocol construction until retrieval. Each getter creates a fresh instance; retain that returned instance when its local state is needed later. With the Policies plugin attached, governed account-scoped protocols receive the policy proxy. Global protocols receive the raw account. Review the protocol policy boundary before choosing the registration scope.

Error Handling

Handle wallet registration errors at registration time and protocol errors at retrieval time:

Configuration errors
try {
  wdk.registerWallet('ethereum', InvalidWalletClass, config)
} catch (error) {
  console.error('Wallet registration failed:', error.message)
}

try {
  wdk.registerProtocol('ethereum', 'swap', MySwapProtocol, invalidConfig)
  const account = await wdk.getAccount('ethereum', 0)
  account.getSwapProtocol('swap')
} catch (error) {
  console.error('Protocol construction or retrieval failed:', error.message)
}

Next Steps


Need Help?

On this page