​
Introduction

Farcaster is a protocol for building decentralized social apps. Neynar makes it easy to build on Farcaster. This tutorial covers
  • fundamentals of Farcaster protocol
  • getting your Neynar API key
  • understanding core concepts like FIDs and Casts
  • tutorial steps to start developing social applications

​
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:

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.

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”.

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? Create an account to get started. Don’t hesitate to reach out to us on our channel or Slack with any questions!

​
If building a mini app, you can go straight to Set up mini app in < 60 s

​
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
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"
  }
}
2

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. Read through our tutorials and API reference for more. If you have questions or feedback, please reach out to us on our Developer Slack .