neynar

name	neynar
description	Access the Farcaster open social graph via Neynar. Use when the user wants to search casts, look up user profiles, browse channels, or fetch feeds.

Neynar

Neynar provides access to the open social graph through the Farcaster protocol. Search casts, look up users, browse channels, and fetch feeds.

Common Operations

Search Casts

Search for casts (Farcaster posts) matching a query.

Pricing: $0.01

Request:

obulx "https://api.neynar.com/v2/farcaster/cast/search?q=ethereum&limit=25"

Response: JSON with casts array containing cast objects with text, author info, reactions, and timestamps.

User Search

Search for users by username or display name.

Pricing: $0.01

Request:

obulx "https://api.neynar.com/v2/farcaster/user/search?q=vitalik&limit=10"

Response: JSON with users array containing user objects with username, display name, bio, follower stats, and connected addresses.

User Lookup by FID

Look up user profiles by their Farcaster ID (FID).

Pricing: $0.01

Request:

obulx "https://api.neynar.com/v2/farcaster/user/bulk?fids=3,194"

Response: JSON with users array containing full user profile objects.

Feed

Fetch a feed of casts based on following or filters.

Pricing: $0.01

Request:

obulx "https://api.neynar.com/v2/farcaster/feed?feed_type=filter&filter_type=channel_id&channel_id=ethereum&limit=25"

Response: JSON with casts array containing cast objects with text, author, reactions, and replies.

Channel Search

Search for Farcaster channels by name.

Pricing: $0.01

Request:

obulx "https://api.neynar.com/v2/farcaster/channel/search?q=defi"

Response: JSON with channels array containing channel objects with name, description, follower count, and image URL.

Endpoint Pricing Reference

Endpoint	Price	Purpose
GET /v2/farcaster/cast/search	$0.01	Search casts by query
GET /v2/farcaster/user/search	$0.01	Search users by username
GET /v2/farcaster/user/bulk	$0.01	Lookup users by FID
GET /v2/farcaster/feed	$0.01	Get feed by channel or following
GET /v2/farcaster/channel/search	$0.01	Search channels

When to Use

• Cast search — User asks to search Farcaster for casts or posts
• User lookup — User wants to look up a Farcaster user profile
• Channel discovery — User asks about a Farcaster channel
• Feed browsing — User wants to browse a Farcaster feed
• User search — User asks to find Farcaster users by username

Best Practices

• Use search operators — The query supports operators: + (AND), | (OR), * (prefix), "..." (exact phrase), - (exclude), before:YYYY-MM-DD, after:YYYY-MM-DD
• Sort options — Use sort_type: desc_chron (default), chron, or algorithmic
• Pagination — Use cursor from response for pagination through large result sets
• FID — Remember that FID (Farcaster ID) is the unique numeric identifier for each user

Notes

• Neynar's x402 mode activates when no x-api-key header is present; the Obul proxy handles payment automatically
• All endpoints are GET requests; no Content-Type header needed
• Pricing is approximately $0.01 per request across all endpoints

Error Handling

Error	Cause	Solution
402 Payment Required	Payment not processed or insufficient	Check that obulx is configured correctly and your account has balance.
400 Bad Request	Missing or invalid parameters	Ensure required parameters like q for search are provided.
404 Not Found	User or channel not found	Verify the username or channel name exists.
429 Too Many Requests	Rate limit exceeded	Add a short delay between requests.
500 Internal Server Error	Neynar service issue	Wait a few seconds and retry. If persistent, the service may be experiencing downtime.