Accounts

Each user has one application wallet with an EVM account and, optionally, a managed Solana account. Accounts are isolated from those the same person creates in other applications. See Networks for the shared model and differences.

Before you start

Use Node.js and a browser application served over HTTPS. The hosted provider does not accept plain http://localhost; use local HTTPS for development.
Register your application and domains in the Dashboard.
Configure sponsorship token endpoints before calling intent or asset methods. Authentication itself does not require a funded account.

Install the SDK

Upgrading an existing integration? Follow Migration for the changes between versions.

npm install @rhinestone/wallet

pnpm add @rhinestone/wallet

yarn add @rhinestone/wallet

Initialize the client

Create wallet.ts and reuse its client throughout your application. The Solana variant opts into the experimental account alongside EVM; it does not disable EVM or deploy either account. Replace my-app with the client ID of your registered application. The sponsorship URLs are same-origin backend endpoints; follow Sponsorship setup to implement them.

Authenticate and obtain an account

import { wallet } from "./wallet";

const auth = await wallet.authenticate();

if (!auth.success) {
  throw new Error(auth.error.message);
}

const accountAddress = auth.session.accounts.evm.address;
console.log(accountAddress);

accountAddress is a typed 0x${string} address. Pass it as accountAddress to methods such as signMessage() and getAssets(); sendIntent() and sendBatchIntent() always use the authenticated account. Authentication creates an account when the verified identity has none in your application’s namespace, or signs in to the existing account. To restore a current wallet session without opening the dialog, call getSession():

import { wallet } from "./wallet";

const session = await wallet.getSession();
const accountAddress = session.success
  ? session.session.accounts.evm.address
  : undefined;

Read Solana account state

With experimental_solana, the first passkey login provisions one persistent Solana identity. The provisioning login’s passkey becomes its original authority; later logins reuse the same wallet. Passkey sessions report optional accounts.solana:

Status	Meaning
`unavailable`	The service could not report the account; this does not mean no wallet exists.
`not_provisioned`	A passkey sign-in with the opt-in is needed to provision the identity.
`provisioned`	The address is known; check `clusters[chain].ready` separately.

A restored session may need a fresh passkey login for Solana spending (SOLANA_SIGN_IN_REQUIRED). There is no caller-selected root or alternate-key fallback. See Sign up and sign in.

Deploy accounts

EVM

The first real execution on an EVM chain deploys the account if needed. Your app does not submit a separate factory call. Receiving at the counterfactual address does not deploy it; preserve the account’s exact configuration. See Account deployment.

Set up a Solana wallet

Solana needs explicit setup before receiving. deploy() creates and verifies the wallet, enrolls service recovery and confirms the other active passkeys. Your app sponsors transaction fees and rent through its sponsorship configuration; refusal never falls back to charging the user.

import { solanaDevnet } from "@rhinestone/wallet";
import { wallet } from "./wallet";

export async function setupSolanaWallet() {
  const auth = await wallet.authenticate();
  if (!auth.success) throw new Error(auth.error.message);

  const setup = await wallet.deploy({ chain: solanaDevnet });
  if (setup.status !== "ready" && setup.status !== "already_ready") {
    return { setup, receiveAddress: undefined };
  }

  const current = await wallet.getSession();
  const solana = current.success ? current.session.accounts.solana : undefined;
  const receiveAddress = solana?.status === "provisioned"
    && solana.clusters[solanaDevnet]?.ready
    ? solana.address
    : undefined;

  return { setup, receiveAddress };
}

Only expose a receive address or QR code when the selected cluster currently reports ready: true. Re-read getSession() before showing it: an address, a balance or a previous readiness result is not enough.

Deployment result	Next action
`ready`, `already_ready`	Re-read readiness, then offer receiving on that cluster.
`incomplete`	Keep progress; call `deploy()` again to resume missing steps.
`pending`	Wait for `retryAfterSeconds` when provided; a submitted step or another run may still be settling.
`refused`	Resolve `error.code` before retrying; do not fund the address.

Setup can require several passkey approvals and is not atomic across creation and enrollment. It resumes on the same wallet; EVM remains usable while Solana setup is incomplete. Review availability, then follow funding and execution.

Account isolation

Passkeys are created and used on your application’s domain. By default, each hostname has its own passkey and account namespace, even when the user verifies the same email or OAuth identity. Funding and recovery configuration remain isolated to that namespace. See Passkeys and domains before sharing accounts across subdomains or changing your production hostname. Changing the RP ID selects a different account; existing balances do not move automatically.

Account management

Build account management in your application. The SDK provides no account-management dialog, redirect signing, or inline-embed signing.

Try an account

Create or use a passkey for this docs hostname, then check the session or send a test transaction. The test intent mints 0.1 mUSD on Base Sepolia with sponsored fees. It uses clear signing: review the prepared action before approving the passkey prompt.

Getting started

Authentication

External wallets

Signing

Integration

Security

Before you start

Install the SDK

Initialize the client

Authenticate and obtain an account

Read Solana account state

Deploy accounts

EVM

Set up a Solana wallet

Account isolation

Account management

Try an account

​Before you start

​Install the SDK

​Initialize the client

​Authenticate and obtain an account

​Read Solana account state

​Deploy accounts

​EVM

​Set up a Solana wallet

​Account isolation

​Account management

​Try an account

Before you start

Install the SDK

Initialize the client

Authenticate and obtain an account

Read Solana account state

Deploy accounts

EVM

Set up a Solana wallet

Account isolation

Account management

Try an account