← Protocols
EIP-2255 — Wallet Permissions System
Standard / EIP·EVM

EIP-2255 — Wallet Permissions System

01Description

Standards-Track interface EIP that defines `wallet_requestPermissions`, `wallet_getPermissions`, and (later) `wallet_revokePermissions` so dapps can request batched, OAuth-style permissions (account access, network switches, signing scopes) instead of hitting the user with one prompt per action.

02Best for
  • 01batched permission requests
  • 02fine-grained capability scopes
  • 03session-style dapp connections
  • 04wallet-RPC permission gating
  • 05EIP-7715 / ERC-5792 capability flows
03Install
  • pnpm add viem
  • pnpm add wagmi
  • pnpm add @metamask/providers
05Prompt snippet
Request permissions via `await provider.request({ method: 'wallet_requestPermissions', params: [{ eth_accounts: {}, eth_signTypedData_v4: {} }] })`; the wallet returns an array of `RequestedPermission` objects each containing `invoker` (origin URI), `parentCapability` (the gated method), and `caveats` (e.g. allowed addresses, chain restrictions). Read current grants with `wallet_getPermissions` (no params) and revoke via `wallet_revokePermissions` (MetaMask 11.7+ / EIP-2256). Treat user rejection as standard EIP-1193 `code: 4001`. Pair with EIP-1102 for the underlying `eth_accounts` capability and with EIP-7715 (session-key permissions) for AA-style scoped grants.
06Gotchas
  • Wallet support is uneven — MetaMask, Rabby, and Frame implement 2255 but most mobile wallets fall back to per-method prompts; feature-detect by calling `wallet_getPermissions` and catching `-32601 method not found`.
  • `caveats` are wallet-defined — the spec lists examples (`restrictReturnedAccounts`) but each wallet honors a different subset; never rely on a caveat for security, only as UX hints.
  • Permissions are per-origin and persist across sessions — revocation only happens via `wallet_revokePermissions` or wallet UI; logging out of your dapp does not revoke `eth_accounts`, so re-prompt if the user expects a fresh consent screen.
  • Requesting too many capabilities at once leads to user fatigue and rejection — group only the capabilities needed for the next action, not the whole dapp's lifetime needs.
  • `parentCapability` strings must match the RPC method name exactly (`eth_accounts`, not `accounts`) — typos silently grant nothing and the next call still prompts.
  • EIP-2255 predates EIP-7715 (Granted Permissions for AA wallets) — for 4337/7702 smart accounts, prefer 7715's session-key model with on-chain enforcement instead of relying on wallet-side caveats.
07Alternatives