Farcaster Agent

Create Farcaster accounts and post casts autonomously. Official skill from the Farcaster team.

Security Scan

The skill's stated purpose (creating Farcaster accounts) is plausible, but the runtime instructions reference local code files that are not included, use sensitive environment variables (private keys) that are not declared, and instruct saving plaintext credentials and running npm install in a parent directory — these inconsistencies and data-handling choices warrant caution and verification before installing or funding any wallet.

Purpose & Capability

Creating wallets, registering FIDs, and posting casts legitimately requires wallet private keys and blockchain fees; asking for ~ $1 of ETH/USDC to fund a wallet is consistent with that purpose. However, the skill's metadata declares no required env vars or credentials while the SKILL.md repeatedly instructs use of PRIVATE_KEY, SIGNER_PRIVATE_KEY, and FID environment variables — a mismatch. The skill also claims to auto-handle bridging/swaps and to run scripts under src/, but no code files are included in the skill bundle, which is inconsistent with the claimed capabilities.

Instruction Scope

The SKILL.md instructs the agent/user to generate and provide private keys via environment variables and to run node scripts (e.g., src/auto-setup.js, src/post-cast.js) that are not present in the package. It instructs automatic saving of credentials to ~/.openclaw/farcaster-credentials.json or ./credentials.json in plain text and shows CLI usage patterns that would expose secrets. Instructions also direct the user to transfer real funds to addresses the skill generates. Storing private keys in plain text and executing unspecified scripts are high-risk behaviors and exceed what a simple helper should require.

Install Mechanism

The only install step is a shell npm install run in {baseDir}/.. — this will run whatever package.json exists in the parent directory, potentially executing arbitrary postinstall scripts. Because the skill bundle contains no code, the npm install target is unclear (and may rely on external repository structure). Running npm install without an included, auditable package is risky.

Credentials

The skill declares no required environment variables yet the instructions expect sensitive vars (PRIVATE_KEY, SIGNER_PRIVATE_KEY, FID). It also instructs saving these secrets in plaintext files. Requesting private keys is proportional to the described blockchain operations, but not declaring them in metadata and recommending plaintext persistence is a poor security design and a red flag.

Persistence & Privilege

The skill is not marked always:true and does not request elevated platform privileges. However, it instructs writing persistent credential files to user paths (~/.openclaw/farcaster-credentials.json or ./credentials.json). While saving credentials for convenience can be normal, the combination of plaintext storage and absent included code increases the risk if the user does not audit where and how keys are stored.

What to consider before installing

Do not send real funds or hand over your primary private key until you verify the code and origin. Specific steps to consider: - The SKILL.md references node scripts under src/ but the skill bundle contains no code; ask the publisher for the repository URL or source code and inspect it before running anything. - Inspect package.json and all scripts (including postinstall) in the codebase that npm install would run; avoid running npm install blindly in an unverified directory. - Use a throwaway/ephemeral wallet with a small test amount (e.g., <$1) when experimenting — never use your primary wallet. - Prefer the --no-save option and do not allow plaintext credential files; if you must persist keys, use an encrypted key manager or a hardware wallet. - Verify the skill's publisher and homepage (none are provided). An "Official" claim here is unsupported by source or homepage metadata; ask for provenance (signed release, GitHub org, or official announcement). - If you proceed, run all actions in an isolated environment (VM or container) and monitor network/file activity. If you are not comfortable auditing JS code, decline or seek a developer to review it. These inconsistencies and missing artifacts make this skill suspicious — verify source code and storage behavior before installing or funding any wallet.

Official skill from the Farcaster team. Create and manage a Farcaster account autonomously. Register a new Farcaster identity (FID), add signing keys, set up a profile with username, and post casts to the network.

When to Use This Skill

Use this skill when:

• You need to create a Farcaster account from scratch
• You want to post casts (messages) to Farcaster
• You need to set up a profile with username, bio, and profile picture
• You want autonomous presence on the Farcaster social network

Prerequisites

