---

name: farcaster-agent description: Create Farcaster accounts and manage on-chain identity. Register FIDs, manage signing keys, set up profiles, purchase storage. Official skill from the Farcaster team. metadata: {"openclaw":{"emoji":"🟣","requires":{"bins":["node","npm"],"env":[]},"install":[{"id":"npm","kind":"shell","command":"cd {baseDir}/.. && npm install","label":"Install dependencies"}]}}

Farcaster Agent

Official skill from the Farcaster team. Create and manage a Farcaster account autonomously. Register a new Farcaster identity (FID), manage signing keys, set up profiles, and handle on-chain operations.

When to Use This Skill vs Neynar

| Task | Use This Skill | Use Neynar | |------|---------------|------------| | Create a new Farcaster account | ✅ | ❌ | | Register FID on-chain | ✅ | ❌ | | Add/rotate signing keys | ✅ | ❌ | | Set up profile (username, bio, PFP) | ✅ | ❌ | | Purchase storage units | ✅ | ❌ | | Post casts | ⚠️ Possible, but heavier | ✅ Preferred | | Read feeds, search, look up users | ❌ | ✅ | | Like, recast, follow/unfollow | ❌ | ✅ | | Check notifications | ❌ | ✅ | | Browse channels | ❌ | ✅ |

Rule of thumb:

• This skill = account setup, on-chain operations, key management (one-time or rare tasks)
• Neynar = daily social operations (posting, reading, engaging — the neynar.sh CLI)

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 Setup Flow

Step 1: Generate Wallet and Request Funding

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."

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

Step 2: Run Auto-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) on Optimism
4. Add a signer key
5. Wait for hub synchronization
6. Post your first cast
7. Save credentials to persistent storage

Step 3: Verify Credentials

Credentials are saved to ~/.openclaw/farcaster-credentials.json (or ./credentials.json as fallback).

cd {baseDir}/..
node src/credentials.js list    # List all stored accounts
node src/credentials.js get     # Get active account credentials
node src/credentials.js path    # Show credentials file path

Profile Management

Set Up Full Profile

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

Update Display Name & Bio

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

await setProfileData({
  privateKey: creds.custodyPrivateKey,
  signerPrivateKey: creds.signerPrivateKey,
  fid: Number(creds.fid),
  displayName: 'New Display Name',
  bio: 'Updated bio text here'
});

Change Profile Picture

await setProfileData({
  privateKey: creds.custodyPrivateKey,
  signerPrivateKey: creds.signerPrivateKey,
  fid: Number(creds.fid),
  pfpUrl: 'https://your-new-pfp-url.com/image.png'
});

PFP options:

• DiceBear (generated avatars): https://api.dicebear.com/7.x/bottts/png?seed=yourname
• IPFS via Pinata: Upload to Pinata, use gateway URL
• Any publicly accessible HTTPS image URL

Change Username (Fname)

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

await registerFname({
  privateKey: creds.custodyPrivateKey,
  fid: Number(creds.fid),
  fname: 'newusername'
});

Fname rules:

• 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

Key Rotation Guide

Signing keys should be rotated periodically or if compromised.

Step 1: Add a New Signer Key

cd {baseDir}/..
PRIVATE_KEY=0x... node src/add-signer.js

This generates a new Ed25519 keypair, registers it on-chain via the KeyGateway contract, and outputs the new signer private key.

Step 2: Update Your Config

Save the new signer private key in your credentials. If using Neynar managed signers, create a new signer in the Neynar dashboard and update signerUuid in ~/.clawdbot/skills/neynar/config.json.

Step 3: Revoke the Old Key

Old keys can be revoked via the KeyGateway contract on Optimism:

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

const KEY_GATEWAY = '0x00000000fC56947c7E7183f8Ca4B62398CaAdf0B';
const provider = new ethers.JsonRpcProvider('https://mainnet.optimism.io');
const wallet = new ethers.Wallet(CUSTODY_PRIVATE_KEY, provider);

const keyGateway = new ethers.Contract(KEY_GATEWAY, [
  'function remove(bytes calldata key) external'
], wallet);

// Remove old signer public key
const tx = await keyGateway.remove(OLD_SIGNER_PUBLIC_KEY_BYTES);
await tx.wait();

Step 4: Verify

# Check active signers for your FID via hub
curl "https://hub-api.neynar.com/v1/onChainSignersByFid?fid=YOUR_FID" | jq .

Recovery Address Management

The recovery address can recover your FID if the custody wallet is compromised.

Set during registration: The recovery address is set when the FID is first registered via the IdGateway contract. By default, auto-setup.js sets it to the custody address itself.

Change recovery address:

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

const ID_REGISTRY = '0x00000000Fc6c5F01Fc30151999387Bb99A9f489b';
const provider = new ethers.JsonRpcProvider('https://mainnet.optimism.io');
const wallet = new ethers.Wallet(CUSTODY_PRIVATE_KEY, provider);

const idRegistry = new ethers.Contract(ID_REGISTRY, [
  'function changeRecoveryAddress(address recovery) external'
], wallet);

const tx = await idRegistry.changeRecoveryAddress(NEW_RECOVERY_ADDRESS);
await tx.wait();

Best practice: Set the recovery address to a hardware wallet or multisig that you control separately from the custody wallet.

Storage Purchase

Each FID gets 1 storage unit by default. Additional units allow more casts, reactions, and links.

Check Current Storage

# Via neynar CLI
neynar.sh storage YOUR_FID

Purchase More Storage

Storage is purchased via the StorageRegistry contract on Optimism:

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

const STORAGE_REGISTRY = '0x00000000fcCe7f938e7aE6D3c335bD6a1a7c593D';
const provider = new ethers.JsonRpcProvider('https://mainnet.optimism.io');
const wallet = new ethers.Wallet(CUSTODY_PRIVATE_KEY, provider);

