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>'import requests
url = "https://api.neynar.com/v2/farcaster/user/fid/"
headers = {
"x-wallet-id": "<x-wallet-id>",
"x-api-key": "<api-key>"
}
response = requests.get(url, headers=headers)
print(response.text)const options = {
method: 'GET',
headers: {'x-wallet-id': '<x-wallet-id>', 'x-api-key': '<api-key>'}
};
fetch('https://api.neynar.com/v2/farcaster/user/fid/', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.neynar.com/v2/farcaster/user/fid/",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"x-api-key: <api-key>",
"x-wallet-id: <x-wallet-id>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.neynar.com/v2/farcaster/user/fid/"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("x-wallet-id", "<x-wallet-id>")
req.Header.Add("x-api-key", "<api-key>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.neynar.com/v2/farcaster/user/fid/")
.header("x-wallet-id", "<x-wallet-id>")
.header("x-api-key", "<api-key>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.neynar.com/v2/farcaster/user/fid/")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["x-wallet-id"] = '<x-wallet-id>'
request["x-api-key"] = '<api-key>'
response = http.request(request)
puts response.read_body{
"fid": 3
}{
"message": "<string>",
"code": "<string>",
"property": "<string>",
"status": 123
}Register New User
Fetch fresh FID
Fetches FID to assign it to new user.
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>'import requests
url = "https://api.neynar.com/v2/farcaster/user/fid/"
headers = {
"x-wallet-id": "<x-wallet-id>",
"x-api-key": "<api-key>"
}
response = requests.get(url, headers=headers)
print(response.text)const options = {
method: 'GET',
headers: {'x-wallet-id': '<x-wallet-id>', 'x-api-key': '<api-key>'}
};
fetch('https://api.neynar.com/v2/farcaster/user/fid/', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.neynar.com/v2/farcaster/user/fid/",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"x-api-key: <api-key>",
"x-wallet-id: <x-wallet-id>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.neynar.com/v2/farcaster/user/fid/"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("x-wallet-id", "<x-wallet-id>")
req.Header.Add("x-api-key", "<api-key>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.neynar.com/v2/farcaster/user/fid/")
.header("x-wallet-id", "<x-wallet-id>")
.header("x-api-key", "<api-key>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.neynar.com/v2/farcaster/user/fid/")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["x-wallet-id"] = '<x-wallet-id>'
request["x-api-key"] = '<api-key>'
response = http.request(request)
puts response.read_body{
"fid": 3
}{
"message": "<string>",
"code": "<string>",
"property": "<string>",
"status": 123
}Related documentation:
- Create new Farcaster account - Complete tutorial
- Managing Onchain Wallets - Wallet setup guide
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)
Thex-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
curl -X GET 'https://api.neynar.com/v2/farcaster/user/fid' \
-H 'x-api-key: YOUR_NEYNAR_API_KEY' \
-H 'x-wallet-id: your-wallet-id'
import requests
headers = {
'x-api-key': 'YOUR_NEYNAR_API_KEY',
'x-wallet-id': 'your-wallet-id' # REQUIRED
}
response = requests.get(
'https://api.neynar.com/v2/farcaster/user/fid',
headers=headers
)
data = response.json()
print(f"Fresh FID: {data['fid']}")
Error Handling
Error: Missing Wallet ID
{
"code": "RequiredField",
"message": "x-wallet-id header is required"
}
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."
}
Error: Insufficient Wallet Balance
{
"code": "InsufficientFunds",
"message": "Wallet does not have enough balance to complete this transaction."
}
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
- You call this endpoint β Neynar returns a pre-registered FID from the shelf
- Neynar replenishes β Async onchain transactions register new FIDs to refill the shelf
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
API key to authorize requests
Headers
Wallet ID to use for transactions
Response
Success
The unique identifier of a farcaster user or app (unsigned integer)
Required range:
x >= 0Example:
3
Related topics
getFreshAccountFIDRegister new accountfetchSubscriptionsForFidfetchSubscribedToForFidfetchSubscribersForFidWas this page helpful?