API Reference
WdkMcpServer class and all 35 built-in MCP tools
WdkMcpServer
The WdkMcpServer class extends McpServer from @modelcontextprotocol/sdk with WDK-specific wallet, pricing, indexer, and protocol capabilities.
Constructor
const server = new WdkMcpServer(name: string, version: string, options?: ServerOptions)| Parameter | Type | Description |
|---|---|---|
name | string | Server name (shown to AI clients) |
version | string | Server version string |
options.capabilities.elicitation | boolean | Defaults to true. When false, confirmation requests are automatically accepted; see confirmation settings. |
Core Methods
useWdk(config)
Initializes the WDK wallet engine. Must be called before registerWallet() or registerProtocol().
server.useWdk(config: WdkConfig): WdkMcpServer| Parameter | Type | Required | Description |
|---|---|---|---|
config.seed | string | Unless WDK_SEED is set | BIP-39 mnemonic seed phrase. An omitted or empty value falls back to WDK_SEED. |
Pass a mnemonic resolved by your application's secret-manager integration. This method does not execute WDK_SEED_COMMAND or read WDK_SEED_FILE; those are seed sources for the built-in serve command. See the custom server example for an explicit command loader.
Returns: WdkMcpServer (for chaining)
registerWallet(blockchain, WalletManager, config)
Registers a wallet module for a specific blockchain.
server.registerWallet<W extends typeof WalletManager>(
blockchain: string,
WalletManager: W,
config: ConstructorParameters<W>[1]
): WdkMcpServer| Parameter | Type | Required | Description |
|---|---|---|---|
blockchain | string | Yes | Chain name (e.g., 'ethereum', 'bitcoin') |
WalletManager | class | Yes | Wallet module class (e.g., WalletManagerEvm) |
config | object | Yes | Module-specific config (see each wallet module's docs) |
Requires: useWdk() called first
registerProtocol(chain, label, Protocol, config?)
Registers a DeFi protocol (swap, bridge, lending, or fiat) for a chain.
server.registerProtocol<P extends typeof SwapProtocol | typeof BridgeProtocol | typeof LendingProtocol | typeof FiatProtocol>(
chain: string,
label: string,
Protocol: P,
config?: ConstructorParameters<P>[1]
): WdkMcpServer| Parameter | Type | Required | Description |
|---|---|---|---|
chain | string | Yes | Chain name (must have a wallet registered) |
label | string | Yes | Protocol identifier (e.g., 'velora', 'aave') |
Protocol | class | Yes | Protocol module class |
config | object | No | Protocol-specific config |
Requires: useWdk() called first
useIndexer(config)
Enables the WDK Indexer client for querying token balances and transfer history.
server.useIndexer(config: { apiKey: string }): WdkMcpServer| Parameter | Type | Required | Description |
|---|---|---|---|
config.apiKey | string | Yes | WDK Indexer API key |
usePricing()
Enables the Bitfinex pricing client for current and historical prices.
server.usePricing(): WdkMcpServerregisterTools(tools)
Registers multiple MCP tools at once.
server.registerTools(tools: ToolFunction[]): WdkMcpServerregisterToken(chain, symbol, token)
Registers a custom token for a chain.
server.registerToken(chain: string, symbol: string, token: TokenInfo): WdkMcpServer| Parameter | Type | Description |
|---|---|---|
chain | string | Chain name |
symbol | string | Token symbol (e.g., 'XAUT') |
token.address | string | Token contract address |
token.decimals | number | Token decimal places |
close()
Attempts WDK disposal, then clears the server's WDK reference and closes the MCP server. Await this when shutting down. If disposal throws, close() rejects before clearing the reference or closing the transport. Successful cleanup does not guarantee erasure of every seed or key copy in process memory.
server.close(): Promise<void>Query Methods
| Method | Returns | Description |
|---|---|---|
getChains() | string[] | Registered blockchain names |
getTokenInfo(chain, symbol) | TokenInfo | undefined | Token address and decimals |
getRegisteredTokens(chain) | string[] | Registered token symbols for a chain |
getSwapChains() | string[] | Chains with swap protocols |
getSwapProtocols(chain) | string[] | Swap protocol labels for a chain |
getBridgeChains() | string[] | Chains with bridge protocols |
getBridgeProtocols(chain) | string[] | Bridge protocol labels for a chain |
getLendingChains() | string[] | Chains with lending protocols |
getLendingProtocols(chain) | string[] | Lending protocol labels for a chain |
getFiatChains() | string[] | Chains with fiat protocols |
getFiatProtocols(chain) | string[] | Fiat protocol labels for a chain |
Getters
| Getter | Type | Description |
|---|---|---|
server.wdk | WalletKit | WDK instance (after useWdk()) |
server.indexerClient | WdkIndexerClient | Indexer client (after useIndexer()) |
server.pricingClient | WdkPricingClient | Pricing client (after usePricing()) |
Types
type WdkConfig = {
seed?: string
}
type TokenInfo = {
address: string
decimals: number
}
type ToolFunction = (server: WdkMcpServer) => voidBuilt-in MCP Tools
All tools use Zod for input/output validation and include MCP tool annotations that describe their behavior to AI clients.
MCP Annotations
Every tool declares these annotations:
| Annotation | Type | Meaning |
|---|---|---|
readOnlyHint | boolean | Tool does not modify state |
destructiveHint | boolean | Tool may spend funds or make irreversible changes |
idempotentHint | boolean | Calling multiple times produces the same result |
openWorldHint | boolean | Tool interacts with external systems |
Configurable confirmation - Tools that request confirmation use MCP elicitation when enabled. Disabling elicitation automatically accepts confirmation requests. The annotations are descriptive hints, not authorization checks; see confirmation and agent access.
Wallet Tools
Requires: useWdk() + registerWallet()
getAddress
Get the wallet address for a blockchain. Read-only.
Input:
| Parameter | Type | Required | Description |
|---|---|---|---|
chain | enum | Yes | The blockchain to get the address for |
Output:
| Field | Type | Description |
|---|---|---|
address | string | The wallet address |
getBalance
Get the native token balance for a blockchain (ETH, BTC, SOL, etc.). Read-only.
Input:
| Parameter | Type | Required | Description |
|---|---|---|---|
chain | enum | Yes | The blockchain to query |
Output:
| Field | Type | Description |
|---|---|---|
balance | string | Balance in base units (wei, satoshis, etc.) |
getTokenBalance
Get the balance of a registered token, such as USD₮ or XAU₮. Read-only.
Input:
| Parameter | Type | Required | Description |
|---|---|---|---|
chain | enum | Yes | The blockchain to query |
token | string | Yes | Token symbol (e.g., "USDT") |
Output:
| Field | Type | Description |
|---|---|---|
balance | string | Human-readable token balance |
balanceBaseUnits | string | Balance in smallest unit |
getFeeRates
Get current network fee rates. Read-only.
Input:
| Parameter | Type | Required | Description |
|---|---|---|---|
chain | enum | Yes | The blockchain to query |
Output:
| Field | Type | Description |
|---|---|---|
normal | string | Normal fee rate (balanced speed) |
fast | string | Fast fee rate (higher cost, faster confirmation) |
Fee units vary by chain: satoshis/byte (Bitcoin), wei (Ethereum), or chain-specific units.
getMaxSpendableBtc
Get the maximum spendable Bitcoin amount after fees. Read-only. Bitcoin-only.
Input: None
Output:
| Field | Type | Description |
|---|---|---|
amount | string | Maximum spendable amount (satoshis) |
fee | string | Estimated transaction fee (satoshis) |
changeValue | string | Expected change output (satoshis) |
quoteSendTransaction
Estimate the fee for sending native currency. Read-only. Does not broadcast.
Input:
| Parameter | Type | Required | Description |
|---|---|---|---|
chain | enum | Yes | The blockchain |
to | string | Yes | Recipient address |
value | string | Yes | Amount in base units (wei, satoshis) |
Output:
| Field | Type | Description |
|---|---|---|
fee | string | Estimated transaction fee in base units |
quoteTransfer
Estimate the fee for transferring a token. Read-only. Does not broadcast.
Input:
| Parameter | Type | Required | Description |
|---|---|---|---|
chain | enum | Yes | The blockchain |
token | string | Yes | Token symbol (e.g., "USDT") |
recipient | string | Yes | Recipient address |
amount | string | Yes | Amount in human-readable format (e.g., "10") |
Output:
| Field | Type | Description |
|---|---|---|
fee | string | Estimated transaction fee in base units |
sendTransaction
Send native currency (ETH, BTC, etc.). Destructive - requests confirmation when elicitation is enabled.
Input:
| Parameter | Type | Required | Description |
|---|---|---|---|
chain | enum | Yes | The blockchain |
to | string | Yes | Recipient address |
value | string | Yes | Amount in base units (wei, satoshis) |
Output:
| Field | Type | Description |
|---|---|---|
hash | string | Transaction hash |
fee | string | Actual fee paid |
With elicitation enabled and a compatible MCP client, this tool requests approval before broadcasting. With elicitation disabled, the confirmation request is automatically accepted.
transfer
Transfer a registered token. Destructive - requests confirmation when elicitation is enabled.
Input:
| Parameter | Type | Required | Description |
|---|---|---|---|
chain | enum | Yes | The blockchain |
token | string | Yes | Token symbol (e.g., "USDT") |
to | string | Yes | Recipient address |
amount | string | Yes | Amount in human-readable format (e.g., "100") |
Output:
| Field | Type | Description |
|---|---|---|
hash | string | Transaction hash |
fee | string | Actual fee paid |
With elicitation enabled and a compatible MCP client, this tool requests approval before broadcasting. With elicitation disabled, the confirmation request is automatically accepted.
sign
Sign an arbitrary message with the wallet's private key. Does not reveal the private key.
Input:
| Parameter | Type | Required | Description |
|---|---|---|---|
chain | enum | Yes | The blockchain |
message | string | Yes | Message to sign |
Output:
| Field | Type | Description |
|---|---|---|
signature | string | Cryptographic signature |
verify
Verify that a signature is valid for a given message. Read-only.
Input:
| Parameter | Type | Required | Description |
|---|---|---|---|
chain | enum | Yes | The blockchain |
message | string | Yes | Original message |
signature | string | Yes | Signature to verify |
Output:
| Field | Type | Description |
|---|---|---|
valid | boolean | Whether the signature is valid |
Pricing Tools
Requires: usePricing()
getCurrentPrice
Get the current spot price from Bitfinex. Read-only.
Input:
| Parameter | Type | Required | Description |
|---|---|---|---|
base | string | Yes | Base currency (e.g., "BTC", "ETH") |
quote | string | Yes | Quote currency (e.g., "USD", "USDT") |
Output:
| Field | Type | Description |
|---|---|---|
base | string | Base currency |
quote | string | Quote currency |
price | number | Current spot price |
getHistoricalPrice
Get historical price data (OHLCV candles) from Bitfinex. Read-only.
Input:
| Parameter | Type | Required | Description |
|---|---|---|---|
from | string | Yes | Base currency (e.g., "BTC") |
to | string | Yes | Quote currency (e.g., "USD") |
start | number | No | Start timestamp (ms, unix epoch) |
end | number | No | End timestamp (ms, unix epoch) |
Output:
| Field | Type | Description |
|---|---|---|
from | string | Base currency |
to | string | Quote currency |
start | number | Start timestamp (if provided) |
end | number | End timestamp (if provided) |
points | number[][] | Array of [timestamp, open, close, high, low, volume] |
Long time ranges are automatically downscaled to ≤100 data points.
Indexer Tools
Requires: useIndexer()
getIndexerTokenBalance
Get token balance for any address via the WDK Indexer API. Read-only.
Input:
| Parameter | Type | Required | Description |
|---|---|---|---|
blockchain | enum | Yes | Blockchain to query |
token | enum | Yes | Token (e.g., "usdt", "xaut", "btc") |
address | string | Yes | Wallet address |
Output:
| Field | Type | Description |
|---|---|---|
tokenBalance.blockchain | string | Blockchain name |
tokenBalance.token | string | Token name |
tokenBalance.amount | string | Token balance |
This queries the indexed balance, which may have slight delay compared to real-time blockchain state. For your own wallet's balance, use getBalance or getTokenBalance instead.
getTokenTransfers
Get token transfer history for an address. Read-only.
Input:
| Parameter | Type | Required | Description |
|---|---|---|---|
blockchain | enum | Yes | Blockchain to query |
token | enum | Yes | Token (e.g., "usdt", "xaut", "btc") |
address | string | Yes | Wallet address |
limit | number | No | Results per page (1–1000, default: 10) |
fromTs | number | No | Start timestamp (unix seconds) |
toTs | number | No | End timestamp (unix seconds) |
sort | enum | No | "asc" or "desc" (default: "desc") |
Output:
| Field | Type | Description |
|---|---|---|
transfers | object[] | Array of transfer records |
transfers[].blockchain | string | Blockchain |
transfers[].blockNumber | number | Block number |
transfers[].transactionHash | string | Transaction hash |
transfers[].token | string | Token |
transfers[].amount | string | Transfer amount |
transfers[].timestamp | number | Unix timestamp |
transfers[].from | string | Sender address |
transfers[].to | string | Recipient address |
Swap Tools
Requires: registerProtocol() with a swap protocol
quoteSwap
Get a swap quote without executing. Read-only.
Input:
| Parameter | Type | Required | Description |
|---|---|---|---|
chain | enum | Yes | Blockchain with swap protocol |
tokenIn | string | Yes | Token to sell (e.g., "USDT") |
tokenOut | string | Yes | Token to buy (e.g., "XAUT" on Ethereum, when supported by the registered protocol) |
amount | string | Yes | Amount in human-readable units |
side | enum | Yes | "sell" or "buy" |
Output:
| Field | Type | Description |
|---|---|---|
protocol | string | DEX protocol used |
tokenIn | string | Input token symbol |
tokenOut | string | Output token symbol |
tokenInAmount | string | Input amount (human-readable) |
tokenOutAmount | string | Output amount (human-readable) |
fee | string | Estimated fee |
swap
Execute a token swap. Destructive - requests confirmation when elicitation is enabled.
Input:
| Parameter | Type | Required | Description |
|---|---|---|---|
chain | enum | Yes | Blockchain with swap protocol |
tokenIn | string | Yes | Token to sell |
tokenOut | string | Yes | Token to buy |
amount | string | Yes | Amount in human-readable units |
side | enum | Yes | "sell" or "buy" |
to | string | No | Recipient address (defaults to wallet) |
Output:
| Field | Type | Description |
|---|---|---|
success | boolean | Whether the swap succeeded |
protocol | string | DEX protocol used |
hash | string | Transaction hash |
tokenIn | string | Input token symbol |
tokenOut | string | Output token symbol |
tokenInAmount | string | Actual input amount |
tokenOutAmount | string | Actual output amount |
fee | string | Fee paid |
This tool quotes the swap first, then requests approval when elicitation is enabled. With elicitation disabled, the confirmation request is automatically accepted.
Bridge Tools
Requires: registerProtocol() with a bridge protocol
quoteBridge
Get a bridge quote without executing. Read-only.
Input:
| Parameter | Type | Required | Description |
|---|---|---|---|
chain | enum | Yes | Source blockchain |
targetChain | string | Yes | Destination blockchain |
token | string | Yes | Token to bridge (e.g., "USDT") |
amount | string | Yes | Amount in human-readable units |
recipient | string | No | Recipient on target chain (defaults to wallet) |
Output:
| Field | Type | Description |
|---|---|---|
protocol | string | Bridge protocol used |
sourceChain | string | Source blockchain |
targetChain | string | Destination blockchain |
token | string | Token symbol |
amount | string | Amount to bridge |
fee | string | Estimated gas fee |
bridgeFee | string | Bridge protocol fee |
bridge
Execute a cross-chain bridge. Destructive - requests confirmation when elicitation is enabled.
Input:
| Parameter | Type | Required | Description |
|---|---|---|---|
chain | enum | Yes | Source blockchain |
targetChain | string | Yes | Destination blockchain |
token | string | Yes | Token to bridge |
amount | string | Yes | Amount in human-readable units |
recipient | string | No | Recipient on target chain (defaults to wallet) |
Output:
| Field | Type | Description |
|---|---|---|
success | boolean | Whether the bridge succeeded |
protocol | string | Bridge protocol used |
hash | string | Transaction hash |
sourceChain | string | Source blockchain |
targetChain | string | Destination blockchain |
token | string | Token symbol |
amount | string | Amount bridged |
fee | string | Gas fee paid |
bridgeFee | string | Bridge protocol fee paid |
Bridge finality varies by target chain - tokens may take minutes to hours to arrive.
Lending Tools
Requires: registerProtocol() with a lending protocol
quoteSupply
Get a fee estimate for supplying tokens to a lending pool. Read-only.
Input:
| Parameter | Type | Required | Description |
|---|---|---|---|
chain | enum | Yes | Blockchain with lending protocol |
token | string | Yes | Token to supply |
amount | string | Yes | Amount in human-readable units |
onBehalfOf | string | No | Address to receive aTokens (defaults to wallet) |
Output:
| Field | Type | Description |
|---|---|---|
protocol | string | Lending protocol used |
chain | string | Blockchain |
token | string | Token symbol |
amount | string | Amount to supply |
fee | string | Estimated gas fee |
supply
Supply tokens to a lending pool. Destructive - requests confirmation when elicitation is enabled.
Same input as quoteSupply. Output includes success, protocol, hash, token, amount, and fee.
quoteWithdraw
Estimate fee for withdrawing from a lending pool. Read-only.
Input:
| Parameter | Type | Required | Description |
|---|---|---|---|
chain | enum | Yes | Blockchain |
token | string | Yes | Token to withdraw |
amount | string | Yes | Amount in human-readable units |
Output: Same structure as quoteSupply.
withdraw
Withdraw tokens from a lending pool. Destructive - requests confirmation when elicitation is enabled.
Same input as quoteWithdraw. Output includes success, protocol, hash, token, amount, and fee.
quoteBorrow
Estimate fee for borrowing from a lending pool. Read-only.
Input:
| Parameter | Type | Required | Description |
|---|---|---|---|
chain | enum | Yes | Blockchain |
token | string | Yes | Token to borrow |
amount | string | Yes | Amount in human-readable units |
Output: Same structure as quoteSupply.
borrow
Borrow tokens from a lending pool. Destructive - requests confirmation when elicitation is enabled.
Same input as quoteBorrow. Output includes success, protocol, hash, token, amount, and fee.
quoteRepay
Estimate fee for repaying a loan. Read-only.
Input:
| Parameter | Type | Required | Description |
|---|---|---|---|
chain | enum | Yes | Blockchain |
token | string | Yes | Token to repay |
amount | string | Yes | Amount in human-readable units |
Output: Same structure as quoteSupply.
repay
Repay borrowed tokens. Destructive - requests confirmation when elicitation is enabled.
Same input as quoteRepay. Output includes success, protocol, hash, token, amount, and fee.
Fiat Tools
Requires: registerProtocol() with a fiat protocol
quoteBuy
Get a quote for purchasing crypto with fiat. Read-only.
Input:
| Parameter | Type | Required | Description |
|---|---|---|---|
chain | enum | Yes | Blockchain for the fiat protocol |
cryptoAsset | string | Yes | Crypto asset code (e.g., "eth", "btc") |
fiatCurrency | string | Yes | Fiat currency code (e.g., "USD", "EUR") |
amount | string | Yes | Amount to quote |
amountType | enum | Yes | "crypto" or "fiat" |
Output:
| Field | Type | Description |
|---|---|---|
protocol | string | Fiat protocol used |
cryptoAsset | string | Crypto asset code |
fiatCurrency | string | Fiat currency code |
cryptoAmount | string | Crypto amount (base units) |
fiatAmount | string | Fiat amount (smallest units, e.g., cents) |
fee | string | Total fee (fiat smallest units) |
rate | string | Exchange rate |
buy
Generate a provider URL for a fiat-to-crypto purchase. This tool does not request MCP confirmation; the user opens the URL to complete the purchase with the provider.
Accepts the quoteBuy inputs plus an optional recipient address, which defaults to the wallet address. Returns protocol and buyUrl.
quoteSell
Get a quote for selling crypto to fiat. Read-only.
Requires chain, cryptoAsset, fiatCurrency, and cryptoAmount (a string in base units). Returns the same output fields as quoteBuy.
sell
Generate a provider URL for a crypto-to-fiat sale. This tool does not request MCP confirmation; the user opens the URL to complete the sale with the provider.
Requires chain, cryptoAsset, fiatCurrency, and cryptoAmount (a string in base units). The optional refundAddress defaults to the wallet address. Returns protocol and sellUrl.
getTransactionDetail
Get details of a fiat transaction by ID. Read-only.
Input:
| Parameter | Type | Required | Description |
|---|---|---|---|
chain | enum | Yes | Blockchain |
transactionId | string | Yes | Transaction ID from the fiat provider |
getSupportedCryptoAssets
List crypto assets supported by the fiat provider. Read-only.
Input:
| Parameter | Type | Required | Description |
|---|---|---|---|
chain | enum | Yes | Blockchain |
getSupportedFiatCurrencies
List fiat currencies supported by the fiat provider. Read-only.
Input:
| Parameter | Type | Required | Description |
|---|---|---|---|
chain | enum | Yes | Blockchain |
getSupportedCountries
List countries supported by the fiat provider. Read-only.
Input:
| Parameter | Type | Required | Description |
|---|---|---|---|
chain | enum | Yes | Blockchain |
Utility Exports
Utility functions for converting between human-readable amounts and blockchain base units:
import {
parseAmountToBaseUnits,
formatBaseUnitsToAmount,
AmountParseError,
AMOUNT_ERROR_CODES
} from '@tetherto/wdk-mcp-toolkit'parseAmountToBaseUnits(amount, decimals)
Converts a human-readable amount string to BigInt base units without floating-point errors.
parseAmountToBaseUnits('2.01', 6) // → 2010000n
parseAmountToBaseUnits('100', 18) // → 100000000000000000000n
parseAmountToBaseUnits('1,000.50', 6) // → 1000500000nformatBaseUnitsToAmount(baseUnits, decimals)
Converts BigInt base units to a human-readable string.
formatBaseUnitsToAmount(2010000n, 6) // → '2.01'
formatBaseUnitsToAmount(100000000000000000000n, 18) // → '100'AmountParseError
Custom error class with a code property for programmatic handling:
| Error Code | Description |
|---|---|
EMPTY_STRING | Empty amount string |
INVALID_FORMAT | Not a valid number |
NEGATIVE_AMOUNT | Negative amounts not allowed |
EXCESSIVE_PRECISION | More decimal places than token supports |
INVALID_DECIMALS | Decimals value out of range |
SCIENTIFIC_NOTATION_PRECISION | Scientific notation exceeds precision |