API Reference

This page documents the 54 leaf commands in @tetherto/wdk-cli@1.0.0-beta.6. Run wdk COMMAND --help to inspect the installed command surface.

Root Options

The WDK-specific global flags are --json and --verbose; version and help are also root options. Options such as --wallet and --index belong to individual commands.

Shared Wallet Selection

Wallet-dependent read, message, send, swap, bridge, buy, and sell commands use:

The selected wallet must be unlocked before daemon-backed operations. See Manage Wallets.

Wallet Commands

wdk wallet create

Creates a named wallet from a newly generated BIP-39 seed phrase.

The first created wallet becomes the default. The command prompts for a passphrase and prints the seed phrase. With --json, the success object also contains seedPhrase.

wdk wallet import

Imports an existing 12-word or 24-word BIP-39 seed phrase.

Without --seed-stdin, the command prompts for the seed phrase and a new storage passphrase. With --seed-stdin, a piped run must also set WDK_PASSPHRASE, because the same input stream cannot answer the passphrase prompt. The seed is never accepted as a command-line argument.

wdk wallet export

Decrypts and prints a wallet's seed phrase.

With --json, the success object contains seedPhrase.

wdk wallet list

Lists local wallets with their default, lock, and TTL state. This command has no command-specific options.

wdk wallet delete

Deletes a named wallet after verifying its passphrase.

If the deleted wallet was the default, the CLI selects the first remaining wallet as the new default. See Manage Wallets for the deletion and backup implications.

wdk wallet unlock

Unlocks a wallet and starts the daemon when needed.

Unlocking an already unlocked wallet resets that wallet's timer. The timer is absolute from unlock or reset; wallet activity does not extend it.

wdk wallet lock

Locks one wallet or every wallet.

If both selectors are present, beta.6 applies --all.

wdk wallet default

Sets the default wallet after passphrase confirmation.

wdk wallet rename

Renames a wallet after verifying its passphrase. An unlocked source wallet is locked first.

wdk wallet change-passphrase

Decrypts a wallet with its current passphrase, rewrites seed.enc with a new passphrase, and then attempts to lock that wallet's daemon session.

Interactive use prompts for the current passphrase, then asks for and confirms the new passphrase. WDK_PASSPHRASE may supply only the current passphrase; it is deliberately ignored for the new passphrase. A piped --new-passphrase-stdin run must set WDK_PASSPHRASE and rejects an empty new passphrase.

Read Commands

wdk get address

Derives an address for one network or for a network group.

When both --network and --all are supplied, beta.6 runs the single-network path. In aggregate mode, networks that fail address derivation are omitted from the result.

wdk get balance

Reads one registered asset balance or native balances across a network group.

--token is ignored by the aggregate path, which queries native assets. Networks that fail in aggregate mode are omitted. A missing price produces a USD value of 0 rather than failing the balance lookup.

Single-network balance results include the account address. Aggregate balance entries also include their account address.

wdk get history

Reads token-transfer history through the configured indexer.

When --token is omitted, beta.6 batches the network's supported token requests, ignores failed batch items, merges successful transfers by timestamp, and then applies --limit.

wdk get transaction

Reads a normalized transaction receipt, optionally waiting for a finality target.

Without --finality, the command calls the account's current transaction lookup and returns without waiting for a later state. With --finality, it waits until the target, a dropped transaction, or the timeout. The text view shows the common receipt fields; use --json for the full module-specific receipt. Every returned bigint is serialized as a decimal string.

Send Command

wdk send

Previews or broadcasts a native or registered-token transfer.

Use --dry-run before broadcasting:

wdk send \
  --network ethereum \
  --to 0x000000000000000000000000000000000000dEaD \
  --amount 0.001 \
  --dry-run

Without --dry-run, the command broadcasts immediately. There is no additional interactive confirmation.

Before either fee estimation or broadcast, beta.6 validates the recipient against the selected built-in network's CAIP-2 address rules. A format or mainnet/testnet mismatch fails with INVALID_ADDRESS after the unlocked-wallet check but before the estimate or send request. A custom network without a supported CAIP-2 validator is left to its wallet module for final validation.

Send previews and execution results include from, the sender address.

Message Commands

Both message commands require an unlocked wallet. They use the selected account's signing and verification methods.

wdk message sign

The result includes the network, account index, signer address, original message, and signature.

wdk message verify

The result reports valid: true or valid: false for that account, message, and signature.

Message verification results include the checked account address alongside valid.

Swap Command

wdk swap

