Configuration

WDK CLI stores its configuration and wallet data under one local configuration directory. Use wdk config for supported changes instead of editing config.json directly.

Local Paths

The default configuration directory is ~/.config/wdk-cli. If XDG_CONFIG_HOME is a non-empty environment variable, WDK CLI uses $XDG_CONFIG_HOME/wdk-cli instead.

Print the resolved config.json path:

wdk config path

With JSON output:

wdk config path --json

{"path":"/home/user/.config/wdk-cli/config.json"}

See Storage Format for seed-file and daemon-file permissions.

Configuration Precedence

WDK CLI resolves runtime values in this order:

--wallet and --index are options on wallet-dependent commands; they are not root flags.

An empty WDK_PASSPHRASE value does not override the prompt. To use an empty passphrase, enter it interactively. See Manage Wallets before choosing an empty passphrase.

Environment Variables

There are no beta.6 environment-variable mappings for indexer.baseUrl, wallet defaults, account defaults, network configuration, custom modules, or MoonPay configuration.

Supported Keys

Custom-module, custom-network, and custom-token records also live in config.json. Manage them with wdk module, wdk network, and wdk token so the CLI can coordinate package installation, validate record shapes, and update related state.

Read Configuration

Read one global key:

wdk config get --key defaultIndex

Read one network configuration:

wdk config get --network ethereum

Read a key inside one network configuration:

wdk config get --network ethereum --key provider

Read the full configuration view:

wdk config get --all

config get --all excludes the custom-token registry. Use wdk token list to read tokens.

Prefer WDK_INDEXER_API_KEY when you do not want to persist the indexer key. No environment override is available for MoonPay configuration in beta.6.

Set Configuration

Set a string:

wdk config set --key indexer.baseUrl --value https://indexer.example.com

Set a number:

wdk config set --key defaultIndex --value 1

Set a JSON object:

wdk config set \
  --key ramp.moonpay \
  --value '{"apiKey":"pk_test_...","signUrl":"https://example.com/sign","environment":"sandbox"}'

config set parses a valid JSON value into its JSON type. If parsing fails, it stores the value as a string. Quote objects and arrays so the shell passes them as one argument.

Set a network-specific key:

wdk config set \
  --network ethereum \
  --key provider \
  --value https://ethereum-rpc.publicnode.com

Replace a network's complete wallet-module configuration:

wdk config set \
  --network ethereum \
  --value '{"chainId":1,"provider":"https://ethereum-rpc.publicnode.com","transferMaxFee":5000000000000000}'

Network configuration is passed to the selected WDK wallet module. Use only keys supported by that module.

Reset Configuration

Reset one global key:

wdk config reset --key indexer.baseUrl

Reset one network key:

wdk config reset --network ethereum --key provider

Reset configuration defaults:

wdk config reset --all

config reset --all preserves the default-wallet selection, custom networks, custom tokens, and custom providers. It resets the remaining values to their installed defaults, including removing customModules registrations. It also clears registry overrides and does not uninstall packages. Beta.6 rejects unregistered packages when loading wallet managers or providers, so preserved custom networks/providers can stop working until their modules are registered again. Record module pins, network specs, and provider specs before a full reset.

Authorization and Wallet Locking

When at least one wallet exists, these configuration mutations verify the current default wallet's passphrase:

• wdk config set
• wdk config reset
• wdk network create
• wdk network delete
• wdk token add
• wdk token delete
• wdk module add
• wdk module remove
• wdk module enable and disable
• wdk network enable and disable
• wdk token enable and disable
• wdk provider add, delete, enable, and disable

Set WDK_PASSPHRASE for non-interactive local automation or enter the passphrase at the prompt.

Changing or resetting a key under networks or providers locks a running daemon so the next unlock initializes fresh wallet and provider instances. config reset --all, module add/remove, registry toggles, and provider add/delete also lock running wallet sessions. Their JSON output includes walletsLocked; when no daemon is running, changes take effect at the next unlock.

Module Packages

Beta.6 records built-in module pins in the installed catalog, custom pins under customModules, and user overrides under overrides.modules in config.json. Use module enable/disable to control availability without uninstalling a package.

