Farcaster 代理

Farcaster 团队官方技能。自主创建和管理 Farcaster 账户。注册新的 Farcaster 身份（FID），添加签名密钥，设置包含用户名的个人资料，并向网络发布广播。

使用时机

在以下情况下使用此技能：

• 你需要从头创建 Farcaster 账户
• 你想向 Farcaster 发布广播（消息）
• 你需要设置包含用户名、简介和个人资料图片的个人资料
• 你希望在 Farcaster 社交网络上拥有自主存在

前提条件

你需要大约价值 1 美元的 ETH 或 USDC在任何主流链上（以太坊、Optimism、Base、Arbitrum 或 Polygon）。该技能会自动处理跨链桥接和兑换。

完整流程

步骤 1：生成钱包并请求资金

如果你没有已注资的钱包，请先创建一个：

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

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

询问你的用户："我已创建一个钱包。请向以下地址发送约 1 美元的 ETH 或 USDC：<地址>"在以太坊、Optimism、Base、Arbitrum 或 Polygon 任意一条链上操作。完成后请告诉我。"

请安全保存私钥- 后续所有步骤都需要用到它。

步骤 2：运行自动设置

资金到位后，运行完整设置：

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

这将：

1. 检测哪条链上有资金（ETH 或 USDC）
2. 跨链桥接/兑换，以在 Optimism 上获取 ETH 并在 Base 上获取 USDC
3. 注册您的 FID（Farcaster ID）
4. 添加签名者密钥
5. 等待中心同步
6. 发布您的第一条动态
7. 自动保存凭据至持久化存储

步骤 3：凭据自动保存

凭据将自动保存至：

• ~/.openclaw/farcaster-credentials.json（如果安装了 OpenClaw）
• ./credentials.json（备用位置）

安全警告：凭据以纯文本JSON格式存储。任何能访问这些文件的人都可以控制钱包资金和Farcaster账户。用于生产环境时，请自行实现安全的存储方案。

您可以验证和管理凭据：

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

要禁用自动保存，请使用--no-save：

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

发布动态

要发布更多动态，请从存储中加载凭据：

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);

或通过CLI使用环境变量：

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

设置个人资料

要设置用户名、显示名称、个人简介和头像：

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

或以编程方式：

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（用户名）要求

• 仅限小写字母、数字和连字符
• 不能以连字符开头
• 1-16个字符
• 每个账户只能有一个fname
• 每28天只能更改一次

头像选项

对于PFP（个人资料图片），请使用任何可公开访问的HTTPS图片URL：

• DiceBear（生成的头像）：https://api.dicebear.com/7.x/bottts/png?seed=yourname
• IPFS托管的图片
• 任何公开的图片URL

成本明细

预算$1，为重试和Gas费用波动留出缓冲。

API端点

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

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

Farcaster Fname注册表 (https://fnames.farcaster.xyz)

x402 支付

• 地址： 0xA6a8736f18f383f1cc2d938576933E5eA7Df01A1
• 费用：每次 API 调用 0.001 USDC（在 Base 链上）
• 请求头： X-PAYMENT包含 base64 编码的 EIP-3009transferWithAuthorization签名

常见错误

"invalid hash"

原因：库版本过旧。解决方法：运行npm install @farcaster/hub-nodejs@latest

"unknown fid"

原因：Hub尚未同步您的注册信息。解决方法：等待30-60秒后重试。

添加签名者时交易回滚

原因：元数据编码问题。解决方法：代码已使用正确的SignedKeyRequestValidator.encodeMetadata()方法。

"fname未注册给fid"

原因：Hub尚未同步您的fname注册信息。解决方法：等待30-60秒（代码会自动处理此问题）。

手动分步操作（若自动设置失败）

若自动设置中途失败，您可以单独运行以下步骤：

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"

编程接口

所有函数均可导入使用：

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

示例：完整自主流程

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

源代码

完整实现位于：https://github.com/rishavmukherji/farcaster-agent

详细技术文档请参阅该仓库中的AGENT_GUIDE.md文件。