API Reference

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

Root Options

Option	Behavior
`--json`	Requests machine-readable output from the selected command; see JSON and exit behavior for exceptions
`--verbose`	Adds a stack trace to handled errors; it does not enable general debug logging
`-V`, `--version`	Prints the CLI version followed by the installed WDK dependency versions
`-h`, `--help`	Prints help for the selected command

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:

Option	Behavior
`--wallet <name>`	Uses the named wallet; otherwise uses `defaultWallet`
`--index <n>`	Uses a non-negative account index; otherwise uses `defaultIndex`, initially `0`

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.

Option	Required	Default	Description
`--name <name>`	Yes	—	Wallet name
`--words <count>`	No	`12`	Seed length; accepts `12` or `24`

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.

Option	Required	Description
`--name <name>`	Yes	Wallet name
`--seed-stdin`	No	Read one trimmed seed-phrase line from standard input instead of prompting

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.

Option	Required	Description
`--name <name>`	Yes	Wallet name

With --json, the success object contains seedPhrase.

The output from wallet create and wallet export is secret material in both text and JSON modes. Do not log it, paste it into an agent transcript, or store it in CI output.

`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.

Option	Required	Description
`--name <name>`	Yes	Wallet name

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.

Option	Required	Default	Description
`--name <name>`	Yes	—	Wallet name
`--ttl <minutes>`	No	`5`	Non-negative session duration in minutes; `0` disables automatic expiry

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.

Option	Required	Description
`--name <name>`	One selector required	Wallet to lock
`--all`	One selector required	Lock every wallet

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

`wdk wallet default`

Sets the default wallet after passphrase confirmation.

Option	Required	Description
`--name <name>`	Yes	Existing wallet name

`wdk wallet rename`

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

Option	Required	Description
`--name <name>`	Yes	Current wallet name
`--new-name <name>`	Yes	New wallet name

`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.

Option	Required	Description
`--name <name>`	Yes	Existing wallet name
`--new-passphrase-stdin`	No	Read one trimmed new-passphrase line from standard input instead of prompting and confirmation

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.

Option	Required	Default	Description
`--network <network>`	One selector required	—	Derive one network address
`--all`	One selector required	—	Derive addresses for all mainnets by default
`--wallet <name>`	No	Default wallet	Wallet selection
`--index <n>`	No	Configured index, initially `0`	Non-negative account index
`--testnet`	No	Off	With `--all`, select testnets instead of mainnets

When both --network and --all are supplied, beta.5 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.

Option	Required	Default	Description
`--network <network>`	One selector required	—	Query one network
`--all`	One selector required	—	Query native balances on all mainnets by default
`--token <token>`	No	Native asset	Registered ticker for a single-network query
`--wallet <name>`	No	Default wallet	Wallet selection
`--index <n>`	No	Configured index, initially `0`	Non-negative account index
`--testnet`	No	Off	With `--all`, select testnets instead of mainnets

--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.

`wdk get history`

Reads token-transfer history through the configured indexer.

Option	Required	Default	Description
`--network <network>`	Yes	—	Network to query
`--token <token>`	No	All indexer-supported tokens	Exact `metadata.indexerSlug` code; the installed registry yields `btc`, `usdt`, and `xaut`, while custom entries can add other codes
`--limit <n>`	No	`30`	Positive maximum number of transfers
`--from-date <date>`	No	—	ISO 8601 start date
`--to-date <date>`	No	—	ISO 8601 end date
`--wallet <name>`	No	Default wallet	Wallet selection
`--index <n>`	No	Configured index, initially `0`	Non-negative account index

When --token is omitted, beta.5 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.

Option	Required	Default	Description
`--network <network>`	Yes	None	Network containing the transaction
`--hash <hash>`	Yes	None	Non-empty transaction hash
`--finality <target>`	No	Current receipt	Wait for `confirmed` or `final`
`--timeout <ms>`	No	`150000` with `--finality`	Positive wait budget in milliseconds; valid only with `--finality`
`--wallet <name>`	No	Default wallet	Wallet selection
`--index <n>`	No	Configured index, initially `0`	Non-negative account index

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.

