proxmox/docs/04-configuration/THIRDWEB_WALLETS_INTEGRATION.md

# 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.

**References:** [thirdweb Wallets – Get Started](https://portal.thirdweb.com/wallets), [User Wallets](https://portal.thirdweb.com/wallets/users), [External Wallets](https://portal.thirdweb.com/wallets/external-wallets), [Quickstart (TypeScript/React)](https://portal.thirdweb.com/wallets/quickstart), [Connect SDK v5](https://portal.thirdweb.com/react/v5).

---

## 1. Portal overview

The thirdweb Wallets section covers:

- **User wallets (embedded/in-app):** Email, phone, social OAuth (Google, Apple, Facebook, Discord, X, etc.), passkey, guest, custom JWT.
- **External wallets:** 500+ wallets, EIP-6963; MetaMask, WalletConnect, Coinbase Wallet, etc.
- **Server wallets:** Backend-controlled wallets (send tx, monitor).
- **Gas sponsorship / session keys:** Optional.

For each user, thirdweb can create a **non-custodial wallet** and expose it via SDK or HTTP API.

---

## 2. HTTP API (Wallets)

Relevant for backend or headless flows:

| Endpoint | Purpose |
|----------|--------|
| `POST /v1/auth/initiate` | Start auth (email, phone, passkey, SIWE); get challenge. |
| `POST /v1/auth/complete` | Verify and complete auth; returns `token`, `userId`, `walletAddress`. |
| `GET /v1/auth/social` | Redirect to OAuth provider (`provider`, `redirectUrl`). |
| `GET /v1/wallets/me` | Get authenticated user wallet (use token from complete). |

**Headers:**

- **Frontend:** `x-client-id` (project Client ID).
- **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).

---

## 4. Full integration options

### 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).  
- [x] **Connect UI (demo):** `/wallets` page with v5 `ConnectButton` + `inAppWallet` (email, google, apple, passkey) + external wallets; Chain 138 balance shown.  
- [ ] **Chain 138:** Supported in the thirdweb client/chains config used by the dapp.  
- [ ] **Migration (optional):** Bridge and other components moved from v4 hooks to v5 extensions/hooks so one account source is used everywhere.  
- [ ] **Backend (optional):** Use of `/v1/wallets/me` or auth endpoints from a secure service when needed.

---

## 6. Quick links

- [Wallets – Get Started](https://portal.thirdweb.com/wallets)  
- [User Wallets (auth methods)](https://portal.thirdweb.com/wallets/users)  
- [External Wallets](https://portal.thirdweb.com/wallets/external-wallets)  
- [Quickstart (TypeScript/React)](https://portal.thirdweb.com/wallets/quickstart)  
- [React v5 ConnectButton / ConnectEmbed](https://portal.thirdweb.com/react/v5/components/ConnectButton)  
- [In-App Wallet (v5)](https://portal.thirdweb.com/react/v5/in-app-wallet/get-started)  
- [Migrate from v4 to v5](https://portal.thirdweb.com/react/v5/migrate)  
- [API Reference – Authentication](https://portal.thirdweb.com/reference#tag/authentication)  
- [Custom auth](https://portal.thirdweb.com/wallets/custom-auth)