Farcaster Profile

Get connected addresses and profile metadata including name, description, profile image, and Warpcast.

farcasterProfile

Use farcasterProfile to resolve Farcaster profiles using either FID or username.

Example Variables

{
  "fid": 99, // Query by FID
  "username": "jessepollak" // Or query by username
}

Example Query

query GetFarcasterProfile($username: String) {
  farcasterProfile(username: $username) {
    username
    fid
    metadata {
      displayName
      description
      imageUrl
      warpcast
    }
    custodyAddress
    connectedAddresses
    
  }
}

Example Response

{
  "data": {
    "farcasterProfile": {
      "username": "jessepollak",
      "fid": 99,
      "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"
      },
      "custodyAddress": "0x4ce34af3378a00c640125e4dbf4c9e64dff4c93b",
      "connectedAddresses": [
        "0x2211d1d0020daea8039e46cf1367962070d77da9",
        "0x6adea326faea1b688af33df59e18f7a819bcaa4f",
        "0x6e0d9c6dd8a08509bb625caa35dc61a991406f62",
        "0x849151d7d0bf1f34b70d5cad5149d28cc2308bf1",
        "0x85c0ba9e1456bc755a6ce69e1a85ccaa1faa9e41",
        "0x8e86e5331d3a020909c9e42ea9051675555f5e49",
        "0xe73f9c181b571cac2bf3173634d04a9921b7ffcf"
      ]
    }
  }
}

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 farcasterProfile query when you have a Farcaster FID or username
   • Use account query when you have an Ethereum address
5. Consider implementing retry logic for failed queries
6. Keep your cached data fresh with regular updates