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

# Fetch fresh FID

> Fetches FID to [assign it to new user](https://docs.neynar.com/reference/register-account).

<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
</Info>

## 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](/docs/managing-onchain-wallets) is **required** for this endpoint. You must provide a wallet\_id to cover the costs of async FID shelf replenishment.

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

## Code Examples

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

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

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

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

```json theme={"system"}
{
  "code": "InvalidWalletId",
  "message": "The provided wallet_id is invalid or not found."
}
```

**Solution:** Verify your wallet\_id in the [Developer Portal](https://dev.neynar.com) or contact support.

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

## Important Notes

<Warning>
  **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.
</Warning>

<Warning>
  **Wallet Consistency Required:** The same `wallet_id` used to fetch a FID must also be used when calling [`POST /v2/farcaster/user/`](/reference/register-account) to register that account. Using different wallets will result in an error.
</Warning>

<Warning>
  **10 Minute Deadline:** After fetching a FID, you must call the [register account endpoint](/reference/register-account) within **10 minutes**. Otherwise, Neynar will assign this FID to another user.
</Warning>

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

<CardGroup cols={2}>
  <Card title="Register the Account" href="/reference/register-account" icon="user-plus">
    After fetching a FID, register the account within 10 minutes
  </Card>

  <Card title="Manage Your Wallet" href="/docs/managing-onchain-wallets" icon="wallet">
    Learn how to set up and fund your wallet for onchain operations
  </Card>

  <Card title="Full Tutorial" href="/docs/how-to-create-a-new-farcaster-account-with-neynar" icon="book">
    Complete guide to creating Farcaster accounts
  </Card>

  <Card title="Contact Support" href="https://t.me/rishdoteth" icon="telegram">
    Need help? Reach out to our team
  </Card>
</CardGroup>


## OpenAPI

````yaml get /v2/farcaster/user/fid/
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/fid/:
    get:
      tags:
        - User
      summary: Fetch fresh FID
      description: >-
        Fetches FID to [assign it to new
        user](https://docs.neynar.com/reference/register-account).
      operationId: get-fresh-account-FID
      parameters:
        - $ref: '#/components/parameters/NeynarExperimentalHeader'
        - $ref: '#/components/parameters/WalletIdHeader'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserFIDResponse'
          description: Success
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRes'
          description: Server Error
      externalDocs:
        url: https://docs.neynar.com/reference/get-fresh-account-fid
components:
  parameters:
    NeynarExperimentalHeader:
      description: >-
        Enables experimental features including filtering based on the Neynar
        score. See
        [docs](https://neynar.notion.site/Experimental-Features-1d2655195a8b80eb98b4d4ae7b76ae4a)
        for more details.
      in: header
      name: x-neynar-experimental
      schema:
        default: false
        type: boolean
      x-is-global-header: true
    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:
    UserFIDResponse:
      properties:
        fid:
          $ref: '#/components/schemas/Fid'
      required:
        - fid
      title: UserFIDResponse
      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
    Fid:
      description: The unique identifier of a farcaster user or app (unsigned integer)
      example: 3
      format: int32
      minimum: 0
      title: Fid
      type: integer
  securitySchemes:
    ApiKeyAuth:
      description: API key to authorize requests
      in: header
      name: x-api-key
      type: apiKey
      x-default: NEYNAR_API_DOCS

````