The provider emits events when the wallet's state changes. Subscribe with
provider.on(event, handler); clean up with provider.removeListener(event, handler).
const onAccounts = (accounts: string[]) => {/* … */};
provider.on("accountsChanged", onAccounts);
// later
provider.removeListener("accountsChanged", onAccounts);For a working React subscription pattern, see Handle events.
accountsChanged
Fires when the user switches accounts in the extension popup.
Payload: string[] — the new accounts.
Recommended handler: refetch every user-scoped piece of state your dApp holds. Invalidate any SIWC JWT (it was scoped to the previous party).
networkChanged
Fires when the user switches network in the extension settings (DevNet ↔ TestNet ↔ MainNet).
Payload: "devnet" | "testnet" | "mainnet".
Recommended handler: remount the dApp. Different network means different backend endpoint and different ledger state. A page refresh is typically the right move.
statusChanged
Fires when the wallet locks (auto-lock timer expired) or unlocks.
Payload: "locked" | "unlocked".
Recommended handler: hide signing-related UI when locked, restore
when unlocked. There's no need to act on initializing — that state
appears only during initial load.
disconnect
Fires when the user revokes your origin's access from inside the extension (Settings → Connected sites → Remove).
Payload: none.
Recommended handler: treat as logged-out. Clear the SIWC token, redirect to the landing screen, show a Connect prompt.
txChanged
Fires when any transaction whose commandId your dApp submitted
changes status.
Payload:
{
commandId: string,
status: "submitted" | "settled" | "failed",
txId?: string, // present when settled
}Recommended handler: for transactions you're tracking (e.g. an async-settling swap intent), update the UI in place. This is a cheaper alternative to polling the backend's status endpoint.
What's next
- Provider methods — the request-side API.
- Error codes — error semantics for the methods events depend on.