{"id":"ERC-1328","name":"WalletConnect URI Format","status":"Final","chain":"both","category":{"id":"onboarding","name":"Onboarding & Access","description":"Getting users into web3 without friction"},"journeyStages":[{"id":"discovery","name":"Discovery & Connection","description":"Finding and connecting wallet to dApp"}],"uxImpact":"ERC-1328 defines how WalletConnect connection data is encoded in a wc: URI that can be shown as a QR code or link. The URI carries versioned connection parameters such as keys, relay data, methods, and optional expiry. A compatible app and wallet still need to support the selected protocol version, transport, session flow, and fallback behavior.","officialUrl":"https://ercs.ethereum.org/ERCS/erc-1328","lastReviewed":"2026-09-18","lastUpdated":"2026-09-18","kind":"proposal","hasDetailedContent":true,"content":{"id":"ERC-1328","specConstraints":[{"id":"erc-1328-versioned-parameters","constraint":"The required WalletConnect URI parameters depend on the protocol version.","appliesTo":"application","normativity":"normative","specQuote":"Required parameters are dependent on the WalletConnect protocol version:","specSection":"Specification — Semantics","specUrl":"https://ercs.ethereum.org/ERCS/erc-1328#semantics","designImplication":"Parse the version before displaying pairing details or enabling approval. Explain missing parameters as an unsupported version or transport rather than as a generic malformed connection."},{"id":"erc-1328-versioned-uri","constraint":"WalletConnect URI syntax must include a protocol version so clients can evolve while preserving compatibility handling.","appliesTo":"application","normativity":"backwards-compatibility","specQuote":"Versioning is required as part of the syntax for this URI specification to allow the WalletConnect protocol to evolve and allow backwards-compatibility whenever a new version is introduced.","specSection":"Backwards Compatibility","specUrl":"https://ercs.ethereum.org/ERCS/erc-1328#backwards-compatibility","designImplication":"Parse and display the URI version, route it to a compatible transport, and preserve a copy/manual fallback when the selected wallet cannot handle that version."},{"id":"erc-1328-uri-sensitive-data-boundary","constraint":"The URI must not carry sensitive data that could compromise communication or control private keys.","appliesTo":"wallet","normativity":"security-considerations","specQuote":"URIs should be shared between user devices or applications and no sensitive data is shared within the URI that could compromise the communication or would allow control of the user's private keys.","specSection":"Security Considerations","specUrl":"https://ercs.ethereum.org/ERCS/erc-1328#security-considerations","designImplication":"Treat the displayed URI as connection material, not a secret-key container. Give users a deliberate share/copy step and avoid adding private keys or equivalent authorization material to QR or deep-link payloads."},{"id":"expiry-timestamp","constraint":"The optional expiryTimestamp parameter records the pairing expiry as Unix epoch seconds.","appliesTo":"application","normativity":"normative","specQuote":"`expiryTimestamp` - (optional) unix epoch in seconds when pairing expires","specSection":"Specification — Semantics","specUrl":"https://ercs.ethereum.org/ERCS/erc-1328#semantics","designImplication":"Show pairing expiry when the URI supplies it, distinguish expired pairing material from failed transport, and keep retry or copy fallback available."}],"summary":"ERC-1328 defines how WalletConnect connection data is encoded in a wc: URI that can be shown as a QR code or link. The URI carries versioned connection parameters such as keys, relay data, methods, and optional expiry. A compatible app and wallet still need to support the selected protocol version, transport, session flow, and fallback behavior.","applicability":{"whenToUse":["Your product needs to exchange a versioned WalletConnect connection URI between an app and wallet.","The selected wallet and transport support the URI version and required parameters.","The flow can provide pairing expiry, connection status, and a manual or injected-wallet fallback.","Connect flows can list wallet choices with announced or separately sourced names and icons."],"whenToAvoid":["The user is on a desktop with an injected wallet and no remote pairing is needed.","The wallet does not support the URI or session transport selected by the app.","QR or deep-link expiry and recovery cannot be supported."]},"designerTakeaways":["Show the wc: URI as a QR code or link when the selected wallet and protocol version support it.","Display the requested protocol version, pairing details, and the app's connection state before approval.","Provide expiry, retry, copy-URI, and injected-wallet or other transport fallbacks.","Choose QR dimensions and deep-link behavior from the target devices and implementation, not from ERC-1328 itself.","Label wallet names and icons as integration metadata, and keep explicit user approval in the wallet flow."],"problemsSolved":[{"problem":"No standard way to connect mobile wallet to desktop","oldWay":"Each wallet had proprietary connection methods","newWay":"A shared wc: URI grammar gives compatible app and wallet implementations a common connection payload","impact":"critical"},{"problem":"Users couldn't use preferred wallet","oldWay":"DApp only supported specific wallets","newWay":"A matching protocol version and supported parameters let the selected wallet and app exchange connection data","impact":"high"},{"problem":"Complex pairing process","oldWay":"Manual key exchange, multiple steps","newWay":"The user can scan or open a URI, review the connection request, and continue when the session flow succeeds","impact":"high"},{"problem":"Security concerns with connection","oldWay":"Unclear what permissions were being granted","newWay":"The URI carries connection data; encryption, relay behavior, session permissions, and approval are handled by the selected protocol implementation","impact":"medium"}],"uxPatterns":[{"name":"QR Code Connection","description":"A QR handoff for a supported WalletConnect URI","userFlow":["User clicks \"Connect Wallet\"","QR code displays the versioned WalletConnect URI","User opens mobile wallet","Scans QR code","Wallet and app establish their supported session flow","User approves or rejects the connection"]},{"name":"Mobile Deep Link Connection","description":"A link handoff when the device and wallet support the selected URI transport","userFlow":["User on mobile browser","Wallet list or supported link targets shown instead of QR","User taps preferred wallet","Deep link opens wallet app","Connection request and expiry are shown","User approves, rejects, or returns to the app"]},{"name":"Connection Status","description":"Show pairing progress without implying that ERC-1328 defines the session manager","userFlow":["QR scanned or deep link opened","Show pairing in progress","Guide user to approve in wallet","Update status from the selected implementation","Show connected only after the app confirms the session"]},{"name":"Session Management","description":"Show active sessions when the selected WalletConnect implementation exposes them","userFlow":["User views connected sessions","Show sessions returned by the integration","View available details and expiry","Disconnect when the integration supports it","Handle unsupported session-management controls"]}],"uiComponents":[{"name":"WalletConnectQR","description":"QR code component for WalletConnect URI","states":["generating","ready","scanned","expired"],"props":["uri","size","onScanned","expiryTime"]},{"name":"ConnectionProgress","description":"Shows pairing status steps","states":["scanning","pairing","approving","connected","failed"],"props":["currentStep","onCancel"]},{"name":"WalletSelector","description":"List of compatible wallets with deep links","states":["idle","loading","selected"],"props":["wallets[]","uri","onSelect"]},{"name":"SessionManager","description":"Manage active WalletConnect sessions","states":["empty","has-sessions"],"props":["sessions[]","onDisconnect","onSwitch"]}],"antiPatterns":[{"pattern":"Treating QR dimensions as an ERC-1328 guarantee","why":"Mobile cameras struggle with tiny QR codes","instead":"Test an appropriate size and error-correction level for target devices, and offer an enlarge path","severity":"high"},{"pattern":"Assuming deep links are defined by the URI format","why":"Mobile users can't scan their own screen","instead":"Feature-detect the selected wallet and transport, then offer supported links or QR/manual fallback","severity":"high"},{"pattern":"Hiding pairing expiry or implementation failures","why":"User scans expired QR, nothing happens","instead":"Show the expiry supplied by the protocol version when available and provide retry/copy fallback","severity":"medium"},{"pattern":"Presenting a QR scan as a completed connection","why":"User doesn't know if QR was scanned","instead":"Show scanned, pairing, approval, failure, and confirmed-session states from the integration","severity":"medium"},{"pattern":"Can't copy URI for manual connection","why":"Some users prefer pasting into wallet","instead":"Offer \"Copy link\" as alternative to QR","severity":"low"}],"relatedStandards":[{"id":"EIP-1193","relationship":"A connected wallet may expose an EIP-1193 provider; ERC-1328 does not define provider methods"},{"id":"EIP-6963","relationship":"EIP-6963 concerns injected-provider discovery; remote connection transport is separate"},{"id":"EIP-155","relationship":"Transaction replay protection and chain binding belong to transaction/signature standards"},{"id":"EIP-695","relationship":"An EIP-1193 provider may expose eth_chainId after connection; compare it with the app target"}],"technicalNotes":"ERC-1328 defines wc:topic@version?parameters syntax. WalletConnect v1 parameters include key and bridge; v2 parameters include symKey, methods, relay-protocol, optional relay-data, and optional expiryTimestamp. The URI format does not define QR sizing, wallet discovery metadata, session management, relay availability, or universal wallet interoperability. Treat URI contents as connection material and use the selected protocol implementation's approval, expiry, transport, and recovery behavior.","lastUpdated":"2026-09-18","sources":[{"label":"ERC-1328 official specification","url":"https://ercs.ethereum.org/ERCS/erc-1328","type":"official-spec"}],"lastReviewed":"2026-09-18"},"sources":[{"label":"Official specification","url":"https://ercs.ethereum.org/ERCS/erc-1328","type":"official-spec"},{"label":"Discussion search","url":"https://ethereum-magicians.org/search?q=ERC-1328","type":"discussion"}],"urls":{"canonical":"https://www.eipsfordesigners.com/standards/ERC-1328","markdown":"https://www.eipsfordesigners.com/standards/ERC-1328/content.md","agent":"https://www.eipsfordesigners.com/standards/ERC-1328/agent.md","api":"https://www.eipsfordesigners.com/api/standards/ERC-1328","official":"https://ercs.ethereum.org/ERCS/erc-1328","discussion":"https://ethereum-magicians.org/search?q=ERC-1328"},"freshness":{"lastReviewed":"2026-09-18","lastUpdated":"2026-09-18"}}