Farcaster APIs by Neynar

Farcaster is a protocol for building decentralized social apps. Neynar makes it easy to build on Farcaster.

Basic understanding of Farcaster

Farcaster is a decentralized social protocol. Here are three short bullets on the primary Farcaster primitives that will be helpful to keep in mind as you dive in:

User - every user on Farcaster is represented by a permanent FID that is the numerical identifier for the user. All user profile data for this FID e.g. username, display name, bio, etc. are stored on Farcaster protocol and mapped to this FID.
Casts - users can broadcast information to the protocol in units of information called "casts". It's somewhat similar to a tweet on Twitter/X. Each cast has a unique "hash".
Followers / following - users can follow each other to see casts from them. This creates a social graph for each user on Farcaster.

There's obviously more to this but let's start with this. All the above data is open and decentralized, available on Farcaster nodes called hubs. Neynar makes interfacing with this data relatively trivial.

In this tutorial, we will learn how use the above primitives to fetch a simple feed of casts for a given user.

Get Neynar API key

Don't have an API key yet? Register now at neynar.com.

Click "Subscribe now."
You will be redirected to a Stripe checkout page.
Upon successful payment, we'll send you an email. Once the email arrives, you'll be able to sign in to the Developer Portal

Don't hesitate to reach out to us on our channel or Telegram with any questions!

Set up Neynar SDK

Neynar nodejs SDK is an easy way to use the APIs. This section only needs to be done once when setting up the SDK for the first time.

To install the Neynar TypeScript SDK:

yarn add @neynar/nodejs-sdk

npm install @neynar/nodejs-sdk

pnpm install @neynar/nodejs-sdk

bun add @neynar/nodejs-sdk

To get started, initialize the client in a file named index.ts:

import { NeynarAPIClient, Configuration } from "@neynar/nodejs-sdk";

const config = new Configuration({
  apiKey: process.env.NEYNAR_API_KEY,
});

// make sure to set your NEYNAR_API_KEY .env
// for testing purposes, you can insert your key as a string param into NeynarAPIClient
const client = new NeynarAPIClient(config);

Depending on your build environment, you might also need the following two steps:

check the type field in package.json. Since we're using ES6 modules, you may need to set it to "module".

{
  "scripts": {
    "start": "node --loader ts-node/esm index.ts"
  },
  "type": "module", // <-- set to module if needed
  "dependencies": {
    // this is for illustration purposes, the version numbers will depend on when you do this tutorial
    "@neynar/nodejs-sdk": "^2.0.2", 
    "ts-node": "^10.9.2",
    "typescript": "^5.6.3"
  }
}

If you hit errors, try adding a tsconfig.json file in the directory to help with typescript compilation

{
    "compilerOptions": {
      "module": "ESNext",
      "moduleResolution": "node",
      "target": "ESNext",
      "esModuleInterop": true,
      "skipLibCheck": true
    },
    "ts-node": {
      "esm": true
    }
  }

Your directory should have the following:

node_modules
index.ts
package-lock.json
package.json
tsconfig.json (optional)
yarn.lock

Fetch Farcaster data using Neynar SDK

Fetching feed

To fetch the feed for a user, you need to know who the user is following and then fetch casts from those users. Neynar abstracts away all this complexity. Simply put in the fid of the user in the fetchFeed function and get a feed in response.

In this example, we will fetch the feed for Dan Romero . This is the feed Dan would see if he were to log into a client that showed a feed from people he followed in a reverse chronological order.

import { NeynarAPIClient, Configuration } from "@neynar/nodejs-sdk";
import { FeedType } from "@neynar/nodejs-sdk/build/api";

const config = new Configuration({
  apiKey: process.env.NEYNAR_API_KEY,
});

const client = new NeynarAPIClient(config);

// fetch feed of Dan Romero: fid 3
async function fetchFollowingFeed() {
  const feedType = FeedType.Following;
  const fid = 3;
  const limit = 1;

  const feed = await client.fetchFeed({
    fid,
    feedType,
    limit,
  });
  console.log("User Feed:", feed);
}

fetchFollowingFeed();

You can now run this code by opening up this folder in the terminal and running

yarn start

Depending on your machine, typescript might take a few seconds to compile. Once done, it should print the output to your console. Something like below:

