Create new Farcaster account
Currently, this feature is available only for Enterprise tier customers. Please get in touch with us if you wish to access this feature.
Each new user account costs $X (based on the contract) and the total will be charged at the end of the month
This guide enables developers to seamlessly create and register new user accounts on Farcaster through Neynar. This API is allowlisted so if you're interested in using it, reach out to @rish . By the end, you will:
- Claim and register a new user account.
- Assign a fname and username to the new user account.
- Obtain a
signer_uuid
for the new user account and make changes on Farcaster. - Get an understanding of the entire flow behind the scenes.
Prerequisites
- Ensure you're in the Enterprise tier (Check plans here)
- Installation of curl, yarn, and Node.js and npm.
If using embedded wallets
We will update this doc to better walk through how to do the above with embedded wallets. Till then, see this guide written by community member jpfraneto ; includes source code you can use to get started.
Step 1: Claim an account for the new user
To register a new user, you need to claim an account for that user.
API Call
curl --location 'https://api.neynar.com/v2/farcaster/user/fid' \
--header 'api_key: NEYNAR_API_KEY'
Note: Replace NEYNAR_API_KEY with your actual API key.
Responses
{
"fid": UNIQUE_FID // UNIQUE_FID is a number
}
{
"message": "Please try again later"
}
In the next step, you'll need this fid here to generate a signature.
Step 2: Ask the user to sign a message accepting their new Farcaster account
To create a Farcaster account, users must sign a message proving they're willing to accept the account using a particular wallet address. The user needs to sign a message containing
- fid (fetched in the previous step)
- the address that will custody the Farcaster account (connected address on the client/app developer)
- and a deadline until which their signature is valid. (generated by the client/app developer)
Usually, client or application developers must implement this step by constructing a message and asking the user to sign it in their connected web3 wallet.
However, for the sake of testing out the flow, here's a script that effectively produces the equivalent signatures you would get back from eth.sign
Setup project
mkdir generate-required-parameters
cd generate-required-parameters
Install Dependencies
yarn add @farcaster/hub-nodejs viem
npm install @farcaster/hub-nodejs viem
Create the Script
Create a file named generate-required-parameters.js
touch generate-required-parameters.js
Paste the following script in it. This script generates certain parameters that you'll need to make the next API call.
Replace FID_TO_COLLECT_SIGNATURE_FOR
with fid returned from GET - /v2/farcaster/user/fid
and NEW_ACCOUNT_MNEMONIC
with a new account MNEMONIC.
// generate-required-parameters.js --> Filename
const {
ID_REGISTRY_ADDRESS,
ViemLocalEip712Signer,
idRegistryABI,
} = require('@farcaster/hub-nodejs');
const { bytesToHex, createPublicClient, http } = require('viem');
const { mnemonicToAccount } = require('viem/accounts');
const { optimism } = require('viem/chains');
const publicClient = createPublicClient({
chain: optimism,
transport: http(),
});
const FID = 'FID_TO_COLLECT_SIGNATURE_FOR'; // fid returned from GET - /v2/farcaster/user/fid
const MNEMONIC = 'NEW_ACCOUNT_MNEMONIC';
const getDeadline = () => {
const now = Math.floor(Date.now() / 1000);
const oneHour = 60 * 60;
return BigInt(now + oneHour);
};
(async () => {
const deadline = getDeadline();
console.log('\ndeadline: ', parseInt(deadline));
const requestedUserAccount = mnemonicToAccount(MNEMONIC);
const requestedUserAccountSigner = new ViemLocalEip712Signer(
requestedUserAccount
);
console.log(
'\nrequested_user_custody_address: ',
requestedUserAccount.address
);
let requestedUserNonce = await publicClient.readContract({
address: ID_REGISTRY_ADDRESS,
abi: idRegistryABI,
functionName: 'nonces',
args: [requestedUserAccount.address],
});
console.log('\nfid: ', parseInt(FID));
let requestedUserSignature = await requestedUserAccountSigner.signTransfer({
fid: BigInt(FID),
to: requestedUserAccount.address,
nonce: requestedUserNonce,
deadline,
});
console.log(
'\nsignature: ',
bytesToHex(requestedUserSignature.value),
'\n'
);
})();
Execute Script
Run the script to generate the necessary parameters for user registration. Get the FID i.e UNIQUE_FID
from Step 1 and pass it on in the following command
node generate-required-parameters.js
Script Output
You'll receive output containing several values, including deadline
, requested_user_custody_address
, fid
, signature
Step 3: Ask the user to pick their fname (optional)
Client applications should ask users to pick a username for their Farcaster account. The fname availability API should be used to check if their chosen username is available. The fname should match the following regex - /^[a-z0-9][a-z0-9-]{0,15}$/
. Official regex defined in the farcaster/core library
Step 4: Register the User
Construct a POST request with the generated parameters to finalize the user's registration.
Finalize Registration
curl --location 'https://api.neynar.com/v2/farcaster/user' \
--header 'api_key: NEYNAR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
"deadline": "DEADLINE_FROM_SCRIPT",
"requested_user_custody_address": "CUSTODY_ADDRESS_FROM_SCRIPT",
"fid": 0,
"signature": "SIGNATURE_FROM_SCRIPT",
"fname": "desired-username"
}'
Responses
{
"success": true,
"message": "Account transferred successfully.",
"signer": {
"fid": 0,
"signer_uuid": "35b0bbd5-4e20-4213-a30c-4183258a73ab",
"status": "APPROVED",
"public_key": "0x123412341234123412341234123412341234"
}
}
{
"message": "Account not found"
}
{
"message": "Account is not issued to you"
}
{
"message": "Account not found"
}
{
"message": "Account is already registered to another user"
}
{
"success": false,
"message": "Failed to sign transfer",
}
Step 5: Profile setup (optional)
Using the approved signer_uuid from the response in Step 4, you can ask the user to update their profile by picking a profile photo, display name, bio, and more.
Updated 12 days ago