Farcaster Login
Farcaster Login
#Overview
Provide users the ability to log into your app via Farcaster. This login method allows Farcaster users to login with their account and create a Magic wallet associated to their digital Farcaster Identifier (FID). Developers can access Farcaster user information such as fid and username, along with Magic metadata.
#Compatibility
Farcaster Login is only available with Dedicated Wallet, available as of magic-sdk@28.0.7.
#Use Cases
- Authenticate and create wallets for end users by prompting users to login via Farcaster native app.
#Usage
You can implement Farcaster Login by including the Farcaster extension to your Magic instance. Once you've created a Magic client-side instance with the extension, log users in by calling magicClient.farcaster.login(). You can pass a showUI parameter boolean indicating whether or not to show a pre-built modal interface displaying the QR code to the user. When false, you can implement a custom UI to continue the Farcaster login.
Once logged in, you can retrieve the user's Magic wallet address using getInfo for Web/React Native.
#Login
Farcaster Login works as an extension to Magic SDK. To add Farcaster Login to your Magic integration, start by installing the Farcaster Extension:
01npm install magic-sdk @magic-ext/farcaster
#Initialization
When creating your Magic instance, you'll need to add an instance of FarcasterExtension to the Magic constructor:
01import { Magic } from 'magic-sdk';
02import { FarcasterExtension } from '@magic-ext/farcaster';
03
04// Must use a Dedicated Wallet API Key
05const magic = new Magic('YOUR_API_KEY', {
06 extensions: [new FarcasterExtension()],
07});
#Arguments
showUI?(Boolean): Iftrue, show an out-of-the-box UI to display the QR code to the user. Defaults totrue.
#Returns
PromiEvent<string | null>: The promise resolves upon authentication request success and rejects with a specific error code if the request fails. The resolved value is a Decentralized ID token with a default 15-minute lifespan.
#Example
01import { Magic } from 'magic-sdk';
02import { FarcasterExtension } from '@magic-ext/farcaster';
03
04const magic = new Magic('YOUR_API_KEY', {
05 extensions: [new FarcasterExtension()],
06});
07
08try {
09 await magic.farcaster.login();
10} catch {
11 // Handle errors or reject if required!
12}
13
14try {
15 const didToken = await magic.farcaster.login({ showUI: false });
16} catch {
17 // Handle errors if required!
18}
#Event Handling
A white-label Farcaster Login flow is available when passing showUI: false to this login method. Here's a short example to illustrate listening for and emitting events during the login flow:
01import { Magic } from 'magic-sdk';
02import { FarcasterExtension } from '@magic-ext/farcaster';
03
04const magic = new Magic('YOUR_API_KEY', {
05 extensions: [new FarcasterExtension()],
06});
07
08try {
09 const handle = magic.farcaster.login({ showUI: false });
10
11 handle
12 .on("channel", (channel) => {
13 console.log("channel URL", channel.url)
14 // display custom UI with QR code
15 })
16 .on("success", (data) => {
17 // get Farcaster user information
18 })
19 .on('done', (did) => {
20 // get DID Token
21 .on("failed", (e) => {
22 // user rejects
23 })
24 .on('error', (e) => {
25 // handle error
26 }
27 .on('settled', (e) => {
28 // handle resolve or reject
29 }
30} catch (err) {
31 // handle errors
32}