---

name: neynar description: Interact with Farcaster via Neynar API. Read feeds, look up users, post casts, search content, manage reactions, explore channels, check notifications, and more. Pure bash (curl + jq). Requires NEYNAR_API_KEY. metadata: {"clawdbot":{"emoji":"🟪","homepage":"https://neynar.com","requires":{"bins":["curl","jq"]}}}

Neynar (Farcaster API)

Full-featured CLI for the Farcaster decentralized social protocol via Neynar's REST API. Pure bash — only requires curl and jq.

Farcaster Protocol Concepts

| Concept | Description | |---------|-------------| | FID | Farcaster ID — permanent numeric identifier for each account (e.g., 2664317). Registered on-chain on Optimism. | | Cast | A post on Farcaster (max 320 chars). Identified by a hex hash like 0xabc123.... | | Channel | Topic-based feed (like a subreddit). Has an ID (e.g., base, ethereum), a lead user, and follower count. | | Signer | An Ed25519 keypair authorized to act on behalf of an FID. Required for all write operations. Managed by Neynar via signerUuid. | | Hub | Peer-to-peer node that stores and validates Farcaster messages. Neynar runs hub infrastructure. | | Storage | On-chain storage units that determine how many casts/reactions an account can store. Purchased on Optimism. Expires annually. | | Frame | Interactive mini-app embedded in a cast (buttons, forms, transactions). | | Power Badge | Verified quality signal from Warpcast. Shown as power_badge: true. | | Neynar Score | 0-1 quality score computed by Neynar based on account activity and graph position. |

Setup

1. Get API Key

Sign up at dev.neynar.com and copy your API key.

2. Create Config

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

| Field | Required | Description | |-------|----------|-------------| | apiKey | Yes | Neynar API key | | signerUuid | For writes | Managed signer UUID from Neynar | | fid | For notifications/defaults | Your Farcaster ID number |

3. Verify

scripts/neynar.sh user dwr.eth

Command Reference

User Lookup

# By username
neynar.sh user vitalik.eth

# By FID
neynar.sh user 5650

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

Output includes: fid, username, display_name, pfp_url, bio, follower_count, following_count, verified_addresses, power_badge, neynar_score.

Feeds

# User's casts (includes parent_hash to detect replies)
neynar.sh feed --user dwr.eth --limit 5

# Channel feed
neynar.sh feed --channel base --limit 10

# Trending casts
neynar.sh feed --trending --limit 10

# Following feed (requires signer)
neynar.sh feed --following --limit 20

The --user feed includes parent_hash — if non-null, the cast is a reply. Use this to filter out replies when you only want top-level posts.

Cast Details

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

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

Conversation (Thread)

# Get root cast + all replies (depth 2, up to 20 replies)
neynar.sh conversation 0xabc123

Returns the root cast plus nested replies array, each with their own replies for depth-2 threading.

Search

# Search casts
neynar.sh search "ethereum" --limit 10

# Search casts in a channel
neynar.sh search "onchain summer" --channel base

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

Notifications

# Your notifications (requires fid in config)
neynar.sh notifications --limit 10

Returns: type (mention, reply, like, recast, follow), cast_hash, author, text_preview, timestamp.

Followers & Following

# Your followers (default: own FID from config)
neynar.sh followers --limit 20

# Specific user's followers
neynar.sh followers dwr.eth --limit 20

# By FID
neynar.sh followers 3 --limit 10

# Who you follow
neynar.sh following

# Who someone else follows
neynar.sh following dwr.eth --limit 20

Popular Casts

# Your most popular casts
neynar.sh popular --limit 5

# Someone else's popular casts
neynar.sh popular dwr.eth --limit 10

Channels

# Get channel info
neynar.sh channel base
# → {id, name, description, follower_count, lead, image_url, created_at}

# Search channels
neynar.sh channels "ethereum"
# → [{id, name, description, follower_count}]

# Trending channels
neynar.sh trending-channels --limit 5

Storage

# Your storage allocations (default: own FID)
neynar.sh storage

# Check another user's storage
neynar.sh storage 3
neynar.sh storage dwr.eth

Returns: units, expiry, timestamp for each allocation.

Fname Availability

# Check if a username is available
neynar.sh fname coolname
# → {fname: "coolname", available: true/false}

Post Cast (requires signer)

# Simple cast
neynar.sh post "gm farcaster"

# Reply to a cast
neynar.sh post "great point!" --reply-to 0xabc123

# Post in a channel
neynar.sh post "hello base" --channel base

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

# Channel + reply + embed (all options)
neynar.sh post "interesting" --reply-to 0xabc --channel base --embed "https://x.com/..."

Newlines: The script auto-converts literal \\n from LLM output to real newlines.

Reactions (require signer)

# Like a cast
neynar.sh like 0xabc123

# Remove a like
neynar.sh unlike 0xabc123

# Recast
neynar.sh recast 0xabc123

# Remove a recast
neynar.sh unrecast 0xabc123

Delete Cast (requires signer)

neynar.sh delete 0xabc123

Follow / Unfollow (require signer)

# By username
neynar.sh follow dwr.eth
neynar.sh unfollow dwr.eth

# By FID
neynar.sh follow 3
neynar.sh unfollow 3