Quotes or executes a token swap. Same-network swaps are the documented beta.6 path; see the warning below before using the accepted cross-network option.

Provide exactly one of --amount-in and --amount-out. Exact-input routing selects the successful quote with the highest output. Exact-output routing selects the quote with the lowest input. Separate gas and bridge fees are displayed but excluded from ranking because their denomination and inclusion differ between protocol types. Failed quote attempts appear under skipped when another protocol succeeds.

If --recipient is omitted, the daemon derives an address on the destination network from the selected wallet and the same account index. The preview includes the sender in from, but does not include that recipient, wallet, or index. Select all three explicitly and verify the destination address with wdk get address --network NETWORK --wallet WALLET --index INDEX before previewing.

Velora beta.6 requires a prior allowance when the input is an ERC-20 token. Beta.6 does not approve automatically or expose the provider spender. Resolve the chain-specific spender with Velora SDK 9's swap.getSpender() lookup, approve a bounded base-unit amount through the catalog-declared wallet method, verify a confirmed receipt with success: true, and read the allowance again. Native-token input has no ERC-20 allowance, and other protocols can manage approval differently. See Call Module Methods.

Use wdk provider list to discover provider names and wdk provider info to inspect effective configuration. Package installation with wdk module add and provider registration with wdk provider add are separate operations. See Swap and Bridge for the complete workflow.

Bridge Command

wdk bridge

Quotes or executes an exact-input transfer of the same registered token between different networks.

The source and destination networks must differ. The omitted-recipient behavior, preview identity omission, ranking, skipped-protocol reporting, fresh execution quote, lack of CLI bounds relative to the preview, and immediate-execution warning are the same as for wdk swap.

Fiat Ramp Commands

wdk buy and wdk sell derive the selected wallet address and print a signed provider URL to open in a browser. Both require an unlocked wallet and valid MoonPay configuration.

wdk buy

wdk sell

For each command, provide exactly one of --fiat-amount and --crypto-amount. Beta.6 supports only the moonpay module.

Configuration Commands

See Configuration for keys, types, precedence, and storage considerations.

wdk config get

--all cannot be combined with --key or --network. --network and --key can be combined.

wdk config set

wdk config reset

--key and --all are mutually exclusive. --network can be combined only with --key.

wdk config path

Prints the resolved config.json path. This command has no command-specific options.

Network Commands

wdk network list

With neither option, the command shows enabled networks and networks disabled directly. Networks hidden by a disabled module are omitted; re-enable their module first. If both are provided, beta.6 applies --testnet.

wdk network create <data>

Creates a custom network from an inline JSON object or a JSON file path. The <data> positional argument is required.

See Custom Networks for the network schema and validation rules.

wdk network delete

Built-in networks cannot be deleted. Deleting a custom network also removes its network configuration and custom token entries.

wdk network info

wdk network enable

Enable a built-in or custom network with required --name <name>. If its module is disabled, enable that module first. Enabling an orphaned override clears it.

wdk network disable

Disable a network with required --name <name>. This hides its tokens from normal token listings and prevents operations on the network. Both network toggles verify the default wallet passphrase when a wallet exists and lock a running daemon; unlock again to apply the registry change.

Token Commands

wdk token list

wdk token info

wdk token add <data>

Adds or overrides a token from an inline JSON object or a JSON file path. The <data> positional argument is required.

See Manage Tokens for the token schema and built-in override behavior.

wdk token delete

The command removes only a custom entry. If that entry overrides a built-in token, the built-in entry becomes effective again.

wdk token enable

Enable a token with required --network <network> and --token <token>. The network must be enabled. Enabling an orphaned token override clears it.

wdk token disable

Disable a built-in or custom token with required --network <network> and --token <token>. The registry entry stays stored. Both token toggles verify the default wallet passphrase when a wallet exists and lock a running daemon. Listing includes tokens disabled directly, but omits tokens whose network is disabled.

Wallet Module Method Commands

These commands expose chain-specific methods declared in the built-in module catalog. They do not discover arbitrary methods from a custom package at runtime.

wdk method list

Provide exactly one selector:

Each method entry reports its name, read or write kind, and required and optional parameters. Listing methods does not require an unlocked wallet.

wdk method call

Scalar parameters accept string, number, boolean, or non-negative decimal bigint values. Pass scalar arrays as comma-separated values and structured parameters as JSON strings. Represent every bigint inside JSON as a quoted decimal string. Unknown, missing, or malformed parameters fail before the method reaches the daemon. Returned bigint values are serialized as decimal strings. JSON output contains { network, method, address, result }; address identifies the account that ran the method.

