Farcaster Network

Your own node
for Farcaster

Hypersnap is a full Farcaster node you run on your own server. Read casts, query profiles, follow the social graph — all through your own infrastructure. No third-party APIs.

Run this in your terminal
mkdir hypersnap && cd hypersnap && curl -sSL https://raw.githubusercontent.com/farcasterorg/hypersnap/refs/heads/main/scripts/hypersnap-bootstrap.sh | bash

Requires Docker & Docker Compose. Works on Linux and macOS.

Setup Guide
From install to fully synced

The node syncs automatically after install. Here's what to expect at each stage and exactly how to know when to move on.

1

Download snapshot

The node downloads the latest network snapshot. You'll see a percentage counter and an estimated time remaining.

Done when: Progress hits 100% and the logs switch to unzipping chunk messages.
Warning: Do not stop the node during download — it restarts from zero.
2

Unzip snapshot

~2,542 chunks are extracted one by one. No progress bar — watch the chunk number in the logs count up.

Done when: The last chunk (~2542) finishes and unzipping chunk messages stop appearing. You'll only see Grafana-related logs. The node may look idle — this is expected.
3

Restart the node

The initial sync is complete. Restart the node to begin live syncing with the Farcaster network.

Run these two commands:
./hypersnap.sh down — stops the node
./hypersnap.sh up — starts it in sync mode
4

Syncing with the network

The node connects to Farcaster peers and processes blocks in real time. This runs indefinitely.

Working when you see:
Processed decided block height with increasing numbers
Requesting sync value from peer between blocks
HTTP API
Read the entire Farcaster network

Your node exposes a full REST API on port 3381 and gRPC on port 3383. Query casts, profiles, reactions, follows, and more — directly from your machine.

Timestamps

All timestamps use Farcaster epoch (seconds since Jan 1, 2021). Convert with:

unix = farcaster_ts + 1609459200

Shards

Data is split across 2 shards. FIDs are deterministically assigned. Some endpoints need shard_id (1 or 2) — query both for complete data.

Health Check

Poll /v1/info — when blockDelay < 5 on both shards, the node is synced and ready for production reads.

Casts

Read casts by user, by parent, or by mention.

GET /v1/castsByFid?fid=2

Profiles

Fetch display name, bio, PFP, and username.

GET /v1/userDataByFid?fid=6833

Follows

Query who follows who across the network.

GET /v1/linksByFid?fid=2&link_type=follow

Reactions

Get likes and recasts on any cast.

GET /v1/reactionsByFid?fid=2&reaction_type=Like

Verifications

See which addresses an FID has verified.

GET /v1/verificationsByFid?fid=2

Node Info

Sync status, DB stats, and shard info.

GET /v1/info

Submit Messages

POST signed protobuf messages. Requires an Ed25519 signer registered on-chain for the FID.

POST /v1/submitMessage

gRPC

Same API over gRPC on port 3383. For streaming, higher throughput, or protobuf-native clients.

See full docs

Full reference at snapchain.farcaster.xyz

Reference
Commands

Everything you need to manage your node.

./hypersnap.sh up

Start the node and begin syncing

./hypersnap.sh down

Stop all services

./hypersnap.sh logs

Tail live logs

./hypersnap.sh upgrade

Pull latest version and restart

Before you start
Requirements
Docker & Docker Compose
Linux or macOS
Farcaster FID or username

Build with an LLM

Copy the full Hypersnap context file and paste it into your LLM to start building on Farcaster immediately.