🫂Social Capital

Learn how to fetch Social Capital Scores and Ranks of Farcaster users, and how to fetch Social Capital Values of Farcaster casts.

In this guide you will learn how to use Airstack to:

Social Capital Scores (SCS) are a measure of each Farcaster user's influence in the network.
- This score is derived from a variety of onchain criteria (including Farcaster Hubs). Users with higher SCSs have more positive downstream influence, as their actions and engagements tends to result in higher quality overall engagement.
- User's rank for their SCS is represented by Social Capital Rank (SCR).
- Currently, the SCS is powered by a proprietary algorithm from Airstack. This algorithm is kept confidential to prevent manipulation.
- Over time, we aim to refine the SCS based on its performance and eventually release it as an open-source protocol.

Social Capital Value (SCV) is a metric developed by Airstack to identify high-quality Trending Casts on Farcaster.
The SCS of a user impacts the SCV of a cast when the user engages with it. The type of engagement also plays a role. The accumulated SCS of all interactions contributes to the cast's overall SCV. Casts are then ranked by their SCV, promoting higher-quality casts.

Pre-requisites

An Airstack account
Basic knowledge of GraphQL

Get Started

JavaScript/TypeScript/Python

If you are using JavaScript/TypeScript or Python, Install the Airstack SDK:

React

npm install @airstack/airstack-react

Node

npm install @airstack/node

React

yarn add @airstack/airstack-react

Node

yarn add @airstack/node

React

pnpm install @airstack/airstack-react

Node

pnpm install @airstack/node

pip install airstack

Then, add the following snippets to your code:

import { init, useQuery } from "@airstack/airstack-react";

init("YOUR_AIRSTACK_API_KEY");

const query = `YOUR_QUERY`; // Replace with GraphQL Query

const Component = () => {
  const { data, loading, error } = useQuery(query);

  if (data) {
    return <p>Data: {JSON.stringify(data)}</p>;
  }

  if (loading) {
    return <p>Loading...</p>;
  }

  if (error) {
    return <p>Error: {error.message}</p>;
  }
};

import { init, fetchQuery } from "@airstack/node";

init("YOUR_AIRSTACK_API_KEY");

const query = `YOUR_QUERY`; // Replace with GraphQL Query

const { data, error } = await fetchQuery(query);

console.log("data:", data);
console.log("error:", error);

import asyncio
from airstack.execute_query import AirstackClient

api_client = AirstackClient(api_key="YOUR_AIRSTACK_API_KEY")

query = """YOUR_QUERY""" # Replace with GraphQL Query

async def main():
    execute_query_client = api_client.create_execute_query_object(
        query=query)

    query_response = await execute_query_client.execute_query()
    print(query_response.data)

asyncio.run(main())

Other Programming Languages

To access the Airstack APIs in other languages, you can use https://api.airstack.xyz/gql as your GraphQL endpoint.

You can use Socials API to fetch a Farcaster user's social capital score by providing the Farcaster user's fname or fid (check here for identity formats) to the identity input:

Try Demo

Code

query MyQuery {
  Socials(
    input: {
      filter: {
        dappName: {
          _eq: farcaster
        },
        identity: { _eq: "fc_fid:602" }
      },
      blockchain: ethereum
    }
  ) {
    Social {
      socialCapital {
        socialCapitalScoreRaw
        socialCapitalScore
      }
    }
  }
}

{
  "data": {
    "Socials": {
      "Social": [
        {
          "socialCapital": {
            "socialCapitalScoreRaw": "4354877467024.49997743418218819",
            "socialCapitalScore": 43.548774670245
          }
        }
      ]
    }
  }
}

You can use Socials API to fetch a Farcaster user's social capital rank by providing the Farcaster user's fname or fid (check here for identity formats) to the identity input:

Try Demo

Code

query MyQuery {
  Socials(
    input: {
      filter: {
        dappName: {
          _eq: farcaster
        },
        identity: { _eq: "fc_fid:602" }
      },
      blockchain: ethereum
    }
  ) {
    Social {
      socialCapital {
        socialCapitalRank
      }
    }
  }
}

