> ## Documentation Index
> Fetch the complete documentation index at: https://docs.neynar.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Register new account

> Register account on farcaster. Optionally provide x-wallet-id header to use your own wallet. 

**Note:** This API must be called within 10 minutes of the fetch FID API call (i.e., /v2/farcaster/user/fid). Otherwise, Neynar will assign this FID to another available user.

<Info>
  ### Related documentation:

  * [Create new Farcaster account](/docs/how-to-create-a-new-farcaster-account-with-neynar) - Complete tutorial
  * [Managing Onchain Wallets](/docs/managing-onchain-wallets) - Wallet setup guide
  * [Developer managed version](/reference/register-account-onchain) - For advanced users with developer\_managed signers
</Info>

## Node.js SDK

🔗 **SDK Method:** [registerAccount](/nodejs-sdk/user-apis/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](/docs/managing-onchain-wallets) is **required** for this endpoint. You must provide a wallet\_id to pay for the onchain registration transactions.

<Warning>
  **Wallet Consistency Required:** You must use the **same `wallet_id`** that was used when fetching the FID via [`GET /v2/farcaster/user/fid`](/reference/get-fresh-account-fid). Using a different wallet will result in an error.
</Warning>

<Warning>
  **Important Timing:** You must call this endpoint within **10 minutes** of fetching the FID via [`GET /v2/farcaster/user/fid`](/reference/get-fresh-account-fid). Otherwise, the FID may be assigned to another user.
</Warning>

<Note>
  **New to Wallet IDs?** See [Managing Onchain Wallets](/docs/managing-onchain-wallets) to create your app wallet in the developer portal and obtain your `x-wallet-id` value.
</Note>

## Complete Registration Flow

### Step 1: Fetch FID

First, get a fresh FID from the shelf:

```javascript theme={"system"}
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:

```javascript theme={"system"}
// 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:

