Farcaster Profile Resolution

This guide explains how to resolve Farcaster profiles in both directions - from Farcaster identifiers (FID/username) to addresses, and from addresses to Farcaster profiles.

Resolution by Farcaster ID or Username

Use the accounts query to resolve Farcaster profiles using either FID or username.

Example Variables

{
  "fids": [99], // Query by FID
  "farcasterUsernames": ["jessepollak"] // Or query by username
}

Example Query

query GetFarcasterProfile($fids: [Float!], $farcasterUsernames: [String!]) {
  accounts(fids: $fids, farcasterUsernames: $farcasterUsernames) {
    farcasterProfile {
      username
      fid
      custodyAddress
      connectedAddresses
      metadata {
        displayName
        description
        imageUrl
        warpcast
      }
    }
  }
}

Example Response

{
  "data": {
    "accounts": [
      {
        "farcasterProfile": {
          "username": "jessepollak",
          "fid": 99,
          "custodyAddress": "0x4ce34af3378a00c640125e4dbf4c9e64dff4c93b",
          "connectedAddresses": [
            "0x6adea326faea1b688af33df59e18f7a819bcaa4f",
            "0x8e86e5331d3a020909c9e42ea9051675555f5e49",
            "0x2211d1d0020daea8039e46cf1367962070d77da9",
            "0x6e0d9c6dd8a08509bb625caa35dc61a991406f62",
            "0xe73f9c181b571cac2bf3173634d04a9921b7ffcf",
            "0x849151d7d0bf1f34b70d5cad5149d28cc2308bf1"
          ],
          "metadata": {
            "displayName": "jesse.base.eth 🔵",
            "description": "@base builder #001; onchain cities w/ OAK & city3",
            "imageUrl": "https://imagedelivery.net/BXluQx4ige9GuW0Ia56BHw/1013b0f6-1bf4-4f4e-15fb-34be06fede00/original",
            "warpcast": "https://warpcast.com/jessepollak"
          }
        }
      }
    ]
  }
}

Resolution by Address

Use the same accounts query to resolve Farcaster profiles from Ethereum addresses.

Example Variables

{
  "addresses": ["0x6adea326faea1b688af33df59e18f7a819bcaa4f"]
}

Example Query

query GetFarcasterProfileByAddress($addresses: [Address!]) {
  accounts(addresses: $addresses) {
    address
    farcasterProfile {
      username
      fid
      custodyAddress
      connectedAddresses
      metadata {
        displayName
        description
        imageUrl
        warpcast
      }
    }
  }
}

Example Response

{
  "data": {
    "accounts": [
      {
        "address": "0x6adea326faea1b688af33df59e18f7a819bcaa4f",
        "farcasterProfile": {
          "username": "jessepollak",
          "fid": 99,
          "custodyAddress": "0x4ce34af3378a00c640125e4dbf4c9e64dff4c93b",
          "connectedAddresses": [
            "0x6adea326faea1b688af33df59e18f7a819bcaa4f",
            "0x8e86e5331d3a020909c9e42ea9051675555f5e49",
            "0x2211d1d0020daea8039e46cf1367962070d77da9",
            "0x6e0d9c6dd8a08509bb625caa35dc61a991406f62",
            "0xe73f9c181b571cac2bf3173634d04a9921b7ffcf",
            "0x849151d7d0bf1f34b70d5cad5149d28cc2308bf1"
          ],
          "metadata": {
            "displayName": "jesse.base.eth 🔵",
            "description": "@base builder #001; onchain cities w/ OAK & city3",
            "imageUrl": "https://imagedelivery.net/BXluQx4ige9GuW0Ia56BHw/1013b0f6-1bf4-4f4e-15fb-34be06fede00/original",
            "warpcast": "https://warpcast.com/jessepollak"
          }
        }
      }
    ]
  }
}

Available Fields

Core Profile Fields

Field	Description	Type
username	Farcaster username	String!
fid	Farcaster ID	Int!
custodyAddress	Address that owns the Farcaster account	String!
connectedAddresses	Array of verified addresses owned by the user	[String!]!

Metadata Fields

Field	Description	Type
displayName	User's display name	String
description	User's profile description/bio	String
imageUrl	URL of the user's profile image	String
warpcast	User's Warpcast profile URL	String

Error Handling

Common scenarios to handle:

• Invalid or non-existent Farcaster username/FID
• Address not associated with any Farcaster profile
• Missing optional metadata fields

Best Practices

1. Cache profile data to minimize API calls
2. Implement proper error handling for all resolution methods
3. Always check for null values in optional metadata fields
4. Use the most appropriate resolution method based on your use case:
   • Use FID/username resolution when you have Farcaster identifiers
   • Use address resolution when you have Ethereum addresses
5. Consider batch queries when resolving multiple profiles