wdk module list

Use wdk module add and wdk module remove instead of editing customModules directly. Those commands coordinate the stored pin with npm installation and lock the daemon before its module graph changes.

Custom packages are installed with npm's --no-save option. A later npm operation can prune them. Use wdk module list to detect a missing or mismatched package, then run wdk module add --name PACKAGE to repair the stored pin. See Manage Modules.

Swap And Bridge Protocols

wdk swap and wdk bridge use the providers registry in the installed catalog plus customProviders. Each entry declares its kind (swap, bridge, or swidge), backing module, general configuration, and optional per-network overrides. Swidge providers can serve either command; the selected module still determines supported chains and assets.

Inspect provider names and effective configuration before choosing --protocol NAME:

wdk provider list
wdk provider info --name velora

Use wdk provider add to register a reviewed, installed module under a new name. Package installation and provider registration are separate operations. Provider enable/disable controls routing availability; disabling a module also hides its providers.

Configuration is shallow-merged in this order: the provider's general config, providers.NAME.config, its packaged per-network config (or the custom registration's networks.NETWORK), then providers.NAME.networks.NETWORK. Inspect provider info after changes. Keys under providers lock running wallet sessions so the next unlock reloads the configuration.

The MCP server has no provider-management or provider-listing tools. Discover names through the CLI before passing protocol to an MCP transaction tool. See Swap and Bridge for execution behavior and Manage Modules for package overrides and repair limits.

Indexer

Within the CLI command set, only wdk get history uses the WDK Indexer API. The MCP get_history tool uses the same history path. Request an Indexer API key before connecting directly.

Connect Directly

The default indexer.baseUrl is https://wdk-api.tether.io. Store your API key:

wdk config set --key indexer.apiKey --value YOUR_INDEXER_API_KEY

Alternatively, supply it to the current process without writing it to config.json:

WDK_INDEXER_API_KEY=YOUR_INDEXER_API_KEY \
  wdk get history --network ethereum --wallet dev

Use an Indexer Proxy

Point the CLI at your own endpoint when you do not want Indexer API keys on developer machines:

wdk config reset --key indexer.apiKey
wdk config set --key indexer.baseUrl --value https://indexer-proxy.example.com

Also ensure WDK_INDEXER_API_KEY is not set in the CLI process. A non-empty environment value overrides the stored empty value and causes the CLI to send an x-api-key header.

The proxy must accept both history request forms:

Forward the query parameters or JSON request body and the Indexer response unchanged. Add the Indexer x-api-key header when forwarding the request upstream.

WDK_INDEXER_BASE_URL is not read by beta.6.

MoonPay

wdk buy and wdk sell derive the selected wallet address and build a signed MoonPay widget URL. The CLI prints the URL, or returns it in JSON output; it does not open the browser or execute the fiat transaction. Open the URL to continue on MoonPay, which processes the transaction through the integration associated with your MoonPay account.

Get a publishable key from Developers → API Keys in the MoonPay dashboard. Use a pk_test_... or pk_live_... publishable key here, never the sk_test_... or sk_live_... secret key.

The commands require all three MoonPay values:

wdk config set --key ramp.moonpay.apiKey --value pk_test_...
wdk config set --key ramp.moonpay.signUrl --value https://example.com/moonpay/sign
wdk config set --key ramp.moonpay.environment --value sandbox

Sign Widget URLs

Because the CLI includes a wallet address in the MoonPay widget URL, it sends the unsigned URL to your signing service. That service signs the URL with your MoonPay secret key and returns the complete signed URL. See MoonPay's on-ramp URL signing and off-ramp URL signing guides.

The CLI sends this request to ramp.moonpay.signUrl:

POST /moonpay/sign HTTP/1.1
Content-Type: application/json

{"urlForSignature":"https://..."}

Return a successful JSON response with the complete signed URL:

{"signedUrl":"https://...&signature=..."}

Returning only the signature is not supported.

Select an Environment

The CLI rejects a sandbox/mainnet or production/testnet mismatch. It does not validate the publishable-key prefix, so configure the matching key yourself.

Need Help?