Unzipped Skill

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:

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

Profile Picture Options

For PFP, use any publicly accessible HTTPS 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)

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

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

x402 Payment

Common Errors

"invalid hash"

"unknown fid"

Transaction reverts when adding signer

"fname is not registered for fid"

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.