Wallet / Auth·EVM · Solana · Bitcoin · Cosmos · TON · Aptos · Sui
OKX Wallet
Multi-chain self-custody wallet (mobile + browser extension) covering EVM, Solana, Bitcoin/Ordinals, Cosmos, TON, Aptos, Sui, and TRON. Ships an injected provider at `window.okxwallet`, full EIP-6963 support, and `@okxweb3/connect-kit` for one-click integration plus `@okx/js-wallet-sdk` for offline transaction construction across chains.
- 01EVM + Solana + Bitcoin multi-chain dApps
- 02BTC Ordinals / Runes / BRC-20 flows
- 03WalletConnect alternative with native injected provider
- 04high-traffic Asia-region consumer apps
- 05DEX and aggregator UIs needing OKX-specific signing
- pnpm add @okxweb3/connect-kit
- pnpm add @okx/js-wallet-sdk
- pnpm add wagmi viem@2.x @tanstack/react-query
| Variable | Scope | Description |
|---|---|---|
| NEXT_PUBLIC_WALLETCONNECT_PROJECT_ID | Client | WalletConnect / Reown Cloud project ID — used by `@okxweb3/connect-kit` for mobile deep-link flows. |
| OKX_WAAS_API_KEY | Server | Server-side OKX WaaS API key from the OKX Web3 Developer Portal (https://web3.okx.com/build/dev-docs). Required for the WaaS REST APIs (account, transaction, swap). Never expose to the client. |
Use OKX Wallet for multi-chain auth. Prefer EIP-6963: `window.addEventListener('eip6963:announceProvider', e => { if (e.detail.info.rdns === 'com.okex.wallet') setProvider(e.detail.provider) })` then dispatch `eip6963:requestProvider`. As a fallback, read `window.okxwallet?.ethereum` (EVM), `window.okxwallet?.solana` (Solana), `window.okxwallet?.bitcoin` (BTC + Ordinals), or `window.okxwallet?.ton` (TON). For a turnkey UI install `@okxweb3/connect-kit` and call `OKXUniversalConnectUI.init({ dappMetaData: { name, icon } })` then `await universalUi.openModal({ namespaces: { eip155: { chains: ['eip155:1','eip155:8453'], events: ['chainChanged','accountsChanged'] } } })`. For wagmi v2 use the `injected({ target: 'okx' })` connector. For server-side transaction construction across 60+ chains, import `@okx/js-wallet-sdk` and use chain-specific `*Wallet` classes (`EthWallet`, `SolWallet`, `BtcWallet`) with offline key derivation.
- ⚑Provider collision: OKX Wallet writes `isOkxWallet` and `isOKExWallet` flags on `window.ethereum`, but if MetaMask is installed it usually wins the global. Always use EIP-6963 (`com.okex.wallet` rDNS) — reading `window.ethereum.isOkxWallet` is unreliable.
- ⚑Mobile deep-link UX: OKX uses `okx://wallet/dapp/url?dappUrl=...` for in-app browser launches; iOS Safari intercepts the scheme inconsistently — prefer WalletConnect v2 with the OKX universal link `https://www.okx.com/download?deeplink=...` for cross-platform reliability.
- ⚑Bitcoin provider quirks: `window.okxwallet.bitcoin.signPsbt` returns a hex-encoded PSBT but on some builds returns a base64 string instead — branch on string format (`/^[0-9a-f]+$/i.test(psbt)`) before passing to bitcoinjs-lib, otherwise broadcasts silently fail.
- ⚑WaaS key safety: never expose `OKX_WAAS_API_KEY` to the client — the WaaS APIs are usage-billed and a leaked key allows arbitrary transaction construction; sign requests server-side with HMAC-SHA256 over the canonical request string.
- ⚑Browser extension lifecycle: OKX's content script reinjects after every navigation, so `window.okxwallet` references can become stale on SPA route transitions — re-resolve the provider on each connect rather than caching at module load.
- ⚑Region restrictions: OKX Wallet may be blocked or geo-fenced in some jurisdictions (US users on certain flows) — handle `provider.request` rejections with code `-32000 region restricted` and fall back to a generic injected/WalletConnect path.