Building a Farcaster Frame

Farcaster is a sufficiently decentralized social network whose core social graph is stored on-chain. Users can choose how content they create is stored and it enables unique, composable experiences by enabling users to link their accounts with a wallet of their choosing.

Privy enables seamless login with your user’s Farcaster account within a Frame. This means you can easily integrate Privy with Farcaster frames to compose experiences with a user’s existing social graph or network.

Here’s how!

​

1. Enable Farcaster login in your dashboard

Go to your app in your developer dashboard and navigate to User management > Authentication > Socials. From here, enable Farcaster as a social option.

This will enable you to configure Farcaster as a login and account linking option in your app.

​

2. Configure your allowed domains

Go to the Domains tab of your Configuration > App settings page in the developer dashboard and configure allowed domains for your app. This is the URL that your app is deployed to.

To use the embedded wallet, your application must also include https://warpcast.com as an allowed domain. Including Warpcast as an allowed domain allows the Privy iframe, where the embedded wallet is hosted, to load in the Warpcast browser app.

​

3. Configure your app’s Farcaster integration

The following assumes you have set up Privy with your app. If you haven’t, start by following the instructions in the Privy Quickstart to get your app set up with Privy.

Be sure to configure 'farcaster' as an upfront login method in your PrivyProvider, like so:

<PrivyProvider
  appId={process.env.NEXT_PUBLIC_PRIVY_APP_ID}
  config={{
    loginMethods: ['farcaster', ...insertTheRestOfYourLoginMethods]
    ...insertTheRestOfYourPrivyProviderConfig
  }}
>

​

4. Setup seamless Farcaster login with the Frames SDK

In your app, install the @farcaster/frame-sdk.

Add the below useEffect to your main frame page. This will automatically log a user in, if they are not already authenticated.

import frameSdk, { type FrameContext } from "@farcaster/frame-sdk";
import { usePrivy } from "@privy-io/react-auth";
import { useLoginToFrame } from "@privy-io/react-auth/farcaster";

...

const { ready, authenticated } = usePrivy();
const { initLoginToFrame, loginToFrame } = useLoginToFrame();

...

// Login to Frame with Privy automatically
useEffect(() => {
  if (ready && !authenticated) {
    const login = async () => {
      // Initialize a new login attempt to get a nonce for the Farcaster wallet to sign
      const { nonce } = await initLoginToFrame();
      // Request a signature from Warpcast
      const result = await frameSdk.actions.signIn({ nonce: nonce });
      // Send the received signature from Warpcast to Privy for authentication
      await loginToFrame({
        message: result.message,
        signature: result.signature,
      });
    };
    login();
  }
}, [ready, authenticated]);

Once a user has logged in with or linked their Farcaster account, you can find their Farcaster object, including their fid, username, pfp and more, in the user object returned by the usePrivy hook.

That’s it! You can now use this to power composable experiences in your new frame. When building out your frame, be sure to visit Farcaster’s resources page for help with testing and common issues!