@elizaos/plugin-farcaster

A multi-language Farcaster plugin for elizaOS, providing full integration with the Farcaster decentralized social network via the Neynar API.

Languages

This plugin is implemented in three languages with full feature parity:

• TypeScript - Primary implementation for Node.js and browser
• Python - Python implementation for ML/AI pipelines
• Rust - High-performance implementation with WASM support

Features

• Cast Management: Send casts, reply to casts, and manage your timeline
• Profile Management: Fetch and cache user profiles
• Mentions & Notifications: Monitor and respond to mentions
• Timeline Provider: Access your Farcaster feed
• Thread Support: Navigate and respond within cast threads
• Embed Processing: Handle images, videos, and embedded casts
• Webhook Support: Real-time updates via webhooks
• Polling Mode: Periodic fetching for simple deployments

Installation

TypeScript/Node.js

npm install @elizaos/plugin-farcaster
# or
bun add @elizaos/plugin-farcaster

Python

pip install elizaos-plugin-farcaster

Rust

Add to your Cargo.toml:

[dependencies]
elizaos-plugin-farcaster = "1.0"

Configuration

The plugin requires the following environment variables:

| Variable | Required | Description | | -------------------------- | -------- | --------------------------------------------------------- | | FARCASTER_FID | Yes | Your Farcaster ID (FID) | | FARCASTER_SIGNER_UUID | Yes | Neynar signer UUID for signing casts | | FARCASTER_NEYNAR_API_KEY | Yes | Neynar API key for API access | | FARCASTER_DRY_RUN | No | Enable dry run mode (default: false) | | FARCASTER_MODE | No | Operation mode: 'polling' or 'webhook' (default: polling) | | MAX_CAST_LENGTH | No | Maximum cast length (default: 320) | | FARCASTER_POLL_INTERVAL | No | Polling interval in seconds (default: 120) | | ENABLE_CAST | No | Enable auto-casting (default: true) | | CAST_INTERVAL_MIN | No | Min cast interval in minutes (default: 90) | | CAST_INTERVAL_MAX | No | Max cast interval in minutes (default: 180) |

Usage

TypeScript

import farcasterPlugin from "@elizaos/plugin-farcaster";

// Register with agent runtime
const agent = new AgentRuntime({
  plugins: [farcasterPlugin],
  // ... other config
});

Python

from elizaos_plugin_farcaster import FarcasterClient, FarcasterConfig

# Load configuration from environment
config = FarcasterConfig.from_env()

# Create client
async with FarcasterClient(config) as client:
    # Send a cast
    casts = await client.send_cast("Hello from elizaOS! 🤖")
    print(f"Cast sent: {casts[0].hash}")

Rust

use elizaos_plugin_farcaster::{FarcasterClient, FarcasterConfig};

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let config = FarcasterConfig::from_env()?;
    let client = FarcasterClient::new(config)?;

    let casts = client.send_cast("Hello from elizaOS! 🤖", None).await?;
    println!("Cast sent: {}", casts[0].hash);

    Ok(())
}

Actions

SEND_CAST

Posts a new cast to Farcaster.

// Triggered by messages containing: post, cast, share, announce, farcaster, post
"Please post about the new ElizaOS features on Farcaster";

REPLY_TO_CAST

Replies to an existing cast.

// Triggered by messages containing: reply, respond, answer, comment
"Reply to that cast and thank them for the feedback";

Providers

farcaster_profile

Provides the agent's Farcaster profile information for context.

farcaster_timeline

Provides the agent's recent timeline for context about recent activity.

farcaster_thread

Provides thread context for understanding conversation flow.

Development

Building

# TypeScript
bun run build

# Python
cd python && python -m build

# Rust
cd rust && cargo build --release

Testing

# All languages
bun run test

# TypeScript only
bun run test:ts

# Python only
bun run test:python

# Rust only
bun run test:rust

Linting

# TypeScript
bun run lint

# Python
bun run lint:python

# Rust
bun run lint:rust

Architecture

plugin-farcaster/
├── typescript/          # TypeScript implementation
│   ├── index.ts         # Main plugin entry
│   ├── client/          # Neynar API client
│   ├── services/        # Service layer
│   ├── actions/         # SEND_CAST, REPLY_TO_CAST
│   ├── providers/       # Context providers
│   └── types/           # Type definitions
├── python/              # Python implementation
│   ├── elizaos_plugin_farcaster/
│   │   ├── __init__.py
│   │   ├── client.py    # Neynar API client
│   │   ├── service.py   # Service layer
│   │   └── types.py     # Type definitions
│   └── tests/
└── rust/                # Rust implementation
    ├── src/
    │   ├── lib.rs       # Library entry
    │   ├── client.rs    # Neynar API client
    │   ├── service.rs   # Service layer
    │   ├── actions/     # Action implementations
    │   └── providers/   # Provider implementations
    └── tests/

API Reference

TypeScript

• FarcasterService - Main service managing client lifecycle
• FarcasterClient - Low-level API client
• sendCastAction - Action for posting casts
• replyCastAction - Action for replying to casts
• farcasterProfileProvider - Profile context provider
• farcasterTimelineProvider - Timeline context provider

Python

• FarcasterService - Main service class
• FarcasterClient - Async API client
• FarcasterConfig - Configuration dataclass
• SendCastAction - Cast action
• ReplyCastAction - Reply action
• ProfileProvider - Profile provider
• TimelineProvider - Timeline provider

Rust

• FarcasterService - Main service struct
• FarcasterClient - API client
• FarcasterConfig - Configuration struct
• SendCastAction - Cast action
• ReplyCastAction - Reply action
• ProfileProvider - Profile provider
• TimelineProvider - Timeline provider

License

MIT License - see LICENSE file for details.

Contributing

Contributions are welcome! Please ensure that any changes maintain feature parity across all three language implementations.