ERC-7846 Wallet connection and authentication API (Wallet Connection API)
Draft · Accounts & wallets · created 2024-12-15
A wallet connection standard that lets an app request both account connection and signature-based login (Sign In With Ethereum) from a wallet in a single JSON-RPC call.
Why it is needed
Until now, for an app to connect to a wallet it had to get accounts via eth_requestAccounts, and if login was needed, request a signature separately via personal_sign. These two methods are not extensible, so there has been no standardized way to fold authentication or other add-on functionality into the connection process, and users have had to check the wallet window at least twice, once for connection and once for signing. As apps increasingly demand more complex connection flows (authentication, permissions, metadata sharing, etc.), this fragmented approach degrades the user experience and leads to inconsistent implementations across apps. There is also no standard for the disconnection process, so wallets and apps handle it differently.
What to implement
type Request = { method: 'wallet_connect', params: [{ // JSON-RPC method version. version: string; // Optional capabilities to request (e.g. Sign In With Ethereum). capabilities?: Record<string, unknown>; }] }: The request format an app sends when calling wallet_connect, containing the version and the capabilities being requested.type Response = { accounts: { // Address of the connected account. address: `0x${string}`; // Capabilities granted that is associated with this account. capabilities: Record<string, unknown>; }[] }: The wallet_connect response, returning an array of the connected account addresses along with the capabilities results granted to each account.type Request = { method: 'wallet_disconnect' }: The wallet_disconnect call format, used to request that a wallet release the connected accounts and the capabilities granted to them.type Parameters = { signInWithEthereum: { nonce: string; chainId: string; // EIP-155 hex-encoded version?: string; scheme?: string; domain?: string; uri?: string; statement?: string; issuedAt?: string; expirationTime?: string; notBefore?: string; requestId?: string; resources?: string[]; } }: A parameter placed inside wallet_connect's capabilities to request an ERC-4361-formatted login signature.type Response = { signInWithEthereum: { // Formatted SIWE message. message: string; // Signature over the EIP-191 personal_sign hash of the message. signature: `0x${string}`; } }: The response for the signInWithEthereum capability, returning the completed SIWE message along with the signature over that message.
In depth
Default behavior of wallet_connect
wallet_connect is a method that requests accounts together with optional capabilities. The request can include a version string indicating the JSON-RPC method version, and optionally an ERC-5792-style modular capabilities object. The response is an accounts array containing the address of each connected account and the capabilities results granted to that account. Multiple accounts can be returned, but in practice most apps are expected to use only the first account in the array.
Behavior of wallet_disconnect
wallet_disconnect is a method called with no parameters, which causes the wallet to revoke access to the connected account information and the capabilities that were granted via wallet_connect. The spec defines this as a SHOULD.
signInWithEthereum capability
signInWithEthereum is a capability that adds off-chain authentication using ERC-4361 (SIWE) to wallet_connect. The parameters are nearly identical to ERC-4361, except multi-word fields use camelCase instead of kebab-case, and resources is an array field. nonce and chainId (hex per EIP-155) are required, while version, scheme, domain, uri, statement, issuedAt, expirationTime, notBefore, requestId, and resources are optional.
Defaults for optional parameters and the address match requirement
If version is not specified, one of the versions permitted by ERC-4361 is used as the default; if domain and uri are not specified, the requesting app's domain and uri are used as defaults; and if issuedAt is not specified, the current time is used. Additionally, the account address returned by wallet_connect MUST match the address included in the SIWE message.
Message and signature verification requirements
The wallet MUST return a message in ERC-4361 format that exactly matches the requested parameters, and MUST also return a signature over the EIP-191 personal_sign hash of that message. On the app side, it is RECOMMENDED (SHOULD) to verify that the received message and signature match each other.
Intent behind returning multiple accounts and capabilities
Returning multiple accounts was designed to give generality to apps that want more complex interactions and to improve backward compatibility with the existing eth_requestAccounts. Returning capabilities results alongside the connection was designed to open up various use cases such as authentication, sharing of user metadata, and permissions granted to the app.
Backward compatibility and extensibility
This standard builds on top of existing JSON-RPC methods and complements future extensions together with ERC-5792. Wallets can continue to support legacy methods such as eth_requestAccounts.
Current status
ERC-7846 is a proposal created on 2024-12-15 that is currently in Draft status, has not yet been finalized, and its details may change or discussion may stall.
Things to watch out for
- Applying ERC-4361 security principles: The signInWithEthereum capability follows the security considerations of ERC-4361 as is.
- Unpredictable interactions from adding capabilities: As more capabilities are added, care must be taken to avoid unpredictable interactions arising between capabilities.
- Secure handling of address and capability data: Wallet addresses and shared capabilities data must be handled securely to prevent data leakage or man-in-the-middle attacks.