Neynar Documentation

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 '
{
  "deadline": 123,
  "fid": 123,
  "requested_user_custody_address": "<string>",
  "signature": "<string>",
  "fname": "<string>",
  "metadata": {
    "bio": "<string>",
    "display_name": "<string>",
    "pfp_url": "<string>",
    "url": "<string>",
    "username": "<string>",
    "verified_accounts": {
      "github": "<string>",
      "x": "<string>"
    }
  }
}
'

import requests

url = "https://api.neynar.com/v2/farcaster/user/"

payload = {
    "deadline": 123,
    "fid": 123,
    "requested_user_custody_address": "<string>",
    "signature": "<string>",
    "fname": "<string>",
    "metadata": {
        "bio": "<string>",
        "display_name": "<string>",
        "pfp_url": "<string>",
        "url": "<string>",
        "username": "<string>",
        "verified_accounts": {
            "github": "<string>",
            "x": "<string>"
        }
    }
}
headers = {
    "x-wallet-id": "<x-wallet-id>",
    "x-api-key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'x-wallet-id': '<x-wallet-id>',
    'x-api-key': '<api-key>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    deadline: 123,
    fid: 123,
    requested_user_custody_address: '<string>',
    signature: '<string>',
    fname: '<string>',
    metadata: {
      bio: '<string>',
      display_name: '<string>',
      pfp_url: '<string>',
      url: '<string>',
      username: '<string>',
      verified_accounts: {github: '<string>', x: '<string>'}
    }
  })
};

