Skip to main content
This guide enables developers to seamlessly create and register new user accounts on Farcaster through Neynar. 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.

​
What You’ll Need

​
Prerequisites

New to App Wallets? All onchain operations require a wallet_id. See Managing Onchain Wallets to create your app wallet in the developer portal (self-service!).Recommended Setup Steps:
  1. Log in to dev.neynar.com and select your app
  2. Activate a wallet from the “App Wallet” tab
  3. Fund the wallet with $5+ ETH on Optimism
  4. Add the x-wallet-id header to your API requests (treat it like a secret)

​
If using embedded wallets, 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.
Cold Start (First Call Only): The first time you call this endpoint with a new wallet_id, it will take approximately 1 minute to complete as it pre-registers a few FID accounts. Subsequent calls will be fast (< 1 second). Make sure your wallet has $5+ ETH on Optimism before the first call.
Wallet Consistency Required: The same wallet_id used here must also be used in Step 5 when calling POST /v2/farcaster/user/. Using different wallets will result in an error.

​
API Call

curl --location 'https://api.neynar.com/v2/farcaster/user/fid' \
--header 'api_key: NEYNAR_API_KEY' \
--header 'x-wallet-id: YOUR_WALLET_ID'
Note: Replace NEYNAR_API_KEY with your actual API key and YOUR_WALLET_ID with your wallet ID from the setup guide.

​
Responses

{
	"fid": UNIQUE_FID // UNIQUE_FID is a number
}
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
  1. fid (fetched in the previous step)
  2. the address that will custody the Farcaster account (connected address on the client/app developer)
  3. 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

​
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: Add a managed signer to new account (optional)

If you want to add a managed signer to the new account during registration, you can include signer details in the registration request. This allows your application to manage the account on behalf of the user.

​
Create a Signer

First, create a signer using the Create Signer API: 
curl --location 'https://api.neynar.com/v2/farcaster/signer' \
--header 'api_key: NEYNAR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{}'
This will return a signer_uuid and public_key that you’ll need for the next step.

​
Generate Signed Key Request Metadata Signature

Use the following script to generate the signed_key_request_metadata_signature needed for the registration request. 
// generate-signed-key-request-metadata-signature.js --> Filename

const { bytesToHex, hexToBytes } = require('viem');
const { mnemonicToAccount } = require('viem/accounts');
const { ViemLocalEip712Signer } = require('@farcaster/core');

(async () => {
  /**_ Get public_key and signer_uuid of the signer _**/
  const signer_uuid = 'bb81ddbb-8c4f-4a61-94ad-6a82fc2e3e6d'; // From CREATE signer API
  const key = '0x900ac01061e15e11d332796e9ebbece5b46afdac4a1b641e82f3e344371433a4'; // From CREATE signer API

  /*** Get account ***/
  const fid = 0; // Your app's FID
  const account = mnemonicToAccount(''); // Your app's Mnemonic

  const signer = new ViemLocalEip712Signer(account);

  /*** Generating a Signed Key Request signature ***/
  const deadline = Math.floor(Date.now() / 1000) + 86400;

  console.log('signer_uuid', signer_uuid);
  console.log('\napp_fid', fid);
  console.log('\ndeadline', deadline);

  const signed_key_request_metadata = await signer.getSignedKeyRequestMetadata({
    requestFid: fid,
    key: hexToBytes(key),
    deadline,
  });

  if (!signed_key_request_metadata.isOk()) {
    console.log('Error getting signed key request metadata');
    return;
  }

  const signed_key_req_metadata_sig = bytesToHex(
    signed_key_request_metadata.value
  );

  console.log('\nsigned_key_req_metadata_sig', signed_key_req_metadata_sig);

})();

​
Install Additional Dependencies

yarn add @farcaster/core
This script will output the signed_key_request_metadata_signature along with the signer_uuid, app_fid, and deadline that you’ll include in the registration request.

​
Step 4: 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 5: 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 'x-wallet-id: YOUR_WALLET_ID' \
--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"
}'
Required: The x-wallet-id header is required for account registration. See Managing Onchain Wallets for setup instructions.

​
Responses

{
	"success": true,
	"message": "Account transferred successfully.",
  	"signer": {
  		"fid": 0,
  		"signer_uuid": "35b0bbd5-4e20-4213-a30c-4183258a73ab",
  		"status": "APPROVED",
  		"public_key": "0x123412341234123412341234123412341234"
  },
  "signers": [
      {
        "fid": 0,
        "signer_uuid": "35b0bbd5-4e20-4213-a30c-4183258a73ab",
        "status": "APPROVED",
        "public_key": "0x123412341234123412341234123412341234"
      },
      {
        "fid": 0,
        "signer_uuid": "9f6efd31-97a7-4fbe-b7e8-259871da8745",
        "status": "APPROVED",
        "public_key": "0x1234123412341234123412332322323232323"
      }
    ]
}

​
Step 6: Profile setup (optional)

Using the approved signer_uuid from the response in Step 5, you can ask the user to update their profile by picking a profile photo, display name, bio, and more.