WalletConnect Sessions: What You Approve, and for How Long

A connection, not a login

WalletConnect does not hand a dapp your keys, and it does not log you in to anything. It establishes a session: a channel over which an application can send requests to a wallet, and the wallet can answer them. The session is the thing that carries permission, and it is worth reading as a document rather than treating the connection prompt as a one-off.

The protocol separates two steps that the first version combined. A pairing is the initial link between the two clients, created from a QR code or deep link, and used to exchange the messages that set up a session. The session is negotiated on top of that pairing. The WalletConnect specification describes the flow: the dapp sends a session proposal on the pairing with its public key, relay and metadata; the wallet generates its own key pair and settles a session using a symmetric key derived from the two; the session topic is derived from the SHA-256 hash of that symmetric key.

The stored session is not a single flag. It holds both parties’ metadata, the relay, an expiry timestamp, a controller, and the namespaces — the permissions themselves. Because the pairing and the session are decoupled, a wallet can hold sessions with several applications at once, and one application can keep a session alive long after the page you connected from has closed.

What the dapp asks for

A session proposal contains two maps. requiredNamespaces lists what the wallet must satisfy for the session to exist at all. optionalNamespaces lists what the wallet may grant, in whole, in part or not at all. If the required namespaces are invalid, the specification assigns error code 1006, and no session is established.

In the specification’s own example, the required eip155 namespace asks for five methods — eth_sendTransaction, eth_signTransaction, eth_sign, personal_sign and eth_signTypedData — on chains eip155:1 and eip155:10, plus the chainChanged and accountsChanged events. The same proposal can carry a solana or polkadot namespace with their own method names.

That list is the part most people never see. A wallet that renders “Connect to Example App” and nothing else has received a request for transaction sending and message signing on two networks. Whether the wallet shows the list before approval is a product decision, not a protocol requirement.

What the namespace actually grants

The approved namespace is not identical to the proposal. The specification describes the session namespace as carrying accounts, each one a chain identifier plus an address, and requires the wallet to grant all methods and events of every required namespace. It may add more than was requested, but never less. The table below reads the fields in the order they matter.

Two consequences follow. First, the permission is account-specific: a session that returns one address does not expose the others, and the wallet decides how many to return. Second, the permission is method-specific: granting personal_sign is not the same as granting eth_sendTransaction, and the specification’s example asks for both. The chain identifiers follow CAIP-2, the namespace-and-reference format that makes eip155:1 unambiguous across implementations.

CAIP-25 standardizes the same negotiation outside WalletConnect’s own message format. It describes a session proposed by a caller and accepted by a respondent, with authorization expressed as scopes keyed by CAIP-2 (or CAIP-104) identifiers. Its lifecycle methods are worth knowing by name because they describe what any session system must be able to do: wallet_getSession to inspect, wallet_revokeSession to end, and wallet_sessionChanged to notify the caller when the wallet changes something.

Expiry: the “for how long” part

Every session carries an expiry field, an integer timestamp in seconds. It is set when the session is agreed, and the session record names a controller — the party the specification assumes is the wallet that approved the proposal — which can update the session’s accounts, methods, events and expiry. The client interface exposes that as extendSession.

The lifecycle is visible in the event names: session_expire when a session has expired, session_extend when it is extended, session_delete when it is disconnected, and proposal_expire when an unanswered proposal lapses. Once a session has expired, requests cannot be sent on it; the application has to propose a new one.

What the specification does not do is fix a single duration. The timestamp is data in the session record, and the value you see is set by the wallet or SDK implementing it. That matters for the question in the title: “for how long” is answered by the session list in your wallet, not by a protocol constant. It also means a session can outlive the site’s front end. The application disappearing does not delete the permission; only expiry or an explicit disconnect does.

Disconnecting is local, and it is not revocation

In MetaMask, the connected-site list is under the top-right menu, then Permissions. It shows every dapp the wallet is connected to and how many accounts each one can reach. Selecting a dapp and choosing Disconnect ends that connection; Disconnect all clears the list. Other wallets expose the same idea under names such as connected apps or sessions.

MetaMask’s help center is explicit about the limit: disconnecting stops the dapp from viewing your public address, wallet contents and transaction history, and from initiating transactions, but it “will not revoke any token approvals that you have in place with that dapp.” An allowance is stored in the token contract and can be spent by the spender whether or not a session exists. Ending the session and revoking the allowance are two different jobs, done in two different places, and only one of them costs gas. The review-and-revoke procedure is covered in token allowances.

The asymmetry is the useful part. A session ends with a tap and no network fee, because it is local state shared by two clients. An allowance ends with a transaction, because it is state that every node agrees on.

Every request still asks

A session is permission to ask, not permission to move. When the dapp sends eth_sendTransaction or personal_sign, the wallet still presents the request and the user still approves it. The session determines which requests are allowed to arrive, not which ones execute silently.

That distinction is easy to lose when a session includes eth_sign. Approving that method at connection time means the dapp may later ask the wallet to sign raw bytes. The signature still requires a click, but the bytes may be unreadable, and a signature over unreadable bytes can authorize more than the prompt suggests. What a wallet can decode, and what it cannot, is the subject of clear signing versus blind signing.

The session record also carries a Verify Context on proposals and requests: a verified object with an origin and a validation value such as UNKNOWN or VALID, constructed by the client. It is a signal about the requesting domain, not a guarantee about the contract behind the request, and it should be read the way you read a padlock: useful, insufficient.

A review routine

The session list is the only place where the accumulated permissions are visible, so it is worth a periodic pass.

1. List the sessions. Open the wallet’s permissions or connected-apps screen and read the names, not just the count.
2. Check the account count. A site that can reach four accounts has four times the exposure of one that can reach a single account you use for testing.
3. Check the chains. A session for a network you never use is a session you do not need.
4. Check the expiry. If the wallet shows it, note the date; if it does not, treat the session as indefinite and disconnect it when the work is done.
5. Disconnect what you no longer use, then revoke allowances separately. The first is free and immediate; the second is an on-chain action and should be done deliberately.

None of this requires trusting the dapp. It requires reading the record the wallet already holds, and remembering that the connection prompt approved a set of methods and accounts, not a single visit.