Skip to main content
POST
/
v2
/
farcaster
/
user
Register new account
curl --request POST \
  --url https://api.neynar.com/v2/farcaster/user/ \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --header 'x-wallet-id: <x-wallet-id>' \
  --data '
{
  "signature": "<string>",
  "fid": 123,
  "requested_user_custody_address": "<string>",
  "deadline": 123,
  "signer": {
    "uuid": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "signed_key_request_metadata_signature": "<string>",
    "app_fid": 123,
    "deadline": 123
  },
  "fname": "<string>",
  "metadata": {
    "bio": "<string>",
    "pfp_url": "<string>",
    "url": "<string>",
    "username": "<string>",
    "display_name": "<string>",
    "verified_accounts": {
      "x": "<string>",
      "github": "<string>"
    },
    "location": {
      "latitude": 0,
      "longitude": 0
    }
  }
}
'
{
  "success": true,
  "message": "<string>",
  "signers": [
    {
      "public_key": "0x3daa8f99c5f760688a3c9f95716ed93dee5ed5d7722d776b7c4deac957755f22",
      "status": "generated",
      "uuid": "19d0c5fd-9b33-4a48-a0e2-bc7b0555baec",
      "object": "signer",
      "signer_approval_url": "<string>",
      "fid": 3,
      "permissions": [
        "WRITE_ALL"
      ]
    }
  ],
  "signer": {
    "signer_uuid": "19d0c5fd-9b33-4a48-a0e2-bc7b0555baec",
    "public_key": "0x3daa8f99c5f760688a3c9f95716ed93dee5ed5d7722d776b7c4deac957755f22",
    "status": "generated",
    "object": "signer",
    "signer_approval_url": "<string>",
    "fid": 3,
    "permissions": [
      "WRITE_ALL"
    ]
  },
  "user": {
    "object": "user",
    "fid": 3,
    "username": "<string>",
    "custody_address": "0x5a927ac639636e534b678e81768ca19e2c6280b7",
    "registered_at": "2023-11-07T05:31:56Z",
    "profile": {
      "bio": {
        "text": "<string>",
        "mentioned_profiles": [
          {
            "object": "user_dehydrated",
            "fid": 3,
            "username": "<string>",
            "display_name": "<string>",
            "pfp_url": "<string>",
            "custody_address": "0x5a927ac639636e534b678e81768ca19e2c6280b7",
            "score": 123
          }
        ],
        "mentioned_profiles_ranges": [
          {
            "start": 1,
            "end": 1
          }
        ],
        "mentioned_channels": [
          {
            "id": "<string>",
            "name": "<string>",
            "object": "channel_dehydrated",
            "image_url": "<string>",
            "viewer_context": {
              "following": true,
              "role": "member"
            }
          }
        ],
        "mentioned_channels_ranges": [
          {
            "start": 1,
            "end": 1
          }
        ]
      },
      "location": {
        "latitude": 0,
        "longitude": 0,
        "address": {
          "city": "<string>",
          "country": "<string>",
          "state": "<string>",
          "state_code": "<string>",
          "country_code": "<string>"
        },
        "radius": 1
      },
      "banner": {
        "url": "<string>"
      }
    },
    "follower_count": 123,
    "following_count": 123,
    "verifications": [
      "0x5a927ac639636e534b678e81768ca19e2c6280b7"
    ],
    "auth_addresses": [
      {
        "address": "0x5a927ac639636e534b678e81768ca19e2c6280b7",
        "app": {
          "object": "user_dehydrated",
          "fid": 3,
          "username": "<string>",
          "display_name": "<string>",
          "pfp_url": "<string>",
          "custody_address": "0x5a927ac639636e534b678e81768ca19e2c6280b7",
          "score": 123
        }
      }
    ],
    "verified_addresses": {
      "eth_addresses": [
        "0x5a927ac639636e534b678e81768ca19e2c6280b7"
      ],
      "sol_addresses": [
        "<string>"
      ],
      "primary": {
        "eth_address": "0x5a927ac639636e534b678e81768ca19e2c6280b7",
        "sol_address": "<string>"
      }
    },
    "verified_accounts": [
      {
        "platform": "x",
        "username": "<string>"
      }
    ],
    "display_name": "<string>",
    "pro": {
      "status": "subscribed",
      "subscribed_at": "2023-11-07T05:31:56Z",
      "expires_at": "2023-11-07T05:31:56Z"
    },
    "pfp_url": "<string>",
    "experimental": {
      "neynar_user_score": 123,
      "deprecation_notice": "<string>"
    },
    "viewer_context": {
      "following": true,
      "followed_by": true,
      "blocking": true,
      "blocked_by": true
    },
    "score": 123
  }
}

​
Node.js SDK

🔗 SDK Method: registerAccount Use this API endpoint with the Neynar Node.js SDK for typed responses and better developer experience.

​
Understanding Wallet ID for Account Registration