{
  "data": {
    "Socials": {
      "Social": [
        {
          "socialCapital": {
            "socialCapitalRank": 70 // rank 70
          }
        }
      ]
    }
  }
}

You can use the Socials API to fetch all Farcaster users sorted by social capital scores by adding socialCapitalScore to the order field and set it to DESC value to sort in descending order:

Try Demo

Code

query MyQuery {
  Socials(
    input: {
      filter: {
        dappName: {_eq: farcaster}
      },
      blockchain: ethereum,
      order: {socialCapitalScore: DESC}, # Add this to sort by SCS
      limit: 200
    }
  ) {
    Social {
      profileName
      fid: userId
      custodyAddress: userAddress
      connectedAddresses {
        address
        blockchain
      }
      socialCapital {
        socialCapitalScore
      }
    }
  }
}

{
  "data": {
    "Socials": {
      "Social": [
        {
          "profileName": "dwr.eth",
          "fid": "3",
          "custodyAddress": "0x6b0bda3f2ffed5efc83fa8c024acff1dd45793f1",
          "connectedAddresses": [
            {
              "address": "0x8fc5d6afe572fefc4ec153587b63ce543f6fa2ea",
              "blockchain": "ethereum"
            },
            {
              "address": "0xd7029bdea1c17493893aafe29aad69ef892b8ff2",
              "blockchain": "ethereum"
            }
          ],
          "socialCapital": {
            "socialCapitalScore": 279.70459538175
          }
        },
        // Other highly influential user on Farcaster network
      ]
    }
  }
}

You can use the Socials API to fetch all Farcaster users with social capital scores above certain number by using the socialCapitalScore input field and provide the X value to the _gt filter (for other comparators, check out here).

In the example below, X is 50:

If you would like to also sort the result by social capital score, simply add socialCapitalScore to the order field and set the value to DESC. To learn more how to do it, click here.

Try Demo

Code

query MyQuery {
  Socials(
    input: {
      filter: {
        dappName: {_eq: farcaster},
        socialCapitalScore: {_gt: 50} # greater than to 50
      },
      blockchain: ethereum,
      limit: 200
    }
  ) {
    Social {
      profileName
      fid: userId
      custodyAddress: userAddress
      connectedAddresses {
        address
        blockchain
      }
      socialCapital {
        socialCapitalScore
      }
    }
  }
}

{
  "data": {
    "Socials": {
      "Social": [
        {
          "profileName": "dwr.eth",
          "fid": "3",
          "custodyAddress": "0x6b0bda3f2ffed5efc83fa8c024acff1dd45793f1",
          "connectedAddresses": [
            {
              "address": "0x8fc5d6afe572fefc4ec153587b63ce543f6fa2ea",
              "blockchain": "ethereum"
            },
            {
              "address": "0xd7029bdea1c17493893aafe29aad69ef892b8ff2",
              "blockchain": "ethereum"
            }
          ],
          "socialCapital": {
            "socialCapitalScore": 279.70459538175
          }
        },
        // Other Farcaster users w/ SCS > 50
      ]
    }
  }
}

You can use the Socials API to fetch all Farcaster users sorted by social capital rank by adding socialCapitalRank to the order field and set it to ASC value to sort in ascending order:

Try Demo

Code

query MyQuery {
  Socials(
    input: {
      # Order by social capital rank in ascending order
      order: {socialCapitalRank: ASC},
      filter: {
        dappName: {
          _eq: farcaster
        }
      },
      blockchain: ethereum
    }
  ) {
    Social {
      profileName
      fid: userId
      custodyAddress: userAddress
      connectedAddresses {
        address
        blockchain
      }
      socialCapital {
        socialCapitalRank
      }
    }
  }
}

