Use and manage connected wallets

Use the provider from Connect external wallets for subsequent wallet requests. It routes requests to the account the user selected. The examples below assume the user selected an external wallet.

Read the active account

Read the selected address without opening a connection dialog. Disable signing and transaction actions when no account is connected.

wallet.ts

import { isAddress } from "viem";
import { provider } from "./provider";

export async function getConnectedAddress() {
  const accounts = await provider.request({ method: "eth_accounts" });
  const address = Array.isArray(accounts) ? accounts[0] : undefined;

  if (typeof address !== "string" || !isAddress(address)) {
    throw new Error("Connect a wallet first");
  }

  return address;
}

Read the address again before each action instead of reusing an address captured before a wallet switch. A locally remembered address does not prove that the external wallet is still connected or unlocked.

Sign a message

Call personal_sign with a hex-encoded message and the selected address:

import { stringToHex } from "viem";
import { provider } from "./provider";
import { getConnectedAddress } from "./wallet";

const signature = await provider.request({
  method: "personal_sign",
  params: [
    stringToHex("Confirm this message with your wallet."),
    await getConnectedAddress(),
  ],
});

The external wallet displays its signing prompt. For structured data, use eth_signTypedData_v4 or viem’s signTypedData action through the same provider.

Send a transaction

Switch to the intended chain before submitting. This example sends ETH on Base; the external account needs enough ETH for both the transfer and gas.

import { parseEther, toHex, type Address } from "viem";
import { base } from "viem/chains";
import { provider } from "./provider";
import { getConnectedAddress } from "./wallet";

export async function sendEth(recipient: Address, amount: string) {
  await provider.request({
    method: "wallet_switchEthereumChain",
    params: [{ chainId: toHex(base.id) }],
  });

  return provider.request({
    method: "eth_sendTransaction",
    params: [
      {
        from: await getConnectedAddress(),
        to: recipient,
        value: toHex(parseEther(amount)),
        chainId: toHex(base.id),
      },
    ],
  });
}

The user approves the transaction in their external wallet. For this external-wallet flow, the result is a transaction hash. Wait for its receipt on the submission chain and check the receipt status before showing success. With viem, use a public client’s waitForTransactionReceipt action.

Batch transactions

For external accounts, the wallet provider implements wallet_sendCalls as sequential transactions, not an atomic batch. Users may see multiple approval prompts, and earlier transactions can succeed even if a later one fails. A batch must target one chain; calls with different chainIds are rejected before anything is sent. wallet_getCallsStatus returns the batch’s transaction receipts and stays 100 (pending) until every transaction is mined and the wallet is on the batch’s chain. It then reports 200 when all succeeded, 500 when all reverted, or 600 when some reverted.

Switch wallets and reconnect

Call wallet_connect again from your wallet-switching UI:

await provider.request({ method: "wallet_connect" });

The chooser lets users select an external wallet or return to their embedded account. Refresh the displayed account after the request succeeds and discard any unsigned transaction prepared for the previous account. After a reload, eth_accounts can report a remembered address, but it does not verify that the external connection is usable. Offer an explicit reconnect action when needed. If you use createWalletConnection with your own picker, call connection.connect() instead. Host-provided external wallet connections are memory-only; your wallet integration must reconnect them after a reload.

Disconnect

await provider.disconnect();

This clears the provider’s active account and local connection state. It does not revoke token approvals, undo transactions, or guarantee removal of the site’s permissions in the external wallet. Users manage those permissions in their wallet. For a custom connection created with createWalletConnection, use connection.disconnect() and clear any additional connection state owned by your wallet integration.

Next steps

See Ecosystem to use the connected provider with viem or wagmi.

Getting started

Authentication

External wallets

Signing

Integration

Security

Use and manage connected wallets

Read the active account

Sign a message

Send a transaction

Batch transactions

Switch wallets and reconnect

Disconnect

Next steps

​Read the active account

​Sign a message

​Send a transaction

​Batch transactions

​Switch wallets and reconnect

​Disconnect

​Next steps

Read the active account

Sign a message

Send a transaction

Batch transactions

Switch wallets and reconnect

Disconnect

Next steps