Loading...
;
+
+ if (!authenticated) {
+ return ;
+ }
+
+ return (
+
+
+ );
+}
+```
+
+### useWallets Hook
+
+Returns all connected wallets (embedded + external). Always filter by type.
+
+```typescript
+import { useWallets } from "@privy-io/react-auth";
+
+function WalletDisplay() {
+ const { ready, wallets } = useWallets();
+
+ if (!ready) return User ID: {user?.id}
+ +Loading wallets...
;
+
+ const embeddedWallet = wallets.find(
+ (w) => w.walletClientType === "privy"
+ );
+ const externalWallets = wallets.filter(
+ (w) => w.walletClientType !== "privy"
+ );
+
+ return (
+
+ {embeddedWallet && (
+
+ );
+}
+```
+
+### useEmbeddedWallet Hook
+
+Direct access to the embedded wallet for creation and management.
+
+```typescript
+import {
+ useEmbeddedWallet,
+ isNotCreated,
+ isConnected,
+} from "@privy-io/react-auth";
+
+function EmbeddedWalletManager() {
+ const wallet = useEmbeddedWallet();
+
+ if (isNotCreated(wallet)) {
+ return (
+
+ );
+ }
+
+ if (!isConnected(wallet)) {
+ return Embedded: {embeddedWallet.address}
+ )} + {externalWallets.map((w) => ( ++ {w.walletClientType}: {w.address} +
+ ))} +Connecting wallet...
;
+ }
+
+ return Wallet: {wallet.address}
; +} +``` + +## Embedded Wallet Management + +### Sign a Message + +```typescript +import { useWallets } from "@privy-io/react-auth"; + +async function signMessage(wallets: ReturnTypeSolana address: {solanaWallet.address}
; +} +``` + +## Smart Wallet Integration + +### Privy + Safe (Account Abstraction) + +Privy embedded wallets can serve as the signer/owner for a Safe smart account, enabling gas sponsorship and batched transactions. + +```typescript +import { PrivyProvider } from "@privy-io/react-auth"; + +
+ {embeddedWallet && (
+
+ );
+}
+```
+
+### Sponsored Transactions with Smart Wallets
+
+Smart wallets enable gas sponsorship through Privy's paymaster. Users pay zero gas.
+
+```typescript
+async function sendSponsoredTx(
+ smartWallet: ConnectedWallet
+) {
+ const provider = await smartWallet.getEthereumProvider();
+ const walletClient = createWalletClient({
+ chain: base,
+ transport: custom(provider),
+ });
+
+ const [account] = await walletClient.getAddresses();
+
+ // Gas is sponsored by the paymaster -- user pays nothing
+ const hash = await walletClient.sendTransaction({
+ account,
+ to: "0xRecipient..." as `0x${string}`,
+ value: parseEther("0.001"),
+ });
+
+ return hash;
+}
+```
+
+### Privy + ZeroDev
+
+For advanced account abstraction (session keys, custom validators), use ZeroDev's Kernel with Privy as the signer.
+
+```typescript
+import { createKernelAccount } from "@zerodev/sdk";
+import { signerToEcdsaValidator } from "@zerodev/ecdsa-validator";
+import { providerToSmartAccountSigner } from "permissionless";
+
+async function createZeroDevAccount(
+ embeddedWallet: ConnectedWallet
+) {
+ const provider = await embeddedWallet.getEthereumProvider();
+ const signer = await providerToSmartAccountSigner(provider);
+
+ const ecdsaValidator = await signerToEcdsaValidator(publicClient, {
+ signer,
+ entryPoint: entryPoint07Address,
+ });
+
+ const kernelAccount = await createKernelAccount(publicClient, {
+ plugins: { sudo: ecdsaValidator },
+ entryPoint: entryPoint07Address,
+ });
+
+ return kernelAccount;
+}
+```
+
+## Custom UI / Headless Mode
+
+Privy provides a default login modal, but you can build fully custom UI using headless hooks.
+
+Each auth method has a headless hook: `useLoginWithEmail` (sendCode/loginWithCode flow), `useLoginWithOAuth` (initOAuth with provider), `useLoginWithPasskey`, `useLoginWithWallet`, `useLoginWithFarcaster`, and `useLoginWithCustomAuth`. Each hook exposes a `state` object for tracking the multi-step flow.
+
+```typescript
+import { useLoginWithEmail } from "@privy-io/react-auth";
+
+function CustomEmailLogin() {
+ const { sendCode, loginWithCode, state } = useLoginWithEmail();
+
+ if (state.status === "awaiting-code-input") {
+ return ;
+ }
+
+ return ;
+}
+```
+
+```typescript
+import { useLoginWithOAuth } from "@privy-io/react-auth";
+
+function GoogleLogin() {
+ const { initOAuth } = useLoginWithOAuth();
+ return (
+
+ );
+}
+```
+
+## Alternatives Comparison
+
+| Feature | Privy | Dynamic | Web3Auth | Magic |
+|---------|-------|---------|----------|-------|
+| Auth-first (social login) | Yes | Yes | Yes | Yes |
+| Embedded wallets | Yes (SSS + TEE) | Yes (MPC) | Yes (MPC/TSS) | Yes (delegated key) |
+| Smart wallet (AA) built-in | Yes (Safe) | Yes | No (BYO) | No |
+| Solana support | Yes | Yes | Yes | Limited |
+| Passkey support | Yes | Yes | Yes | No |
+| Headless mode | Yes | Yes | Yes | Yes |
+| Farcaster login | Yes | No | No | No |
+| WalletConnect built-in | Opt-in | Yes | Opt-in | No |
+| Stripe integration | Native (acquired) | No | No | No |
+| Pricing | Free tier + usage | Free tier + usage | Free tier + usage | Free tier + usage |
+
+## Related Skills
+
+- **frontend-ux** -- dApp UX patterns, transaction lifecycle, error handling. Privy handles auth; frontend-ux handles everything after.
+- **wagmi** -- React hooks for Ethereum. Privy's embedded wallet provider is compatible with wagmi's `custom` transport.
+- **safe** -- Safe smart accounts. Privy's smart wallet mode uses Safe under the hood. See safe skill for multisig patterns.
+- **account-abstraction** -- ERC-4337 and EIP-7702 deep dive. Privy's smart wallets build on this infrastructure.
+
+## References
+
+- Privy Documentation: https://docs.privy.io
+- Privy React SDK: https://www.npmjs.com/package/@privy-io/react-auth
+- Privy Server Auth: https://www.npmjs.com/package/@privy-io/server-auth
+- Privy Dashboard: https://dashboard.privy.io
+- Privy GitHub: https://github.com/privy-io
+- Privy Security Model: https://docs.privy.io/guide/security
+- Stripe Acquisition Announcement: https://stripe.com/blog/privy (June 2025)
+- Shamir Secret Sharing: https://en.wikipedia.org/wiki/Shamir%27s_secret_sharing
From cf8b7107d6cc446b22d502153e385bbab5654e05 Mon Sep 17 00:00:00 2001
From: 0xinit <28729137+0xinit@users.noreply.github.com>
Date: Mon, 2 Mar 2026 11:34:05 -0800
Subject: [PATCH 06/20] feat: add privy examples
---
.../examples/embedded-wallet-tx/README.md | 238 ++++++++++++++++
skills/privy/examples/server-auth/README.md | 201 ++++++++++++++
skills/privy/examples/smart-wallet/README.md | 259 ++++++++++++++++++
skills/privy/examples/social-login/README.md | 161 +++++++++++
4 files changed, 859 insertions(+)
create mode 100644 skills/privy/examples/embedded-wallet-tx/README.md
create mode 100644 skills/privy/examples/server-auth/README.md
create mode 100644 skills/privy/examples/smart-wallet/README.md
create mode 100644 skills/privy/examples/social-login/README.md
diff --git a/skills/privy/examples/embedded-wallet-tx/README.md b/skills/privy/examples/embedded-wallet-tx/README.md
new file mode 100644
index 0000000..5019148
--- /dev/null
+++ b/skills/privy/examples/embedded-wallet-tx/README.md
@@ -0,0 +1,238 @@
+# Send ETH from Embedded Wallet
+
+Working TypeScript/React example for sending an ETH transaction from a Privy embedded wallet using viem.
+
+## Dependencies
+
+```bash
+npm install @privy-io/react-auth viem
+```
+
+## Transaction Component
+
+```tsx
+// components/SendTransaction.tsx
+"use client";
+
+import { useState } from "react";
+import { usePrivy, useWallets } from "@privy-io/react-auth";
+import {
+ createWalletClient,
+ createPublicClient,
+ custom,
+ http,
+ parseEther,
+ formatEther,
+ type Hash,
+} from "viem";
+import { base } from "viem/chains";
+
+type TxState =
+ | "idle"
+ | "switching-chain"
+ | "awaiting-signature"
+ | "pending"
+ | "confirmed"
+ | "failed";
+
+export function SendTransaction() {
+ const { authenticated } = usePrivy();
+ const { ready, wallets } = useWallets();
+ const [txState, setTxState] = useStateSigner (EOA): {embeddedWallet.address}
+ )} + {smartWallet && ( +Smart Wallet (Safe): {smartWallet.address}
+ )} +Please log in first.
; + } + + if (!embeddedWallet) { + returnNo embedded wallet found. Wait for wallet creation.
; + } + + async function handleSend() { + if (!embeddedWallet) return; + if (!recipient || !amount) return; + + setTxState("switching-chain"); + setError(null); + setTxHash(null); + + try { + await embeddedWallet.switchChain(base.id); + + setTxState("awaiting-signature"); + + const provider = await embeddedWallet.getEthereumProvider(); + const walletClient = createWalletClient({ + chain: base, + transport: custom(provider), + }); + + const publicClient = createPublicClient({ + chain: base, + transport: http(), + }); + + const [account] = await walletClient.getAddresses(); + + const hash = await walletClient.sendTransaction({ + account, + to: recipient as `0x${string}`, + value: parseEther(amount), + }); + + setTxHash(hash); + setTxState("pending"); + + const receipt = await publicClient.waitForTransactionReceipt({ + hash, + }); + + if (receipt.status === "success") { + setTxState("confirmed"); + } else { + setTxState("failed"); + setError("Transaction reverted on-chain."); + } + } catch (err) { + setTxState("failed"); + const message = err instanceof Error ? err.message : "Unknown error"; + + // User rejection -- silently reset + if ( + message.includes("User rejected") || + message.includes("user denied") + ) { + setTxState("idle"); + return; + } + + setError(message); + } + } + + function reset() { + setTxState("idle"); + setTxHash(null); + setError(null); + } + + const explorerUrl = txHash + ? `https://basescan.org/tx/${txHash}` + : null; + + const buttonLabels: Record
+
+ );
+}
+```
+
+## Usage
+
+```tsx
+// app/send/page.tsx
+"use client";
+
+import { SendTransaction } from "@/components/SendTransaction";
+
+export default function SendPage() {
+ return (
+ Send ETH on Base
+From: {embeddedWallet.address}
+
+ setRecipient(e.target.value)}
+ placeholder="0x..."
+ disabled={txState !== "idle"}
+ />
+
+
+
+
+ setAmount(e.target.value)}
+ placeholder="0.001"
+ type="text"
+ inputMode="decimal"
+ disabled={txState !== "idle"}
+ />
+
+
+
+
+ {txState === "pending" && explorerUrl && (
+ + Submitted.{" "} + + View on BaseScan + +
+ )} + + {txState === "confirmed" && explorerUrl && ( +
+
+ )}
+
+ {txState === "failed" && error && (
+ + Confirmed.{" "} + + View on BaseScan + +
+ +
+
+ )}
+ {error}
+ +Please log in first.
; + } + + if (!smartWallet) { + return ( +
+
+ );
+ }
+
+ async function handleSendSponsored() {
+ if (!smartWallet) return;
+
+ setSending(true);
+ setError(null);
+ setTxHash(null);
+
+ try {
+ const provider = await smartWallet.getEthereumProvider();
+ const walletClient = createWalletClient({
+ chain: base,
+ transport: custom(provider),
+ });
+
+ const publicClient = createPublicClient({
+ chain: base,
+ transport: http(),
+ });
+
+ const [account] = await walletClient.getAddresses();
+
+ // Gas is sponsored through Privy's paymaster infrastructure
+ // The user pays zero gas for this transaction
+ const hash = await walletClient.sendTransaction({
+ account,
+ to: "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045" as `0x${string}`,
+ value: parseEther("0.0001"),
+ });
+
+ setTxHash(hash);
+
+ const receipt = await publicClient.waitForTransactionReceipt({
+ hash,
+ });
+
+ if (receipt.status !== "success") {
+ setError("Transaction reverted on-chain.");
+ }
+ } catch (err) {
+ const message = err instanceof Error ? err.message : "Unknown error";
+ if (
+ message.includes("User rejected") ||
+ message.includes("user denied")
+ ) {
+ setSending(false);
+ return;
+ }
+ setError(message);
+ } finally {
+ setSending(false);
+ }
+ }
+
+ const explorerUrl = txHash
+ ? `https://basescan.org/tx/${txHash}`
+ : null;
+
+ return (
+ Smart wallet not available.
+ {embeddedWallet && ( +EOA signer ready: {embeddedWallet.address}
+ Ensure smartWallets.enabled: true is set in
+ PrivyProvider config.
+
+
+ );
+}
+```
+
+## Batch Transactions with Smart Wallet
+
+Smart wallets support batched calls in a single transaction via the Safe's `multiSend` capability.
+
+```typescript
+import { encodeFunctionData } from "viem";
+
+const erc20Abi = [
+ {
+ name: "transfer",
+ type: "function",
+ stateMutability: "nonpayable",
+ inputs: [
+ { name: "to", type: "address" },
+ { name: "amount", type: "uint256" },
+ ],
+ outputs: [{ name: "", type: "bool" }],
+ },
+] as const;
+
+async function batchTransfer(smartWallet: ConnectedWallet) {
+ const provider = await smartWallet.getEthereumProvider();
+
+ // Privy smart wallets support eth_sendTransaction with batch encoding
+ // through the Safe's built-in multiSend
+ const walletClient = createWalletClient({
+ chain: base,
+ transport: custom(provider),
+ });
+
+ const [account] = await walletClient.getAddresses();
+ const TOKEN = "0xTokenAddress..." as `0x${string}`;
+
+ const hash = await walletClient.sendTransaction({
+ account,
+ to: TOKEN,
+ data: encodeFunctionData({
+ abi: erc20Abi,
+ functionName: "transfer",
+ args: [
+ "0xRecipient1..." as `0x${string}`,
+ 1000000n, // 1 USDC (6 decimals)
+ ],
+ }),
+ });
+
+ return hash;
+}
+```
+
+## Notes
+
+- **Smart wallet address differs from embedded wallet address.** The embedded wallet (EOA) is the owner/signer of the Safe smart wallet. Send funds to the smart wallet address, not the EOA.
+- **Gas sponsorship** is configured in the Privy dashboard under your app's gas policy. On testnets, Privy sponsors gas by default. On mainnet, you configure sponsorship rules (per-user limits, allowlisted contracts, etc.).
+- **Smart wallets are deployed lazily.** The Safe contract is deployed on the user's first transaction, not at wallet creation time. The address is deterministic (CREATE2) so it can receive funds before deployment.
+- **The Safe smart wallet is a 1-of-1 multisig** with the Privy embedded wallet as the sole owner. For multi-owner Safe setups, use the Safe SDK directly with the Privy embedded wallet as one of the signers (see the `safe` skill).
+- **Chain support:** Smart wallets work on any EVM chain in your `supportedChains` config. The same smart wallet address is valid across all chains (counterfactual deployment).
diff --git a/skills/privy/examples/social-login/README.md b/skills/privy/examples/social-login/README.md
new file mode 100644
index 0000000..4ada631
--- /dev/null
+++ b/skills/privy/examples/social-login/README.md
@@ -0,0 +1,161 @@
+# Social Login with Privy
+
+Working TypeScript/React example for a Next.js app with Google and email login, displaying authenticated user state and embedded wallet address.
+
+## Dependencies
+
+```bash
+npm install @privy-io/react-auth next react react-dom
+```
+
+## Environment Variables
+
+```bash
+# .env.local
+NEXT_PUBLIC_PRIVY_APP_ID=your-privy-app-id # From dashboard.privy.io
+```
+
+## Provider Setup
+
+```tsx
+// app/providers.tsx
+"use client";
+
+import { PrivyProvider } from "@privy-io/react-auth";
+import { mainnet, base } from "viem/chains";
+import type { ReactNode } from "react";
+
+export function Providers({ children }: { children: ReactNode }) {
+ return (
+ Smart Wallet (Safe)
+ +-
+
- Smart Wallet Address +
{smartWallet.address}
+
+ {embeddedWallet && (
+ <>
+ - Signer (EOA) +
{embeddedWallet.address}
+
+ )}
+
+ The smart wallet address is a Safe contract owned by your embedded + wallet. Transactions are sponsored -- you pay zero gas. +
+ + + + {txHash && explorerUrl && ( ++ Transaction: {" "} + + View on BaseScan + +
+ )} + + {error && ( +
+
+ )}
+ {error}
+Loading Privy...
;
+ }
+
+ if (!authenticated) {
+ return (
+
+
+ );
+ }
+
+ const embeddedWallet = wallets.find(
+ (w) => w.walletClientType === "privy"
+ );
+
+ const displayEmail = user?.email?.address;
+ const displayGoogle = user?.google?.email;
+
+ return (
+ Welcome
+Sign in with your email or Google account.
+ +
+
+
+
+
+
+
+
+
+ );
+}
+```
+
+## Notes
+
+- The `PrivyProvider` must be in a Client Component (`"use client"`) for Next.js App Router.
+- `createOnLogin: 'all-users'` creates an embedded wallet for every user, including those who logged in with an external wallet. Use `'users-without-wallets'` to skip wallet creation for users connecting MetaMask, etc.
+- The login modal appearance (theme, accent color, logo) is configured in the `appearance` object. You can also configure this in the Privy dashboard.
+- Always check `ready` from both `usePrivy()` and `useWallets()` before rendering wallet-dependent UI.
+- HTTPS is required in production. `localhost` works for local development.
From 0a4e179257295ae300cf0318d295fdf95b3cdca5 Mon Sep 17 00:00:00 2001
From: 0xinit <28729137+0xinit@users.noreply.github.com>
Date: Mon, 2 Mar 2026 11:52:39 -0800
Subject: [PATCH 07/20] feat: add privy docs and resources
---
skills/privy/docs/troubleshooting.md | 140 ++++++++++++++++++++++++
skills/privy/resources/auth-methods.md | 95 ++++++++++++++++
skills/privy/resources/error-codes.md | 52 +++++++++
skills/privy/resources/sdk-reference.md | 100 +++++++++++++++++
4 files changed, 387 insertions(+)
create mode 100644 skills/privy/docs/troubleshooting.md
create mode 100644 skills/privy/resources/auth-methods.md
create mode 100644 skills/privy/resources/error-codes.md
create mode 100644 skills/privy/resources/sdk-reference.md
diff --git a/skills/privy/docs/troubleshooting.md b/skills/privy/docs/troubleshooting.md
new file mode 100644
index 0000000..57a22ea
--- /dev/null
+++ b/skills/privy/docs/troubleshooting.md
@@ -0,0 +1,140 @@
+# Privy Troubleshooting
+
+Common issues when integrating Privy's React SDK, embedded wallets, and server-side auth.
+
+## HTTPS / Secure Context Errors
+
+**Symptom:** SDK initializes but wallet creation or signing silently fails. No error in console.
+
+**Cause:** Web Crypto API requires a secure context. `http://` origins (except `localhost`) are not secure contexts.
+
+**Fix:**
+- Local dev: use `localhost` (not `127.0.0.1` or `192.168.x.x` over HTTP)
+- Staging/production: always HTTPS
+- If using a tunnel (ngrok, cloudflared), ensure the tunnel URL is HTTPS
+
+```bash
+# ngrok provides HTTPS automatically
+ngrok http 3000
+```
+
+## Embedded Wallet Not Created After Login
+
+**Symptom:** User logs in successfully but `useWallets()` returns empty array. `useEmbeddedWallet()` shows `not-created`.
+
+**Causes and fixes:**
+
+1. **`createOnLogin` not set:** Default is `'off'`. Set to `'all-users'` or `'users-without-wallets'`.
+2. **Farcaster login with `'users-without-wallets'`:** Farcaster accounts have a custody wallet, so Privy skips embedded wallet creation. Use `'all-users'` instead.
+3. **Checking too early:** Wallet creation is async. Wait for `useWallets()` `ready === true`.
+
+```typescript
+const { ready, wallets } = useWallets();
+// Do NOT check wallets until ready === true
+if (!ready) return Dashboard
+ +Account
+-
+
- User ID +
- {user?.id} + + {displayEmail && ( + <> +
- {displayEmail} + + )} + + {displayGoogle && ( + <> +
- {displayGoogle} + + )} + +
- Linked accounts +
- {user?.linkedAccounts.length ?? 0} +
Embedded Wallet
+ {!walletsReady ? ( +Loading wallet...
+ ) : embeddedWallet ? ( +-
+
- Address +
{embeddedWallet.address}
+ - Chain ID +
- {embeddedWallet.chainId} +
No embedded wallet found.
+ )} +Loading...
;
+```
+
+## Solana Wallet Created Before EVM
+
+**Symptom:** EVM embedded wallet cannot be created. `createWallet()` for EVM throws error.
+
+**Cause:** Creating a Solana embedded wallet first permanently blocks EVM wallet creation for that user.
+
+**Fix:** No fix for affected users -- they must create a new account. Prevent this by:
+- Using `createOnLogin: 'all-users'` (creates both in correct order)
+- If creating manually, always create EVM first: `createWallet({ type: 'ethereum' })` before `createWallet({ type: 'solana' })`
+
+## JWT Verification Failures
+
+**Symptom:** `verifyAuthToken` throws "Invalid token" or returns unexpected results.
+
+**Common causes:**
+
+1. **Using identity token instead of access token:** `verifyAuthToken` only works with access tokens. For identity tokens, use `getUser({ idToken })`.
+
+```typescript
+// Access token (from getAccessToken on client)
+const claims = await privy.verifyAuthToken(accessToken);
+
+// Identity token (from getIdToken on client)
+const user = await privy.getUser({ idToken: identityToken });
+```
+
+2. **Using app ID instead of app secret:** Server-side `PrivyClient` requires both app ID AND app secret.
+
+```typescript
+const privy = new PrivyClient(
+ process.env.PRIVY_APP_ID!, // "clx..." format
+ process.env.PRIVY_APP_SECRET! // "secret-..." format
+);
+```
+
+3. **Token expired:** Access tokens have short TTLs. Call `getAccessToken()` on the client before each API request -- it auto-refreshes.
+
+## v3 Solana Peer Dependency Errors
+
+**Symptom:** `npm install` fails with peer dependency conflicts mentioning `@solana/web3.js`.
+
+**Cause:** Privy v3 migrated from `@solana/web3.js` to `@solana/kit`.
+
+**Fix:**
+
+```bash
+npm uninstall @solana/web3.js
+npm install @solana/kit
+```
+
+Update imports:
+
+```typescript
+// Before (v2)
+import { Connection, PublicKey } from "@solana/web3.js";
+
+// After (v3)
+import { createSolanaRpc, address } from "@solana/kit";
+```
+
+## Wallet Not Ready After Authentication
+
+**Symptom:** `authenticated === true` but signing transactions throws "wallet not ready".
+
+**Cause:** Authentication and wallet initialization are separate async operations.
+
+**Fix:** Check both `authenticated` and wallet `ready` state:
+
+```typescript
+const { authenticated } = usePrivy();
+const { ready: walletsReady, wallets } = useWallets();
+
+const canTransact = authenticated && walletsReady && wallets.length > 0;
+```
+
+## WalletConnect Not Working
+
+**Symptom:** External mobile wallets cannot connect. No WalletConnect QR code shown.
+
+**Cause:** Privy does not include WalletConnect by default.
+
+**Fix:** Add WalletConnect project ID to your Privy config:
+
+```typescript
+
+
+ `;
+
+ document.getElementById("share-btn")!.addEventListener("click", () => {
+ sdk.actions.composeCast({
+ text: `I'm using this Mini App!`,
+ embeds: ["https://myapp.example.com"],
+ });
+ });
+
+ document.getElementById("add-btn")!.addEventListener("click", () => {
+ sdk.actions.addFrame();
+ });
+
+ sdk.actions.ready();
+}
+
+main().catch(console.error);
+```
+
+## Notes
+
+- The `fc:frame` meta tag must be valid JSON in the `content` attribute -- malformed JSON silently breaks frame detection
+- `sdk.actions.ready()` must be called for the splash screen to dismiss. If omitted, the app appears stuck on the splash screen
+- Mini Apps run in a sandboxed iframe -- `window.top` access is blocked
+- The `context.user` object is provided by the hosting client (Warpcast) and represents the currently logged-in user viewing the app
+- Test locally with the Warpcast developer tools or the Frames Debugger at `https://debugger.framesjs.org`
diff --git a/skills/farcaster/examples/neynar-feed/README.md b/skills/farcaster/examples/neynar-feed/README.md
new file mode 100644
index 0000000..784716f
--- /dev/null
+++ b/skills/farcaster/examples/neynar-feed/README.md
@@ -0,0 +1,170 @@
+# Fetch and Display a Farcaster Feed
+
+Working TypeScript example for fetching a user's Farcaster feed using the Neynar API v2 SDK, including user lookup and cast rendering.
+
+## Dependencies
+
+```bash
+npm install @neynar/nodejs-sdk
+```
+
+## Setup
+
+```typescript
+import { NeynarAPIClient, Configuration } from "@neynar/nodejs-sdk";
+
+const config = new Configuration({
+ apiKey: process.env.NEYNAR_API_KEY,
+});
+
+const neynar = new NeynarAPIClient(config);
+```
+
+## Fetch User Profile
+
+```typescript
+interface UserProfile {
+ fid: number;
+ username: string;
+ displayName: string;
+ bio: string;
+ followerCount: number;
+ followingCount: number;
+ pfpUrl: string;
+}
+
+async function getUserProfile(fid: number): Promise
+ 
+
+
+
+
+
+ ${user.displayName}
+ @${user.username} (FID: ${user.fid})
+
+
+ `;
+
+ document.getElementById("send-btn")!.addEventListener("click", async () => {
+ const status = document.getElementById("status")!;
+ status.textContent = "Confirming...";
+
+ try {
+ const hash = await walletClient.sendTransaction({
+ account: address,
+ to: "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045" as Address,
+ value: parseEther("0.001"),
+ });
+ status.textContent = `Sent! Hash: ${hash}`;
+ } catch (err) {
+ status.textContent = `Error: ${err instanceof Error ? err.message : "Unknown"}`;
+ }
+ });
+
+ sdk.actions.ready();
+}
+
+main().catch(console.error);
+```
+
+## Notes
+
+- The wallet provider is only available inside a Farcaster client (Warpcast). Testing outside a client will throw
+- `sdk.wallet.ethProvider` follows EIP-1193 -- it works with viem's `custom()` transport and wagmi connectors
+- Users must confirm transactions in their Farcaster client's wallet UI before they are broadcast
+- Always check `receipt.status` after `waitForTransactionReceipt` -- a mined transaction can still have reverted
+- The connected chain depends on the Farcaster client's wallet configuration. Use `wallet_switchEthereumChain` to request a specific chain if needed
+- Token amounts must use `bigint`, not JavaScript `number`, to avoid precision loss
diff --git a/skills/farcaster/examples/webhook-listener/README.md b/skills/farcaster/examples/webhook-listener/README.md
new file mode 100644
index 0000000..6e305aa
--- /dev/null
+++ b/skills/farcaster/examples/webhook-listener/README.md
@@ -0,0 +1,195 @@
+# Neynar Webhook Listener
+
+Working TypeScript example for an Express server that receives Neynar webhook events with complete HMAC-SHA512 signature verification.
+
+## Dependencies
+
+```bash
+npm install express @neynar/nodejs-sdk
+npm install -D @types/express typescript
+```
+
+## Webhook Signature Verification
+
+Neynar signs every webhook delivery with HMAC-SHA512 using your webhook secret. The signature is sent in the `X-Neynar-Signature` header as a hex string.
+
+Verification MUST happen before JSON parsing. Use the raw request body bytes for HMAC computation.
+
+```typescript
+import crypto from "node:crypto";
+import type { IncomingHttpHeaders } from "node:http";
+
+function verifyNeynarWebhook(
+ rawBody: Buffer,
+ headers: IncomingHttpHeaders,
+ webhookSecret: string
+): boolean {
+ const signature = headers["x-neynar-signature"];
+ if (typeof signature !== "string") return false;
+
+ const hmac = crypto.createHmac("sha512", webhookSecret);
+ hmac.update(rawBody);
+ const computedSignature = hmac.digest("hex");
+
+ // Both must be the same length for timingSafeEqual
+ const sigBuffer = Buffer.from(signature, "hex");
+ const computedBuffer = Buffer.from(computedSignature, "hex");
+ if (sigBuffer.length !== computedBuffer.length) return false;
+
+ return crypto.timingSafeEqual(sigBuffer, computedBuffer);
+}
+```
+
+## Webhook Event Types
+
+| Event Type | Description |
+|-----------|-------------|
+| `cast.created` | New cast published |
+| `cast.deleted` | Cast removed by author |
+| `reaction.created` | Like or recast added |
+| `reaction.deleted` | Like or recast removed |
+| `follow.created` | User followed another user |
+| `follow.deleted` | User unfollowed another user |
+| `user.created` | New FID registered |
+| `user.updated` | User profile updated |
+
+## Express Server
+
+```typescript
+import express from "express";
+import crypto from "node:crypto";
+
+const app = express();
+const WEBHOOK_SECRET = process.env.NEYNAR_WEBHOOK_SECRET;
+
+if (!WEBHOOK_SECRET) {
+ throw new Error("NEYNAR_WEBHOOK_SECRET environment variable is required");
+}
+
+// Raw body middleware -- ONLY on the webhook route
+// Global express.json() would parse the body and break signature verification
+app.use("/api/webhook", express.raw({ type: "application/json" }));
+
+// Use express.json() for all other routes
+app.use(express.json());
+
+interface WebhookEvent {
+ created_at: number;
+ type: string;
+ data: RecordConnected: ${address.slice(0, 6)}...${address.slice(-4)}
+User: @${context.user.username} (FID: ${context.user.fid})
+ + +