You need approximately $1 of ETH or USDC on any major chain (Ethereum, Optimism, Base, Arbitrum, or Polygon). The skill handles bridging and swapping automatically.

Complete Flow

Step 1: Generate Wallet and Request Funding

If you don't have a funded wallet, create one first:

const { Wallet } = require('ethers');

const wallet = Wallet.createRandom();
console.log('Address:', wallet.address);
console.log('Private Key:', wallet.privateKey);

Ask your human: "I've created a wallet. Please send ~$1 of ETH or USDC to <address> on any of these chains: Ethereum, Optimism, Base, Arbitrum, or Polygon. Let me know when done."

Save the private key securely - you'll need it for all subsequent steps.

Step 2: Run Auto-Setup

Once funded, run the complete setup:

cd {baseDir}/..
PRIVATE_KEY=0x... node src/auto-setup.js "Your first cast text here"

This will:

1. Detect which chain has funds (ETH or USDC)
2. Bridge/swap to get ETH on Optimism and USDC on Base
3. Register your FID (Farcaster ID)
4. Add a signer key
5. Wait for hub synchronization
6. Post your first cast
7. Automatically save credentials to persistent storage

Step 3: Credentials are Saved Automatically

Credentials are automatically saved to:

• ~/.openclaw/farcaster-credentials.json (if OpenClaw is installed)
• ./credentials.json (fallback)

Security Warning: Credentials are stored as plain text JSON. Anyone with access to these files can control the wallet funds and Farcaster account. For production use, implement your own secure storage.

You can verify and manage credentials:

cd {baseDir}/..

# List all stored accounts
node src/credentials.js list

# Get credentials for active account
node src/credentials.js get

# Show credentials file path
node src/credentials.js path

To disable auto-save, use --no-save:

PRIVATE_KEY=0x... node src/auto-setup.js "Your cast" --no-save

Posting Casts

To post additional casts, load credentials from storage:

const { postCast, loadCredentials } = require('{baseDir}/../src');

// Load saved credentials
const creds = loadCredentials();

const { hash } = await postCast({
  privateKey: creds.custodyPrivateKey,
  signerPrivateKey: creds.signerPrivateKey,
  fid: Number(creds.fid),
  text: 'Your cast content'
});

console.log('Cast URL: https://farcaster.xyz/~/conversations/' + hash);

Or via CLI with environment variables:

cd {baseDir}/..
PRIVATE_KEY=0x... SIGNER_PRIVATE_KEY=... FID=123 node src/post-cast.js "Your cast content"

Setting Up Profile

To set username, display name, bio, and profile picture:

cd {baseDir}/..
PRIVATE_KEY=0x... SIGNER_PRIVATE_KEY=... FID=123 npm run profile myusername "Display Name" "My bio" "https://example.com/pfp.png"

Or programmatically:

const { setupFullProfile } = require('{baseDir}/../src');

await setupFullProfile({
  privateKey: '0x...',
  signerPrivateKey: '...',
  fid: 123,
  fname: 'myusername',
  displayName: 'My Display Name',
  bio: 'I am an autonomous AI agent.',
  pfpUrl: 'https://api.dicebear.com/7.x/bottts/png?seed=myagent'
});

Fname (Username) Requirements

• Lowercase letters, numbers, and hyphens only
• Cannot start with a hyphen
• 1-16 characters
• One fname per account
• Can only change once every 28 days

Profile Picture Options

For PFP, use any publicly accessible HTTPS image URL:

• DiceBear (generated avatars): https://api.dicebear.com/7.x/bottts/png?seed=yourname
• IPFS-hosted images
• Any public image URL

Cost Breakdown

Operation	Cost
FID Registration	~$0.20
Add Signer	~$0.05
Bridging	~$0.10-0.20
Each API call	$0.001
Total minimum	~$0.50

Budget $1 to have buffer for retries and gas fluctuations.

API Endpoints

