Skip to main content

​
Fetching User Balances Using Farcaster FID with Neynar API

This API abstracts the complexity of finding Ethereum addresses and querying multiple providers, allowing developers to retrieve balances with a single API call.

​
Overview

  • API Endpoint: /farcaster/user/balance
  • Method: GET
  • Parameters:
    • fid (required): The Farcaster FID of the user.
    • networks (required): A comma-separated list of networks to fetch balances for. Currently, only “base” is supported.

​
Prerequisites

  • API Key: Ensure you have a Neynar API key. You can obtain one by signing up at neynar.com.
  • Node.js SDK: Install the Neynar Node.js SDK.
npm install @neynar/nodejs-sdk

​
Fetching User Balances

1

Initialize the Neynar Client

First, set up the Neynar client using your API key.
import { NeynarAPIClient, Configuration } from "@neynar/nodejs-sdk";

const config = new Configuration({
  apiKey: process.env.NEYNAR_API_KEY,
});

const client = new NeynarAPIClient(config);
2

Fetch User Balances

Use the fetchUserBalance method to retrieve the token balances for a user by their FID.
async function fetchUserBalances(fid) {
  try {
    const response = await client.fetchUserBalance({
      fid: fid,
      networks: ['base'], // Currently, only 'base' is supported
    });

    console.log("User Balances:", response.user_balance);
  } catch (error) {
    console.error("Error fetching user balances:", error);
  }
}

// Example usage
fetchUserBalances(3); // Replace '3' with the actual FID

​
Response Structure

The response will include the user’s balance information structured as follows: 
{
  "user_balance": {
    "object": "user_balance",
    "user": {
      "fid": 3,
      "username": "example_user",
      // Additional user details
    },
    "address_balances": [
      {
        "object": "address_balance",
        "verified_address": {
          "address": "0x1234567890abcdef",
          "network": "base"
        },
        "token_balances": [
          {
            "object": "token_balance",
            "token": {
              "object": "token",
              "name": "Ethereum",
              "symbol": "ETH",
              "decimals": 18
            },
            "balance": {
              "in_token": "1.2345",
              "in_usdc": "1234.56"
            }
          }
          // Additional tokens
        ]
      }
      // Additional addresses
    ]
  }
}

​
Error Handling

Ensure to handle potential errors, such as invalid FID or network issues, by wrapping your API calls in try-catch blocks.

​
Conclusion

By following this guide, you can efficiently fetch token balances for a user using their Farcaster FID with the Neynar API. This streamlined process eliminates the need for multiple API calls and simplifies the integration into your application.

​
Ready to start building? Get your subscription at neynar.com and reach out to us on Slack with any questions!