{
  "data": {
    "Socials": {
      "Social": [
        {
          "profileName": "dwr.eth",
          "fid": "3",
          "custodyAddress": "0x6b0bda3f2ffed5efc83fa8c024acff1dd45793f1",
          "connectedAddresses": [
            {
              "address": "0x8fc5d6afe572fefc4ec153587b63ce543f6fa2ea",
              "blockchain": "ethereum"
            },
            {
              "address": "0xd7029bdea1c17493893aafe29aad69ef892b8ff2",
              "blockchain": "ethereum"
            }
          ],
          "socialCapital": {
            "socialCapitalRank": 1
          }
        },
        // Other Farcaster users ranked by social capital rank
      ]
    }
  }
}

You can use the Socials API to fetch all Farcaster users with social capital rank below certain value by using the socialCapitalRank input field and the _lte operator. If you prefer other comparator for your logic, you can use other available comparator that suits you need (check more here).

If you would like to also sort the result by social capital rank, simply add socialCapitalRank to the order field and set the value to ASC. To learn more how to do it, click here.

Try Demo

Code

query MyQuery {
  Socials(
    input: {
      filter: {
        dappName: {
          _eq: farcaster
        },
        socialCapitalRank: {
          _lte: 100 # less than or equal to 100
        }
      },
      blockchain: ethereum
    }
  ) {
    Social {
      profileName
      fid: userId
      custodyAddress: userAddress
      connectedAddresses {
        address
        blockchain
      }
      socialCapital {
        socialCapitalRank
      }
    }
  }
}

{
  "data": {
    "Socials": {
      "Social": [
        {
          "profileName": "corbin.eth",
          "fid": "358",
          "custodyAddress": "0x3bcadeaef7f8e3bf5ec9ca5212cc9c72556c43ed",
          "connectedAddresses": [
            {
              "address": "0x869ec00fa1dc112917c781942cc01c68521c415e",
              "blockchain": "ethereum"
            }
          ],
          "socialCapital": {
            "socialCapitalRank": 82
          }
        },
        // Other user with social capital rank below or equal to 100
      ]
    }
  }
}

You can use FarcasterCasts API to fetch a Farcaster cast's social capital value by providing the Warpcast URL to the url input:

Alternatively, you can also use the hash input filter and provide the cast hash if you have the cast hash value.

Try Demo

Code

query MyQuery {
  FarcasterCasts(
    input: {
      filter: {
        url: {_eq: "https://warpcast.com/dannylove/0xabc68559"}
      },
      blockchain: ALL
    }
  ) {
    Cast {
      socialCapitalValue {
        rawValue
        formattedValue
      }
    }
  }
}

{
  "data": {
    "FarcasterCasts": {
      "Cast": [
        {
          "socialCapitalValue": {
            "rawValue": "33984720",
            "formattedValue": 0.0003398472
          }
        }
      ]
    }
  }
}

Developer Support

If you have any questions or need help regarding fetching Social Capital data, please join our Airstack's Telegram group.

More Resources

PreviousFarcaster APIs NextFarcaster Casts

Last updated 1 month ago

Was this helpful?

Airstack Developer Docs & FAQs

🫂Social Capital

Table Of Contents

Pre-requisites

Get Started

Try Demo

Code

Try Demo

Code

Try Demo

Code

Try Demo

Code

Try Demo

Code

Try Demo

Code

Try Demo

Code

Developer Support

More Resources

Table Of Contents

Social Capital Scores

Social Capital Value

Pre-requisites

Get Started

Get A Farcaster User's Social Capital Score

Try Demo

Code

Get A Farcaster User's Social Capital Rank

Try Demo

Code

Get All Farcaster Users Sorted By Social Capital Scores

Try Demo

Code

Get All Farcaster Users With Social Capital Scores > X

Try Demo

Code

Get All Farcaster Users Sorted By Social Capital Rank

Try Demo

Code

Get All Farcaster Users With Social Capital Rank < X

Try Demo

Code

Get A Farcaster Casts's Social Capital Value

Try Demo

Code

Developer Support

More Resources