Option	Required	Default	Description
`--network <network>`	Yes	—	Network to send on
`--to <address>`	Yes	—	Recipient address
`--amount <value>`	Yes	—	Positive decimal amount, or an integer when `--base-units` is set
`--token <token>`	No	Native asset	Registered token ticker
`--wallet <name>`	No	Default wallet	Wallet selection
`--index <n>`	No	Configured index, initially `0`	Non-negative account index
`--base-units`	No	Off	Treat `--amount` as raw base units
`--dry-run`	No	Off	Estimate fees and return a preview without broadcasting

Use --dry-run before broadcasting:

Terminal

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.5 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.

Message Commands

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

`wdk message sign`

Option	Required	Default	Description
`--network <network>`	Yes	None	Network whose account key signs the message
`--message <message>`	Yes	None	Non-empty message to sign
`--wallet <name>`	No	Default wallet	Wallet selection
`--index <n>`	No	Configured index, initially `0`	Non-negative account index

Signing happens immediately. The command has no dry run, confirmation prompt, or second passphrase check. A signature can authorize actions on some chains, so review the exact message, network, wallet, and account index before running it.

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

`wdk message verify`

Option	Required	Default	Description
`--network <network>`	Yes	None	Network whose account key verifies the message
`--message <message>`	Yes	None	Original signed message
`--signature <signature>`	Yes	None	Signature to verify
`--wallet <name>`	No	Default wallet	Wallet selection
`--index <n>`	No	Configured index, initially `0`	Non-negative account index

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

Swap Command

`wdk swap`

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

Option	Required	Default	Description
`--network <network>`	Yes	None	Source network
`--from-token <token>`	Yes	None	Registered source token
`--to-token <token>`	Yes	None	Registered destination token
`--amount-in <value>`	One amount required	None	Exact decimal amount to sell
`--amount-out <value>`	One amount required	None	Exact decimal amount to receive
`--to-network <network>`	No	Source network	Accepted destination network; unsafe in beta.5 because same-chain candidates can receive no destination
`--recipient <address>`	No	Selected account	Destination-network recipient
`--protocol <name>`	No	Best route	Restrict quoting to one short key in the exact installed catalog; beta.5 has no protocol-list command
`--wallet <name>`	No	Default wallet	Wallet selection
`--index <n>`	No	Configured index, initially `0`	Non-negative account index
`--dry-run`	No	Off	Quote without executing

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.

Without --dry-run, wdk swap executes immediately. Execution requests fresh quotes. Unless --protocol is set, the provider can change; amounts and fees can change even when it is set. Beta.5 exposes no CLI option that binds a minimum output, maximum input, fee, slippage limit, or expiry to the preview, and there is no daemon confirmation step.

Do not use --to-network for a beta.5 swap. Candidate selection can admit a same-chain swap provider, and the swap adapter omits the destination network from that provider's quote and execution options.

If --recipient is omitted, the daemon derives an address on the destination network from the selected wallet and the same account index. The preview output 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.5 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.

Beta.5 has no protocol-list command or MCP tool. Read the protocols object in its exact released catalog and compare it with the installed wdk.config.json; wdk module list does not list routing keys. wdk module add cannot add a routing entry or repair a built-in package. Reinstall @tetherto/wdk-cli@1.0.0-beta.5 if a built-in dependency is missing. 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.

