Abstract

This ERC introduces a new wallet connection JSON-RPC method focused on extensibility, wallet_connect. It leverages the modular capabilities approach defined in ERC-5792 to streamline connections and authentication into a single interaction.

Motivation

With applications beginning to require support for more sophisticated functionality in wallet connection flows, the need for a unified and extensible wallet connection JSON-RPC method has become more apparent.

This is especially evident in the case of attempting to batch connection with authentication, where existing methods like eth_requestAccounts and personal_sign lack extensibility and require at least two separate user interactions (ie. connect and then sign).

Specification

The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “NOT RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in RFC 2119 and RFC 8174.

JSON-RPC Methods

wallet_connect

Requests to connect account(s) with optional capabilities.

Request
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>;
  }]
}
Response

List of connected accounts with their associated capabilities.

type Response = {
  accounts: {
    // Address of the connected account.
    address: `0x${string}`;
    // Capabilities granted that is associated with this account.
    capabilities: Record<string, unknown>;
  }[]
}
Example
const response = await provider.request({
  method: 'wallet_connect',
  params: [{
    version: '1',
    capabilities: {
      signInWithEthereum: {
        nonce: '12345678',
        chainId: '0x1'
      }
    }
  }]
})
/**
 * {
 *   accounts: [
 *     {
 *       address: '0x...',
 *       capabilities: {
 *         signInWithEthereum: {
 *           message: 'app.com wants you to sign in with your Ethereum account:\n0x...',
 *           signature: '0x...'
 *         }
 *       }
 *     }
 *   ]
 * }
 */

wallet_disconnect

Disconnects connected account(s).

  • The wallet SHOULD revoke access to the user account(s) information, as well as to any capabilities associated with them that were granted upon connection via wallet_connect.
Request
type Request = {
  method: 'wallet_disconnect'
}
Example
await provider.request({
  method: 'wallet_disconnect',
})

Capabilities

signInWithEthereum

Adds support for offchain authentication using ERC-4361.

Parameters

Same as ERC-4361 specification with minor modifications:

  • The casing of multi-word fields has been adjusted to camelCase instead of kebab-case. Resources are an array field.
  • The account address returned by wallet_connect MUST match the address inferred in the Sign-In with Ethereum (SIWE) message.
  • version is optional and defaults to an accepted version defined in ERC-4361 if not provided.
  • domain is optional and defaults to the domain of the requesting app if not provided.
  • uri is optional and defaults to the uri of the requesting app if not provided.
  • issuedAt is optional and defaults to the current time if not provided.

The wallet MUST return a ERC-4361-formatted message that exactly matches the requested parameters and a signature over the EIP-191 personal_sign hash of the message. The app SHOULD also verify that the two match for security.

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[];
  }
}
Response

Formatted SIWE message and signature.

type Response = {
  signInWithEthereum: {
    // Formatted SIWE message.
    message: string;
    // Signature over the EIP-191 personal_sign hash of the message.
    signature: `0x${string}`;
  }
}

Example

const result = await provider.request({
  method: 'wallet_connect',
  params: [{
    version: '1',
    capabilities: {
      signInWithEthereum: {
        nonce: '12345678',
        chainId: '0x1',
        version: '1',
        domain: 'app.com',
        uri: 'https://app.com/connect',
        issuedAt: '2024-12-35T04:20:00Z',
        expirationTime: '2024-12-35T06:09:00Z'
      }
    }
  }]
})
/**
 * {
 *   accounts: [
 *     {
 *       address: '0x...',
 *       capabilities: {
 *         signInWithEthereum: {
 *           message: 'app.com wants you to sign in with your Ethereum account:\n0x...',
 *           signature: '0x...'
 *         }
 *       }
 *     }
 *   ]
 * }
 */

Rationale

Multiple Accounts

Returning multiple accounts allows greater generality for apps that wish to interact in more complex ways with users. This also improves our backwards compatibility with eth_requestAccounts. In practice, we expect most apps only interact with the first account in the array.

Capability Results

Returning capability results alongside the connection unlocks many valuable use cases such as authentication, user metadata sharing, and permissions granted to the app.

Initial Authentication Capability

To ensure immediate value, this proposal includes a capability that combines wallet connection with authentication using the widely adopted Sign In With Ethereum (ERC-4361) standard. This optional capability simplifies the onboarding process for apps and users by combining two steps — connection and authentication — into a single interaction. Apps that prefer alternative authentication flows can implement their own capabilities without being constrained by this design.

By unifying connection and authentication into one step, apps can reduce friction, improve the user experience, and minimize redundant interactions.

Backwards Compatibility

This standard builds on existing JSON-RPC methods and complements ERC-5792 for future extensibility. Wallets can continue supporting legacy methods.

Security Considerations

Applies ERC-4361 security principles. As more capabilities are added, care must be taken to avoid unpredictable interactions.

Wallet addresses and any shared capabilities must be handled securely to avoid data leaks or man-in-the-middle attacks.

Copyright and related rights waived via CC0.