# Thirdweb Wallets – Documentation Review and Integration
**Purpose:** Review [thirdweb Wallets portal](https://portal.thirdweb.com/wallets) and document how we use or can fully integrate user/embedded wallets (email, phone, social, passkey, external) across the repo.
- **Backend:** `x-secret-key` (Dashboard → Settings → API Keys); never in frontend.
**Auth flow (e.g. email):**
1.`POST /v1/auth/initiate` with `{ "type": "email", "email": "user@example.com" }`.
2. User receives code; then `POST /v1/auth/complete` with `{ "type": "email", "email": "...", "code": "123456" }`.
3. Response includes `token`, `walletAddress`; use `token` for `GET /v1/wallets/me` or other authenticated calls.
**Custom auth:** If you already have an auth system, you can attach thirdweb wallets via [Custom Authentication](https://portal.thirdweb.com/wallets/custom-auth).
---
## 3. Current usage in this repo
| Area | What we use | Notes |
|------|-------------|--------|
| **smom-dbis-138/frontend-dapp** | `ThirdwebProvider` (v4), `useAddress` / `useBalance` / `useContract` from `@thirdweb-dev/react`; bridge UI uses thirdweb v4 hooks. | Connect UI is **wagmi** (MetaMask, WalletConnect, Coinbase) in `WalletConnect.tsx`; no embedded wallet (email/social) yet. |
| **x402-api** | `thirdweb` v5: `createThirdwebClient`, `facilitator`, `settlePayment` from `thirdweb/x402`; custom Chain 138. | Server-side only; no user wallets. |
| **explorer-monorepo** | Raw ethers + MetaMask + custom `/api/v1/auth/nonce` and `/api/v1/auth/wallet`. | No thirdweb SDK. |
**Secrets / env:**
- **frontend-dapp:** `VITE_THIRDWEB_CLIENT_ID`, `VITE_WALLETCONNECT_PROJECT_ID` (see [MASTER_SECRETS.md](MASTER_SECRETS.md), [DAPP_LXC_DEPLOYMENT.md](../03-deployment/DAPP_LXC_DEPLOYMENT.md)).
- **x402-api:** `THIRDWEB_SECRET_KEY` (backend only), `SERVER_WALLET_ADDRESS` (treasury for x402). When `X402_USE_ALLTRA=true`, local verification does not require `THIRDWEB_SECRET_KEY`.
---
## 3.1 Server wallet (admin signer) — usage policy
Use the **server wallet** (e.g. the key backing `SERVER_WALLET_ADDRESS` or an Engine backend wallet) only for:
**Do not** use it for user flows (no user impersonation). Keep keys in **KMS, HSM, or secure custody**. See [ALLTRA_X402_OPERATOR_GUIDE.md](ALLTRA_X402_OPERATOR_GUIDE.md) for Alltra/x402 operator context.
**User wallets vs server wallet:**
- **External connect:** power users (MetaMask, WalletConnect, etc.).
- **Embedded:** email/social/passkeys for smooth onboarding; both are user-controlled.
- **Server wallet:** backend-only; never exposed to or used on behalf of end users.
### 4.1 Frontend: one connect experience (embedded + external)
**Goal:** Single “Connect” that supports both **in-app wallets** (email, phone, social) and **external wallets** (MetaMask, WalletConnect, etc.) as in the [portal Get Started](https://portal.thirdweb.com/wallets) and [Quickstart](https://portal.thirdweb.com/wallets/quickstart).
**Recommended path: thirdweb SDK v5**
- Portal and Quickstart use **v5** (`thirdweb` package, `thirdweb/react`).
- v5 provides `ConnectButton` / `ConnectEmbed`, `inAppWallet({ auth: { options: ["email", "google", "passkey", ...] } })`, and 500+ external wallets with smaller bundle and better perf than v4.
- v4 (`@thirdweb-dev/react`) is still in use in the dapp for contract hooks; v5 can run [alongside v4](https://portal.thirdweb.com/react/v5/migrate) for a gradual move.
**Steps:**
1.**Add v5 and a dedicated wallets flow (e.g. demo page)**
- Install: `npm i thirdweb`.
- Use `createThirdwebClient({ clientId })`, `ThirdwebProvider`, `ConnectButton` from `thirdweb/react`.
- Configure `ConnectButton` with `inAppWallet({ auth: { options: ["email", "google", "apple", "passkey"] } })` so users can sign in with email/social or connect MetaMask/WalletConnect.
- **Done:** The frontend-dapp has a **Wallets** page (`/wallets`, `src/pages/WalletsDemoPage.tsx`) that uses only v5: `ConnectButton` with in-app wallet + external wallets, `useActiveAccount`, `useWalletBalance` on Chain 138. Use it to try email/social/external connect without changing the rest of the app.
2.**Unify connect UI (full integration)**
- Replace the current wagmi-only connect modal in `Layout` / `WalletConnect.tsx` with thirdweb v5’s `ConnectButton` (or `ConnectEmbed`) so the same button offers embedded + external.
- Migrate bridge and other features from v4 hooks to v5: e.g. `useAddress` → `useActiveAccount`, `useContract`/`useContractWrite` → v5 contract extensions + `useSendTransaction` (see [v5 migrate](https://portal.thirdweb.com/react/v5/migrate)).
- Keep Chain 138 in v5 (e.g. `defineChain` or use a chain list that includes 138) so the same RPC and chain are used.
3.**Env**
- Use the same `VITE_THIRDWEB_CLIENT_ID` (and optional `VITE_WALLETCONNECT_PROJECT_ID` if needed by v5). No backend secret in frontend.
### 4.2 Backend: optional use of Wallets API
- If you need to **resolve or manage user wallets server-side** (e.g. after a custom auth), call `GET /v1/wallets/me` with the thirdweb token, or use the HTTP auth flow (`/v1/auth/initiate`, `/v1/auth/complete`) with `x-secret-key` from a secure backend.
- **x402-api** already uses `THIRDWEB_SECRET_KEY` for x402; the same key can be used for server-side Wallets API calls if you add them.
### 4.3 Explorer (Blockscout frontend)
- The explorer uses ethers + MetaMask and custom auth endpoints; it does not use thirdweb.
- Full thirdweb Wallets integration there would mean adding the thirdweb SDK and either replacing or complementing the current connect flow with `ConnectButton` + in-app wallet; that’s a separate, optional project.
---
## 5. Checklist for “fully integrated” thirdweb Wallets
- [x]**Documentation:** This file + links to portal (Get Started, Users, Quickstart, v5 migrate).
- [x]**Client ID:**`VITE_THIRDWEB_CLIENT_ID` set in frontend-dapp (and any other app that uses thirdweb).
