web3-thirdweb-siwe
Implement and debug wallet connection and authentication in this repo using thirdweb v5 and the SIWE-style flow in `app/hooks/useWalletAuth.ts` and `app/hooks/server_actions.ts`. Use for ConnectButton setup, account state, signature/auth verification, Base/USDC config, and CSP issues with embedded wallet.
When & Why to Use This Skill
This Claude skill streamlines the implementation and debugging of Web3 wallet authentication using thirdweb v5 and Sign-In with Ethereum (SIWE). It provides expert guidance on configuring ConnectButton components, managing account states, and resolving complex Content Security Policy (CSP) issues related to embedded wallets, specifically optimized for Next.js environments and Base/USDC configurations.
Use Cases
- Case 1: Implementing a secure SIWE-style authentication flow using thirdweb v5 hooks and server-side signature verification.
- Case 2: Troubleshooting and fixing Content Security Policy (CSP) errors that prevent thirdweb embedded wallet frames from loading correctly.
- Case 3: Configuring and debugging the thirdweb ConnectButton and account state management within a React/Next.js application.
- Case 4: Resolving environment variable issues and network connectivity problems for Web3 apps targeting the Base network.
| name | web3-thirdweb-siwe |
|---|---|
| description | Implement and debug wallet connection and authentication in this repo using thirdweb v5 and the SIWE-style flow in `app/hooks/useWalletAuth.ts` and `app/hooks/server_actions.ts`. Use for ConnectButton setup, account state, signature/auth verification, Base/USDC config, and CSP issues with embedded wallet. |
Web3 (thirdweb v5) + SIWE Auth (Stacked Poker)
Repo entry points
- thirdweb client + wallets:
app/thirdwebclient.ts - Provider wiring:
app/providers.tsx - Connect UI:
app/components/WalletButton.tsx - Auth orchestration:
app/hooks/useWalletAuth.ts,app/contexts/AuthContext.tsx - Backend calls:
app/hooks/server_actions.ts - Security headers / embedded wallet frames:
next.config.js
Documentation sources (don’t paste full docs)
- thirdweb LLM docs (per repo rules): https://portal.thirdweb.com/llms.txt
- thirdweb full LLM docs: https://portal.thirdweb.com/llms-full.txt
- thirdweb API docs: https://api.thirdweb.com/llms.txt
- Use the
thirdweb-apiMCP server (see.cursor/mcp.json) for up-to-date references.
Debug workflow (common issues)
- Confirm env is set:
NEXT_PUBLIC_THIRDWEB_CLIENT_IDNEXT_PUBLIC_API_URLNEXT_PUBLIC_WS_URL
- Confirm CSP allows thirdweb embedded wallet frames and network:
frame-srcincludeshttps://embedded-wallet.thirdweb.comconnect-srcallows required hosts
- Trace auth flow:
getAuthPayload(address)→ returns{ payload, message }account.signMessage({ message })(sign the message string)verifySignedPayload({ payload, signature })- On failure, disconnect wallet and clear attempt ref
What to load next
- For the repo’s exact auth sequence and edge cases: read
references/auth-flow.md. - For CSP gotchas (embedded wallet / Turnstile / Tenor): read
references/csp-and-headers.md. - To quickly sanity-check env vars: run
scripts/check-web3-env.sh.