User Feed: {
  "casts": [
    {
      "object": "cast",
      "hash": "0xd9993ef80c1a7f75c6f75de3b79bc8a18de89a30",
      "author": {
        "object": "user",
        "fid": 1265,
        "username": "akhil-bvs",
        "display_name": "Akhil",
        "pfp_url": "https://imagedelivery.net/BXluQx4ige9GuW0Ia56BHw/6f618f59-2290-4350-100a-4b5d10abef00/original",
        "custody_address": "0xdf055eb92e2c97d7da4036278d145458eb11811c",
        "profile": {
          "bio": {
            "text": "product @cooprecs | player /fbi"
          }
        },
        "follower_count": 1919,
        "following_count": 252,
        "verifications": [
          "0xab14023979a34b4abb17abd099a1de1dc452011a"
        ],
        "verified_addresses": {
          "eth_addresses": [
            "0xab14023979a34b4abb17abd099a1de1dc452011a"
          ],
          "sol_addresses": []
        },
        "verified_accounts": null,
        "power_badge": true,
        "viewer_context": {
          "following": true,
          "followed_by": true,
          "blocking": false,
          "blocked_by": false
        }
      },
      "thread_hash": "0xd9993ef80c1a7f75c6f75de3b79bc8a18de89a30",
      "parent_hash": null,
      "parent_url": null,
      "root_parent_url": null,
      "parent_author": {
        "fid": null
      },
      "text": "👀",
      "timestamp": "2024-11-22T17:39:21.000Z",
      "embeds": [
        {
          "cast_id": {
            "fid": 880094,
            "hash": "0x82e6e0e20539578dcb7e03addb94f3a7f7491c49"
          },
          "cast": {
            "object": "cast_embedded",
            "hash": "0x82e6e0e20539578dcb7e03addb94f3a7f7491c49",
            "author": {
              "object": "user_dehydrated",
              "fid": 880094,
              "username": "anoncast",
              "display_name": "anoncast",
              "pfp_url": "https://imagedelivery.net/BXluQx4ige9GuW0Ia56BHw/2c3250ee-e91d-4e8d-76b1-42d1c6ebef00/rectcrop3"
            },
            "thread_hash": "0x82e6e0e20539578dcb7e03addb94f3a7f7491c49",
            "parent_hash": null,
            "parent_url": null,
            "root_parent_url": null,
            "parent_author": {
              "fid": null
            },
            "text": "one day this account will be used by a whistleblower to release classified documents about government fuckery. this account will break the internet and be impossible for anyone to ignore.",
            "timestamp": "2024-11-22T16:35:36.000Z",
            "embeds": [],
            "channel": null
          }
        }
      ],
      "channel": null,
      "reactions": {
        "likes_count": 0,
        "recasts_count": 0,
        "likes": [],
        "recasts": []
      },
      "replies": {
        "count": 0
      },
      "mentioned_profiles": [],
      "viewer_context": {
        "liked": false,
        "recasted": false
      }
    }
  ],
  "next": {
    "cursor": "eyJ0aW1lc3RhbXAiOiIyMDI0LTExLTIyIDE3OjM5OjIxLjAwMDAwMDAifQ%3D%3D"
  }
}

You've successfully fetched the feed for a user in a simple function call!

Future reading: you can fetch many different kind of feeds. See Feed APIs.

Fetching user profile data

Now let's fetch data about a user. Remember users are represented by FIDs? We will take an FID and fetch data for that user. Here's how to do it using the SDK:

import { NeynarAPIClient, Configuration } from "@neynar/nodejs-sdk";
import { FeedType } from "@neynar/nodejs-sdk/build/api";

const config = new Configuration({
  apiKey:process.env.NEYNAR_API_KEY,
});

const client = new NeynarAPIClient(config);

// fetch feed of Dan Romero: fid 3
async function fetchUser() {
  const fids = [3];

  const { users } = await client.fetchBulkUsers({ fids });
  console.log("User :", users[0]);
}

fetchUser();

You can run this in your terminal similar to above by typing in:

yarn start

It should show you a response like below:

User : {
      "object": "user",
      "fid": 3,
      "username": "dwr.eth",
      "display_name": "Dan Romero",
      "pfp_url": "https://imagedelivery.net/BXluQx4ige9GuW0Ia56BHw/bc698287-5adc-4cc5-a503-de16963ed900/original",
      "custody_address": "0x6b0bda3f2ffed5efc83fa8c024acff1dd45793f1",
      "profile": {
        "bio": {
          "text": "Working on Farcaster and Warpcast."
        },
        "location": {
          "latitude": 34.05,
          "longitude": -118.24,
          "address": {
            "city": "Los Angeles",
            "state": "California",
            "state_code": "ca",
            "country": "United States of America",
            "country_code": "us"
          }
        }
      },
      "follower_count": 490770,
      "following_count": 3498,
      "verifications": [
        "0xd7029bdea1c17493893aafe29aad69ef892b8ff2"
      ],
      "verified_addresses": {
        "eth_addresses": [
          "0xd7029bdea1c17493893aafe29aad69ef892b8ff2"
        ],
        "sol_addresses": []
      },
      "verified_accounts": [
        {
          "platform": "x",
          "username": "dwr"
        }
      ],
      "power_badge": true
    }

Future reading: you can also fetch data about a user by using their wallet address or username as identifiers. See APIs for that here: User by wallet address, By username.

You're ready to build!

Now that you're able to fetch user and cast data, you're ready to dive in further and start making your first Farcaster application. We have numerous guides available here and our full API reference is here .

If you have questions or feedback, please reach out to rish on Farcaster or Telegram .