Farcaster Mini Apps: Exclusive, Effortless Auth & Wallets.

Farcaster Frames v2 turns simple posts into mini apps that run inside clients like Warpcast. A frame can render a dynamic image, accept input, verify the user, and trigger onchain actions. This guide shows how to get your mini app discovered, handle secure auth, and ship wallet flows that users trust.

What Frames v2 changes

Frames v1 proved the format. Frames v2 adds deeper interactivity and a clearer contract between the client and your server. You publish a URL with Open Graph tags. The client fetches it, renders the frame image, and posts user events to your endpoints. You return the next state, or a transaction request. The loop feels like a chat between your app and the client.

Distribution: how people find and keep using your frame

Distribution on Farcaster is social-first. The best frames spread through casts, channels, and embeds. Plan for repeat use and quick sharing from day one.

1. Seed the first cast with a tight pitch and a visual cue in the frame image. Show the core action in one glance.
2. Post in the most relevant channel. Pin an explainer cast that answers “what it does” in one sentence.
3. Give power users a reason to recast. Add a tiny reward, leaderboard, or fresh daily state.
4. Add deep links. A URL with prefilled params lets creators share “their” version of your frame.
5. Ship a fallback web page. Outside Farcaster, the link should load a plain web view with the same action.

After launch, keep a cadence. Refresh the frame art for events, add small modes, and reply to top feedback threads. A frame that changes earns another round of casts.

More channels that work

A few lightweight tactics push reliable traffic without spam. Pick the ones that fit your app and audience.

• Profile link and bio banner. Give the URL a short slug and a clear emoji cue.
• Channel sidebar resource. Ask mods to list your frame if it adds value to that topic.
• QR poster for meetups. The frame opens inside the client on mobile with one tap.
• Mini demo cast. Record a 10-second screen capture of the full loop, from tap to result.

One small example: a “daily mint” frame placed a countdown on the image and reset at UTC. The cast kept resurfacing each morning because the visual state made the time pressure obvious.

Frame structure: endpoints and state

A frame is a set of HTTP endpoints that return HTML meta tags and JSON responses. You render state to an image URL and accept user events via POST. Store user state by Farcaster ID (FID) or by a signed token that the client sends. Keep responses under a second to avoid timeouts and drop-off.

Auth: proving user and intent

You usually need two checks: who the user is, and whether the client event is genuine. Frames v2 supports standard patterns that you can verify server-side without guesswork.

Pick the lightest method that matches the risk. For read-only views, skip auth. For rewards or writes, verify the client signature. For onchain perks, bind the FID to a wallet with SIWE or a signer map and cache it.

Wallet actions: safe transactions from a frame

Frames can request a transaction that the client routes to the user’s wallet. You return an unsigned transaction spec with chain ID, to, data, and value. The client shows a confirm screen, and the user signs in their wallet. After broadcast, the client can call your webhook or re-open the frame with the result.

Design the flow so the user sees cost and benefit upfront. Put price and chain on the image. Use a single call with clear intent instead of a multi-step wizard. For mints, precompute calldata server-side. For tips, show the exact recipient and fee.

Common wallet patterns that convert

Small design choices can lift completion rates. These patterns have worked well for frames that move real value.

• Chain default. Set Base or the chain you support as the default; avoid mid-flow switches.
• Gas hint. Display an estimated gas range like “~$0.12–$0.20”. Refresh it every few minutes.
• Post-tx state. After success, change the image to show the item owned or the points earned.
• Idempotency key. Include a server-generated key to prevent duplicate mints on retries.

Picture a “Support this cast” frame. The button shows “Tip 0.001 ETH on Base.” Tap opens the wallet confirm with a single transfer. After send, the frame image flips to “Thanks, you tipped 0.001 ETH,” and offers a share button.

Security checklist for frames

A few guardrails block fraud and broken states. Run these checks for every event and transaction request.

1. Verify the client signature and payload hash against the documented scheme.
2. Validate FID, cast ID, and timestamps. Reject if the payload is too old.
3. Bind user actions to your session store. Use short-lived tokens per step.
4. For TX requests, recalc calldata server-side and compare before returning.
5. Add rate limits per IP and per FID. Log denials with reasons for review.

These checks cost little to run and save you from replay attacks or scripted drains. Keep logs for audits and user support.

Minimal backend: what you need to host

You can ship a production-ready frame with a small stack. Aim for fast cold starts and low-latency image renders.

• Static HTML endpoint with Open Graph tags for the frame metadata and image URL.
• Action endpoint to process button clicks and input events.
• Image renderer (server-side canvas or templated PNG) that reads your state.
• Optional webhook to receive transaction results and update state.

Serverless works fine if you keep warm. If the image takes time, cache it behind a CDN and bust the cache on state changes.

Step-by-step: shipping your first mini app

Here is a clear path that keeps scope tight and helps you avoid the usual traps.

1. Define the single action. Write the button label before any code.
2. Set up the frame HTML with image, buttons, and action URLs.
3. Implement the action POST handler. Return the next frame state.
4. Add client signature verification and reject invalid payloads.
5. Render the image with the current state and a visible affordance.
6. If you need a wallet action, add a transaction endpoint and test on a testnet or a low-fee chain.
7. Track events: loads, clicks, conversions, unique FIDs.
8. Ship a cast with a crisp visual and one-line pitch. Gather feedback in-thread.

Keep your first loop simple. You can add custom input, pagination, or multi-step flows after you see real users complete the core action.

Metrics that matter

Frames live or die on completion. Vanity views do not help. Watch these numbers in your logs or analytics.

• Click-through rate from cast view to first frame action
• Completion rate from first action to success state
• Median response time for action endpoint and image render
• Unique FIDs per day and 7-day repeat rate

As a rule of thumb, aim for sub-700 ms action responses and image loads under 300 ms from cache. Longer waits hurt taps by a lot.

Testing and rollout

Test with a small group before a channel blast. Use a hidden cast or a direct link and collect screenshots of failures. Check how your frame looks on dark mode, low bandwidth, and with slow wallets. Stage a mock chain outage and confirm that you show a clean error with a retry path.

Final notes

Farcaster Frames v2 gives you a lightweight app surface with social distribution built in. Keep the core action sharp, verify every event, and present wallet steps with plain details. With these pieces in place, your mini app can travel fast across casts and still feel safe to use.