```javascript theme={"system"}
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

<CodeGroup>
  ```javascript Node.js theme={"system"}
  // 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);
  ```

  ```bash cURL theme={"system"}
  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
    }'
  ```

  ```python Python theme={"system"}
  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)
  ```
</CodeGroup>

## 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

```json theme={"system"}
{
  "code": "RequiredField",
  "message": "x-wallet-id header is required"
}
```

**Solution:** Add the `x-wallet-id` header. See [Managing Onchain Wallets](/docs/managing-onchain-wallets) for setup instructions.

### Error: FID Expired

```json theme={"system"}
{
  "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

```json theme={"system"}
{
  "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

```json theme={"system"}
{
  "code": "InsufficientFunds",
  "message": "Wallet does not have enough balance to complete this transaction."
}
```

**Solution:** Fund your wallet with more ETH on Optimism.

## Next Steps

<CardGroup cols={2}>
  <Card title="Update Profile" href="/reference/update-user" icon="user-pen">
    Set username, bio, and profile picture
  </Card>

  <Card title="Create Signer" href="/reference/create-signer" icon="key">
    Enable your app to write on behalf of user
  </Card>

  <Card title="Manage Your Wallet" href="/docs/managing-onchain-wallets" icon="wallet">
    Fund your wallet for more operations
  </Card>

  <Card title="Complete Tutorial" href="/docs/how-to-create-a-new-farcaster-account-with-neynar" icon="book">
    Full account creation guide with code examples
  </Card>
</CardGroup>


## OpenAPI

````yaml post /v2/farcaster/user/
openapi: 3.0.4
info:
  contact:
    email: team@neynar.com
    name: Neynar
    url: https://neynar.com/
  description: >-
    The Neynar API allows you to interact with the Farcaster protocol among
    other things. See the [Neynar docs](https://docs.neynar.com/reference) for
    more details.
  title: Neynar API
  version: 3.173.0
servers:
  - url: https://api.neynar.com
security:
  - ApiKeyAuth: []
tags:
  - description: Operations related to user
    externalDocs:
      description: More info about user
      url: https://docs.neynar.com/reference/user-operations
    name: User
  - description: Operations related to signer
    externalDocs:
      description: More info about signer
      url: https://docs.neynar.com/reference/signer-operations
    name: Signer
  - description: Operations related to cast
    externalDocs:
      description: More info about cast
      url: https://docs.neynar.com/reference/cast-operations
    name: Cast
  - description: Operations related to feed
    externalDocs:
      description: More info about feed
      url: https://docs.neynar.com/reference/feed-operations
    name: Feed
  - description: Operations related to reaction
    externalDocs:
      description: More info about reaction
      url: https://docs.neynar.com/reference/reaction-operations
    name: Reaction
  - description: Operations related to notifications
    externalDocs:
      description: More info about notifications
      url: https://docs.neynar.com/reference/notifications-operations
    name: Notifications
  - description: Operations related to channels
    externalDocs:
      description: More info about channels
      url: https://docs.neynar.com/reference/channel-operations
    name: Channel
  - description: Operations related to follows
    externalDocs:
      description: More info about follows
      url: https://docs.neynar.com/reference/follows-operations
    name: Follows
  - description: Operations related to storage
    externalDocs:
      description: More info about storage
      url: https://docs.neynar.com/reference/storage-operations
    name: Storage
  - description: Operations related to mini apps
    name: Frame
  - description: Operations for building AI agents
    name: Agents
  - description: Operations related to fname
    name: fname
  - description: Operations related to a webhook
    name: Webhook
  - description: >-
      Securely communicate and perform actions on behalf of users across
      different apps
    externalDocs:
      description: More info about farcaster actions
      url: https://docs.neynar.com/docs/farcaster-actions-spec
    name: Action
  - description: Operations related to a subscriptions
    name: Subscribers
  - description: Operations related to a mute
    name: Mute
  - description: Operations related to a block
    name: Block
  - description: Operations related to a ban
    name: Ban
  - description: Operations related to onchain data
    name: Onchain
  - description: Operations related to login
    name: Login
  - description: Operations related to retrieving metrics
    name: Metrics
  - description: Operations related to mini app host notifications
    externalDocs:
      description: More info about mini app host notifications
      url: https://docs.neynar.com/docs/app-host-notifications
    name: App Host
paths:
  /v2/farcaster/user/:
    post:
      tags:
        - User
      summary: Register new account
      description: >-
        Register account on farcaster. Optionally provide x-wallet-id header to
        use your own wallet. 


        **Note:** This API must be called within 10 minutes of the fetch FID API
        call (i.e., /v2/farcaster/user/fid). Otherwise, Neynar will assign this
        FID to another available user.
      operationId: register-account
      parameters:
        - $ref: '#/components/parameters/WalletIdHeader'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RegisterUserReqBody'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RegisterUserResponse'
          description: Success
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRes'
          description: Bad Request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRes'
          description: Unauthorized
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRes'
          description: Resource not found
        '409':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConflictErrorRes'
          description: Conflict
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRes'
          description: Server Error
      externalDocs:
        url: https://docs.neynar.com/reference/register-account
components:
  parameters:
    WalletIdHeader:
      description: Wallet ID to use for transactions
      in: header
      name: x-wallet-id
      required: true
      schema:
        type: string
      x-is-global-header: true
  schemas:
    RegisterUserReqBody:
      properties:
        deadline:
          type: number
        fid:
          type: number
        fname:
          type: string
        metadata:
          properties:
            bio:
              type: string
            display_name:
              type: string
            location:
              properties:
                latitude:
                  format: double
                  maximum: 90
                  minimum: -90
                  type: number
                longitude:
                  format: double
                  maximum: 180
                  minimum: -180
                  type: number
              required:
                - latitude
                - longitude
              type: object
            pfp_url:
              type: string
            url:
              type: string
            username:
              type: string
            verified_accounts:
              properties:
                github:
                  type: string
                x:
                  type: string
              type: object
          type: object
        requested_user_custody_address:
          type: string
        signature:
          type: string
        signer:
          properties:
            app_fid:
              type: number
            deadline:
              type: number
            signed_key_request_metadata_signature:
              type: string
            uuid:
              format: uuid
              type: string
          required:
            - uuid
            - signed_key_request_metadata_signature
            - app_fid
            - deadline
          type: object
      required:
        - signature
        - fid
        - requested_user_custody_address
        - deadline
      title: RegisterUserReqBody
      type: object
    RegisterUserResponse:
      properties:
        message:
          type: string
        signer:
          $ref: '#/components/schemas/Signer'
        signers:
          items:
            properties:
              fid:
                $ref: '#/components/schemas/Fid'
              object:
                enum:
                  - signer
                type: string
              permissions:
                items:
                  $ref: '#/components/schemas/SharedSignerPermission'
                type: array
              public_key:
                $ref: '#/components/schemas/Ed25519PublicKey'
              signer_approval_url:
                type: string
              status:
                enum:
                  - generated
                  - pending_approval
                  - approved
                  - revoked
                type: string
              uuid:
                $ref: '#/components/schemas/SignerUUID'
            required:
              - public_key
              - status
              - uuid
            type: object
          type: array
        success:
          enum:
            - true
          type: boolean
        user:
          $ref: '#/components/schemas/User'
      required:
        - success
        - message
        - signers
      title: RegisterUserResponse
      type: object
    ErrorRes:
      description: Details for the error response
      properties:
        code:
          type: string
        message:
          type: string
        property:
          type: string
        status:
          format: int32
          type: integer
      required:
        - message
      title: ErrorRes
      type: object
    ConflictErrorRes:
      description: Details for the conflict error response
      properties:
        code:
          type: string
        key:
          type: string
        message:
          type: string
        property:
          type: string
      required:
        - message
      title: ConflictErrorRes
      type: object
    Signer:
      properties:
        fid:
          $ref: '#/components/schemas/Fid'
        object:
          enum:
            - signer
          type: string
        permissions:
          items:
            $ref: '#/components/schemas/SharedSignerPermission'
          type: array
        public_key:
          $ref: '#/components/schemas/Ed25519PublicKey'
        signer_approval_url:
          type: string
        signer_uuid:
          $ref: '#/components/schemas/SignerUUID'
        status:
          enum:
            - generated
            - pending_approval
            - approved
            - revoked
          type: string
      required:
        - signer_uuid
        - public_key
        - status
      title: Signer
      type: object
    Fid:
      description: The unique identifier of a farcaster user or app (unsigned integer)
      example: 3
      format: int32
      minimum: 0
      title: Fid
      type: integer
    SharedSignerPermission:
      enum:
        - WRITE_ALL
        - READ_ONLY
        - NONE
        - PUBLISH_CAST
        - DELETE_CAST
        - PUBLISH_REACTION
        - DELETE_REACTION
        - UPDATE_PROFILE
        - FOLLOW_USER
        - UNFOLLOW_USER
        - FOLLOW_CHANNEL
        - UNFOLLOW_CHANNEL
        - ADD_VERIFICATION
        - REMOVE_VERIFICATION
        - WRITE_FRAME_ACTION
      title: SharedSignerPermission
      type: string
    Ed25519PublicKey:
      description: Ed25519 public key
      example: '0x3daa8f99c5f760688a3c9f95716ed93dee5ed5d7722d776b7c4deac957755f22'
      pattern: ^0x[a-fA-F0-9]{64}$
      title: Ed25519PublicKey
      type: string
    SignerUUID:
      description: >-
        UUID of the signer.

        `signer_uuid` is paired with API key, can't use a `uuid` made with a
        different API key.
      example: 19d0c5fd-9b33-4a48-a0e2-bc7b0555baec
      title: SignerUUID
      type: string
    User:
      properties:
        auth_addresses:
          items:
            properties:
              address:
                $ref: '#/components/schemas/EthAddress'
              app:
                $ref: '#/components/schemas/UserDehydrated'
            required:
              - address
              - app
            type: object
          type: array
        custody_address:
          $ref: '#/components/schemas/EthAddress'
        display_name:
          nullable: true
          type: string
        experimental:
          properties:
            deprecation_notice:
              type: string
            neynar_user_score:
              description: >-
                Score that represents the probability that the account is not
                spam.
              format: double
              type: number
          required:
            - neynar_user_score
          type: object
        fid:
          $ref: '#/components/schemas/Fid'
        follower_count:
          description: The number of followers the user has.
          format: int32
          type: integer
        following_count:
          description: The number of users the user is following.
          format: int32
          type: integer
        object:
          enum:
            - user
          type: string
        pfp_url:
          description: The URL of the user's profile picture
          nullable: true
          type: string
        pro:
          properties:
            expires_at:
              format: date-time
              type: string
            status:
              description: The subscription status of the user
              enum:
                - subscribed
                - unsubscribed
              type: string
            subscribed_at:
              format: date-time
              type: string
          required:
            - status
            - subscribed_at
            - expires_at
          type: object
        profile:
          properties:
            banner:
              properties:
                url:
                  description: The URL of the user's banner image
                  format: uri
                  type: string
              type: object
            bio:
              properties:
                mentioned_channels:
                  items:
                    $ref: '#/components/schemas/ChannelDehydrated'
                  type: array
                mentioned_channels_ranges:
                  description: >-
                    Positions within the text (inclusive start, exclusive end)
                    where each mention occurs.

                    Each index within this list corresponds to the same-numbered
                    index in the mentioned_channels list.
                  items:
                    $ref: '#/components/schemas/TextRange'
                  type: array
                mentioned_profiles:
                  items:
                    $ref: '#/components/schemas/UserDehydrated'
                  type: array
                mentioned_profiles_ranges:
                  description: >-
                    Positions within the text (inclusive start, exclusive end)
                    where each mention occurs.

                    Each index within this list corresponds to the same-numbered
                    index in the mentioned_profiles list.
                  items:
                    $ref: '#/components/schemas/TextRange'
                  type: array
                text:
                  type: string
              required:
                - text
              type: object
            location:
              $ref: '#/components/schemas/Location'
          required:
            - bio
          type: object
        registered_at:
          format: date-time
          type: string
        score:
          description: Score that represents the probability that the account is not spam.
          format: double
          type: number
        username:
          type: string
        verifications:
          items:
            $ref: '#/components/schemas/EthAddress'
          type: array
        verified_accounts:
          items:
            description: >-
              Verified accounts of the user on other platforms, currently only X
              is supported.
            properties:
              platform:
                enum:
                  - x
                  - github
                type: string
              username:
                type: string
            type: object
          type: array
        verified_addresses:
          properties:
            eth_addresses:
              description: >-
                List of verified Ethereum addresses of the user sorted by oldest
                to most recent.
              items:
                $ref: '#/components/schemas/EthAddress'
              type: array
            primary:
              properties:
                eth_address:
                  allOf:
                    - $ref: '#/components/schemas/EthAddress'
                  nullable: true
                sol_address:
                  allOf:
                    - $ref: '#/components/schemas/SolAddress'
                  nullable: true
              required:
                - eth_address
                - sol_address
              type: object
            sol_addresses:
              description: >-
                List of verified Solana addresses of the user sorted by oldest
                to most recent.
              items:
                $ref: '#/components/schemas/SolAddress'
              type: array
          required:
            - eth_addresses
            - sol_addresses
            - primary
          type: object
        viewer_context:
          $ref: '#/components/schemas/UserViewerContext'
      required:
        - object
        - fid
        - username
        - custody_address
        - registered_at
        - profile
        - follower_count
        - following_count
        - verifications
        - auth_addresses
        - verified_addresses
        - verified_accounts
      title: User
      type: object
    EthAddress:
      description: Ethereum address
      example: '0x5a927ac639636e534b678e81768ca19e2c6280b7'
      pattern: ^0x[a-fA-F0-9]{40}$
      title: EthAddress
      type: string
    UserDehydrated:
      properties:
        custody_address:
          $ref: '#/components/schemas/EthAddress'
        display_name:
          nullable: true
          type: string
        fid:
          $ref: '#/components/schemas/Fid'
        object:
          enum:
            - user_dehydrated
          type: string
        pfp_url:
          nullable: true
          type: string
        score:
          type: number
        username:
          type: string
      required:
        - object
        - fid
      title: UserDehydrated
      type: object
    ChannelDehydrated:
      properties:
        id:
          type: string
        image_url:
          type: string
        name:
          type: string
        object:
          enum:
            - channel_dehydrated
          type: string
        viewer_context:
          $ref: '#/components/schemas/ChannelUserContext'
      required:
        - id
        - name
        - object
      title: ChannelDehydrated
      type: object
    TextRange:
      properties:
        end:
          minimum: 0
          type: number
        start:
          minimum: 0
          type: number
      required:
        - start
        - end
      title: TextRange
      type: object
    Location:
      description: Coordinates and place names for a location
      properties:
        address:
          $ref: '#/components/schemas/LocationAddress'
        latitude:
          format: double
          maximum: 90
          minimum: -90
          type: number
        longitude:
          format: double
          maximum: 180
          minimum: -180
          type: number
        radius:
          description: >-
            The radius in meters for the location search. Any location within
            this radius will be returned.
          minimum: 0
          type: number
      required:
        - latitude
        - longitude
      title: Location
      type: object
    SolAddress:
      description: Solana address
      pattern: ^[1-9A-HJ-NP-Za-km-z]{32,44}$
      title: SolAddress
      type: string
    UserViewerContext:
      description: Adds context on the viewer's follow relationship with the user.
      properties:
        blocked_by:
          description: Indicates if the viewer is blocked by the user.
          type: boolean
        blocking:
          description: Indicates if the viewer is blocking the user.
          type: boolean
        followed_by:
          description: Indicates if the viewer is followed by the user.
          type: boolean
        following:
          description: Indicates if the viewer is following the user.
          type: boolean
      required:
        - following
        - followed_by
        - blocking
        - blocked_by
      title: UserViewerContext
      type: object
    ChannelUserContext:
      description: Adds context on the viewer's or author's role in the channel.
      properties:
        following:
          description: Indicates if the user is following the channel.
          type: boolean
        role:
          $ref: '#/components/schemas/ChannelMemberRole'
      required:
        - following
      title: ChannelUserContext
      type: object
    LocationAddress:
      properties:
        city:
          type: string
        country:
          type: string
        country_code:
          type: string
        state:
          type: string
        state_code:
          type: string
      required:
        - city
        - country
      title: LocationAddress
      type: object
    ChannelMemberRole:
      description: The role of a channel member
      enum:
        - member
        - moderator
        - owner
      title: ChannelMemberRole
      type: string
  securitySchemes:
    ApiKeyAuth:
      description: API key to authorize requests
      in: header
      name: x-api-key
      type: apiKey
      x-default: NEYNAR_API_DOCS

````