Wallet Switch Starknet Chain RPC Method (`wallet_switchStarknetChain`)

Simple Summary

An RPC method for switching the wallet’s active Starknet Chain.

Inspired by EIP-3326.


The wallet_switchStarknetChain RPC method allows Starknet decentralized applications (“dapps”) to request that the wallet switches its active Starknet chain. The caller must specify a chain ID, and the method returns null if the active chain was switched, and an error otherwise.

Important cautions for implementers of this method are included in the Security Considerations section.


With the deprecation of goerli2, all dapps on Starknet are built on either mainnet or testnet - goerli, with some dapps implementing both e.g block explorers.

Most wallets only supports interacting with one chain at a time. We call this the wallet’s “active chain”. Since Starknet users are expected to interact with either of both chains, [mainnet or goerli], it’s important to enable dapps to be able to switch the user’s chain to the appropriate one.

wallet_switchStarknetChain enables dapps to request that the wallet switches its active chain to whichever one is required by the dapp. This improves the UX for both dapps and wallets by a long mile.


Method - wallet_switchStarknetChain

The method accepts a single object parameter with a chainId field. The method returns null if the wallet switched its active chain, and an error otherwise.

NB: The method presupposes that the wallet has a concept of a single “active chain”. The active chain is defined as the chain that the wallet is forwarding RPC requests to.

export interface SwitchStarknetChainParameter {
  chainId: string // A 0x-prefixed hexadecimal string


The method as specified above, accepts a single parameter chainId.

The chainId:

  • MUST be the integer ID of the chain, specified as a 0x-prefixed hexadecimal string.

The wallet:

  • MUST recognize the specified ID, able to switch to the specified chain and capable of servicing RPC requests to it.


The method MUST return null if the request was successful, and an error otherwise.


These examples use JSON-RPC, but the method could be implemented using other RPC protocols.

To switch to Mainnet:

  "id": 1,
  "jsonrpc": "2.0",
  "method": "wallet_switchStarknetChain",
  "params": [
      "chainId": "0x534e5f4d41494e",

To switch to the Goerli testnet:

  "id": 1,
  "jsonrpc": "2.0",
  "method": "wallet_switchStarknetChain",
  "params": [
      "chainId": "0x534e5f474f45524c49",

Code example with get-starknet:


await window.starknet.request({
    type: "wallet_switchStarknetChain",
    params: {
        chainId: "SN_MAIN"



Practical example as implemented by Element

A dapp that currently implements this standard, is Element. When a user connects his wallet, but on the wrong chain, he gets prompted to connect to the right chain.

The request to switch network, looks like this on the Argent X wallet, but could be improved:

Security Consideration

For wallets with a concept of an active chain, switching the active chain has significant implications for pending RPC requests and the user’s experience. If the active chain switches without the user’s awareness, a malicious dapp could induce the user to take actions for unintended chains.

In light of this, the wallet:

  • SHOULD display a confirmation whenever a wallet_switchStarknetChain request is received, clearly identifying the requester and the chain that will be switched to.
  • SHOULD cancel all pending RPC requests and chain-specific user confirmations when switching.

Shouldn’t it be "0x534e5f4d41494e" instead of "SN_MAIN"?

Hello @avimak, apologies for late replies. With Argent X, we support both the hex value 0x534e5f4d41494e and the short string ‘SN_MAIN’. I was hoping we could finalize on one of both, and ‘SN_MAIN’ seemed like a better way to go, but let me know what you think:)

It makes sense to follow the starknet_chainId specifications, which work with schemas/CHAIN_ID, defined as hex -

            "CHAIN_ID": {
                "title": "Chain id",
                "description": "StarkNet chain id, given in hex representation.",
                "type": "string",
                "pattern": "^0x[a-fA-F0-9]+$"

Hence, I would’ve gone with the hex value (only).