Migrate Indexer Providers

Use this guide when upgrading to a CLI build with the wdk-indexer provider. It covers the Indexer configuration change, history requests, provider configuration, and local file permissions.

Check The Installed Provider

Run:

wdk --version
wdk provider list

The provider-based CLI includes wdk-indexer, with kind indexer and module @tetherto/wdk-indexer-http. If it is absent, check the installed release and module status before changing credentials. A disabled backing module hides its providers from the list.

Inspect the effective configuration:

wdk provider info --name wdk-indexer

History requires exactly one enabled Indexer provider. If the backing module is disabled, enable only that module:

wdk module enable --name @tetherto/wdk-indexer-http

Inspect wdk provider list again. If wdk-indexer is still disabled, enable it:

wdk provider enable --name wdk-indexer

Do not run an enable command for an already-enabled entry; the CLI rejects it.

wdk provider add does not accept kind: "indexer"; use the bundled registration. Provider mutations verify the default wallet's passphrase when a wallet exists and lock running wallet sessions.

Move The History Settings

Request an Indexer API key before using the production endpoint.

Stored indexer.* values are not copied into the provider configuration. WDK_INDEXER_API_KEY and WDK_INDEXER_BASE_URL are not read by the provider-based CLI.

Set the provider key:

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

The bundled provider defaults to https://wdk-api.tether.io. Change the endpoint only when needed:

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

The HTTP client defaults to a 30,000 ms request timeout; the previous CLI transport used 20,000 ms. Override it in milliseconds:

wdk config set --key providers.wdk-indexer.config.timeout --value 45000

General configuration is shallow-merged: the provider's bundled config, then providers.wdk-indexer.config. Set individual keys to retain other overrides. Setting the whole config object replaces your earlier override object; omitted keys fall back to bundled defaults. Indexer history uses these general settings, so providers.wdk-indexer.networks.NETWORK does not override its requests.

Changes under providers lock running wallet sessions. Unlock again before requesting history. Keep any old configuration you need for rollback private; an older beta.6 installation still needs its standalone settings.

Read Transfer History

Use an existing local wallet named dev, or create one with Manage Wallets. History lookup does not send a transaction or require funding the wallet.

Inspect the network and token registration, then unlock the wallet:

wdk network info --network ethereum
wdk token info --network ethereum --token usdt
wdk wallet unlock --name dev

The network needs an indexerSlug. The token needs an Indexer mapping under metadata.slugs.indexer. Pass the string mapping itself, or an object mapping's slug, to get history --token; that code can differ from the token's registry key. New token registrations must use metadata.slugs. Existing custom entries with metadata.indexerSlug are normalized when loaded; an explicit metadata.slugs.indexer value takes precedence.

Query USD₮ transfers on Ethereum:

wdk get history --network ethereum --token usdt --wallet dev --limit 10

Apply ISO 8601 date filters:

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

The flags are unchanged. The CLI now sends fromTs and toTs as Unix milliseconds, matching the HTTP client's contract. The MCP get_history tool uses the same provider and date conversion, with fromDate and toDate inputs.

Omitting --token sends a batch request for the network's Indexer-supported tokens. Successful items are merged by timestamp and limited to --limit; failed batch items are omitted. An empty or partial result does not establish that every token lookup succeeded.

Lock the wallet when finished:

wdk wallet lock --name dev

Use An Authenticated Proxy

The client requires a non-empty API key before sending a history request, even when baseUrl points to a proxy. The earlier empty-key proxy recipe cannot be used with this client.

Configure an endpoint you control and a credential that your proxy authenticates:

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 sends that credential in X-API-KEY. Your proxy must authenticate it and replace it with the protected Indexer key before forwarding upstream. Keep the upstream key on the proxy.

Support both request forms:

Forward query parameters or the JSON body and return the Indexer response shape. Preserve millisecond date filters. CLI configuration accepts JSON values; it cannot supply the HTTP client's JavaScript fetch callback.

Review Provider And Storage Changes

Packaged per-network provider defaults move from the catalog's networks.NETWORK.providers.NAME fields into each provider entry's networks.NETWORK object. User overrides remain under providers.NAME.networks.NETWORK; wallet-module settings under networks.NETWORK remain separate. For a network-specific provider, later layers win in this order:

1. The provider entry's general config.
2. Your providers.NAME.config overrides.
3. The provider entry's networks.NETWORK defaults.
4. Your providers.NAME.networks.NETWORK overrides.

Use wdk provider info --name NAME to inspect the result. A provider can omit a backing module; such a direct-service entry is not a wallet-module installation. Provider listings include service kinds as well as routing kinds. Indexer resolution requires one enabled provider; pricing retains its separate one-enabled-feed requirement.

Deleting a custom provider now clears its stored general and per-network overrides as well as its registration and enable/disable override. Registering another provider under the same name no longer inherits those settings. The module package remains installed, and built-in providers cannot be deleted.

wdk module list includes Indexer packages. Its text table abbreviates Git specifications as git# followed by seven commit characters; JSON retains the full specification. For colon or Git specifications, status ok establishes that the package is installed, not that its content was verified against the requested commit.

On macOS and Linux, configuration writes request mode 0600, and initialization attempts to restrict the config directory to 0700. Directory restriction is best effort; verify existing file and directory permissions after upgrading. Windows uses platform access controls. These restrictions do not encrypt config.json or prevent another process running as your OS user from reading it.

Resolve History Errors

Indexer-provider availability is checked before the wallet-unlock requirement. Correct provider errors first, then unlock the wallet if needed. Inspect structured errors when using --json.

Next Steps

• Configuration - Review configuration for the published beta.6 release
• Indexer JavaScript SDK - Use the HTTP client directly in an application
• Use the MCP Server - Connect history lookup to an MCP-compatible client

Need Help?