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.

This page documents 1.0.0-beta.7.

Upgrading from beta.6

The CLI does not copy old Indexer or MoonPay configuration keys. Set their provider-scoped replacements before using history or fiat commands:

Use wdk config set for the new keys, then unlock the wallet again because provider changes lock running wallet sessions. Keep credentials and any rollback configuration private: config.json is plaintext, and command arguments or inspection output can expose its values.

MoonPay and Transak ship enabled. Configure the selected fiat provider and pass --provider moonpay or --provider transak, or disable the unused provider. Pricing also uses registered providers; custom pricing providers can be added through wdk provider add.

New token registrations reject the old metadata.*Slug fields. Existing stored entries are normalized when loaded, with an explicit metadata.slugs mapping taking precedence. See provider mappings.

Configuration writes request file mode 0600 on macOS and Linux, and initialization attempts directory mode 0700. Directory restriction is best effort; verify existing file and directory permissions after upgrading. These modes do not encrypt configuration or prevent other processes running as your OS user from reading it. Windows uses platform access controls.

Review Indexer setup and history dates and provider configuration after moving the keys. History date flags retain their ISO 8601 input format; the client now receives Unix milliseconds. General and network-specific provider settings remain separate.

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.7 environment-variable mappings for Indexer or fiat-provider settings, wallet defaults, account defaults, network configuration, or custom modules. WDK_INDEXER_API_KEY and WDK_INDEXER_BASE_URL are not read.

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.

If your application uses an Indexer proxy, configure a credential that the proxy authenticates; an empty key is rejected before history HTTP requests. See authenticated proxy setup.

Set Configuration

Set a string:

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

Set a number:

wdk config set --key defaultIndex --value 1

Set a JSON object:

wdk config set \
  --key providers.moonpay.config \
  --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 providers.wdk-indexer.config.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.7 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.7 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 same registry also contains fiat, pricing, and indexer services. These do not become swap candidates. Indexer and pricing use general configuration without network overrides; fiat providers can use all four layers. Deleting a custom provider removes its stored general and per-network configuration and its availability override, while leaving the module installed.

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 bundled wdk-indexer provider explicitly sets baseUrl to https://wdk-api.tether.io. Store your API key:

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

History requires exactly one enabled Indexer provider and a non-empty key. The CLI no longer reads indexer.* or the WDK_INDEXER_API_KEY environment variable, and does not copy old settings. The client timeout defaults to 30,000 ms. Set providers.wdk-indexer.config.timeout to override it.

Use an Indexer Proxy

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

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

The client requires a non-empty key even for a proxy, and sends it in X-API-KEY. Authenticate this proxy credential and replace it with your protected upstream Indexer key before forwarding.

The proxy must accept both history request forms:

Forward the query parameters or JSON request body and the Indexer response unchanged. fromTs and toTs use Unix milliseconds. Failed items in an all-token history batch are omitted from the CLI's merged transfer list; empty or partial output does not prove every item succeeded.

WDK_INDEXER_BASE_URL is not read by beta.7.

Read Transfer History

Use an existing local wallet, unlock it with wdk wallet unlock --name NAME, and check its network and token with wdk network info and wdk token info before querying history. History reads do not require funding or send a transaction.

The network needs an indexerSlug. For get history --token, pass the string at metadata.slugs.indexer, or its slug when the mapping is an object. This provider code can differ from the token's registry key.

wdk get history --network ethereum --token usdt --wallet dev \
  --from-date 2026-01-01T00:00:00Z --to-date 2026-02-01T00:00:00Z

Replace dev with your unlocked wallet's name. The flags accept ISO 8601 dates; the CLI sends fromTs and toTs as Unix milliseconds. The MCP get_history tool uses the same provider and conversion with fromDate and toDate inputs.

Omitting --token batches the network's Indexer-supported tokens, merges successful items by timestamp, and applies --limit. Failed items are omitted, so empty or partial output does not establish that every token query succeeded. Lock the wallet when finished with wdk wallet lock --name NAME.

See history errors for provider, credential, and network failures. Provider availability is checked before the wallet-unlock requirement.

Fiat Providers

wdk buy and wdk sell select enabled fiat providers whose modules are installed. MoonPay and Transak are bundled and enabled, so pass --provider moonpay or --provider transak until only one is usable. Inspect their settings with wdk provider info --name NAME in a private terminal.

The commands require --token and exactly one of --fiat-amount and --crypto-amount. Token support comes from metadata.slugs.PROVIDER, with decimals resolved from the provider's own asset and currency listings. There is no symbol fallback for fiat mappings. See Manage Tokens.

Both commands return a URL for the user to open; they do not open a browser or complete a fiat transaction. JSON includes the selected provider. If a provider cannot quote a pair, a URL can still be returned with quoteUnavailable; receiveAmount, fee, and rate are absent without a quote. Credential rejection remains an error.

The bundled Transak 1.0.2 configuration has apiKey, environment, widgetUrl, and getOrder. Set environment to PRODUCTION or STAGING; the catalog's empty value is not a usable environment. widgetUrl is required for buy/sell and must point to your backend, which creates a session URL with Transak's Create Widget URL API using your API secret. getOrder supports the module's order lookup and is not used by CLI buy/sell.

widgetUrl and getOrder are application-owned HTTP endpoint URLs, not dashboard URLs or JavaScript functions entered as JSON. The registration's endpointKeys converts them to callbacks: object payloads are posted as JSON, while string payloads are wrapped as { "urlForSignature": "..." }. A widget response can be a URL string or an object with widgetUrl, url, or signedUrl. Keep API secrets in the backend. See the exact module's API for its payload and backend requirements.

Pricing

USD estimates use the enabled installed pricing provider, with Bitfinex bundled. Only one pricing provider can be enabled; provider add/enable rejects a second one. A token uses metadata.slugs.PROVIDER when present, otherwise its display symbol. Missing prices do not establish that an asset has no value: balance output may show 0 for unavailable USD estimates while retaining the on-chain amount.

MoonPay

With --provider moonpay, the CLI derives the selected wallet address and passes it as the buy recipient or sell refund address. It returns the provider URL to continue the flow in a browser.

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.

Configure the MoonPay provider, including your application-owned signing endpoint:

wdk config set --key providers.moonpay.config.apiKey --value pk_test_...
wdk config set --key providers.moonpay.config.signUrl --value https://example.com/moonpay/sign
wdk config set --key providers.moonpay.config.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 providers.moonpay.config.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.

If signUrl is empty, the CLI omits the callback and MoonPay beta.3 can return an unsigned widget URL. This does not establish that MoonPay will accept that URL for your integration; configure the signing service when its flow requires signing.

Select an Environment

The generic beta.7 fiat path no longer enforces the earlier CLI sandbox/mainnet mismatch check or validates the key prefix. Configure a matching environment, credential, asset mapping, and wallet network yourself. The bundled empty environment value must be replaced with the environment you intend to use.

Need Help?