Neynar (Farcaster API)

Interact with the Farcaster decentralized social protocol via Neynar's API.

Quick Start

Setup

•Get an API key from dev.neynar.com
•Create config:

bash

mkdir -p ~/.clawdbot/skills/neynar
cat > ~/.clawdbot/skills/neynar/config.json << 'EOF'
{
  "apiKey": "YOUR_NEYNAR_API_KEY",
  "signerUuid": "YOUR_SIGNER_UUID"
}
EOF

Note: signerUuid is only required for posting casts. Get one via Neynar's signer management.

Verify Setup

bash

scripts/neynar.sh user dwr.eth

Core Concepts

•FID — Farcaster ID, a permanent numeric identifier for each user
•Cast — A post on Farcaster (like a tweet)
•Channel — Topic-based feeds (like subreddits)
•Frame — Interactive mini-apps embedded in casts

Usage

User Lookup

bash

# By username
scripts/neynar.sh user vitalik.eth

# By FID
scripts/neynar.sh user --fid 5650

# Multiple users
scripts/neynar.sh users dwr.eth,v,jessepollak

Read Feed

bash

# User's casts
scripts/neynar.sh feed --user dwr.eth

# Channel feed
scripts/neynar.sh feed --channel base

# Trending feed
scripts/neynar.sh feed --trending

# Following feed (requires signer)
scripts/neynar.sh feed --following

Search

bash

# Search casts
scripts/neynar.sh search "ethereum"

# Search users
scripts/neynar.sh search-users "vitalik"

# Search in channel
scripts/neynar.sh search "onchain summer" --channel base

Get Cast

bash

# By hash
scripts/neynar.sh cast 0x1234abcd...

# By URL
scripts/neynar.sh cast "https://warpcast.com/dwr.eth/0x1234"

Post Cast (requires signer)

bash

# Simple cast
scripts/neynar.sh post "gm farcaster"

# Reply to cast
scripts/neynar.sh post "great point!" --reply-to 0x1234abcd

# Cast in channel
scripts/neynar.sh post "hello base" --channel base

# Cast with embed
scripts/neynar.sh post "check this out" --embed "https://example.com"

Reactions

bash

# Like a cast
scripts/neynar.sh like 0x1234abcd

# Recast
scripts/neynar.sh recast 0x1234abcd

Follow/Unfollow

bash

scripts/neynar.sh follow dwr.eth
scripts/neynar.sh unfollow dwr.eth

API Reference

Endpoints Used

Action	Endpoint	Auth
User lookup	`GET /v2/farcaster/user/by_username`	API key
User by FID	`GET /v2/farcaster/user/bulk`	API key
User feed	`GET /v2/farcaster/feed/user/casts`	API key
Channel feed	`GET /v2/farcaster/feed/channels`	API key
Trending	`GET /v2/farcaster/feed/trending`	API key
Search casts	`GET /v2/farcaster/cast/search`	API key
Get cast	`GET /v2/farcaster/cast`	API key
Post cast	`POST /v2/farcaster/cast`	API key + Signer
React	`POST /v2/farcaster/reaction`	API key + Signer
Follow	`POST /v2/farcaster/user/follow`	API key + Signer

Response Format

All responses are JSON. The script extracts key fields for readability:

json

{
  "user": {
    "fid": 3,
    "username": "dwr.eth",
    "display_name": "Dan Romero",
    "follower_count": 450000,
    "following_count": 2800,
    "verified_addresses": ["0x..."]
  }
}

Common Patterns

Monitor a Channel

bash

# Get latest casts from /base channel
scripts/neynar.sh feed --channel base --limit 20

Find Active Users

bash

# Search for users by keyword
scripts/neynar.sh search-users "ethereum developer"

Cross-Post from Twitter

bash

# Post same content to Farcaster
scripts/neynar.sh post "gm, just shipped a new feature 🚀"

Reply to Mentions

bash

# Get your notifications (requires signer)
scripts/neynar.sh notifications

# Reply to specific cast
scripts/neynar.sh post "thanks!" --reply-to 0xabc123

Error Handling

Error	Cause	Fix
401 Unauthorized	Invalid API key	Check `config.json`
403 Forbidden	Signer required	Set up signer for write operations
404 Not Found	User/cast doesn't exist	Verify username/hash
429 Rate Limited	Too many requests	Wait and retry

Signer Setup

For write operations (posting, liking, following), you need a signer:

•Go to dev.neynar.com
•Create a new signer or use managed signer
•Add signerUuid to your config

Managed signers are easiest — Neynar handles the key custody.

Rate Limits

•Free tier: 300 requests/minute
•Paid tiers: Higher limits available
•Check X-RateLimit-Remaining header

Best Practices

•Cache user lookups — FIDs don't change, usernames rarely do
•Use channels — Better reach than random posting
•Engage genuinely — Farcaster culture values authenticity
•Batch requests — Use bulk endpoints when possible
•Handle rate limits — Implement backoff

Resources

•Neynar Docs: https://docs.neynar.com
•API Reference: https://docs.neynar.com/reference
•Developer Portal: https://dev.neynar.com
•Farcaster Docs: https://docs.farcaster.xyz

Troubleshooting

API Key Not Working

bash

# Verify key works
curl -H "x-api-key: YOUR_KEY" \
  "https://api.neynar.com/v2/farcaster/user/bulk?fids=1"

Signer Issues

•Ensure signer is approved and active
•Check signer permissions match your FID
•Managed signers are simpler than self-hosted

Cast Not Appearing

•Casts propagate in seconds, but indexing may take longer
•Check the cast hash in the response
•Verify on warpcast.com directly