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 — 基于主题的动态流（类似Reddit子版块）
  • 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

用户发布的动态

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

搜索动态

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

获取动态

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)

发布动态（需要签名者）

bash
undefined
bash
undefined

Simple cast

发布简单动态

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

Reply to cast

回复动态

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

Cast in channel

在指定频道发布动态

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

Cast with embed

发布带嵌入内容的动态

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

点赞动态

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

Recast

转发动态

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密钥
搜索动态
GET /v2/farcaster/cast/search
API密钥
获取动态
GET /v2/farcaster/cast
API密钥
发布动态
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条动态

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

回复指定动态

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 未找到用户/动态不存在验证用户名/哈希值是否正确
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

故障排查

—

API密钥无法使用

bash
undefined

Troubleshooting

验证密钥是否有效

API Key Not Working

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

Verify key works

签名者问题

curl -H "x-api-key: YOUR_KEY"
"https://api.neynar.com/v2/farcaster/user/bulk?fids=1"
undefined
  • 确保签名者已被批准且处于活跃状态
  • 检查签名者权限是否与你的FID匹配
  • 托管签名者比自托管签名者更简单

Signer Issues

动态未显示

  • Ensure signer is approved and active
  • Check signer permissions match your FID
  • Managed signers are simpler than self-hosted
  • 动态会在几秒内传播，但索引可能需要更长时间
  • 检查响应中的动态哈希值
  • 直接在warpcast.com上验证动态状态

Cast Not Appearing

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