Guides

Getting started

Start building on Farcaster with Neynar

Suggest Edits

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 a few of the primary Farcaster primitives that will be helpful to keep in mind as you dive in:

  1. User - every user on Farcaster is represented by a permanent FID, the user's numerical identifier. All user profile data for this FID, e.g., username, display name, bio, etc., are stored on the Farcaster protocol and mapped to this FID.
  2. 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".
  3. User Relationships - users can follow each other to see casts from them. This creates a social graph for each user on Farcaster.

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

In this tutorial, we will learn how to 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.

  1. Click "Subscribe now."
  2. You will be redirected to a Stripe checkout page.
  3. 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 must only 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: "YOUR_NEYNAR_API_KEY",
});

const client = new NeynarAPIClient(config);

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

  1. 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.5", 
    "ts-node": "^10.9.2",
    "typescript": "^5.6.3"
  }
}
  1. 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. 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";

const config = new Configuration({
  apiKey: "YOUR_NEYNAR_API_KEY",
});

const client = new NeynarAPIClient(config);

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

const feedType = FeedType.Following;
const fid = 3;
const withRecasts = true;
const limit = 50;
const viewerFid = 6131;

client
  .fetchFeed({ feedType, fid, withRecasts, limit, viewerFid })
  .then((response) => {
    console.log("response:", response);
  });

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

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: '0x5300d6bd8f604c0b5fe7d573e02bb1489362f4d3',
      author: [Object],
      thread_hash: '0x5300d6bd8f604c0b5fe7d573e02bb1489362f4d3',
      parent_hash: null,
      parent_url: null,
      root_parent_url: null,
      parent_author: [Object],
      text: 'https://open.spotify.com/track/5oQcOu1omDykbIPSdSQQNJ?si=2qMjk-fESMmxqCoAxTsPmw',
      timestamp: '2024-11-14T04:57:23.000Z',
      embeds: [Array],
      channel: null,
      reactions: [Object],
      replies: [Object],
      mentioned_profiles: [],
      viewer_context: [Object]
    },
  ]
}

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

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


Fetching user profile data

Now, let's fetch data about a user. 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";

const config = new Configuration({
  apiKey: "YOUR_NEYNAR_API_KEY",
});

const client = new NeynarAPIClient(config);
const fids = [2, 3];
const viewerFid = 6131;

client.fetchBulkUsers({ fids, viewerFid }).then((response) => {
  console.log("response:", response);
});

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

yarn start

It should show you a response like the one below: 

User: {
  users: [
    {
      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: [Object],
      follower_count: 489109,
      following_count: 3485,
      verifications: [Array],
      verified_addresses: [Object],
      verified_accounts: [Array],
      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 can 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 complete API reference is here.

If you have questions or feedback, please contact rish on Farcaster or Telegram .

Updated 14 days ago