Farcaster Integration

​

Overview

​

About Farcaster

• Decentralized - Your identity and content are stored on the blockchain and IPFS
• Permissionless - Anyone can build clients and apps on top of the protocol
• Portable - Your social graph and content move with you between apps
• Censorship-resistant - No central authority can remove your content

​

Prerequisites

• A Farcaster account (FID - Farcaster ID)
• An Ethereum wallet with a small amount of ETH for registration
• Access to a Farcaster hub or API service
• Your Farcaster custody address and recovery phrase

​

Setup

# Farcaster Identity
FARCASTER_FID=your_farcaster_id
FARCASTER_MNEMONIC=your_recovery_phrase_here

# Hub/API Connection (example: Neynar)
FARCASTER_HUB_URL=https://hub-api.neynar.com
NEYNAR_API_KEY=your_neynar_api_key

# Optional: Custom hub
# FARCASTER_HUB_URL=http://localhost:2281

{
  "name": "YourAgent",
  "plugins": [
    "@elizaos/plugin-farcaster"
  ],
  "settings": {
    "channels": {
      "farcaster": {
        "enabled": true
      }
    }
  }
}

​

Configuration

​

Environment Variables

​

Character Settings

{
  "settings": {
    "channels": {
      "farcaster": {
        "enabled": true,
        "autoReply": true,
        "replyToMentions": true,
        "engageWithFollowers": true,
        "castInterval": 3600000,
        "maxCastsPerDay": 30
      }
    }
  }
}

​

Features

​

Casting (Posting)

// Simple cast
{
  "action": "cast",
  "text": "Hello Farcaster! Building with elizaOS 🤖"
}

// Cast with embeds
{
  "action": "cast",
  "text": "Check out this project",
  "embeds": [
    { "url": "https://github.com/elizaos/eliza" }
  ]
}

// Cast with image
{
  "action": "cast",
  "text": "Visual content",
  "embeds": [
    { "url": "https://example.com/image.png" }
  ]
}

​

Replies

{
  "action": "reply",
  "parentHash": "0x1234...",
  "text": "Great point! Here's my take..."
}

​

Reactions

// Like a cast
{
  "action": "like",
  "castHash": "0x1234..."
}

// Remove like
{
  "action": "unlike",
  "castHash": "0x1234..."
}

​

Recasts

{
  "action": "recast",
  "castHash": "0x1234..."
}

​

Follow/Unfollow

// Follow a user by FID
{
  "action": "follow",
  "fid": 12345
}

// Unfollow
{
  "action": "unfollow",
  "fid": 12345
}

​

Get User Information

// Get user by FID
{
  "action": "getUserByFid",
  "fid": 12345
}

// Get user by username
{
  "action": "getUserByUsername",
  "username": "elizaos"
}

​

Get Casts

// Get user's casts
{
  "action": "getUserCasts",
  "fid": 12345,
  "limit": 25
}

// Get cast thread
{
  "action": "getCastThread",
  "castHash": "0x1234..."
}

// Get home feed
{
  "action": "getFeed",
  "fid": 12345,
  "feedType": "following",
  "limit": 50
}

​

Monitor Mentions

{
  "action": "getNotifications",
  "fid": 12345,
  "limit": 20
}

​

Channels

// Cast to a channel
{
  "action": "cast",
  "text": "Contributing to the discussion",
  "channel": "elizaos"
}

// Get channel casts
{
  "action": "getChannelCasts",
  "channel": "elizaos",
  "limit": 25
}

​

Farcaster Protocol Details

​

Hubs

• Store and validate casts and user data
• Propagate messages across the network
• Provide APIs for reading and writing data

​

Signers

• Custody address: Your main Farcaster identity (keep secure!)
• App signers: Delegated keys for specific applications
• Each signer must be authorized by your custody address

​

Content Storage

• On-chain: FID registration, username, key registrations
• Off-chain: Casts, reactions, follows stored in hubs
• Media: Images/files typically stored on IPFS or CDNs

​

Best Practices

​

Engagement

1. Be authentic - Farcaster values genuine interaction
2. Add value - Share insights, help others, contribute meaningfully
3. Use channels - Participate in topic-specific channels
4. Build relationships - Engage with the community consistently
5. Respect the culture - Farcaster has a unique, Web3-native community

​

Content Strategy

1. Share builders’ updates - The community loves seeing what people are building
2. Engage with threads - Thoughtful replies get noticed
3. Use appropriate channels - Post in relevant topic channels
4. Quality over quantity - Better to post less frequently with value
5. Cross-promote thoughtfully - Share content but don’t spam

​

Technical

1. Monitor hub sync status - Ensure your hub is in sync
2. Handle errors gracefully - Network issues can occur
3. Respect rate limits - Be a good network citizen
4. Keep signers secure - Protect private keys
5. Test before deploying - Use test accounts first

​

Rate Limits

​

Protocol Limits

• Casts per day: Varies by hub and anti-spam measures
• Reactions: Generally unrestricted but monitored for abuse
• Follows: Reasonable limits to prevent spam

​

API Limits (Neynar Example)

• Free tier: 100 requests per minute
• Paid tiers: Higher limits available
• Check your specific hub/API provider’s documentation

​

Troubleshooting

​

Cannot connect to hub

1. Verify FARCASTER_HUB_URL is correct and accessible
2. Check network connectivity
3. Ensure API key is valid (if using managed service)
4. Try alternative hub endpoints

​

Casts not appearing

1. Check hub sync status
2. Verify signer is properly authorized
3. Ensure cast content meets protocol requirements
4. Check for error messages in logs
5. Try viewing on different Farcaster clients

​

Authentication errors

1. Verify FARCASTER_FID is correct
2. Check FARCASTER_MNEMONIC is valid
3. Ensure signer is authorized for your FID
4. Re-authorize signer if necessary

​

”User not found” errors

1. Verify FID or username is correct
2. Check if user exists on the network
3. Ensure hub is synced
4. Try different hub endpoints

​

Use Cases

​

Developer Community

• Share project updates and releases
• Answer technical questions
• Gather feedback from users
• Network with other builders

​

Content Distribution

• Cross-post from blogs or documentation
• Share announcements
• Thread complex topics
• Build thought leadership

​

Community Management

• Respond to mentions and questions
• Moderate channels (if admin)
• Welcome new community members
• Share community highlights

​

Research and Monitoring

• Track project mentions
• Monitor sentiment
• Identify trends
• Gather user feedback

​

Farcaster vs Traditional Social

​

Related Resources

• Farcaster Documentation
• Warpcast
• Neynar API Docs
• Hub Monorepo
• Farcaster Protocol Specification
• elizaOS Plugin Architecture
• Create a Plugin Guide