See Call Module Methods for examples and the write-method safety boundary.

Module Package Commands

wdk module list

Lists built-in and custom modules with their pinned version, installed version, status, and source. Statuses are ok, not installed, version mismatch, disabled, and stale override. A version override also exposes defaultVersion. This command has no command-specific options and does not require an unlocked wallet.

wdk module add

For a new custom package, omitting the version resolves npm's current version once. A supplied suffix is stored verbatim, so use a reviewed exact version rather than an accepted tag or range. To change an existing custom pin, remove it first. For a built-in package, supply an explicit version different from its current configured pin; the command records an override of the catalog version.

The command verifies the default wallet passphrase when a wallet exists, locks a running daemon, runs npm install --no-save PACKAGE@VERSION inside the CLI installation, and records the pin under customModules in config.json. A custom package registered but missing or mismatched on disk can be repaired by running module add again without changing its pin. Built-in overrides are stored under overrides.modules. Adding the current built-in pin is rejected even if its package is missing; reinstall the exact CLI version to repair a missing default package.

wdk module remove

The command verifies the default wallet passphrase when a wallet exists, locks a running daemon, removes the custom-module record, and runs npm uninstall --no-save. For a built-in package with a version override, it instead clears the override and reinstalls the catalog version. It rejects a built-in package with no version override.

See Manage Modules for the trust boundary, repair behavior, and custom-network workflow.

wdk module enable

Enable a module with required --name <package>. Enabling an orphaned module override clears it. It does not install a missing package.

wdk module disable

Disable a module with required --name <package>. Its networks and providers become unavailable. Both module toggles verify the default wallet passphrase when a wallet exists and lock a running daemon. module list retains disabled modules and stale overrides so they can be inspected.

Provider Commands

Providers register installed modules for swap, bridge, or Swidge routing. These commands are available through the CLI, not as MCP tools.

wdk provider list

List names, kind, backing module, source, and enabled status. JSON output is { providers, count }. Providers disabled directly remain listed; providers hidden by a disabled module are omitted.

wdk provider info

Inspect a provider with required --name <name>. Returns its registry fields, merged general config, and effective per-network networks configuration, including disabled entries.

wdk provider add

Register a provider from an inline JSON object or JSON file path. The <data> argument is required.

The command verifies the default wallet passphrase when a wallet exists, imports the module to check its declared kind, saves the provider, and locks a running daemon. Importing executes package code: register only a package you have reviewed. The kind check is not a safety or chain-compatibility check. Adding a provider does not install its module.

wdk provider delete

Delete a custom provider with required --name <name>. Built-in providers cannot be deleted. This removes the registration, its configuration overrides, and its enable/disable override; the module package remains installed.

wdk provider enable

Enable a provider with required --name <name>. If its module is disabled, enable that module first. Enabling an orphaned provider override clears it.

wdk provider disable

Disable a provider with required --name <name> while retaining its registration. Delete, enable, and disable verify the default wallet passphrase when a wallet exists and lock a running daemon. Mutation JSON includes walletsLocked; unlock again to use the changed registry.

MCP Setup Commands

The accepted --ai-tool values are claude-desktop, claude-code, and openclaw.

wdk mcp setup

Adds the bundled MCP server to the selected client. --ai-tool <name> is required.

wdk mcp remove

Removes the bundled MCP server from the selected client. --ai-tool <name> is required.

wdk mcp verify-setup

Checks the selected client's configuration and tests the MCP server. --ai-tool <name> is required.

wdk mcp list

Shows setup status for all supported clients. This command has no command-specific options.

See Use the MCP Server for client-specific setup and the exposed tool surface.

JSON and Exit Behavior

Most command handlers print one JSON value to stdout when --json is set. The current contract has exceptions:

• wdk mcp setup, remove, verify-setup, and list print human-readable success output even with --json.
• Help and version output remains human-readable text. With --json, unknown commands, unknown options, missing required options, and invalid option values return an INVALID_ARGUMENT JSON envelope on stdout with status 1.
• Interactive wallet prompts render on stdout. If a wallet command opens a prompt, prompt text and terminal-control bytes can precede any JSON result. Use wallet import --seed-stdin with WDK_PASSPHRASE for a non-interactive import.
• wdk send --json suppresses its progress spinner and completion text; command errors and results remain on stdout as JSON.
• A non-empty WDK_PASSPHRASE produces a notice on stderr.

Parse stdout separately from stderr and always check the exit status. See Handle Errors for the error envelope and exit-status contract.

Need Help?