请安全保存私钥 —— 后续所有步骤均需使用该私钥。

步骤 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. 添加签名者密钥（signer key）
5. 等待 Hub 同步完成
6. 发布首条 Cast
7. 自动将凭证保存至持久化存储

步骤 3：凭证自动保存

凭证将自动保存至以下路径之一：

• ~/.openclaw/farcaster-credentials.json（若已安装 OpenClaw）
• ./credentials.json（备用路径）

安全警告：凭证以明文 JSON 格式存储。任何可访问这些文件的人员均可控制该钱包资产及 Farcaster 账户。生产环境请自行实现安全存储方案。

您可通过以下命令验证和管理凭证：

cd {baseDir}/..

# 列出所有已保存账户
node src/credentials.js list

# 获取当前活跃账户的凭证
node src/credentials.js get

# 显示凭证文件路径
node src/credentials.js path

如需禁用自动保存，请使用 --no-save 参数：

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

发布 Cast

如需发布额外 Cast，请从存储中加载凭证：

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

// 加载已保存凭证
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）要求

• 仅允许小写字母、数字和连字符（hyphen）
• 不可以连字符开头
• 长度为 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-3009 transferWithAuthorization 签名

常见错误

“invalid hash”

原因：使用了过旧版本的库。修复方法：运行 npm install @farcaster/hub-nodejs@latest

“unknown fid”

原因：Hub 尚未完成您的注册同步。修复方法：等待 30–60 秒后重试。

添加签名者时交易回滚

原因：元数据编码异常。修复方法：代码中已正确使用 SignedKeyRequestValidator.encodeMetadata() 方法。

“fname is not registered for fid”

原因：Hub 尚未完成您的 fname 注册同步。修复方法：等待 30–60 秒（代码已自动处理此等待逻辑）。

手动分步操作（自动初始化失败时）

若自动初始化中途失败，可单独执行各步骤：

cd {baseDir}/..

# 1. 注册 FID（在 Optimism 链上）
PRIVATE_KEY=0x... node src/register-fid.js

# 2. 添加签名者密钥（在 Optimism 链上）
PRIVATE_KEY=0x... node src/add-signer.js

# 3. 将 ETH 兑换为 USDC（在 Base 链上，用于 x402 支付）
PRIVATE_KEY=0x... node src/swap-to-usdc.js

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

# 5. 设置个人资料
PRIVATE_KEY=0x... SIGNER_PRIVATE_KEY=... FID=123 npm run profile username "Name" "Bio" "pfp-url"

编程接口（Programmatic API）

所有函数均可直接导入使用：

const {
  // 完整自主初始化
  autoSetup,
  checkAllBalances,

  // 核心功能
  registerFid,
  addSigner,
  postCast,
  swapEthToUsdc,

  // 个人资料设置
  setProfileData,
  registerFname,
  setupFullProfile,

  // 凭证管理
  saveCredentials,
  loadCredentials,
  listCredentials,
  setActiveAccount,
  updateCredentials,
  getCredentialsPath,

  // 工具函数
  checkFidSync,
  checkSignerSync,
  getCast
} = require('{baseDir}/../src');

示例：完整自主流程

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

// 1. 生成钱包（或复用已有钱包）
const wallet = Wallet.createRandom();
console.log('Fund this address with $1 ETH or USDC:', wallet.address);

// 2. 待人工完成充值后，执行初始化
const result = await autoSetup(wallet.privateKey, 'gm farcaster!');

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

// 3. 设置个人资料
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 文件。