const storage = new ethers.Contract(STORAGE_REGISTRY, [
  'function rent(uint256 fid, uint256 units) external payable',
  'function price(uint256 units) external view returns (uint256)'
], wallet);

// Check price for 1 additional unit
const price = await storage.price(1);
console.log('Price:', ethers.formatEther(price), 'ETH');

// Purchase
const tx = await storage.rent(YOUR_FID, 1, { value: price });
await tx.wait();

Storage Capacity Per Unit

| Resource | Per Unit | |----------|----------| | Casts | 5,000 | | Reactions | 2,500 | | Links (follows) | 2,500 | | User data | 50 |

Multi-Account Management

The credentials system supports multiple accounts:

cd {baseDir}/..

# List all accounts
node src/credentials.js list

# Each auto-setup creates a new account entry
# Switch active account by FID
node -e "
const { setActiveAccount } = require('./src');
setActiveAccount('TARGET_FID');
"

Credential file structure (~/.openclaw/farcaster-credentials.json):

{
  "activeAccount": "fid_123",
  "accounts": {
    "fid_123": {
      "fid": "123",
      "custodyAddress": "0x...",
      "custodyPrivateKey": "0x...",
      "signerPrivateKey": "...",
      "signerPublicKey": "...",
      "createdAt": "2025-01-01T00:00:00Z"
    }
  }
}

Security Best Practices

1. Custody wallet — This is the "master key" for your FID. Store the private key securely (macOS Keychain, encrypted vault). Never expose in logs or version control.

2. Signer keys — These are delegated keys for posting. If compromised, revoke immediately via KeyGateway and create a new one. The custody wallet is NOT compromised if a signer leaks.

3. Recovery address — Set to a separate hardware wallet or multisig. This is your last resort if the custody wallet is compromised.

4. Credential files — farcaster-credentials.json contains plain text private keys. Restrict file permissions:

   chmod 600 ~/.openclaw/farcaster-credentials.json
   

5. Signer rotation — Rotate signing keys every 3-6 months or immediately after any security incident.

6. Neynar managed signers — For bot/agent use, Neynar managed signers (signerUuid) are simpler and Neynar handles key custody. The trade-off is trust in Neynar.

7. Never share custody private key, signer private key, or credential files.

Contract Addresses (Optimism Mainnet)

| Contract | Address | Purpose | |----------|---------|---------| | IdGateway | 0x00000000Fc25870C6eD6b6c7E41Fb078b7a38947 | Register new FIDs | | IdRegistry | 0x00000000Fc6c5F01Fc30151999387Bb99A9f489b | FID ownership registry | | KeyGateway | 0x00000000fC56947c7E7183f8Ca4B62398CaAdf0B | Add/remove signer keys | | KeyRegistry | 0x00000000Fc1237824fb747aBDE0FF18990E59b7e | Signer key registry | | StorageRegistry | 0x00000000fcCe7f938e7aE6D3c335bD6a1a7c593D | Purchase storage units | | Bundler | 0x00000000FC04c910A0b5feA33b03E0447AD0B0aA | Register FID + add key + rent storage in one tx | | SignedKeyRequestValidator | 0x00000000FC700472606ED4fA22623Acf62c60553 | Validates signer key metadata |

All contracts are on Optimism Mainnet (Chain ID: 10).

Explorer: https://optimistic.etherscan.io/address/<contract>

Cost Breakdown

| Operation | Approximate Cost | |-----------|-----------------| | FID Registration (IdGateway) | ~$0.20 | | Add Signer Key (KeyGateway) | ~$0.05 | | Bridging (cross-chain) | ~$0.10-0.20 | | Storage Unit (1 year) | ~$3-5 (variable, market price) | | x402 API call (hub submission) | $0.001 USDC on Base | | Total minimum setup | ~$0.50 |

Budget $1 for initial setup to cover gas fluctuations and retries.

API Endpoints

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

| Endpoint | Method | Description | |----------|--------|-------------| | /v1/submitMessage | POST | Submit casts, profile updates (requires x402 payment) | | /v1/onChainIdRegistryEventByAddress?address=X | GET | Check FID registration sync | | /v1/onChainSignersByFid?fid=X | GET | Check signer key sync |

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

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

x402 Payment

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

Troubleshooting

"invalid hash"

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

"unknown fid"

Cause: Hub hasn't synced your on-chain registration yet. Fix: Wait 30-60 seconds and retry. The auto-setup handles this automatically.

Transaction reverts when adding signer

Cause: Metadata encoding issue or insufficient gas. Fix: Ensure you're using SignedKeyRequestValidator.encodeMetadata() correctly. Check Optimism ETH balance.

"fname is not registered for fid"

Cause: Hub hasn't synced fname registration. Fix: Wait 30-60 seconds. Auto-setup handles this.

Signer not working for posts

Cause: Signer key not yet synced to hubs, or signer was revoked. Fix: Check signer status:

curl "https://hub-api.neynar.com/v1/onChainSignersByFid?fid=YOUR_FID" | jq .

Insufficient funds

Cause: Not enough ETH on Optimism for gas. Fix: Bridge more ETH to Optimism. Need ~$0.50 worth.

Credential file not found

Fix: Check paths:

ls -la ~/.openclaw/farcaster-credentials.json
ls -la ./credentials.json

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

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

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
const wallet = Wallet.createRandom();
console.log('Fund this address with $1 ETH or USDC:', wallet.address);

// 2. After funding, run setup
const result = await autoSetup(wallet.privateKey, 'gm farcaster!');
console.log('FID:', result.fid);

// 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'
});

Source Code

https://github.com/rishavmukherji/farcaster-agent