proxmox/docs/04-configuration/THIRDWEB_WALLETS_INTEGRATION.md

Thirdweb Wallets – Documentation Review and Integration

Purpose: Review thirdweb Wallets portal 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, User Wallets, External Wallets, Quickstart (TypeScript/React), Connect SDK 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.

---

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, 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:

• Contract admin actions: roles, pausing, upgrades.
• Allowlist / signature minting (if your contracts support it).
• Indexer repair jobs (rare, e.g. backfill or reconciliation).
• Operational controls: key rotation, emergency ops.

Do not use it for user flows (no user impersonation). Keep keys in KMS, HSM, or secure custody. See 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. 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 and 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 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).
   • 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

• Documentation: This file + links to portal (Get Started, Users, Quickstart, v5 migrate).
• Client ID: VITE_THIRDWEB_CLIENT_ID set in frontend-dapp (and any other app that uses thirdweb).
• 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
• User Wallets (auth methods)
• External Wallets
• Quickstart (TypeScript/React)
• React v5 ConnectButton / ConnectEmbed
• In-App Wallet (v5)
• Migrate from v4 to v5
• API Reference – Authentication
• Custom auth