Wallet / Auth·EVM · Solana · Bitcoin · Cosmos · TON
Trust Wallet
Multi-chain self-custody wallet (mobile, browser extension) with 140+ chains via Wallet Core, plus Trust Wallet WaaS — APIs and SDKs for embedding wallets, swaps, on/off-ramp, and node/data access into your product. EVM provider injected at `window.trustwallet` (and EIP-6963), with native support for Cosmos, Solana, Bitcoin, and TON.
- 01consumer mobile-first dApps
- 02multi-chain self-custody (EVM, Solana, Cosmos, Bitcoin)
- 03embedded wallets via Trust Wallet WaaS
- 04in-wallet dApp browser distribution
- 05WalletConnect-driven mobile flows
- pnpm add @trustwallet/wallet-core
- pnpm add @walletconnect/modal wagmi viem@2.x
| Variable | Scope | Description |
|---|---|---|
| NEXT_PUBLIC_WALLETCONNECT_PROJECT_ID | Client | WalletConnect / Reown Cloud project ID — required for Trust Wallet mobile deep-links via WalletConnect v2. |
| TRUST_WALLET_WAAS_API_KEY | Server | Server-side Trust Wallet WaaS API key from the Trust Wallet Developer Portal (https://portal.trustwallet.com). Required for swap/transfer/data APIs. Never expose to the client. |
Use Trust Wallet for multi-chain self-custody auth. Detect the injected provider via EIP-6963 (`window.addEventListener('eip6963:announceProvider', e => ...)`) and prefer the announced `info.rdns === 'com.trustwallet.app'` provider over reading `window.ethereum`. As a fallback, read `window.trustwallet` (EVM provider) or `window.trustwallet.solana` for Solana. For wagmi/viem stacks, the `injected({ target: 'trust' })` connector resolves Trust Wallet on desktop, while mobile flows require WalletConnect v2 — Trust Wallet's deep link scheme is `https://link.trustwallet.com/wc?uri=...`. For embedded/WaaS, sign requests server-side with the `TRUST_WALLET_WAAS_API_KEY` and call the Data, Transfer, Swap, and Node APIs from your backend; never proxy the key from a browser. For low-level signing across 140+ chains, import `@trustwallet/wallet-core` and use `HDWallet`, `AnySigner`, and chain-specific `CoinType` enums.
- ⚑Multi-wallet collision: Trust Wallet competes for `window.ethereum` with MetaMask, Rabby, OKX, Coinbase, Bitget — always use EIP-6963 (`eip6963:announceProvider`) to disambiguate; reading `window.ethereum.isTrust` is unreliable when several wallets are installed.
- ⚑Mobile deep-link UX: iOS Safari's PWA mode and in-app browsers (Telegram, Twitter) strip the WalletConnect return URL — the user gets dropped on the wallet screen and the dApp never reconnects. Use universal links (`https://link.trustwallet.com/...`) instead of the `trust://` scheme and test on real iOS devices.
- ⚑WaaS key safety: the WaaS API expects HMAC-signed requests with the API key — leaking the key allows unsigned transfers. Sign on the server, rate-limit per user, and never embed the secret in client bundles or `NEXT_PUBLIC_*` env vars.
- ⚑Wallet Core build size: `@trustwallet/wallet-core` ships a WASM blob (~5MB) — lazy-load it (`await import('@trustwallet/wallet-core')`) and host the `.wasm` next to your assets with the right `Content-Type: application/wasm` header or initialization fails silently in production builds.
- ⚑In-wallet dApp browser quirks: Trust Wallet's mobile dApp browser injects `window.trustwallet` and `window.ethereum` synchronously, but listeners attached before `DOMContentLoaded` fire on the initial provider, missing chain-switch events. Re-bind on `provider.on('chainChanged', ...)` after the SDK reports ready.
- ⚑Solana provider mismatch: Trust Wallet's Solana provider exposes `signTransaction` but rejects versioned transactions (v0) on older mobile builds — encode legacy transactions when targeting Trust Wallet, or branch on the wallet's `version` property.