Connect external wallets

Let users connect an existing EVM wallet alongside your application’s embedded wallet. The SDK’s connection dialog offers both options: users can continue with their passkey account or connect an external wallet such as MetaMask. Connecting an external wallet uses that wallet’s address. It does not create a passkey account, move assets, or make the external wallet an owner of an existing embedded account.

Before you start

Follow Accounts to register your application and initialize the shared oneAuth client. The example below uses @rhinestone/1auth version 0.10.2.

Open the connection dialog

Create one provider around your existing client and reuse it throughout your application:

provider.ts

import { createOneAuthProvider } from "@rhinestone/1auth"
import { oneAuth } from "./oneauth"

export const provider = createOneAuthProvider({
  client: oneAuth,
  chainId: 8453,
})

Call wallet_connect from your application’s connect button:

connect.ts

import { provider } from "./provider"

export async function connectWallet() {
  const accounts = await provider.request({
    method: "wallet_connect",
  })

  if (!Array.isArray(accounts) || typeof accounts[0] !== "string") {
    throw new Error("The wallet did not return an account")
  }

  return accounts[0]
}

The returned address belongs to the account the user selected. Display it as the active wallet in your application. Handle rejected requests in your button handler so cancellation or connection failures do not leave the interface in a loading state.

Connect MetaMask

Open the connection dialog from your application.
Choose Continue with wallet, then select MetaMask from the available wallets.
Approve the connection in MetaMask.
Use the returned address as the active account.

The user can instead follow the email or social sign-in flow to create or access their passkey-controlled embedded wallet. Choosing an external wallet does not require creating a passkey.

wallet_connect is the provider method that opens the chooser. It is not the WalletConnect protocol.

Choose when to offer external wallets

Use the provider method that matches the action in your interface:

Method	Use it to
`wallet_connect`	Open the embedded-or-external wallet chooser, including when an account is already connected.
`eth_requestAccounts`	Request the embedded account through the normal passkey flow, without offering the external-wallet chooser. An already-bound external connection can return its selected account.
`eth_accounts`	Read the currently connected account without opening a dialog.

Keep using the same provider after connection. It routes signing and transaction requests to the selected wallet; do not call the embedded client’s transaction methods to transact from an external address.

Use your own connection UI

If your application already has a wallet picker, use createOneAuthConnection instead of opening the SDK’s chooser. Supply two callbacks:

selectConnection: return "passkey" or "external_wallet" for the user’s choice.
connectExternalWallet: connect through your wallet integration and return its EIP-1193 provider, selected address, and numeric chain ID.

The helper returns a session containing accountAddress, provider, and signerType. Use the returned provider for subsequent wallet requests. The helper does not discover wallets or build a picker for you, and does not try the other connection method if the selected one fails.

External and embedded accounts stay separate

External-wallet requests use the selected wallet’s signing and transaction flow, rather than the embedded wallet’s managed intent path. Connecting does not automatically enable embedded-wallet sponsorship, session keys, recovery, or multichain execution for the external account. A wallet connection also does not, by itself, establish an authenticated backend session for your application.

Next steps

Use and manage connected wallets for signing, transactions, account changes, and disconnection.
Ecosystem for provider, viem, and wagmi integration.

Getting started

Authentication

External wallets

Signing

Integration

Security

Connect external wallets

Before you start

Open the connection dialog

Connect MetaMask

Choose when to offer external wallets

Use your own connection UI

External and embedded accounts stay separate

Next steps

​Before you start

​Open the connection dialog

​Connect MetaMask

​Choose when to offer external wallets

​Use your own connection UI

​External and embedded accounts stay separate

​Next steps

Before you start

Open the connection dialog

Connect MetaMask

Choose when to offer external wallets

Use your own connection UI

External and embedded accounts stay separate

Next steps