Option	Required	Default	Description
`--network <network>`	Yes	None	Source network
`--token <token>`	Yes	None	Registered token on both networks
`--to-network <network>`	Yes	None	Different destination network
`--amount <value>`	Yes	None	Exact decimal input amount
`--recipient <address>`	No	Selected account	Destination-network recipient
`--protocol <name>`	No	Best route	Restrict quoting to one short key in the exact installed catalog; beta.5 has no protocol-list command
`--wallet <name>`	No	Default wallet	Wallet selection
`--index <n>`	No	Configured index, initially `0`	Non-negative account index
`--dry-run`	No	Off	Quote without executing

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`

Option	Required	Default	Description
`--network <network>`	Yes	—	Network to receive the asset on
`--token <token>`	Yes	—	Registered asset code
`--fiat-amount <value>`	One amount required	—	Fiat amount to spend
`--crypto-amount <value>`	One amount required	—	Crypto amount to buy
`--fiat-currency <currency>`	No	`usd`	Fiat currency code
`--module <module>`	No	`moonpay`	Fiat provider module
`--wallet <name>`	No	Default wallet	Wallet selection
`--index <n>`	No	Configured index, initially `0`	Non-negative account index

`wdk sell`

Option	Required	Default	Description
`--network <network>`	Yes	—	Network holding the asset
`--token <token>`	Yes	—	Registered asset code
`--fiat-amount <value>`	One amount required	—	Target fiat amount
`--crypto-amount <value>`	One amount required	—	Crypto amount to sell
`--fiat-currency <currency>`	No	`usd`	Fiat currency code
`--module <module>`	No	`moonpay`	Fiat provider module
`--wallet <name>`	No	Default wallet	Wallet selection
`--index <n>`	No	Configured index, initially `0`	Non-negative account index

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

Configuration Commands

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

`wdk config get`

Option	Required	Description
`--key <key>`	One selector required	Read one dot-separated key
`--network <network>`	One selector required	Read a network object, or scope `--key` to a network
`--all`	One selector required	Read the configuration view

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

`wdk config set`

Option	Required	Description
`--value <value>`	Yes	JSON value when parseable; otherwise a string
`--key <key>`	Without `--network`	Dot-separated key
`--network <network>`	No	Scope `--key`, or replace the network's entire configuration object

`wdk config reset`

Option	Required	Description
`--key <key>`	One selector required	Reset or remove one key
`--network <network>`	No	Scope `--key` to a network
`--all`	One selector required	Reset configuration while preserving the default wallet and custom network/token records

--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`

Option	Default	Description
`--testnet`	Off	Show only testnets
`--mainnet`	Off	Show only mainnets

With neither option, the command shows every registered network. If both are provided, beta.5 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`

Option	Required	Description
`--name <name>`	Yes	Custom network to delete

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

`wdk network info`

Option	Required	Description
`--network <network>`	Yes	Registered network to inspect

Token Commands

`wdk token list`

Option	Default	Description
`--network <network>`	All networks	Filter to one registered network

`wdk token info`

Option	Required	Description
`--network <network>`	Yes	Registered network
`--token <token>`	Yes	Registered token ticker

`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`

Option	Required	Description
`--network <network>`	Yes	Registered network
`--token <token>`	Yes	Custom token ticker to delete

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

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:

Option	Required	Description
`--network <network>`	One of the two selectors	List the methods declared for the registered network's wallet module
`--all`	One of the two selectors	List every built-in module that declares methods

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`

Option	Required	Default or behavior
`--network <network>`	Yes	Registered network whose wallet module declares the method
`--name <name>`	Yes	Exact method name returned by `wdk method list`
`--wallet <name>`	No	Default wallet
`--index <n>`	No	Configured `defaultIndex`, then `0`
`--PARAM <value>`	As declared	One flag for each declared method parameter; camel-case names become kebab-case flags

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.

A method marked write can move funds or mutate state. wdk method call has no dry-run or confirmation prompt. Review the exact method and arguments, then call it only after explicit approval while the intended wallet is unlocked.

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. This command has no command-specific options and does not require an unlocked wallet.

`wdk module add`

Option	Required	Description
`--name <package>`	Yes	npm package name, optionally followed by a version string; use a reviewed literal version, not a tag or range

When no version is supplied, the command resolves npm's current version once and stores that exact pin. When a suffix is supplied, beta.5 stores it verbatim and does not require exact semver, so tags and ranges are accepted even though they are unsafe for artifact pinning. It refuses to replace a built-in module or change an existing custom value in place. Remove the custom module before selecting a different literal 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 packages are rejected; reinstall the exact CLI version to repair them.

`wdk module remove`

Option	Required	Description
`--name <package>`	Yes	Previously added custom package name

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. Built-in modules cannot be removed.

Adding or removing a package runs npm and can execute package lifecycle scripts; an added default export can later run inside the wallet daemon with access to unlocked accounts. Audit the exact package and version before adding it. Beta.5 only warns about a configured/installed version mismatch and still loads the installed package. Delete custom networks that depend on a module before removing that module.

Unset WDK_PASSPHRASE before module add or module remove and use the hidden interactive prompt. Beta.5 passes its environment to npm, so install or uninstall lifecycle scripts can otherwise inherit the wallet passphrase.

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

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?

Discord CommunityConnect with developers, ask questions, share your projects

Join Community

GitHub IssuesReport bugs, request features, and get technical help

Open an Issue

Email ContactFor sensitive or private matters, contact our team directly

Send an email

API Reference

On this page