neynar

What this skill does

# Neynar (Farcaster API)

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

## Quick Start

### Setup

1. Get an API key from [dev.neynar.com](https://dev.neynar.com)
2. Create config:

```bash
mkdir -p ~/.thinkfleet/skills/neynar
cat > ~/.thinkfleet/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:

1. Go to [dev.neynar.com](https://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.

## Rate Limits

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

## 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

## 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