Neynar Hub API (https://hub-api.neynar.com)

Endpoint	Method	Description
/v1/submitMessage	POST	Submit casts, profile updates (requires x402 payment header)
/v1/onChainIdRegistryEventByAddress?address=<addr>	GET	Check if FID is synced for address
/v1/onChainSignersByFid?fid=<fid>	GET	Check if signer keys are synced

Neynar REST API (https://api.neynar.com)

Endpoint	Method	Description
/v2/farcaster/cast?identifier=<hash>&type=hash	GET	Verify cast exists on network

Farcaster Fname Registry (https://fnames.farcaster.xyz)

Endpoint	Method	Description
/transfers	POST	Register or transfer an fname (requires EIP-712 signature)
/transfers/current?name=<fname>	GET	Check fname availability (404 = available)

x402 Payment

• Address: 0xA6a8736f18f383f1cc2d938576933E5eA7Df01A1
• Cost: 0.001 USDC per API call (on Base)
• Header: X-PAYMENT with base64-encoded EIP-3009 transferWithAuthorization signature

Common Errors

"invalid hash"

Cause: Old library version. Fix: Run npm install @farcaster/hub-nodejs@latest

"unknown fid"

Cause: Hub hasn't synced your registration yet. Fix: Wait 30-60 seconds and retry.

Transaction reverts when adding signer

Cause: Metadata encoding issue. Fix: The code already uses the correct SignedKeyRequestValidator.encodeMetadata() method.

"fname is not registered for fid"

Cause: Hub hasn't synced your fname registration. Fix: Wait 30-60 seconds (the code handles this automatically).

Manual Step-by-Step (If Auto-Setup Fails)

If auto-setup fails partway through, you can run individual steps:

cd {baseDir}/..

# 1. Register FID (on Optimism)
PRIVATE_KEY=0x... node src/register-fid.js

# 2. Add signer key (on Optimism)
PRIVATE_KEY=0x... node src/add-signer.js

# 3. Swap ETH to USDC (on Base, for x402 payments)
PRIVATE_KEY=0x... node src/swap-to-usdc.js

# 4. Post cast
PRIVATE_KEY=0x... SIGNER_PRIVATE_KEY=... FID=123 node src/post-cast.js "Hello!"

# 5. Set up profile
PRIVATE_KEY=0x... SIGNER_PRIVATE_KEY=... FID=123 npm run profile username "Name" "Bio" "pfp-url"

Programmatic API

All functions are available for import:

const {
  // Full autonomous setup
  autoSetup,
  checkAllBalances,

  // Core functions
  registerFid,
  addSigner,
  postCast,
  swapEthToUsdc,

  // Profile setup
  setProfileData,
  registerFname,
  setupFullProfile,

  // Credential management
  saveCredentials,
  loadCredentials,
  listCredentials,
  setActiveAccount,
  updateCredentials,
  getCredentialsPath,

  // Utilities
  checkFidSync,
  checkSignerSync,
  getCast
} = require('{baseDir}/../src');

Example: Full Autonomous Flow

const { Wallet } = require('ethers');
const { autoSetup, setupFullProfile } = require('{baseDir}/../src');

// 1. Generate wallet (or use existing)
const wallet = Wallet.createRandom();
console.log('Fund this address with $1 ETH or USDC:', wallet.address);

// 2. After human funds the wallet, run setup
const result = await autoSetup(wallet.privateKey, 'gm farcaster!');

console.log('FID:', result.fid);
console.log('Signer:', result.signerPrivateKey);
console.log('Cast:', result.castHash);

// 3. Set up profile
await setupFullProfile({
  privateKey: wallet.privateKey,
  signerPrivateKey: result.signerPrivateKey,
  fid: result.fid,
  fname: 'myagent',
  displayName: 'My AI Agent',
  bio: 'Autonomous agent on Farcaster',
  pfpUrl: 'https://api.dicebear.com/7.x/bottts/png?seed=myagent'
});

console.log('Profile: https://farcaster.xyz/myagent');

Source Code

The complete implementation is at: https://github.com/rishavmukherji/farcaster-agent

For detailed technical documentation, see the AGENT_GUIDE.md in that repository.