evm-provider-event-handling

EVM Provider Event Handling

EIP-1193 Events (EVM Provider)

• connect — fired when the provider establishes a connection; payload: { chainId: Hex; accounts: Address[] }
• disconnect — fired when the provider loses connection; no payload
• accountsChanged — fired when the user's accounts change; payload: string[] (array of addresses)
• chainChanged — fired when the active chain changes; payload: string (hex chain ID, not decimal)
• message — part of the EIP-1193 provider event type (payload: { type: string; data: unknown }), but not currently emitted by @metamask/connect-evm; don't rely on it for subscription delivery

const provider = client.getProvider();

provider.on('accountsChanged', (accounts: string[]) => {
  console.log('New accounts:', accounts);
});

provider.on('chainChanged', (chainId: string) => {
  // chainId is HEX (e.g., '0x1'), NOT decimal
  console.log('New chain:', chainId);
});

provider.on('connect', ({ chainId, accounts }: { chainId: string; accounts: string[] }) => {
  console.log('Connected to chain:', chainId, 'accounts:', accounts);
});

provider.on('disconnect', () => {
  // No payload — the event itself is the signal
  console.log('Disconnected');
});

chainChanged Payload Type

• chainChanged emits a hex string (e.g., '0x1', '0x89'), not a decimal number
• Never compare directly with decimal numbers: chainId === 1 will always be false
• Convert if needed: parseInt(chainId, 16) to get the decimal chain ID
• This is a common source of bugs — always treat chainChanged payload as a hex string

SDK eventHandlers (Client Options)

• Configure event callbacks directly in client options via eventHandlers:
  • connect — same as EIP-1193 connect
  • disconnect — same as EIP-1193 disconnect
  • accountsChanged — same as EIP-1193 accountsChanged
  • chainChanged — same as EIP-1193 chainChanged
  • displayUri — fires with the connection URI string for QR code rendering
  • connectAndSign — fires with the signature result from connectAndSign flow
  • connectWith — fires with the result from connectWith flow