Events
The window.starkey.supra provider emits events for state changes that can happen outside your dApp’s control — the user switching accounts or networks from the StarKey UI, or disconnecting the site.
These event names (accountChanged, networkChanged) are StarKey-specific. See Ethereum Events for the standard-named EIP-1193 events on the Ethereum provider.
on(event, handler)
Subscribes to provider events.
window.starkey.supra.on('accountChanged', (accounts: string[]) => setAccounts(accounts))
window.starkey.supra.on('networkChanged', (data: { chainId: string }) => setNetworkData(data))
window.starkey.supra.on('disconnect', () => resetWalletData())Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
event | 'accountChanged' | 'networkChanged' | 'disconnect' | yes | The event name to subscribe to. |
handler | (payload) => void | yes | Called with the event’s payload — see the table below for each event’s shape. |
Event reference
| Event | Fires when | Handler payload |
|---|---|---|
accountChanged | Connected accounts change | string[] — updated wallet addresses, e.g. ['0x123...', '0x456...'] |
networkChanged | Connected network changes | { chainId: string }, e.g. { chainId: '8' } |
disconnect | Wallet is disconnected | none — reset local state |
window.starkey.supra.on('accountChanged', function (accounts: string[]) {
console.log('Accounts changed:', accounts)
})
window.starkey.supra.on('networkChanged', function (data: { chainId: string }) {
console.log('Network changed:', data)
})
window.starkey.supra.on('disconnect', function () {
console.log('Wallet disconnected')
})Removing listeners
Provider event handlers should be torn down when your component unmounts to avoid stale closures and duplicate handlers on re-mount (e.g. via the standard EventEmitter-style off/removeListener API, mirroring how you registered with on).
First-time extension install
This is a separate, one-time signal fired via the browser’s native message event on window — not through provider.on. It fires once, right after the user installs the StarKey extension while your dApp tab is already open.
function handleExtensionEvents(event: MessageEvent): void {
if (event?.data?.name === 'starkey-extension-installed') {
window.removeEventListener('message', handleExtensionEvents)
alert('StarKey extension has been installed. Please reload the page to continue.')
}
}
window.addEventListener('message', handleExtensionEvents)See Detecting the Provider for the full install-detection flow this pairs with.
Notes
accountChangedfires with the new account already whitelisted for your dApp if the user previously approved it — the connection stays alive and you just receive the new address list. If the new account has never approved your dApp, StarKey handles re-prompting; your handler still just receives the updated array once approved.- Refresh dependent state (
balance(),getActiveAccount(),getChainId()) inside youraccountChanged/networkChangedhandlers — these values are scoped to the active account and chain.
Best practices
- Register all three provider events (
accountChanged,networkChanged,disconnect) together, right after you detect the provider, so your UI never gets out of sync with wallet-side changes. - Treat
disconnectas the source of truth for clearing local session state, rather than only clearing it on your owndisconnect()button handler — the user can also disconnect from the StarKey UI directly.