Custom Networks

Use a custom network when WDK CLI has a compatible wallet-module package but does not include the specific chain in its built-in registry.

The module field can name a wallet-module type used by a built-in network or a custom package already registered with wdk module add. Adding a package and creating a network are separate, passphrase-protected operations.

Inspect Available Networks

List built-in and custom networks:

Terminal

wdk network list

Use JSON output to inspect the unversioned module and type package names:

Terminal

wdk --json network list

For a built-in wallet type, use a returned name such as @tetherto/wdk-wallet-evm as the module value in a custom network spec. Inspect exact built-in and custom package pins separately:

Terminal

wdk module list

Inspect the effective metadata and SDK configuration for one network:

Terminal

wdk network info --network ethereum

Network Spec

wdk network create <data> accepts either an inline JSON object or the path to a JSON file.

Field	Required	Rules and effect
`network`	Yes	Unique identifier containing lowercase letters, numbers, and hyphens. The first character must be a letter or number.
`module`	Yes	Unversioned wallet-module package used by a built-in network or already registered with `wdk module add`.
`displayName`	No	Non-empty display label. Defaults to the `network` value.
`testnet`	No	Boolean. Defaults to `false`.
`indexerSlug`	No	Non-empty WDK Indexer chain identifier. Without it, `get history` is unavailable for the custom network.
`config`	No	Object passed to the selected wallet module, such as a provider URL and chain ID. The wallet module validates these values when used.
`tokens`	No	Array of token specs to store with the network. Token keys must be unique, and at most one entry can be native.

Each item in tokens uses the fields documented in Manage Tokens, with network omitted because the parent network supplies it.

Registering a custom package makes its name eligible for a network spec; it does not prove that the package exports a compatible wallet manager. Audit and test the exact package version before using it. Methods exposed by wdk method come from the built-in catalog and are not discovered from custom packages.

Create A Custom Network

Create optimism.json:

optimism.json

{
  "network": "optimism",
  "module": "@tetherto/wdk-wallet-evm",
  "displayName": "Optimism",
  "testnet": false,
  "config": {
    "provider": "https://mainnet.optimism.io",
    "chainId": 10
  },
  "tokens": [
    {
      "token": "eth",
      "symbol": "ETH",
      "decimals": 18,
      "isNative": true
    }
  ]
}

Create the network and its native-token entry:

Terminal

wdk network create ./optimism.json

Verify the result:

Terminal

wdk network info --network optimism
wdk token list --network optimism

The example uses a public mainnet RPC endpoint. Verify the chain ID, provider, token addresses, and provider-specific limits before using a custom network with funds. Omit indexerSlug unless you know the WDK Indexer identifier for that chain.

Creation Side Effects

The CLI validates the complete network and token spec before storing it. On success, it writes:

The custom network metadata
The network's SDK config
Every entry in tokens

If storing a token fails, the command rolls back the custom network, its SDK config, and token entries already written by that command.

If at least one wallet exists, network create prompts for the current default wallet's passphrase. It does not require the wallet to be unlocked. With no wallets, it does not prompt.

network create and network delete do not unlock, extend, or lock an existing daemon wallet session. wdk config reset --all preserves custom network entries.

When the spec uses a custom module, install and register that module before creating the network. Do not remove the module while a custom network still references it; the network record remains, but wallet operations fail when the daemon cannot load the package.

Update Network Configuration

Use config set to replace the complete SDK config object:

Terminal

wdk config set \
  --network optimism \
  --value '{"provider":"https://mainnet.optimism.io","chainId":10}'

Or change one nested key:

Terminal

wdk config set \
  --network optimism \
  --key provider \
  --value https://mainnet.optimism.io

Changing networks.* configuration locks every unlocked wallet so the daemon drops cached wallet managers. Unlock the wallet again before reading balances or sending.

Delete A Custom Network

Deleting a custom network also deletes its SDK configuration and every custom token under that network. Export or record the spec first if you may need to recreate it.

Delete the network:

Terminal

wdk network delete --name optimism

Deletion prompts for the default wallet's passphrase when wallets exist. Built-in networks cannot be deleted.

Deleting registry configuration does not move blockchain assets or delete a wallet seed, but the CLI can no longer access that network until you recreate the registry entry.

Next Steps

Manage Tokens - Add token contracts and provider mappings
Manage Modules - Audit, pin, install, repair, and remove custom wallet modules
Configuration - Review paths, environment variables, and precedence
API Reference - Review all network command flags

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

Custom Networks

On this page