WDK logoWDK documentation

Configuration

Configure wallets, capabilities, tokens, protocols, and custom tools

Server Setup

Create a server with a name and version:

import { WdkMcpServer } from '@tetherto/wdk-mcp-toolkit'

const server = new WdkMcpServer('my-server', '1.0.0')

The WdkMcpServer extends McpServer from the official @modelcontextprotocol/sdk with WDK-specific capabilities. All standard MCP server features are available.


Wallet Configuration

Enable WDK

server.useWdk({ seed: process.env.WDK_SEED })

The seed is a BIP-39 mnemonic phrase used for key derivation across all registered blockchains.

Never hardcode seed phrases in source code. Use environment variables or a secrets manager. The setup wizard generates a gitignored .vscode/mcp.json for local development.

Register Wallets

Register a wallet module for each blockchain you want to support:

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

// EVM chains - one module handles all EVM networks
server.registerWallet('ethereum', WalletManagerEvm, {
  provider: 'https://eth-mainnet.g.alchemy.com/v2/KEY'
})
server.registerWallet('polygon', WalletManagerEvm, {
  provider: 'https://polygon-rpc.com'
})

// Bitcoin
server.registerWallet('bitcoin', WalletManagerBtc, {
  network: 'bitcoin',
  host: 'electrum.blockstream.info',
  port: 50001
})

// Solana
server.registerWallet('solana', WalletManagerSolana, {
  provider: 'https://api.mainnet-beta.solana.com'
})

Each registerWallet() call registers the chain name and makes it available to all wallet tools. For configuration details of each wallet module, see the Wallet Modules documentation.


Capabilities

Enable optional capabilities before registering their tools:

CapabilityMethodRequirementUnlocks
Pricingserver.usePricing()NonePRICING_TOOLS (2 tools)
Indexerserver.useIndexer({ apiKey })WDK API keyINDEXER_TOOLS (2 tools)
Swapserver.registerProtocol(chain, label, SwapProtocol)Swap module installedSWAP_TOOLS (2 tools)
Bridgeserver.registerProtocol(chain, label, BridgeProtocol)Bridge module installedBRIDGE_TOOLS (2 tools)
Lendingserver.registerProtocol(chain, label, LendingProtocol)Lending module installedLENDING_TOOLS (8 tools)
Fiatserver.registerProtocol(chain, label, FiatProtocol, config)Fiat module installedFIAT_TOOLS (8 tools)

Pricing

Fetches live prices from Bitfinex. No API key needed.

server.usePricing()

Indexer

Enables querying token balances and transfer history for any address. Requires an API key.

server.useIndexer({ apiKey: process.env.WDK_INDEXER_API_KEY })

Protocols

DeFi protocols are registered per-chain:

import VeloraProtocolEvm from '@tetherto/wdk-protocol-swap-velora-evm'
import Usdt0ProtocolEvm from '@tetherto/wdk-protocol-bridge-usdt0-evm'
import AaveProtocolEvm from '@tetherto/wdk-protocol-lending-aave-evm'
import MoonPayProtocol from '@tetherto/wdk-protocol-fiat-moonpay'

server.registerProtocol('ethereum', 'velora', VeloraProtocolEvm)
server.registerProtocol('ethereum', 'usdt0', Usdt0ProtocolEvm)
server.registerProtocol('ethereum', 'aave', AaveProtocolEvm)
server.registerProtocol('ethereum', 'moonpay', MoonPayProtocol, {
  apiKey: process.env.MOONPAY_API_KEY,
  secretKey: process.env.MOONPAY_SECRET_KEY
})

Token Management

Default Tokens

USDT is auto-registered for supported chains via DEFAULT_TOKENS. You can query what's available:

server.getRegisteredTokens('ethereum')  // ['USDT']

Custom Tokens

Register additional tokens with registerToken():

