Walletconnect
Walletconnect sessions
An approved WalletConnect v2 session connects a wallet with an app until disconnection or expiry. Its scope identifies the accounts, chains, methods, and events approved for that connection. The Web3Wallet guide documents a seven-day default for approved sessions, with support for extending an active session. Check the session's current recorded expiry for its deadline.
Updated on
Session expiry and proposal timeouts
A proposal waiting for approval has a different expiry from an established session. The Web3Wallet usage guide documents a default five-minute expiry for a proposal awaiting a response. That figure describes the proposal timeout, not the duration of an approved connection.
The same guide explains that a missing proposal record can result from expiry or from the proposal having already been approved or rejected. A developer encountering that error should also check the proposal ID before attempting another response.
Pairing and session approval
A QR code or supported deep link conveys the URI used for pairing. WalletConnect v2 separates pairing from sessions: the app proposes a session over the pairing, and the wallet can approve or reject it. A successful scan alone does not confirm the app has an approved session.
The approved session provides the permission scope for subsequent requests. Pairing supplies the communication relationship through which the app can propose that session.
Read the permissions for this connection
The app expresses its requested permissions through required and optional namespaces. Every required namespace must be satisfied for successful approval, including at least one account for each required chain. The wallet may satisfy all, some, or none of the optional namespaces. An active connection therefore need not include every chain the app offered as optional.
Session account entries include a chain identifier alongside the address. An account's inclusion on one approved chain does not by itself authorize requests on another chain.
Methods identify wallet operations. In EVM sessions,
personal_sign
requests a message signature, while
eth_sendTransaction
requests a transaction. Permission to request an operation does not establish that the wallet has signed or executed it. Events such as
accountsChanged
and
chainChanged
communicate relevant changes to the app.
Session namespaces can be updated. Apps need to read the updated scope when handling
session_update
, rather than assume the original account and chain list remains unchanged.
Disconnecting and checking the connection state
Use the wallet's session management controls to end a connection you no longer need. The screen, button names, and gestures vary with the wallet and version.
A browser's connected label can lag behind the wallet's session state. In Sign API integrations, handling
session_delete
lets the app reset its displayed connection state. WalletKit exposes
getActiveSessions()
so an integration can inspect the client's active connections. A session's topic associates requests with the relevant connection.
An active-session record establishes the state of that wallet-app connection. It does not establish whether an earlier blockchain transaction succeeded; that requires a separate check of the transaction's status.
Before you retry or disconnect
- If a proposal has expired, obtain a fresh proposal before attempting approval.
- If a required chain or method is unsupported, resolve the compatibility mismatch before approving the session.
- If the app and wallet disagree about the connection, check the wallet's active-session list before retrying.
- If you have finished using the app, disconnect its session.