Skip to main content
GET
/
v2
/
farcaster
/
user
/
fid
Fetch fresh FID
curl --request GET \
  --url https://api.neynar.com/v2/farcaster/user/fid/ \
  --header 'x-api-key: <api-key>' \
  --header 'x-wallet-id: <x-wallet-id>'
{
  "fid": 3
}

​
Understanding Wallet ID for FID Operations

This endpoint fetches a fresh FID (Farcaster ID) that can be assigned to a new user. When you fetch a FID, Neynar maintains a “shelf” of pre-registered FIDs that are replenished asynchronously via onchain transactions.

​
Wallet ID (REQUIRED)

The x-wallet-id header is required for this endpoint. You must provide a wallet_id to cover the costs of async FID shelf replenishment.
New to Wallet IDs? See Managing Onchain Wallets to create your app wallet in the developer portal and obtain your x-wallet-id value.

​
Code Examples

const response = 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 data = await response.json();
console.log('Fresh FID:', data.fid);

// Use this FID within 10 minutes to register an account

​
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: Invalid Wallet ID

{
  "code": "InvalidWalletId",
  "message": "The provided wallet_id is invalid or not found."
}
Solution: Verify your wallet_id in the Developer Portal or contact support.

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

​
Important Notes

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 to fetch a FID must also be used when calling POST /v2/farcaster/user/ to register that account. Using different wallets will result in an error.
10 Minute Deadline: After fetching a FID, you must call the register account endpoint within 10 minutes. Otherwise, Neynar will assign this FID to another user.

​
What Happens Behind the Scenes

  1. You call this endpoint → Neynar returns a pre-registered FID from the shelf
  2. Neynar replenishes → Async onchain transactions register new FIDs to refill the shelf
This architecture ensures fast FID fetching while handling blockchain complexity in the background.

​
Next Steps

Register the Account

After fetching a FID, register the account within 10 minutes

Manage Your Wallet

Learn how to set up and fund your wallet for onchain operations

Full Tutorial

Complete guide to creating Farcaster accounts

Contact Support

Need help? Reach out to our team

Authorizations

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

API key to authorize requests

Headers

​
x-neynar-experimental
boolean
default:false

Enables experimental features including filtering based on the Neynar score. See docs for more details.

​
x-wallet-id
string
required

Wallet ID to use for transactions

Response

Success

​
fid
integer<int32>
required

The unique identifier of a farcaster user or app (unsigned integer)

Required range: x >= 0
Example:

3