# `wallet_connect` Requests to connect account(s) with optional capabilities. Set `capabilities.showDeposit` to `true` or funding hints to show an optional deposit prompt after an account connects. The deposit target is always the connected account on the active connect chain. ## Request `capabilities` is a discriminated union over `method` — `'register'` or `'login'`. Both branches share the `digest`, `authorizeAccessKey`, `auth`, `identity`, `personalSign`, and `showDeposit` fields. ```ts type Request = { method: 'wallet_connect' params?: [{ capabilities?: ConnectRegisterCapabilities | ConnectLoginCapabilities /** Chain ID to connect to (hex-encoded number on the wire). */ chainId?: number /** Caller-supplied protocol version string. */ version?: string }] } type ConnectRegisterCapabilities = { method: 'register' /** Optional digest to bind into the registration ceremony. */ digest?: `0x${string}` /** Authorize an access key during the same ceremony. */ authorizeAccessKey?: AuthorizeAccessKeyCapability /** SIWE round-trip configuration. See `Auth` below. */ auth?: Auth /** Request consented identity claims (e.g. a verified email). See `Identity` below. */ identity?: Identity /** Display name to associate with the new account. */ name?: string /** Sign an EIP-191 message in the same passkey ceremony. */ personalSign?: { message: string } /** Show an optional deposit prompt after the account connects. */ showDeposit?: ShowDeposit /** Stable user identifier passed to the WebAuthn credential. */ userId?: string } type ConnectLoginCapabilities = { method?: 'login' /** Optional digest to bind into the login ceremony. */ digest?: `0x${string}` /** Specific WebAuthn credential ID to authenticate with. */ credentialId?: string /** Authorize an access key during the same ceremony. */ authorizeAccessKey?: AuthorizeAccessKeyCapability /** SIWE round-trip configuration. See `Auth` below. */ auth?: Auth /** Request consented identity claims (e.g. a verified email). See `Identity` below. */ identity?: Identity /** Sign an EIP-191 message in the same passkey ceremony. */ personalSign?: { message: string } /** Show an optional deposit prompt after the account connects. */ showDeposit?: ShowDeposit /** Show an account picker before authenticating. */ selectAccount?: boolean } type Identity = { /** * Request the account's verified email. Returned on the connected account * as `capabilities.identity.email` (a plain string, for client-side use) * and `capabilities.identity.idToken` (a signed token, for server-side * verification). * * - `true` — request the email; the wallet auto-issues the signed token, * reusing the `auth` (SIWE) challenge nonce when present. * - `{ nonce }` — same, with an explicit nonce baked into the token (for * standalone use without the `auth` capability). */ email?: boolean | { nonce?: string } } type ShowDeposit = boolean | { /** Human-readable amount to pre-fill (e.g. `"50"`). */ amount?: string /** Display name shown in the deposit UI (e.g. the app name). */ displayName?: string /** Connect method that should show the deposit prompt. Defaults to both methods. */ on?: 'login' | 'register' /** Token contract address or supported token symbol to pre-fill. */ token?: `0x${string}` | string } type AuthorizeAccessKeyCapability = { address?: Address /** Hex on the wire, decoded to `bigint`. */ chainId?: bigint expiry: number keyType?: 'secp256k1' | 'p256' | 'webAuthn' limits?: { token: Address /** Hex on the wire, decoded to `bigint`. */ limit: bigint /** Window length in seconds. Omit for an absolute cap. */ period?: number }[] publicKey?: Hex scopes?: { address: Address selector?: Hex | string recipients?: Address[] }[] } type Auth = string | { /** * Base URL. The SDK derives `${url}/challenge` and `${url}/logout`; * `${url}` itself is the verify endpoint. */ url?: string /** Override individual endpoints. Either `url` or both `challenge` + `verify` must be set. */ challenge?: string verify?: string logout?: string /** * Ask the verify endpoint to also return `{ token }` in the JSON body. * Default `false` — cookie mode relies on `Set-Cookie` only. */ returnToken?: boolean } ``` ## Response ```ts type Response = { accounts: { address: Address capabilities: { /** * Consented identity claims, present only when requested via * `capabilities.identity` AND approved by the user. Omitted entirely * otherwise. Only set on the authenticated account. */ identity?: { /** Verified email address, if requested and approved. May be `null`. */ email?: string | null /** * Signed identity token (JWT) asserting the verified email, bound to * the requesting app origin (`aud`) and the connected account (`sub`). * Verify it server-side against the wallet's JWKS. Present only when * `identity.email` was requested and a verified email is available. */ idToken?: string } /** Authorized access key, if `authorizeAccessKey` was requested. */ keyAuthorization?: KeyAuthorization /** * Echo of the `personalSign` request, present iff the caller set * `capabilities.personalSign` (or `capabilities.auth` folded a SIWE * message into the same slot). The signature itself lives on * `capabilities.signature`. */ personalSign?: { message: string } /** Signature for `personalSign` / SIWE message, if requested. */ signature?: Hex /** Authenticated username, if available. May be `null`. */ username?: string | null /** * SIWE round-trip output, populated when the request `auth` * capability was set. `token` is present in JWT mode or when the * request set `returnToken: true`. Cookie-mode default = `{}`. */ auth?: { token?: string } } }[] } ``` ## Example ```ts import { Provider } from 'accounts' const provider = Provider.create() const { accounts } = await provider.request({ method: 'wallet_connect', }) ``` ### Requesting a verified email Set `capabilities.identity.email` to `true` to ask for the account's verified email. The wallet runs an in-flow approval after the connect ceremony: if the account already has a verified email it shows a consent prompt; otherwise it collects and verifies an email (one-time code) before sharing it. The user can decline — `wallet_connect` still succeeds, just without `identity`. ```ts const { accounts } = await provider.request({ method: 'wallet_connect', params: [{ capabilities: { identity: { email: true } } }], }) // Present only if the user approved sharing; set on the authenticated account. const email = accounts[0]?.capabilities?.identity?.email ``` The response also carries a signed `idToken` alongside the plain `email`. The plain string is convenient for client-side display, but it can be set by anyone. Forward the `idToken` to your backend and verify it against the wallet's JWKS to trust the email server-side. ```ts const identity = accounts[0]?.capabilities?.identity // `email` for display; `idToken` to prove the email to your backend. const { email, idToken } = identity ?? {} ``` The token is a standard OIDC ID token (JWT) bound to your app origin (`aud`) and the connected account address (`sub`). Verify it with any OIDC-aware library, or with [`Identity.verify`](/docs/server/identity.verify).