API Endpoints Reference

| Command | Method | Endpoint | |---------|--------|----------| | user (username) | GET | /v2/farcaster/user/by_username?username=X | | user (FID) | GET | /v2/farcaster/user/bulk?fids=X | | users | GET | /v2/farcaster/user/bulk-by-username?usernames=X,Y | | feed --user | GET | /v2/farcaster/feed/user/casts?fid=X&limit=N | | feed --channel | GET | /v2/farcaster/feed/channels?channel_ids=X&limit=N | | feed --trending | GET | /v2/farcaster/feed/trending?limit=N | | feed --following | GET | /v2/farcaster/feed/following?fid=me&limit=N | | cast | GET | /v2/farcaster/cast?type=hash&identifier=X | | conversation | GET | /v2/farcaster/cast/conversation?identifier=X&type=hash&reply_depth=2&limit=20 | | search | GET | /v2/farcaster/cast/search?q=X&limit=N | | search-users | GET | /v2/farcaster/user/search?q=X&limit=10 | | notifications | GET | /v2/farcaster/notifications?fid=X&limit=N | | followers | GET | /v2/farcaster/followers?fid=X&limit=N | | following | GET | /v2/farcaster/following?fid=X&limit=N | | popular | GET | /v2/farcaster/feed/user/FID/popular?limit=N | | channel | GET | /v2/farcaster/channel?id=X | | channels | GET | /v2/farcaster/channel/search?q=X | | trending-channels | GET | /v2/farcaster/channel/trending?limit=N | | storage | GET | /v2/farcaster/storage/allocations?fid=X | | fname | GET | /v2/farcaster/fname/availability?fname=X | | post | POST | /v2/farcaster/cast | | like | POST | /v2/farcaster/reaction | | recast | POST | /v2/farcaster/reaction | | unlike | DELETE | /v2/farcaster/reaction | | unrecast | DELETE | /v2/farcaster/reaction | | delete | DELETE | /v2/farcaster/cast | | follow | POST | /v2/farcaster/user/follow | | unfollow | POST | /v2/farcaster/user/follow (with unfollow: true) |

Base URL: https://api.neynar.com/v2/farcaster Auth: x-api-key: API_KEY header on all requests.

Rate Limits

• Free tier: 300 requests/minute
• Paid tiers: Higher limits available at neynar.com/pricing
• Check X-RateLimit-Remaining response header
• On 429, wait and retry with exponential backoff

Common Patterns for Bot/Agent Use

Monitor and Reply to Mentions

# Check notifications
neynar.sh notifications --limit 20

# Get conversation context before replying
neynar.sh conversation 0xabc123

# Reply
neynar.sh post "thanks for the mention!" --reply-to 0xabc123

Monitor a Channel

# Get latest from a channel
neynar.sh feed --channel base --limit 20

# Search within channel
neynar.sh search "shipping" --channel base --limit 10

Filter User's Top-Level Casts (Skip Replies)

# parent_hash is null for top-level casts
neynar.sh feed --user dwr.eth --limit 20 | jq 'select(.parent_hash == null)'

Check Account Health

# Storage status
neynar.sh storage

# Follower count
neynar.sh user yourname

Engagement Workflow

# Find trending content
neynar.sh feed --trending --limit 10

# Like the best ones
neynar.sh like 0xhash1
neynar.sh like 0xhash2

# Follow interesting authors
neynar.sh follow interestinguser

Discover Channels

# Search for relevant channels
neynar.sh channels "defi"

# Check what's trending
neynar.sh trending-channels --limit 10

# Get channel details
neynar.sh channel defi

Error Codes

| HTTP Code | Meaning | Resolution | |-----------|---------|------------| | 400 | Bad Request | Check parameters (invalid hash, missing required fields) | | 401 | Unauthorized | API key is invalid or missing | | 403 | Forbidden | Signer not authorized for this FID, or missing signer | | 404 | Not Found | User, cast, or channel doesn't exist | | 409 | Conflict | Already liked/recasted/followed | | 429 | Rate Limited | Too many requests — wait and retry | | 500 | Server Error | Neynar infrastructure issue — retry later |

The script outputs Error: API request failed for <endpoint> on any non-2xx response from curl.

Troubleshooting

API Key Not Working

# Direct test
curl -s -H "x-api-key: YOUR_KEY" \
  "https://api.neynar.com/v2/farcaster/user/bulk?fids=1" | jq .

Signer Issues

• Ensure signer is approved and active in Neynar dashboard
• Signer must be associated with your FID
• Use dev.neynar.com to manage signers

Cast Not Appearing

• Casts propagate in seconds but indexing may take a moment
• Verify using the returned cast hash: neynar.sh cast 0xhash
• Check directly on warpcast.com

jq Parse Errors

The script strips control characters (U+0000-U+001F except newline/tab) from API responses. If you still see parse errors, the response may be HTML (rate limit page) — check your API key and rate limits.

Username Not Resolving

• Ensure exact username (no @ prefix)
• Some usernames include .eth suffix (e.g., dwr.eth)
• Try by FID instead: neynar.sh user 3

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
• Farcaster Protocol Spec: https://github.com/farcasterxyz/protocol