Back to Details

neynar

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Neynar (Farcaster API)

Neynar (Farcaster API)

Interact with the Farcaster decentralized social protocol via Neynar's API.
通过Neynar的API与Farcaster去中心化社交协议交互。

Quick Start

快速开始

Setup

配置

  1. Get an API key from dev.neynar.com
  2. 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.
  1. 从 dev.neynar.com 获取API密钥
  2. 创建配置文件：
bash
mkdir -p ~/.clawdbot/skills/neynar
cat > ~/.clawdbot/skills/neynar/config.json << 'EOF'
{
  "apiKey": "YOUR_NEYNAR_API_KEY",
  "signerUuid": "YOUR_SIGNER_UUID"
}
EOF
注意：
signerUuid
仅在发布Cast时需要，可通过Neynar的签名者管理功能获取。

Verify Setup

验证配置

bash
scripts/neynar.sh user dwr.eth
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
  • FID — Farcaster ID，每个用户的永久数字标识符
  • Cast — Farcaster上的帖子（类似推文）
  • Channel — 基于主题的信息流（类似subreddit）
  • Frame — 嵌入在Cast中的交互式迷你应用

Usage

使用方法

User Lookup

用户查询

bash
undefined
bash
undefined

By username

按用户名查询

scripts/neynar.sh user vitalik.eth
scripts/neynar.sh user vitalik.eth

By FID

按FID查询

scripts/neynar.sh user --fid 5650
scripts/neynar.sh user --fid 5650

Multiple users

批量查询多个用户

scripts/neynar.sh users dwr.eth,v,jessepollak
undefined
scripts/neynar.sh users dwr.eth,v,jessepollak
undefined

Read Feed

读取信息流

bash
undefined
bash
undefined

User's casts

指定用户发布的Cast

scripts/neynar.sh feed --user dwr.eth
scripts/neynar.sh feed --user dwr.eth

Channel feed

频道信息流

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

Trending feed

热门信息流

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

Following feed (requires signer)

关注用户的信息流（需要签名者）

scripts/neynar.sh feed --following
undefined
scripts/neynar.sh feed --following
undefined

Search

搜索

bash
undefined
bash
undefined

Search casts

搜索Cast

scripts/neynar.sh search "ethereum"
scripts/neynar.sh search "ethereum"

Search users

搜索用户

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

Search in channel

在指定频道内搜索

scripts/neynar.sh search "onchain summer" --channel base
undefined
scripts/neynar.sh search "onchain summer" --channel base
undefined

Get Cast

获取单条Cast

bash
undefined
bash
undefined

By hash

按哈希查询

scripts/neynar.sh cast 0x1234abcd...
scripts/neynar.sh cast 0x1234abcd...

By URL

按URL查询

scripts/neynar.sh cast "https://warpcast.com/dwr.eth/0x1234"
undefined
scripts/neynar.sh cast "https://warpcast.com/dwr.eth/0x1234"
undefined

Post Cast (requires signer)

发布Cast（需要签名者）

bash
undefined
bash
undefined

Simple cast

发布普通Cast

scripts/neynar.sh post "gm farcaster"
scripts/neynar.sh post "gm farcaster"

Reply to cast

回复某条Cast

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

Cast in channel

在指定频道发布Cast

scripts/neynar.sh post "hello base" --channel base
scripts/neynar.sh post "hello base" --channel base

Cast with embed

发布带嵌入内容的Cast

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

Reactions

互动反应

bash
undefined
bash
undefined

Like a cast

点赞Cast

scripts/neynar.sh like 0x1234abcd
scripts/neynar.sh like 0x1234abcd

Recast

转发Cast

scripts/neynar.sh recast 0x1234abcd
undefined
scripts/neynar.sh recast 0x1234abcd
undefined

Follow/Unfollow

关注/取消关注

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

API Reference

API参考

Endpoints Used

使用的接口

ActionEndpointAuth
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
操作接口鉴权
用户查询
GET /v2/farcaster/user/by_username
API密钥
按FID查用户
GET /v2/farcaster/user/bulk
API密钥
用户信息流
GET /v2/farcaster/feed/user/casts
API密钥
频道信息流
GET /v2/farcaster/feed/channels
API密钥
热门信息流
GET /v2/farcaster/feed/trending
API密钥
搜索Cast
GET /v2/farcaster/cast/search
API密钥
获取单条Cast
GET /v2/farcaster/cast
API密钥
发布Cast
POST /v2/farcaster/cast
API密钥 + 签名者
互动反应
POST /v2/farcaster/reaction
API密钥 + 签名者
关注用户
POST /v2/farcaster/user/follow
API密钥 + 签名者

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..."]
  }
}
所有响应均为JSON格式，脚本会提取关键字段提升可读性：
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
undefined
bash
undefined