This endpoint registers a new Farcaster account with a fetched FID. Registration includes onchain transactions for:
  • Recording the FID ownership on Optimism
  • Setting up initial storage allocation
  • Configuring account metadata

​
Wallet ID (REQUIRED)

The x-wallet-id header is required for this endpoint. You must provide a wallet_id to pay for the onchain registration transactions.
Wallet Consistency Required: You must use the same wallet_id that was used when fetching the FID via GET /v2/farcaster/user/fid. Using a different wallet will result in an error.
Important Timing: You must call this endpoint within 10 minutes of fetching the FID via GET /v2/farcaster/user/fid. Otherwise, the FID may be assigned to another user.
New to Wallet IDs? See Managing Onchain Wallets to create your app wallet in the developer portal and obtain your x-wallet-id value.

​
Complete Registration Flow

​
Step 1: Fetch FID

First, get a fresh FID from the shelf: 
const fidResponse = await fetch('https://api.neynar.com/v2/farcaster/user/fid', {
  headers: {
    'x-api-key': 'YOUR_NEYNAR_API_KEY',
    'x-wallet-id': 'your-wallet-id'  // REQUIRED
  }
});

const { fid } = await fidResponse.json();
console.log('Got FID:', fid);

​
Step 2: Generate Signature (Client-Side)

The user must sign an EIP-712 message proving ownership of their custody address: 
// This happens in the user's browser with their connected wallet
const signature = await userWallet.signTypedData({
  domain: { /* ... */ },
  types: { /* ... */ },
  message: {
    fid: fid,
    to: custodyAddress,
    // ... other fields
  }
});

​
Step 3: Register Account (This Endpoint)

Call this endpoint within 10 minutes of Step 1: 
const registerResponse = await fetch('https://api.neynar.com/v2/farcaster/user', {
  method: 'POST',
  headers: {
    'x-api-key': 'YOUR_NEYNAR_API_KEY',
    'x-wallet-id': 'your-wallet-id',  // REQUIRED - same as Step 1
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    fid: fid,
    fname: 'username',
    signature: signature,
    requested_user_custody_address: custodyAddress,
    // ... other required fields
  })
});

const result = await registerResponse.json();
console.log('Account registered:', result);

​
Code Examples

// Complete flow with wallet_id
const response = await fetch('https://api.neynar.com/v2/farcaster/user', {
  method: 'POST',
  headers: {
    'x-api-key': 'YOUR_NEYNAR_API_KEY',
    'x-wallet-id': 'your-wallet-id',  // REQUIRED
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    fid: 12345,
    fname: 'alice',
    signature: '0x1234...', // EIP-712 signature from user
    requested_user_custody_address: '0xabcd...',
    timestamp: Math.floor(Date.now() / 1000),
    deadline: Math.floor(Date.now() / 1000) + 3600
  })
});

const result = await response.json();
console.log('Account registered:', result);

​
What You’re Paying For

When you register an account with a wallet_id: Base Costs (Onchain transactions on Optimism):
  • FID registration in ID Registry
  • Initial storage allocation (1 unit)
  • Account configuration
Services Included:
  • Transaction execution and monitoring
  • Gas estimation and optimization
  • Retry logic for failed transactions
  • FID shelf management

​
Error Handling

​
Error: Missing Wallet ID

{
  "code": "RequiredField",
  "message": "x-wallet-id header is required"
}
Solution: Add the x-wallet-id header. See Managing Onchain Wallets for setup instructions.

​
Error: FID Expired

{
  "code": "FidExpired",
  "message": "The FID has expired. Please fetch a new FID and try again within 10 minutes."
}
Solution: Fetch a new FID and complete registration within 10 minutes.

​
Error: Invalid Signature

{
  "code": "InvalidSignature",
  "message": "The provided signature is invalid or does not match the custody address."
}
Solution: Ensure the user properly signed the EIP-712 message with their custody address.

​
Error: Insufficient Wallet Balance

{
  "code": "InsufficientFunds",
  "message": "Wallet does not have enough balance to complete this transaction."
}
Solution: Fund your wallet with more ETH on Optimism.

​
Next Steps

Update Profile

Set username, bio, and profile picture

Create Signer

Enable your app to write on behalf of user

Manage Your Wallet

Fund your wallet for more operations

Complete Tutorial

Full account creation guide with code examples

Authorizations

​
x-api-key
string
header
default:NEYNAR_API_DOCS
required

API key to authorize requests

Headers

​
x-wallet-id
string
required

Wallet ID to use for transactions

Body

application/json
​
signature
string
required
​
fid
number
required
​
requested_user_custody_address
string
required
​
deadline
number
required
​
signer
object
​
fname
string
​
metadata
object

Response

Success

​
success
enum<boolean>
required
Available options:
true
​
message
string
required
​
signers
object[]
required
​
signer
Signer · object
​
user
User · object