Farcaster - Privy docs

Farcaster is a sufficiently decentralized social network whose core social graph is stored onchain. Privy enables your users to log in to your application using their Farcaster account. 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 a user has. Warpcast is currently supported.

Your application can even request permissions from the user to become a signer for their Farcaster account, allowing your application to engage with the Farcaster social graph on their behalf.

Interested in building a Farcaster frame? Check out our Farcaster frames recipe!

Privy currently only supports Farcaster login in React via the Privy UIs. To enable Farcaster login, you need to configure the Privy SDK with the farcaster login method.

<PrivyProvider
  appId={process.env.NEXT_PUBLIC_PRIVY_APP_ID}
  config={{
    // This configures farcaster and other login methods for your app.
    appearance: {
        loginMethods: ['farcaster', ...otherLoginMethods]
    },
    ...otherConfig
  }}
>

From there, you can prompt your users to authenticate via the login method:

import { usePrivy } from '@privy-io/react';
...
const { login } = usePrivy();
login();

Privy currently only supports Farcaster login in React via the Privy UIs. To enable Farcaster login, you need to configure the Privy SDK with the farcaster login method.

<PrivyProvider
  appId={process.env.NEXT_PUBLIC_PRIVY_APP_ID}
  config={{
    // This configures farcaster and other login methods for your app.
    appearance: {
        loginMethods: ['farcaster', ...otherLoginMethods]
    },
    ...otherConfig
  }}
>

From there, you can prompt your users to authenticate via the login method:

import { usePrivy } from '@privy-io/react';
...
const { login } = usePrivy();
login();

To authenticate a user via Farcaster (SIWF), use the loginWithFarcaster method from the useLoginWithFarcaster hook.

loginWithFarcaster(input: {
  relyingParty: string;
  redirectUrl?: string;
  disableSignup?: boolean;
}, config?: {
  pollIntervalMs?: number;
  pollAttempts?: number;
}): Promise<PrivyUser | null>;

To initialize login, use the loginWithFarcaster function from the useLoginWithFarcaster hook to start the Farcaster login flow.

import { useLoginWithFarcaster } from '@privy-io/expo';

const { loginWithFarcaster, state } = useLoginWithFarcaster();

As a parameter to loginWithFarcaster, you should pass an object containing:

input.relyingParty

string

required

Your app’s website. Described in SIWF spec as “Origin domain of app frontend.”

input.redirectUrl

string

A URL path that Warpcast will automatically redirect to after successful authentication. This defaults to a link back to your app root, eg. '/', if not provided.

If true, the flow will only allow existing users to log in, preventing new account creation.

options.pollIntervalMs

number

The interval in milliseconds which your app will poll a status endpoint to check if the user has successfully signed in using Warpcast.

options.pollAttempts

number

The number of polling attempts that will be made to check for successful login.

If you pass in custom polling configuration, make sure to give the user enough time to go through the login process on Warpcast. The default values are pollIntervalMs = 1000 and pollAttempts = 10 giving the user 10 seconds to go through the login process. In our testing, this is usually enough time, but you may want to make it longer.

When this method is invoked, the user will be deeplinked to the Warpcast app on their device if they have it installed, or an installation page for the app. Within the Warpcast app, they can complete the login flow.

If loginWithFarcaster succeeds, it will return a PrivyUser object with details about the authenticated user.

Reasons loginWithFarcaster might fail include:

the network request fails
the login attempt is made after the user is already logged in
the user cancels the login flow after being linked out to Warpcast
the user takes too long to login and the polling time expires

Tracking Flow State

Track the state of the Farcaster flow via the state variable returned by the useLoginWithFarcaster hook.

state:
  | {status: 'initial'}
  | {status: 'error'; error: Error | null}
  | {status: 'generating-uri'}
  | {status: 'awaiting-uri'}
  | {status: 'polling-status'}
  | {status: 'submitting-token'}
  | {status: 'done'};

status

The current state of the Farcaster flow.

error

Error | null

The error that occurred during the Farcaster flow (only present when status is ‘error’).

Usage: Conditional Rendering

import { View, ActivityIndicator, Text } from 'react-native';
import { useLoginWithFarcaster, hasError } from '@privy-io/expo';

export function LoginScreen() {
  const { state, loginWithFarcaster } = useLoginWithFarcaster();

  return (
    <View>
      <Button
        onPress={() => loginWithFarcaster({ relyingParty: 'https://example.app' })}
        title="Login with Farcaster"
        disabled={state.status !== 'initial' && state.status !== 'error'}
      />

      {state.status === 'polling-status' && (
        <View>
          <ActivityIndicator />
          <Text>Waiting for Warpcast confirmation...</Text>
        </View>
      )}

      {hasError(state) && (
        <Text style={{ color: 'red' }}>
          Error: {state.error.message}
        </Text>
      )}
    </View>
  );
}

Callbacks

You can optionally pass callbacks to the useLoginWithFarcaster hook to run custom logic after a successful login or to handle errors.

`onSuccess`

onSuccess: (user: PrivyUser, isNewUser: boolean) => Promise<void>

Parameters

user

PrivyUser

The user object returned after successful login.

isNewUser

boolean

Whether the user is a new user or an existing user.

`onError`

onError: (error: Error) => Promise<void>

Parameters

error

Error

The error that occurred during the Farcaster flow.

Usage with Callbacks

import { useLoginWithFarcaster } from '@privy-io/expo';

export function LoginScreen() {
  const { loginWithFarcaster } = useLoginWithFarcaster({
    onSuccess(user, isNewUser) {
      console.log('Login successful', { user, isNewUser });
      // Navigate to home screen, show welcome message, etc.
    },
    onError(error) {
      console.error('Login failed', error);
      // Show error toast, update UI, etc.
    }
  });

  return (
    <Button
      onPress={() => loginWithFarcaster({ relyingParty: 'https://example.app' })}
      title="Login with Farcaster"
    />
  );
}

User authentication

​Initializing the login flow

​Tracking Flow State

​Usage: Conditional Rendering

​Callbacks

​onSuccess

Parameters

​onError

Parameters

​Usage with Callbacks

Initializing the login flow

Tracking Flow State

Usage: Conditional Rendering

Callbacks

`onSuccess`

`onError`

Usage with Callbacks