fetch('https://api.neynar.com/v2/farcaster/user/', 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/",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'deadline' => 123,
    'fid' => 123,
    'requested_user_custody_address' => '<string>',
    'signature' => '<string>',
    'fname' => '<string>',
    'metadata' => [
        'bio' => '<string>',
        'display_name' => '<string>',
        'pfp_url' => '<string>',
        'url' => '<string>',
        'username' => '<string>',
        'verified_accounts' => [
                'github' => '<string>',
                'x' => '<string>'
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "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"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.neynar.com/v2/farcaster/user/"

	payload := strings.NewReader("{\n  \"deadline\": 123,\n  \"fid\": 123,\n  \"requested_user_custody_address\": \"<string>\",\n  \"signature\": \"<string>\",\n  \"fname\": \"<string>\",\n  \"metadata\": {\n    \"bio\": \"<string>\",\n    \"display_name\": \"<string>\",\n    \"pfp_url\": \"<string>\",\n    \"url\": \"<string>\",\n    \"username\": \"<string>\",\n    \"verified_accounts\": {\n      \"github\": \"<string>\",\n      \"x\": \"<string>\"\n    }\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("x-wallet-id", "<x-wallet-id>")
	req.Header.Add("x-api-key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.neynar.com/v2/farcaster/user/")
  .header("x-wallet-id", "<x-wallet-id>")
  .header("x-api-key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"deadline\": 123,\n  \"fid\": 123,\n  \"requested_user_custody_address\": \"<string>\",\n  \"signature\": \"<string>\",\n  \"fname\": \"<string>\",\n  \"metadata\": {\n    \"bio\": \"<string>\",\n    \"display_name\": \"<string>\",\n    \"pfp_url\": \"<string>\",\n    \"url\": \"<string>\",\n    \"username\": \"<string>\",\n    \"verified_accounts\": {\n      \"github\": \"<string>\",\n      \"x\": \"<string>\"\n    }\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.neynar.com/v2/farcaster/user/")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["x-wallet-id"] = '<x-wallet-id>'
request["x-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"deadline\": 123,\n  \"fid\": 123,\n  \"requested_user_custody_address\": \"<string>\",\n  \"signature\": \"<string>\",\n  \"fname\": \"<string>\",\n  \"metadata\": {\n    \"bio\": \"<string>\",\n    \"display_name\": \"<string>\",\n    \"pfp_url\": \"<string>\",\n    \"url\": \"<string>\",\n    \"username\": \"<string>\",\n    \"verified_accounts\": {\n      \"github\": \"<string>\",\n      \"x\": \"<string>\"\n    }\n  }\n}"

response = http.request(request)
puts response.read_body

{
  "message": "<string>",
  "signers": [
    {
      "public_key": "0x3daa8f99c5f760688a3c9f95716ed93dee5ed5d7722d776b7c4deac957755f22",
      "uuid": "19d0c5fd-9b33-4a48-a0e2-bc7b0555baec",
      "fid": 3,
      "object": "signer",
      "permissions": [],
      "signer_approval_url": "<string>"
    }
  ],
  "success": true,
  "signer": {
    "public_key": "0x3daa8f99c5f760688a3c9f95716ed93dee5ed5d7722d776b7c4deac957755f22",
    "signer_uuid": "19d0c5fd-9b33-4a48-a0e2-bc7b0555baec",
    "fid": 3,
    "object": "signer",
    "permissions": [],
    "signer_approval_url": "<string>"
  },
  "user": {
    "auth_addresses": [
      {
        "address": "0x5a927ac639636e534b678e81768ca19e2c6280b7",
        "app": {
          "fid": 3,
          "object": "user_dehydrated",
          "custody_address": "0x5a927ac639636e534b678e81768ca19e2c6280b7",
          "display_name": "<string>",
          "pfp_url": "<string>",
          "score": 123,
          "username": "<string>"
        }
      }
    ],
    "custody_address": "0x5a927ac639636e534b678e81768ca19e2c6280b7",
    "fid": 3,
    "follower_count": 123,
    "following_count": 123,
    "object": "user",
    "profile": {
      "bio": {
        "text": "<string>",
        "mentioned_channels": [
          {
            "id": "<string>",
            "name": "<string>",
            "object": "channel_dehydrated",
            "image_url": "<string>",
            "viewer_context": {
              "following": true
            }
          }
        ],
        "mentioned_channels_ranges": [
          {
            "end": 1,
            "start": 1
          }
        ],
        "mentioned_profiles": [
          {
            "fid": 3,
            "object": "user_dehydrated",
            "custody_address": "0x5a927ac639636e534b678e81768ca19e2c6280b7",
            "display_name": "<string>",
            "pfp_url": "<string>",
            "score": 123,
            "username": "<string>"
          }
        ],
        "mentioned_profiles_ranges": [
          {
            "end": 1,
            "start": 1
          }
        ]
      },
      "banner": {
        "url": "<string>"
      },
      "live_at": {
        "is_live": true,
        "updated_at": "2023-11-07T05:31:56Z",
        "url": "<string>"
      },
      "location": {
        "latitude": 0,
        "longitude": 0,
        "address": {
          "city": "<string>",
          "country": "<string>",
          "country_code": "<string>",
          "state": "<string>",
          "state_code": "<string>"
        },
        "radius": 1
      }
    },
    "registered_at": "2023-11-07T05:31:56Z",
    "username": "<string>",
    "verifications": [
      "0x5a927ac639636e534b678e81768ca19e2c6280b7"
    ],
    "verified_accounts": [
      {
        "username": "<string>"
      }
    ],
    "verified_addresses": {
      "eth_addresses": [
        "0x5a927ac639636e534b678e81768ca19e2c6280b7"
      ],
      "primary": {
        "eth_address": "0x5a927ac639636e534b678e81768ca19e2c6280b7",
        "sol_address": "<string>"
      },
      "sol_addresses": [
        "<string>"
      ]
    },
    "display_name": "<string>",
    "experimental": {
      "neynar_user_score": 123,
      "deprecation_notice": "<string>"
    },
    "pfp_url": "<string>",
    "pro": {
      "expires_at": "2023-11-07T05:31:56Z",
      "subscribed_at": "2023-11-07T05:31:56Z"
    },
    "score": 123,
    "viewer_context": {
      "blocked_by": true,
      "blocking": true,
      "followed_by": true,
      "following": true
    }
  }
}

{
  "message": "<string>",
  "code": "<string>",
  "property": "<string>",
  "status": 123
}

{
  "message": "<string>",
  "code": "<string>",
  "property": "<string>",
  "status": 123
}

{
  "message": "<string>",
  "code": "<string>",
  "property": "<string>",
  "status": 123
}

{
  "message": "<string>",
  "code": "<string>",
  "key": "<string>",
  "property": "<string>"
}

{
  "message": "<string>",
  "code": "<string>",
  "property": "<string>",
  "status": 123
}

POST

farcaster

user

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 '
{
  "deadline": 123,
  "fid": 123,
  "requested_user_custody_address": "<string>",
  "signature": "<string>",
  "fname": "<string>",
  "metadata": {
    "bio": "<string>",
    "display_name": "<string>",
    "pfp_url": "<string>",
    "url": "<string>",
    "username": "<string>",
    "verified_accounts": {
      "github": "<string>",
      "x": "<string>"
    }
  }
}
'

import requests

url = "https://api.neynar.com/v2/farcaster/user/"

payload = {
    "deadline": 123,
    "fid": 123,
    "requested_user_custody_address": "<string>",
    "signature": "<string>",
    "fname": "<string>",
    "metadata": {
        "bio": "<string>",
        "display_name": "<string>",
        "pfp_url": "<string>",
        "url": "<string>",
        "username": "<string>",
        "verified_accounts": {
            "github": "<string>",
            "x": "<string>"
        }
    }
}
headers = {
    "x-wallet-id": "<x-wallet-id>",
    "x-api-key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'x-wallet-id': '<x-wallet-id>',
    'x-api-key': '<api-key>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    deadline: 123,
    fid: 123,
    requested_user_custody_address: '<string>',
    signature: '<string>',
    fname: '<string>',
    metadata: {
      bio: '<string>',
      display_name: '<string>',
      pfp_url: '<string>',
      url: '<string>',
      username: '<string>',
      verified_accounts: {github: '<string>', x: '<string>'}
    }
  })
};

fetch('https://api.neynar.com/v2/farcaster/user/', 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/",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'deadline' => 123,
    'fid' => 123,
    'requested_user_custody_address' => '<string>',
    'signature' => '<string>',
    'fname' => '<string>',
    'metadata' => [
        'bio' => '<string>',
        'display_name' => '<string>',
        'pfp_url' => '<string>',
        'url' => '<string>',
        'username' => '<string>',
        'verified_accounts' => [
                'github' => '<string>',
                'x' => '<string>'
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "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"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.neynar.com/v2/farcaster/user/"

	payload := strings.NewReader("{\n  \"deadline\": 123,\n  \"fid\": 123,\n  \"requested_user_custody_address\": \"<string>\",\n  \"signature\": \"<string>\",\n  \"fname\": \"<string>\",\n  \"metadata\": {\n    \"bio\": \"<string>\",\n    \"display_name\": \"<string>\",\n    \"pfp_url\": \"<string>\",\n    \"url\": \"<string>\",\n    \"username\": \"<string>\",\n    \"verified_accounts\": {\n      \"github\": \"<string>\",\n      \"x\": \"<string>\"\n    }\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("x-wallet-id", "<x-wallet-id>")
	req.Header.Add("x-api-key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.neynar.com/v2/farcaster/user/")
  .header("x-wallet-id", "<x-wallet-id>")
  .header("x-api-key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"deadline\": 123,\n  \"fid\": 123,\n  \"requested_user_custody_address\": \"<string>\",\n  \"signature\": \"<string>\",\n  \"fname\": \"<string>\",\n  \"metadata\": {\n    \"bio\": \"<string>\",\n    \"display_name\": \"<string>\",\n    \"pfp_url\": \"<string>\",\n    \"url\": \"<string>\",\n    \"username\": \"<string>\",\n    \"verified_accounts\": {\n      \"github\": \"<string>\",\n      \"x\": \"<string>\"\n    }\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.neynar.com/v2/farcaster/user/")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["x-wallet-id"] = '<x-wallet-id>'
request["x-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"deadline\": 123,\n  \"fid\": 123,\n  \"requested_user_custody_address\": \"<string>\",\n  \"signature\": \"<string>\",\n  \"fname\": \"<string>\",\n  \"metadata\": {\n    \"bio\": \"<string>\",\n    \"display_name\": \"<string>\",\n    \"pfp_url\": \"<string>\",\n    \"url\": \"<string>\",\n    \"username\": \"<string>\",\n    \"verified_accounts\": {\n      \"github\": \"<string>\",\n      \"x\": \"<string>\"\n    }\n  }\n}"

response = http.request(request)
puts response.read_body

{
  "message": "<string>",
  "signers": [
    {
      "public_key": "0x3daa8f99c5f760688a3c9f95716ed93dee5ed5d7722d776b7c4deac957755f22",
      "uuid": "19d0c5fd-9b33-4a48-a0e2-bc7b0555baec",
      "fid": 3,
      "object": "signer",
      "permissions": [],
      "signer_approval_url": "<string>"
    }
  ],
  "success": true,
  "signer": {
    "public_key": "0x3daa8f99c5f760688a3c9f95716ed93dee5ed5d7722d776b7c4deac957755f22",
    "signer_uuid": "19d0c5fd-9b33-4a48-a0e2-bc7b0555baec",
    "fid": 3,
    "object": "signer",
    "permissions": [],
    "signer_approval_url": "<string>"
  },
  "user": {
    "auth_addresses": [
      {
        "address": "0x5a927ac639636e534b678e81768ca19e2c6280b7",
        "app": {
          "fid": 3,
          "object": "user_dehydrated",
          "custody_address": "0x5a927ac639636e534b678e81768ca19e2c6280b7",
          "display_name": "<string>",
          "pfp_url": "<string>",
          "score": 123,
          "username": "<string>"
        }
      }
    ],
    "custody_address": "0x5a927ac639636e534b678e81768ca19e2c6280b7",
    "fid": 3,
    "follower_count": 123,
    "following_count": 123,
    "object": "user",
    "profile": {
      "bio": {
        "text": "<string>",
        "mentioned_channels": [
          {
            "id": "<string>",
            "name": "<string>",
            "object": "channel_dehydrated",
            "image_url": "<string>",
            "viewer_context": {
              "following": true
            }
          }
        ],
        "mentioned_channels_ranges": [
          {
            "end": 1,
            "start": 1
          }
        ],
        "mentioned_profiles": [
          {
            "fid": 3,
            "object": "user_dehydrated",
            "custody_address": "0x5a927ac639636e534b678e81768ca19e2c6280b7",
            "display_name": "<string>",
            "pfp_url": "<string>",
            "score": 123,
            "username": "<string>"
          }
        ],
        "mentioned_profiles_ranges": [
          {
            "end": 1,
            "start": 1
          }
        ]
      },
      "banner": {
        "url": "<string>"
      },
      "live_at": {
        "is_live": true,
        "updated_at": "2023-11-07T05:31:56Z",
        "url": "<string>"
      },
      "location": {
        "latitude": 0,
        "longitude": 0,
        "address": {
          "city": "<string>",
          "country": "<string>",
          "country_code": "<string>",
          "state": "<string>",
          "state_code": "<string>"
        },
        "radius": 1
      }
    },
    "registered_at": "2023-11-07T05:31:56Z",
    "username": "<string>",
    "verifications": [
      "0x5a927ac639636e534b678e81768ca19e2c6280b7"
    ],
    "verified_accounts": [
      {
        "username": "<string>"
      }
    ],
    "verified_addresses": {
      "eth_addresses": [
        "0x5a927ac639636e534b678e81768ca19e2c6280b7"
      ],
      "primary": {
        "eth_address": "0x5a927ac639636e534b678e81768ca19e2c6280b7",
        "sol_address": "<string>"
      },
      "sol_addresses": [
        "<string>"
      ]
    },
    "display_name": "<string>",
    "experimental": {
      "neynar_user_score": 123,
      "deprecation_notice": "<string>"
    },
    "pfp_url": "<string>",
    "pro": {
      "expires_at": "2023-11-07T05:31:56Z",
      "subscribed_at": "2023-11-07T05:31:56Z"
    },
    "score": 123,
    "viewer_context": {
      "blocked_by": true,
      "blocking": true,
      "followed_by": true,
      "following": true
    }
  }
}

{
  "message": "<string>",
  "code": "<string>",
  "property": "<string>",
  "status": 123
}

{
  "message": "<string>",
  "code": "<string>",
  "property": "<string>",
  "status": 123
}

{
  "message": "<string>",
  "code": "<string>",
  "property": "<string>",
  "status": 123
}

{
  "message": "<string>",
  "code": "<string>",
  "key": "<string>",
  "property": "<string>"
}

{
  "message": "<string>",
  "code": "<string>",
  "property": "<string>",
  "status": 123
}

Create new Farcaster account - Complete tutorial
Managing Onchain Wallets - Wallet setup guide
Developer managed version - For advanced users with developer_managed signers

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);

curl -X POST 'https://api.neynar.com/v2/farcaster/user' \
  -H 'x-api-key: YOUR_NEYNAR_API_KEY' \
  -H 'x-wallet-id: your-wallet-id' \
  -H 'Content-Type: application/json' \
  -d '{
    "fid": 12345,
    "fname": "alice",
    "signature": "0x1234...",
    "requested_user_custody_address": "0xabcd...",
    "timestamp": 1703001234,
    "deadline": 1703004834
  }'

import requests
import time

headers = {
    'x-api-key': 'YOUR_NEYNAR_API_KEY',
    'x-wallet-id': 'your-wallet-id',  # REQUIRED
    'Content-Type': 'application/json'
}

payload = {
    'fid': 12345,
    'fname': 'alice',
    'signature': '0x1234...',
    'requested_user_custody_address': '0xabcd...',
    'timestamp': int(time.time()),
    'deadline': int(time.time()) + 3600
}

response = requests.post(
    'https://api.neynar.com/v2/farcaster/user',
    headers=headers,
    json=payload
)

result = response.json()
print('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

deadline

number

required

fid

number

required

requested_user_custody_address

string

required

signature

string

required

fname

string

metadata

object

Show child attributes

signer

object

Show child attributes

Response

Success

message

string

required

signers

object[]

required

Show child attributes

success

enum<boolean>

required

Available options:

true

signer

Signer · object

Show child attributes

user

User · object

Show child attributes

Overview

Farcaster

Onchain

Deploy onchain

Farcaster Hub API

Other SDKs

Github

Register new account

Node.js SDK

Understanding Wallet ID for Account Registration

Wallet ID (REQUIRED)

Complete Registration Flow

Step 1: Fetch FID

Step 2: Generate Signature (Client-Side)

Step 3: Register Account (This Endpoint)

Code Examples

What You’re Paying For

Error Handling

Error: Missing Wallet ID

Error: FID Expired

Error: Invalid Signature

Error: Insufficient Wallet Balance

Next Steps

Update Profile

Create Signer

Manage Your Wallet

Complete Tutorial

Authorizations

Headers

Body

Response

​Related documentation:

​Node.js SDK

​Understanding Wallet ID for Account Registration

​Wallet ID (REQUIRED)

​Complete Registration Flow

​Step 1: Fetch FID

​Step 2: Generate Signature (Client-Side)

​Step 3: Register Account (This Endpoint)

​Code Examples

​What You’re Paying For

​Error Handling

​Error: Missing Wallet ID

​Error: FID Expired

​Error: Invalid Signature

​Error: Insufficient Wallet Balance

​Next Steps

Update Profile

Create Signer

Manage Your Wallet

Complete Tutorial

Authorizations

Headers

Body

Response

Related documentation:

Node.js SDK

Understanding Wallet ID for Account Registration

Wallet ID (REQUIRED)

Complete Registration Flow

Step 1: Fetch FID

Step 2: Generate Signature (Client-Side)

Step 3: Register Account (This Endpoint)

Code Examples

What You’re Paying For

Error Handling

Error: Missing Wallet ID

Error: FID Expired

Error: Invalid Signature

Error: Insufficient Wallet Balance

Next Steps