Get latest casts from /base channel

获取/base频道的最新20条Cast

scripts/neynar.sh feed --channel base --limit 20
undefined
scripts/neynar.sh feed --channel base --limit 20
undefined

Find Active Users

查找活跃用户

bash
undefined
bash
undefined

Search for users by keyword

按关键词搜索用户

scripts/neynar.sh search-users "ethereum developer"
undefined
scripts/neynar.sh search-users "ethereum developer"
undefined

Cross-Post from Twitter

从Twitter同步发帖

bash
undefined
bash
undefined

Post same content to Farcaster

将相同内容发布到Farcaster

scripts/neynar.sh post "gm, just shipped a new feature 🚀"
undefined
scripts/neynar.sh post "gm, just shipped a new feature 🚀"
undefined

Reply to Mentions

回复提及你的内容

bash
undefined
bash
undefined

Get your notifications (requires signer)

获取你的通知（需要签名者）

scripts/neynar.sh notifications
scripts/neynar.sh notifications

Reply to specific cast

回复指定Cast

scripts/neynar.sh post "thanks!" --reply-to 0xabc123
undefined
scripts/neynar.sh post "thanks!" --reply-to 0xabc123
undefined

Error Handling

错误处理

ErrorCauseFix
401 UnauthorizedInvalid API keyCheck 
config.json
403 ForbiddenSigner requiredSet up signer for write operations
404 Not FoundUser/cast doesn't existVerify username/hash
429 Rate LimitedToo many requestsWait and retry
错误原因解决方案
401未授权API密钥无效检查
config.json
配置
403禁止访问需要签名者为写入操作配置签名者
404未找到用户/Cast不存在验证用户名/哈希是否正确
429频率限制请求次数过多等待后重试

Signer Setup

签名者配置

For write operations (posting, liking, following), you need a signer:
  1. Go to dev.neynar.com
  2. Create a new signer or use managed signer
  3. Add 
    signerUuid
    to your config
Managed signers are easiest — Neynar handles the key custody.
对于写入操作（发布、点赞、关注），你需要配置签名者：
  1. 访问 dev.neynar.com
  2. 创建新签名者或使用托管签名者
  3. 将
    signerUuid
    添加到配置文件中
托管签名者是最便捷的选择，Neynar会负责密钥托管。

Rate Limits

频率限制

  • Free tier: 300 requests/minute
  • Paid tiers: Higher limits available
  • Check 
    X-RateLimit-Remaining
    header
  • 免费版：300次请求/分钟
  • 付费版：支持更高请求额度
  • 可查看
    X-RateLimit-Remaining
    响应头确认剩余额度

Best Practices

最佳实践

  1. Cache user lookups — FIDs don't change, usernames rarely do
  2. Use channels — Better reach than random posting
  3. Engage genuinely — Farcaster culture values authenticity
  4. Batch requests — Use bulk endpoints when possible
  5. Handle rate limits — Implement backoff
  1. 缓存用户查询结果 — FID不会改变，用户名也极少变更
  2. 使用频道发布 — 比随机发布曝光度更高
  3. 真诚互动 — Farcaster社区文化重视真实性
  4. 批量请求 — 尽可能使用批量接口
  5. 处理频率限制 — 实现退避重试机制

Resources

参考资源

Troubleshooting

问题排查

API Key Not Working

API密钥无法使用

bash
undefined
bash
undefined

Verify key works

验证密钥是否有效

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

Signer Issues

签名者相关问题

  • Ensure signer is approved and active
  • Check signer permissions match your FID
  • Managed signers are simpler than self-hosted
  • 确认签名者已通过审核且处于激活状态
  • 检查签名者权限与你的FID匹配
  • 托管签名者比自行托管的签名者更易维护

Cast Not Appearing

Cast未展示

  • Casts propagate in seconds, but indexing may take longer
  • Check the cast hash in the response
  • Verify on warpcast.com directly
  • Cast传播只需几秒，但索引可能需要更长时间
  • 检查响应中的Cast哈希是否正确
  • 直接在warpcast.com上验证内容是否存在