farcaster-agent

# Farcaster Agent

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:

```javascript
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:

```bash
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:

```bash
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`:
```bash
PRIVATE_KEY=0x... node src/auto-setup.js "Your cast" --no-save
```

## Posting Casts

To post additional casts, load credentials from storage:

```javascript
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:

```bash
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:

```bash
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:

```javascript
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:

```bash
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:

```javascript
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

```javascript
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.