🟪Farcaster Resolver

Learn how to build a Farcaster resolver with Airstack APIs and integrate it into your React application.

This demo is a variation of Universal Resolver that only accepts Farcaster names or IDs as input.

If you are looking to resolve other identities than Farcaster, check out Universal Resolver demo.

Try Demo

Farcaster Resolver

Farcaster Resolver (Demo)

Step 0: Prerequisites

• Completed Get API Key

• Git

• Node v.16+

Step 1: Clone Starter Code

To clone the starter code, simply copy the following code to clone in your preferred directory:

mkdir farcaster-resolver-starter
cd farcaster-resolver-starter
git init
git remote add -f origin https://github.com/Airstack-xyz/demos.git
git config core.sparseCheckout true
git sparse-checkout init
git sparse-checkout set farcaster-resolver
git pull origin main
rm -rf .git
mv farcaster/farcaster-resolver-starter/* .
mv farcaster/farcaster-resolver-starter/.* .
rm -rf farcaster

You can find all the starter code in GItHub.

Step 2: Install Dependencies

Install the dependencies using your preferred package manager with one of the following commands:

npm

npm install

yarn

yarn

pnpm

pnpm install

Once the installation is complete, a new node_modules will be generated

You should also see that Airstack React SDK has been added to your package.json as one of your dependency:

{
  "dependencies": {
    "@airstack/airstack-react": "^0.3.3"
    // other dependencies
  }
  // other config
}

Step 3: Set Environment Variables

Copy and rename .env.example to .env.local

cp .env.example .env.local

And, paste your API key to your environment variable .env.local file.

VITE_AIRSTACK_API_KEY=YOUR_API_KEY

Step 4: Run App Locally

To run the app locally, simply run one of the following command:

npm

npm run dev

yarn

yarn dev

pnpm

pnpm run dev

Then, you can go to http://localhost:5173:

Here you have the UI all given to you out-of-the-box as part of the starter code.

However, the resolving has not been included as no Airstack query is found in the code. You can see in src/graphql/resolve.js with it's empty query:

const FARCASTER_RESOLVER = ``;

export default FARCASTER_RESOLVER;

In order to fill in this, the next steps will be dedicated to constructing your queries for the Farcaster resolver.

Step 5: Create a Query Using AI

Use Airstack AI's Best Practices to get the best and most accurate result for your query.

Airstack provides an AI solution for you to build a GraphQL query efficiently. You can access Airstack AI on the API Studio.

Airstack AI

For example, let's try the following prompt to resolve Farcaster name vbuterin:

For Farcaster user vbuterin, show me the 0x address, web3 socials, ENS domain, and XMTP

After clicking enter, the Airstack AI will output a GraphQL query as follows:

Query

query MyQuery {
  Wallet(input: {identity: "fc_fname:vbuterin", blockchain: ethereum}) {
    addresses
    socials {
      dappName
      profileName
    }
    domains {
      name
    }
    xmtp {
      isXMTPEnabled
    }
  }
}

Responses

{
  "data": {
    "Wallet": {
      "addresses": [
        "0xd8da6bf26964af9d7eed9e03e53415d37aa96045"
      ],
      "socials": [
        {
          "dappName": "farcaster",
          "profileName": "vbuterin"
        },
        {
          "dappName": "lens",
          "profileName": "vitalik.lens"
        }
      ],
      "domains": [
        {
          "name": "quantumexchange.eth"
        },
        {
          "name": "7860000.eth"
        },
        {
          "name": "brianshaw.eth"
        },
        {
          "name": "vbuterin.stateofus.eth"
        },
        {
          "name": "quantumsmartcontracts.eth"
        },
        {
          "name": "openegp.eth"
        },
        {
          "name": "vitalik.cannafam.eth"
        },
        {
          "name": "quantumdapps.eth"
        },
        {
          "name": "vitalik.soy.eth"
        },
        {
          "name": "satoshinart.eth"
        }
      ],
      "xmtp": {
        "isXMTPEnabled": true
      }
    }
  }
}

You can go to the API Studio to test out the query yourself:

https://app.airstack.xyz/DTyOZg/Kcz253OnEV

Resolve vitalik.eth Query (Playground)

Step 6: Modify Your Query

Now that you have your basic query, you can build more complex queries on top of it to resolve a Farcaster name or ID to any web3 identities.

For this, you can simply stay in the API Studio to make the modifications.

The responses has already included everything that you need to resolve a Farcaster name or ID to any web3 identities. However, it is missing a primary ENS domain to highlight domains that is primary or not.

To add primary ENS domain, you will need this one field:

Field	Type	Description
primaryDomains.name	string	primary ENS name

Adding the additional field, the last query with the changes highlighted will be as follows:

Query

query MyQuery {
  Wallet(
    input: {identity: "fc_fname:vbuterin", blockchain: ethereum}
  ) {
    addresses
    socials {
      dappName
      profileName
    }
    domains {
      name
    }
    primaryDomain {
      name
    }
    xmtp {
      isXMTPEnabled
    }
  }
}

Response

{
  "data": {
    "Wallet": {
      "addresses": [
        "0xd8da6bf26964af9d7eed9e03e53415d37aa96045"
      ],
      "socials": [
        {
          "dappName": "farcaster",
          "profileName": "vbuterin"
        },
        {
          "dappName": "lens",
          "profileName": "vitalik.lens"
        }
      ],
      "domains": [
        {
          "name": "quantumexchange.eth"
        },
        {
          "name": "7860000.eth"
        },
        {
          "name": "brianshaw.eth"
        },
        {
          "name": "vbuterin.stateofus.eth"
        },
        {
          "name": "quantumsmartcontracts.eth"
        },
        {
          "name": "openegp.eth"
        },
        {
          "name": "vitalik.cannafam.eth"
        },
        {
          "name": "quantumdapps.eth"
        },
        {
          "name": "vitalik.soy.eth"
        },
        {
          "name": "satoshinart.eth"
        }
      ],
      "xmtp": {
        "isXMTPEnabled": true
      }
    }
  }
}

Step 7: Add Variables to Your Query

In production, you will likely need to have the input value change constantly. This is where you can add variables to your query to accept input values from your application.

Simply replace the input with variables, represented by $ followed by the variable names:

Query

query MyQuery($address: Identity!) {
  Wallet(input: {identity: $address, blockchain: ethereum}) {
    addresses
    socials {
      dappName
      profileName
    }
    domains {
      name
    }
    primaryDomain {
      name
    }
    xmtp {
      isXMTPEnabled
    }
  }
} 

Variable

{
  "address": "vitalik.lens"
}

Response

{
  "data": {
    "Wallet": {
      "addresses": [
        "0xd8da6bf26964af9d7eed9e03e53415d37aa96045"
      ],
      "socials": [
        {
          "dappName": "farcaster",
          "profileName": "vbuterin"
        },
        {
          "dappName": "lens",
          "profileName": "vitalik.lens"
        }
      ],
      "domains": [
        {
          "name": "quantumexchange.eth"
        },
        {
          "name": "7860000.eth"
        },
        {
          "name": "brianshaw.eth"
        },
        {
          "name": "vbuterin.stateofus.eth"
        },
        {
          "name": "quantumsmartcontracts.eth"
        },
        {
          "name": "openegp.eth"
        },
        {
          "name": "vitalik.cannafam.eth"
        },
        {
          "name": "quantumdapps.eth"
        },
        {
          "name": "vitalik.soy.eth"
        },
        {
          "name": "satoshinart.eth"
        }
      ],
      "primaryDomain": {
        "name": "satoshinart.eth"
      },
      "xmtp": {
        "isXMTPEnabled": true
      }
    }
  }
}

Step 8: Call The Airstack Query

Now that you have the query constructed, all you need is just paste it directly into the codebase.

Simply go to src/graphql/resolve.js again and paste the query to FARCASTER_RESOLVER variable:

const FARCASTER_RESOLVER = `
query MyQuery($address: Identity!) {
  Wallet(input: {identity: $address, blockchain: ethereum}) {
    addresses
    socials {
      dappName
      profileName
    }
    domains {
      name
    }
    primaryDomain {
      name
    }
    xmtp {
      isXMTPEnabled
    }
  }
}
`;

export default FARCASTER_RESOLVER;

To call this query, use the useQuery hook from the Airstack React SDK to src/App.jsx:

import { useQuery } from "@airstack/airstack-react";
import FARCASTER_RESOLVER from "./graphql/resolve";
import FarcasterResolver from "./components/FarcasterResolver";

function App() {
  const { data, loading } = useQuery(
    FARCASTER_RESOLVER,
    { address: "fc_fname:vbuterin" },
    { cache: false }
  );

  return (
    <FarcasterResolver
      data={data}
      loading={loading}
    />
  );
}

export default App;

With this simple code, you essentially just integrated Airstack query that you constructed for universally resolving web3 identities.

Since the code now hardcode fc_fname:vbuterin as the query input, the app will universally resolve fc_fname:vbuterin and have the UI look like this:

Step 9: Toggle API Query to Button Click

At its current state, you have successfully loaded Airstack and its data responses to the UI.

However, the query call is not toggled to the button click and is not dependent on the user input.

This is because you only use useQuery which automatically calls the API for every render. To do a manual call, swap useQuery with useLazyQuery in src/App.jsx as follows:

import { useLazyQuery } from "@airstack/airstack-react";
import FARCASTER_RESOLVER from "./graphql/resolve";
import FarcasterResolver from "./components/FarcasterResolver";

function App() {
  const [resolveIdentity, { data, loading }] = useLazyQuery(
    FARCASTER_RESOLVER,
    {},
    { cache: false }
  );

  return (
    <FarcasterResolver
      data={data}
      loading={loading}
      onButtonClick={resolveIdentity}
    />
  );
}

export default App;

The end result is as follows:

Farcaster Resolver (Final)

Congratulations! 🎉You’ve just learned how to use Airstack to build a Farcaster resolver and integrate Airstack API into your React application.

Developer Support

If you have any questions or need help regarding Farcaster resolver, please join our Airstack's Telegram group.

More Resources

• Resolve Farcaster

• Wallet API Reference

• Farcaster Resolver Final Code