Farcaster Agent Example

A self-contained TypeScript reference showing how to run an elizaOS agent that monitors and posts on Farcaster.

Overview

The agent responds to mentions in your Farcaster feed and can autonomously post casts.

Prerequisites

1. OpenAI API key – Get one at platform.openai.com
2. Farcaster account with a Neynar signer:
   • Sign up at neynar.com
   • Create a signer for your Farcaster account
   • Note your FID, Signer UUID, and API key

Quick Start

cd packages/examples/farcaster
cp env.example .env
# Edit .env with your credentials
bun install
bun run start

Configuration

Copy env.example to .env and fill in the required values:

How It Works

For each incoming mention, the examples route the event through the elizaOS "message service" for consistent state composition and response generation.

• Uses @elizaos/plugin-farcaster which registers:
  • Services: FarcasterService (handles polling, client lifecycle)
  • Actions: SEND_CAST, REPLY_TO_CAST
  • Providers: farcasterProfile, farcasterTimeline, farcasterThread
• Mentions/replies are handled by the plugin's FarcasterService background clients
• Incoming mentions are routed into the runtime via runtime.messageService.handleMessage() inside the plugin.

Pipeline Steps

For each incoming mention:

1. Create a Memory for the Farcaster cast (stable IDs per cast/thread)
2. Ensure connection/room exists in elizaOS (world + room + entity)
3. Call the language runtime's message service
4. Post reply to Farcaster (unless FARCASTER_DRY_RUN=true)

The TypeScript example relies on the plugin-farcaster service for polling and posting.

Character

The default character (FarcasterBot) is configured as a helpful AI agent on Farcaster. Customize character.ts to change:

• Name and bio
• Topics and expertise areas
• Response style and personality
• Message examples

Features

• Full elizaOS Pipeline: Uses message_service.handle_message() for proper state composition and response generation
• Reply to mentions: Automatically respond to users who mention your agent
• Memory Persistence: All conversations stored in SQL for continuity and deduplication
• Thread awareness: Understand conversation context when replying
• Dry run mode: Test without actually posting to Farcaster (default: enabled)
• Rate limiting: Built-in handling for API rate limits with backoff

Plugin Components

The @elizaos/plugin-farcaster plugin provides these components:

Actions

Providers

Services

Project Structure

packages/examples/farcaster/
├── README.md           # This file
├── env.example         # Environment variable template
├── .gitignore          # Git ignore rules
├── agent.ts            # Main entry point
├── character.ts        # Character configuration
├── package.json        # Dependencies
└── tsconfig.json       # TypeScript config

Troubleshooting

"Missing FARCASTER_SIGNER_UUID"

Create a signer at neynar.com and add the UUID to your .env file.

"Rate limited"

The agent handles 429 errors automatically with exponential backoff. You can also increase FARCASTER_POLL_INTERVAL.

"Cast too long"

Casts are automatically truncated to MAX_CAST_LENGTH (default 320 characters).

See Also

• Farcaster Plugin Documentation
• elizaOS Docs
• Neynar API Documentation