Usage

Installation

To get started with integrating the StarknetKit SDK in your dApp, you will need to install the StarknetKit package and its peer dependencies:

npm install starknetkit

Imports

After installation, we get access to different methods, such as connect, disconnect, etc which we should import for use in our application:

import { connect, disconnect } from "starknetkit"

Establishing a connection

To establish a wallet connection, we need to call the connect method which was imported earlier like this:

const { wallet, connector, connectorData } = await connect()

The default order of connectors is as follows:

Argent X
Braavos
Argent Mobile
Argent Web Wallet

The order of connectors can be changed by passing connectors argument to the connect method.

import { connect } from "starknetkit"
import { WebWalletConnector } from "starknetkit/webwallet"
import { InjectedConnector } from "starknetkit/injected"
 
const { wallet, connectorData } = await connect({
  connectors: [
    new WebWalletConnector(),
    new InjectedConnector({ options: { id: "argentX" } }),
  ],
})

ℹ️

Connect function parameters types are: ConnectOptions or ConnectOptionsWithConnectors.

ConnectOptions is used to connect with the default connectors
ConnectOptionsWithConnectors is used to connect with specific connectors (or define a custom order).

export interface ConnectOptions extends GetWalletOptions {
  dappName?: string
  modalMode?: "alwaysAsk" | "canAsk" | "neverAsk"
  modalTheme?: "light" | "dark" | "system"
  storeVersion?: StoreVersion | null
  resultType?: "connector" | "wallet"
  webWalletUrl?: string
  argentMobileOptions: ArgentMobileConnectorOptions
}
 
export interface ConnectOptionsWithConnectors
  extends Omit<ConnectOptions, "webWalletUrl" | "argentMobileOptions"> {
  connectors?: StarknetkitConnector[]
}

Below is an example function that establishes a connection, then sets the connection and address states:

const connectWallet = async () => {
  const { wallet, connectorData } = await connect()
 
  if (wallet && connectorData) {
    setConnection(wallet)
    setAddress(connectorData.account)
  }
}

To reconnect to a previously connected wallet on load:

const { wallet, connectorData } = await connect({ modalMode: "neverAsk" })

Example:

useEffect(() => {
  const connectToStarknet = async () => {
    const { wallet, connectorData } = await connect({ modalMode: "neverAsk" })
 
    if (wallet && wallet.isConnected) {
      setConnection(wallet)
      setAddress(wallet.selectedAddress)
    }
  }
 
  connectToStarknet()
}, [])

Connect with connection options example

const { wallet, connectorData } = await connect({
  modalMode: "alwaysAsk",
  modalTheme: "light",
  webWalletUrl: "https://web.argent.xyz",
  argentMobileOptions: {
    dappName: "Dapp name",
    projectId: "YOUR_PROJECT_ID", // wallet connect project id
    chainId: "SN_MAIN",
    url: window.location.hostname,
    icons: ["https://your-icon-url.com"],
    rpcUrl: "YOUR_RPC_URL",
  },
})

Connection parameters

interface ConnectOptions {
  argentMobileOptions?: ArgentMobileConnectorOptions
  dappName?: string
  connectors?: StarknetkitConnector[] // can be used to define a custom order for the connectors
  modalMode?: "alwaysAsk" | "canAsk" | "neverAsk"
  modalTheme?: "light" | "dark" | "system"
  storeVersion?: StoreVersion | null
  webWalletUrl?: string
  resultType?: "connector" | "wallet"
  sort?: Sort
  include?: FilterList
  exclude?: FilterList
}
 
interface ArgentMobileConnectorOptions {
  dappName?: string
  projectId?: string // wallet connect project id
  chainId?: constants.NetworkName
  description?: string
  url?: string
  icons?: string[]
  rpcUrl?: string
}

Disconnecting wallet

To disconnect an existing connection, simply call the disconnect method from our imports, then set previously defined states to undefined:

await disconnect()

Example:

const disconnectWallet = async () => {
  await disconnect()
 
  setConnection(undefined)
  setAddress("")
}

Disconnection Params

await disconnect({ clearLastWallet: true })

Available methods and data

Wallet

wallet is a StarknetWindowObject and supports JSON-RPC Integration. Requests to wallet can be done using the .request method. The following methods are available:

wallet_getPermissions
wallet_requestAccounts
wallet_watchAsset
wallet_addStarknetChain
wallet_switchStarknetChain
wallet_requestChainId
wallet_deploymentData
wallet_addInvokeTransaction
wallet_addDeclareTransaction
wallet_signTypedData
wallet_supportedSpecs
wallet_supportedWalletApi

Examples:

await wallet.request({ type: "wallet_requestAccounts" }) // replaces .enable()
 
await wallet.request({ type: "wallet_requestChainId" })
 
await wallet.request({
  type: "wallet_addInvokeTransaction",
  params: {
    calls: [call],
  },
})
 
await wallet.request({
  type: "wallet_signTypedData",
  params: typedData,
})

wallet can also listen to events using the .on method:

const accountChangeHandler: AccountChangeEventHandler = (
  accounts?: string[],
) => {}
 
const networkChangeHandler: NetworkChangeEventHandler = async (
  chainId?: ChainId,
  accounts?: string[],
) => {}
 
wallet?.on("accountsChanged", accountChangeHandler)
wallet?.on("networkChanged", networkChangeHandler)
 
// Remove event listener
wallet?.off("accountsChanged", accountChangeHandler)
wallet?.off("networkChanged", networkChangeHandler)

Connector data

connectorData is an object containing the account and chainId of the connected wallet:

type ConnectorData = {
  account?: string
  chainId?: bigint
}

Connector

connector is an object containing data and methods related to the connected wallet. It is useful for StarknetKit and starknet-react combo, see here.

Getting Started General UX Guidelines