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.1 environment-variable mappings for indexer.baseUrl, wallet defaults, account defaults, network configuration, or MoonPay configuration.

Supported Keys

Custom-network records and custom-token records also live in config.json. Manage them with wdk network and wdk token so the CLI can validate their shape and 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.1.

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, and custom tokens. It resets the remaining values to their installed defaults.

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

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

Changing or resetting a key under networks locks all wallets so the next unlock initializes WDK with the new wallet-module configuration. config reset --all also locks all wallets.

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

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?