Building a Farcaster Mini App

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 Mini App. This means you can easily integrate Privy with Farcaster Mini Apps to compose experiences with a user’s existing social graph or network.

Here’s how!

Privy supports Farcaster auth addresses, including authentication from The Base App. To authenticate a user, pass a Sign-In With Farcaster (SIWF) message signed by an auth address to loginToMiniApp.

Mini Apps starter

A starter repository for building a Farcaster Mini App with Privy and the Mini Apps SDK.

Show How does seamless Farcaster login work in a Mini App?

Privy uses a standard called Sign in with Farcaster (FIP-11) to issue a signature request to a user’s Farcaster account via the client the user has.

The Mini Apps spec introduces a new sdk.actions.signIn action. This will produce the same FIP-11 conformant signature automatically on the Farcaster mobile app.

The sdk.actions.signIn action, in combination with the Privy useLoginToMiniApp hook, provides a seamless login experience that automatically and securely authenticates a user on Farcaster.

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 and cookies

When building a Farcaster Mini App, you must include https://farcaster.xyz as an allowed domain. Allowed domains is required for iframe-in-iframe which Farcaster uses, even for staging environments.

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://farcaster.xyz as an allowed domain. Including Farcaster as an allowed domain allows the Privy iframe, where the embedded wallet is hosted, to load in the Farcaster browser app.

Use an appClient to override the default cookie settings.

Currently Mini Apps do not support httpOnly cookies. If you have httpOnly cookies enabled for your app, it is recommended to set up an appClient to override the default cookie settings. Learn more about appClients here.

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 Mini Apps SDK

Use loginToMiniApp from useLoginToMiniApp for proper Farcaster Mini App authentication (not Farcaster’s quick auth).

In your app, install the @farcaster/miniapp-sdk:

npm install @farcaster/miniapp-sdk

Privy now supports authentication with Farcaster auth addresses, including from the new Base app!

To authenticate with an auth address, pass a SIWF message signed by an auth address to loginToMiniApp from useLoginToMiniApp. This can be done by fetching a signature from an external wallet, the Farcaster Wallet, or in an app with mini app support (such as the Base app) by calling miniappSdk.actions.signIn.

Automatic embedded wallet creation is currently not supported for Farcaster Mini Apps. You have two options: use the wallet that clients like the Farcaster app and The Base App automatically inject (recommended), or manually create embedded wallets at your chosen onboarding point.

import miniappSdk from '@farcaster/miniapp-sdk';
import {usePrivy} from '@privy-io/react-auth';
import {useLoginToMiniApp} from '@privy-io/react-auth/farcaster';
...

const {ready, authenticated} = usePrivy();
const {initLoginToMiniApp, loginToMiniApp} = useLoginToMiniApp();

// Login to Mini App 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 initLoginToMiniApp();
      // Request a signature from Farcaster
      const result = await miniappSdk.actions.signIn({nonce});
      // Send the received signature from Farcaster to Privy for authentication
      // or pass a SIWF message signed by an auth address
      await loginToMiniApp({
        message: result.message,
        signature: result.signature,
      });
    };
    login();
  }
}, [ready, authenticated]);

The Base App (TBA) Special Requirement: If your users are accessing your Mini App through The Base App, they must add their The Base App Wallet address as an auth address to their Farcaster account for authentication to work properly.

Always check that ready and authenticated from the usePrivy hook are true before taking actions!

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 Mini App. When building out your Mini App, be sure to visit Farcaster’s resources page for help with testing and common issues!