server.registerToken('ethereum', 'DAI', {
  address: '0x6B175474E89094C44Da98b954EedeAC495271d0F',
  decimals: 18
})

Registered tokens are available to all tools that accept a token parameter (getTokenBalance, transfer, quoteTransfer, swap, etc.).


Tool Registration

Built-in Tool Arrays

Each category exports three arrays for fine-grained control:

ExportContents
WALLET_TOOLSAll 11 wallet tools
WALLET_READ_TOOLS7 read-only wallet tools
WALLET_WRITE_TOOLS4 wallet tools that modify state
PRICING_TOOLSAll 2 pricing tools
INDEXER_TOOLSAll 2 indexer tools
SWAP_TOOLSAll 2 swap tools
SWAP_READ_TOOLS1 read-only swap tool
SWAP_WRITE_TOOLS1 swap tool that modifies state
BRIDGE_TOOLSAll 2 bridge tools
BRIDGE_READ_TOOLS1 read-only bridge tool
BRIDGE_WRITE_TOOLS1 bridge tool that modifies state
LENDING_TOOLSAll 8 lending tools
LENDING_READ_TOOLS4 read-only lending tools
LENDING_WRITE_TOOLS4 lending tools that modify state
FIAT_TOOLSAll 8 fiat tools
FIAT_READ_TOOLS6 read-only fiat tools
FIAT_WRITE_TOOLS2 fiat tools that modify state

Read-Only Mode

To allow an AI agent to query data without the ability to make transactions:

import {
  WALLET_READ_TOOLS,
  PRICING_TOOLS,
  INDEXER_TOOLS,
  SWAP_READ_TOOLS
} from '@tetherto/wdk-mcp-toolkit'

server.registerTools([
  ...WALLET_READ_TOOLS,
  ...PRICING_TOOLS,
  ...INDEXER_TOOLS,
  ...SWAP_READ_TOOLS
])

Individual Tool Registration

You can also import and register tools individually:

import { getAddress, getBalance, getCurrentPrice } from '@tetherto/wdk-mcp-toolkit'

server.registerTools([getAddress, getBalance, getCurrentPrice])

Custom Tools

Add your own MCP tools alongside the built-in ones using the standard registerTool() method (inherited from McpServer). See the MCP SDK tools documentation for full details.

server.registerTool(
  'myCustomTool',
  {
    title: 'My Custom Tool',
    description: 'Description of what this tool does',
    inputSchema: z.object({
      param: z.string().describe('A required parameter')
    }),
    outputSchema: z.object({
      result: z.string()
    }),
    annotations: {
      readOnlyHint: true,
      destructiveHint: false,
      idempotentHint: true,
      openWorldHint: false
    }
  },
  async ({ param }) => {
    return {
      content: [{ type: 'text', text: `Result: ${param}` }],
      structuredContent: { result: param }
    }
  }
)

Environment Variables

VariableRequiredDescription
WDK_SEEDYesBIP-39 mnemonic for wallet key derivation
WDK_INDEXER_API_KEYNoAPI key for WDK Indexer
MOONPAY_API_KEYNoAPI key for MoonPay fiat on/off-ramp
MOONPAY_SECRET_KEYNoSecret key for MoonPay

Security Checklist

Self-custodial wallets require careful key management. Follow these guidelines to protect user funds.

  • Use a dedicated development wallet - Never use production wallets with real funds for testing
  • Never hardcode seed phrases - Always use environment variables or .vscode/mcp.json (gitignored)
  • Use WALLET_READ_TOOLS for untrusted agents - Only register write tools when user confirmation is available
  • Call server.close() on shutdown - This disposes the WDK instance and wipes keys from memory
  • Use stdio transport - The default transport communicates only with the local AI client process
  • Review MCP annotations - Tools declare readOnlyHint and destructiveHint so clients can warn users appropriately
  • Keep .vscode/mcp.json gitignored - The setup wizard handles this automatically

Need Help?

On this page