@phoenix-wallet/starknet

Starknet support for the Phoenix Wallet adapter family. Provides connectors for Argent X / Ready, Braavos, OKX Wallet, and Bitget Wallet on Starknet Mainnet and Sepolia.

Built on get-starknet-core v4 for wallet discovery and starknet.js v6 WalletAccount for the Account interface bridge.

Install

npm install @phoenix-wallet/starknet @phoenix-wallet/core

Peer dependency: React ^18 || ^19.

Quick usage

import {
  ArgentStarknetConnector,
  StarknetChain,
  StarknetWallet,
  starknetSepoliaChainConfig,
} from '@phoenix-wallet/starknet'

const chain = new StarknetChain('starknet_sepolia', starknetSepoliaChainConfig)
const connector = new ArgentStarknetConnector(
  { name: 'My App', url: window.location.origin, icon: '/logo.png' },
  ['starknet_mainnet', 'starknet_sepolia'],
)
await connector.addChain(chain)

const { address, chainId } = await connector.connect()
const client = connector.createWalletClient(chain)
const wallet = new StarknetWallet(address, chain, connector, client)

const sig = await wallet.signMessage('login-nonce')
const { uiAmount, symbol } = await wallet.getBalance()
const txHash = await wallet.sendTransaction([
  { contractAddress: '0x…', entrypoint: 'transfer', calldata: ['0x…', '0x1', '0x0'] },
])

Available connectors

| Connector | Wallet | walletId (get-starknet) | | --- | --- | --- | | ArgentStarknetConnector | Argent X / Ready | argentX | | BraavosStarknetConnector | Braavos | braavos | | OkxStarknetConnector | OKX Wallet | okxwallet | | BitgetStarknetConnector | Bitget Wallet | bitkeep |

All extend StarknetConnector (abstract). Each isInstalled() checks both get-starknet-core discovery and the injected window.starknet_<id> fallback.

Chain configs

Pre-built exports: starknetMainnetChainConfig and starknetSepoliaChainConfig. Pass to new StarknetChain(id, config).

| Network | Native chainId hex | Symbol | | --- | --- | --- | | Mainnet (starknet_mainnet) | 0x534e5f4d41494e (SN_MAIN) | STRK | | Sepolia (starknet_sepolia) | 0x534e5f5345504f4c4941 (SN_SEPOLIA) | STRK |

⚠️ STRK token addresses in constants.ts's STRK_TOKEN_ADDRESS_MAP are placeholders. Verify against the official Starknet docs before relying on getBalance() in production.

Local development & testing across repos

wallet-adapter publishes @phoenix-wallet/* to npm. To test an unpublished version against whales-market-frontend-v2 (a separate repo), pick one of:

Option 1 — yalc (recommended for cross-repo testing)

npm i -g yalc
cd wallet-adapter/packages/starknet && yalc publish
cd ../../../whales-market-frontend-v2 && yalc add @phoenix-wallet/starknet
# after edits in wallet-adapter:
cd ../wallet-adapter && pnpm -F @phoenix-wallet/starknet build && yalc push
# cleanup when done:
cd ../whales-market-frontend-v2 && yalc remove @phoenix-wallet/starknet

yalc leaves a .yalc/ folder and yalc.lock — easy to revert by removing both before pushing.

Option 2 — pnpm file: override

In whales-market-frontend-v2/package.json:

"pnpm": {
  "overrides": {
    "@phoenix-wallet/starknet": "file:../wallet-adapter/packages/starknet"
  }
}

Then pnpm install. Remember to revert this override (and the lockfile changes) before pushing.

Option 3 — Demo app inside wallet-adapter/

The Next.js demo at wallet-adapter/src/app/ includes a StarknetDemo smoke-test component. Run pnpm dev from wallet-adapter/ and exercise connect / sign / balance / sendTransaction without touching the FE repo.

Architecture notes

• API surface: get-starknet-core v4 removed wallet.account.* (which v3 had). This package uses starknet.js's WalletAccount.connect(provider, walletProvider) to bridge a StarknetWindowObject into the canonical Account interface, giving us account.address, account.signMessage(), and account.execute().
• StarknetWalletClient holds the bridged WalletAccount and the StarknetChain. The Connector stores the WalletAccount after a successful connect() and constructs a fresh StarknetWalletClient on demand via createWalletClient(chain).
• Events: Each connector subscribes to accountsChanged and networkChanged on the StarknetWindowObject. An empty accountsChanged array is treated as a disconnect.
• Persistence: localStorage keys starknet_connection_status / starknet_address / starknet_wallet_id mirror the pattern used by the Solana sibling.

Limitations

• signTransaction (sign-only) is not supported — get-starknet-core wallets don't expose a uniform sign-only API. Use sendTransaction(calls) which wraps account.execute(calls).
• sendRawTransaction is not supported — Starknet has no raw-bytes broadcast equivalent.
• signAllTransactions is not supported — Starknet uses multicall via a single execute(calls[]) per batch.
• AVNU paymaster / gasless transactions are not in this release.
• Argent Web Wallet (email-based, no window.starknet_* injection) is not supported.
• Privy embedded-wallet support for Starknet is unavailable (upstream Privy limitation).

Version

This package is released in lockstep with the rest of the @phoenix-wallet/* family. Starknet support is first available in 1.0.5.