Skip to main content
Currently, this API is allowlisted. 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.

Related API: Register new account
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

​
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.

​
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
}
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 '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"
  },
  "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.