Establish a Connection

After detecting the provider, an application can request to connect to the Supra network via StarKey. This connection request will prompt the user to grant permission to share their public key, signaling their willingness to engage further. Users must approve the connection request before the app can proceed with additional actions, such as signing a message or sending a transaction.

Once permission is granted for the first time, the web application’s domain will be whitelisted for future connection requests. After a connection is established, either the application or the user can choose to terminate the connection.

Connecting

To connect to the Supra network, call connect on the window.starkey.supra provider.

const provider = window.starkey?.supra // see "Detecting the Provider"
 
const accounts = await provider.connect()
 
if (!accounts?.length) {
  // user declined or dismissed the prompt — nothing was shared
  return
}
 
console.log(accounts[0])
// 0x534583cd8cE0ac1af4Ce01Ae4f294d52b4Cd305F

connect returns a Promise<string[] | null>. On approval it resolves to an array of every connected wallet address, with the active address at index 0. If the user declines the prompt or closes it without answering, it resolves to null — it does not reject, so a try/catch will not catch a rejection. See Errors for the full failure model.

Connect options

connect also accepts an optional options object:

interface ConnectOptions {
  chainId?: string // default: '8' (Supra Mainnet)
  multiple?: boolean // default: false
}
 
const accounts = await provider.connect({ chainId: '8', multiple: true })

See the official Network Information  docs for the full chain ID / RPC endpoint list, including any newly added networks.

Once the web application is connected to StarKey, it will be able to read the connected account’s address and prompt the user for additional transactions. For reading already-connected accounts without prompting the user, see accounts() on the Accounts page.

Checking an existing connection

To silently check whether the site already has an active connection (e.g. on page load, to skip re-prompting the user), call isConnected():

const provider = window.starkey?.supra
const connected: boolean = await provider.isConnected()
 
if (connected) {
  // safe to call accounts(), getActiveAccount(), balance(), etc. without prompting connect()
}

Use this for the reconnect flow: on mount, call isConnected() and, if true, hydrate local state from accounts() instead of calling connect() again.

Disconnecting

Once a user has established a connection, StarKey will add the website they opened a connection with to a list of apps. The user can then revoke access through the UI at any time, and will need to reconnect.

To disconnect StarKey from a dApp, call the disconnect method.

const provider = window.starkey?.supra
await provider.disconnect()

disconnect() resolves with no return value. Clear your own local wallet state (accounts, balance, networkData, etc.) right after it resolves — StarKey doesn’t do this for you.

Changing accounts

StarKey allows users to seamlessly manage multiple accounts (i.e., addresses) from within a single extension or mobile app. Whenever a user switches accounts, StarKey will emit an accountChanged event.

If a user changes accounts while already connected to an application, and the new account had already whitelisted that application, then the user will stay connected and StarKey will pass the public key of the new account.

provider.on('accountChanged', (accounts: string[]) => {
  if (accounts.length > 0) {
    // Set new public key and continue as usual
    console.log(`Switched to account ${accounts[0]}`)
  }
})

See Events for the full event catalog (accountChanged, networkChanged, disconnect) and the one-time starkey-extension-installed install event.

Related pages

• Detecting the Provider
• Accounts
• Events
• Errors — the null-on-decline failure model and disconnected-state handling