wallet_addNetwork

Add a custom to the user's Xverse wallet

The wallet_addNetwork method prompts the user to add a custom network to their Xverse Wallet.

This method allows dApps to onboard users to a custom network (typically for Regtest or staging environments) without requiring manual wallet setup.

The app must have first connected to the wallet and obtained account read permissions.

You can fetch the networks that the user's wallet is currently connected to, using wallet_getNetwork.

Parameters

Request parameters	Description
name	a string representing the user-visible network label (e.g. "my-custom-regtest")
chain	Currently only "bitcoin" is supported, to add custom Regtest networks
rpcUrl	a string representing the main RPC JSON-RPC endpoint for the added network
rpcFallbackUrl ℹ️ Optional	a string representing the fallback RPC URL if primary fails
indexerUrl ℹ️ Optional	a string representing the Indexer API used for advanced indexing of the balances and transaction history on the added network
blockExplorerUrl ℹ️ Optional	a string representing the transaction explorer base URL for the added network

import Wallet from 'sats-connect';

async function example() {
  const res = await Wallet.request('wallet_addNetwork', {
   name: 'my-custom-regtest',
   chain: 'bitcoin',
   rpc_url: 'https://custom-regtest.tech/api/proxy',
   indexer_api: 'https://indexer.my-custom-regtest.app',
   block_explorer_url: 'https://mempool-my-custom-regtest.space',
   rpc_fallback_url: 'https://fallback.custom-regtest.tech/api/proxy' // optional
  });
  if (res.status === 'error') {
    console.error(res.error);
    return;
  }

  console.log(res.result);
}

✅ addNetwork Result

The method will

• prompt the user to add the custom network to their Xverse wallet

• return null if the user accepts the prompt and adds the network -> Null response

The addition of the network to the wallet will emit a networkAdded event which your app can catch.

Your app can then

• prompt the user to switch their Xverse wallet to the newly added network with the wallet_changeNetwork

• fetch the user's active Xverse account under the new network with the wallet_getAccount method.