Add a Signer to Your Farcaster Account

Just created a Farcaster account and ready to start casting, following, or updating your profile? Not so fast, you’ll need a signer first.

In this post, we’ll learn how to add a signer to your account. We’ll generate a new signing keypair, authorize it with your wallet, and register it onchain using viem and @farcaster/core.

Note, this guide is for adding signers to your own account. If you’re building for other users, we’ll cover that in a future post.

You can view the complete script on GitHub to copy, customize, or run it end-to-end.

Setup

First, create a new project and install our dependencies:

bun init -y
bun add viem @farcaster/core @noble/ed25519

This script uses environment variables to load your wallet and FID. Create a .env file with the following values:

WALLET_MNEMONIC="your twelve word seed phrase"
WALLET_FID=1234

Load your Wallet

Start by loading the Ethereum wallet that owns your FID. This wallet will authorize the new signer.

import { mnemonicToAccount } from 'viem/accounts';

const account = mnemonicToAccount(process.env.WALLET_MNEMONIC!);
const fid = Number(process.env.WALLET_FID);

console.log('Account Address:', account.address);
console.log('Account FID:', fid);

Make sure wallet’s address if the owner of the FID. You can confirm this with the idOf function of IdRegistry contract if needed.

Generate a Signer Key

Now generate a new keypair, which includes a public and private key. Farcaster uses keypairs to sign and verify actions without needing your wallet for every interaction.

import * as ed from '@noble/ed25519';
import { bytesToHex } from 'viem';

const privateKey = ed.utils.randomPrivateKey();
const signerKeypair = {
	privateKey: bytesToHex(privateKey),
	publicKey: bytesToHex(await ed.getPublicKeyAsync(privateKey)),
};

console.log('Signer Public Key:', signerKeypair.publicKey);
console.log('Signer Private Key:', signerKeypair.privateKey);

This key will be used to publish account activity to the Farcaster network. You’ll authorize it with your wallet in the next step.

Sign the Key Request

This step creates an EIP-712–compliant request and signs it with your wallet to confirm the signer is authorized to act on your behalf. We’ll submit this signed request for onchain verification in the next step.

const deadline = BigInt(Math.floor(Date.now() / 1000) + 86400); // 24 hours from now

const keyRequestData = {
	...SIGNED_KEY_REQUEST_VALIDATOR_EIP_712_TYPES,
	primaryType: 'SignedKeyRequest',
	message: {
		requestFid: BigInt(fid),
		key: signerKeypair.publicKey,
		deadline,
	},
} as const;

const signature = await account.signTypedData(keyRequestData);
console.log('Signed Key Request:', signature);

The deadline defines how long the key request is valid. If it’s not submitted before then, it will be rejected by the contract.

Prepare the Metadata

This step prepares the signed request in a format the KeyGateway contract expects. In the next step, you’ll use it to register the signer onchain.

import { encodeAbiParameters } from 'viem';
import { signedKeyRequestValidatorABI } from '@farcaster/core';

const metadata = encodeAbiParameters(signedKeyRequestValidatorABI[12].inputs, [
	{
		requestFid: BigInt(fid),
		requestSigner: account.address,
		signature,
		deadline,
	},
]);

Register the Signer Onchain

With the metadata encoded, you’re ready to call the KeyGateway contract to register the signer onchain. After confirmation, the signer is linked to your FID and can be used to publish activity to the network.

import { createPublicClient, createWalletClient, http } from 'viem';
import { optimism } from 'viem/chains';
import { KEY_GATEWAY_ADDRESS, keyGatewayABI } from '@farcaster/core';

const publicClient = createPublicClient({
	chain: optimism,
	transport: http(),
});

const { request } = await publicClient.simulateContract({
	account,
	address: KEY_GATEWAY_ADDRESS,
	abi: keyGatewayABI,
	functionName: 'add',
	args: [1, signerKeypair.publicKey, 1, metadata],
});

const walletClient = createWalletClient({
	chain: optimism,
	transport: http(),
});

const txn = await walletClient.writeContract(request);
console.log(`Transaction: https://optimistic.etherscan.io/tx/${txn}`);

Next Steps

You’ve successfully added a signer to your Farcaster account. Now you can now interact with the network without using your wallet directly.

Here’s what you might do next:

Claim a username and update your profile

Set a human-readable username, add a profile picture, and write a short bio. This makes your account recognizable across Farcaster clients.

Send your first cast

A cast is Farcaster’s version of a post. Once your account is ready, you can start sharing messages on the network just like tweeting, but decentralized.