Free Open-Source Farcaster L1 + L2 APIs

These high-performance APIs are open-sourced under wieldlabs/universe (opens in a new tab)!

Join our Developer Telegram (opens in a new tab) for any questions or support!

Start by creating a free API key! We use API keys to prevent abuse.

curl -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "description": "YOUR_DESCRIPTION",
    "email": "YOUR_EMAIL"
  }' \
  https://protocol.wield.co/apikey/create

Field	Description	Example
`YOUR_DESCRIPTION`	The name and description of the project.	`Project X`
`YOUR_EMAIL`	Your email address for any notifications.	`john.doe@example.com`

You'll use this API key as a request header in your HTTP request (API-KEY).

These APIs are used for Cast (opens in a new tab), a Farcaster L1 + L2 where FIDs are strings and Cast users can create data. Feel free to filter out "external":true from responses, and learn more about our Layer 2 here!

Farcaster L1 + L2 Read Endpoints

Feed Endpoint

curl -X GET \
  -H "API-KEY: DEMO_REPLACE_WITH_FREE_API_KEY" \
  https://protocol.wield.co/farcaster/v2/feed?limit=20

Query Parameter	Description
`limit`	Number of items to return. Default is 20.
`cursor`	Pagination cursor (optional).

Example Response

JSON Result (Expandable)

{
  "result": {
    "casts": [
      {
        "hash": "0x96fe9d465ceefea38fca19bbe2c122f24f9bda1b",
        "threadHash": "0x96fe9d465ceefea38fca19bbe2c122f24f9bda1b",
        "text": "Warp. Drop the cast, it’s cleaner.",
        "embeds": { "images": [], "urls": [] },
        "mentions": [],
        "mentionsPositions": [],
        "external": false,
        "author": {
          "fid": "12938",
          "followingCount": 170,
          "followerCount": 95,
          "pfp": {
            "url": "https://i.seadn.io/gae/ubYLLsa1-2w9N4wqOhantwsSmfoad7TuOHjtyWs7NdLIo1TtXLOWqKcC4J8YlTa1TPJfegZ4OhdvF8rr7z1JpZsepNxAYglv57cFOQ?w=500&auto=format",
            "verified": false
          },
          "bio": {
            "text": "Building products in Africa 🌍 Working on Paie https://paie.money",
            "mentions": []
          },
          "external": false,
          "custodyAddress": "0xda80ebef09c431a19a70a24c8b3342301c5a8735",
          "displayName": "ash",
          "username": "ashrafstakala",
          "registeredAt": 1693453451333,
          "isFollowing": null,
          "isFollowedBy": null
        },
        "parentAuthor": null,
        "timestamp": 1696833919000,
        "replies": { "count": 1 },
        "reactions": { "count": 1 },
        "recasts": { "count": 0, "recasters": [] },
        "isSelfLike": null,
        "isSelfRecast": null,
        "childCast": {
          "hash": "0x0ca15e1e726bc626b15cc0146ffc1a696d58b10c",
          "parentHash": "0x96fe9d465ceefea38fca19bbe2c122f24f9bda1b",
          "parentFid": "12938",
          "threadHash": "0x96fe9d465ceefea38fca19bbe2c122f24f9bda1b",
          "text": "You forgot \"Oh, and one more thing\"",
          "embeds": { "images": [], "urls": [] },
          "mentions": [],
          "mentionsPositions": [],
          "external": false,
          "author": {
            "fid": "10694",
            "followingCount": 416,
            "followerCount": 357,
            "pfp": {
              "url": "https://i.imgur.com/28se29B.jpg",
              "verified": false
            },
            "bio": {
              "text": "0.2x guy, building the good for all mankind. Very serious \"ethical bribery\" expert.",
              "mentions": []
            },
            "external": false,
            "custodyAddress": "0x63c0df9ccb039241bf53baac41cc1d281ef95b63",
            "username": "chukwukaosakwe",
            "displayName": "Chukwuka Osakwe",
            "registeredAt": 1693456351921,
            "isFollowing": null,
            "isFollowedBy": null
          },
          "parentAuthor": {
            "fid": "12938",
            "followingCount": 170,
            "followerCount": 95,
            "pfp": {
              "url": "https://i.seadn.io/gae/ubYLLsa1-2w9N4wqOhantwsSmfoad7TuOHjtyWs7NdLIo1TtXLOWqKcC4J8YlTa1TPJfegZ4OhdvF8rr7z1JpZsepNxAYglv57cFOQ?w=500&auto=format",
              "verified": false
            },
            "bio": {
              "text": "Building products in Africa 🌍 Working on Paie https://paie.money",
              "mentions": []
            },
            "external": false,
            "custodyAddress": "0xda80ebef09c431a19a70a24c8b3342301c5a8735",
            "displayName": "ash",
            "username": "ashrafstakala",
            "registeredAt": 1693453451333
          },
          "timestamp": 1696845536000,
          "replies": { "count": 0 },
          "reactions": { "count": 1 },
          "recasts": { "count": 0, "recasters": [] },
          "isSelfLike": null,
          "isSelfRecast": null
        },
        "childrenCasts": []
      }
    ]
  },
  "next": "1696845536000-6523cedf5c1497c0efa1dff0",
  "source": "v2"
}

Cast by Hash Endpoint

curl -X GET \
  -H "API-KEY: DEMO_REPLACE_WITH_FREE_API_KEY" \
  https://protocol.wield.co/farcaster/v2/cast?hash=0x96fe9d465ceefea38fca19bbe2c122f24f9bda1b

Query Parameter	Description
`hash`	Hash value to identify the cast.

JSON Result (Expandable)

{
   "result": {
      "cast": {
         "hash": "0x96fe9d465ceefea38fca19bbe2c122f24f9bda1b",
         "threadHash": "0x96fe9d465ceefea38fca19bbe2c122f24f9bda1b",
         "text": "Warp. Drop the cast, it’s cleaner.",
         "embeds": {
            "images": [],
            "urls": []
         },
         "mentions": [],
         "mentionsPositions": [],
         "external": false,
         "author": {
            "fid": "12938",
            "followingCount": 170,
            "followerCount": 95,
            "pfp": {
               "url": "https://i.seadn.io/gae/ubYLLsa1-2w9N4wqOhantwsSmfoad7TuOHjtyWs7NdLIo1TtXLOWqKcC4J8YlTa1TPJfegZ4OhdvF8rr7z1JpZsepNxAYglv57cFOQ?w=500&auto=format",
               "verified": false
            },
            "bio": {
               "text": "Building products in Africa 🌍 Working on Paie https://paie.money",
               "mentions": []
            },
            "external": false,
            "custodyAddress": "0xda80ebef09c431a19a70a24c8b3342301c5a8735",
            "displayName": "ash",
            "username": "ashrafstakala",
            "registeredAt": 1693453451333,
            "isFollowing": null,
            "isFollowedBy": null
         },
         "parentAuthor": null,
         "timestamp": 1696833919000,
         "replies": {
            "count": 1
         },
         "reactions": {
            "count": 1
         },
         "recasts": {
            "count": 0,
            "recasters": []
         },
         "isSelfLike": null,
         "isSelfRecast": null
      }
   },
   "source": "v2"
}

Cast by Short Hash and Username Endpoint

curl -X GET \
  -H "API-KEY: DEMO_REPLACE_WITH_FREE_API_KEY" \
  https://protocol.wield.co/farcaster/v2/cast-short?shortHash=0x96fe9d465ceefea&username=ashrafstakala

Query Parameter	Description
`shortHash`	Short hash value to identify the cast.
`username`	Username associated with the cast.

JSON Result (Expandable)

{
   "result": {
      "cast": {
         "hash": "0x96fe9d465ceefea38fca19bbe2c122f24f9bda1b",
         "threadHash": "0x96fe9d465ceefea38fca19bbe2c122f24f9bda1b",
         "text": "Warp. Drop the cast, it’s cleaner.",
         "embeds": {
            "images": [],
            "urls": []
         },
         "mentions": [],
         "mentionsPositions": [],
         "external": false,
         "author": {
            "fid": "12938",
            "followingCount": 170,
            "followerCount": 95,
            "pfp": {
               "url": "https://i.seadn.io/gae/ubYLLsa1-2w9N4wqOhantwsSmfoad7TuOHjtyWs7NdLIo1TtXLOWqKcC4J8YlTa1TPJfegZ4OhdvF8rr7z1JpZsepNxAYglv57cFOQ?w=500&auto=format",
               "verified": false
            },
            "bio": {
               "text": "Building products in Africa 🌍 Working on Paie https://paie.money",
               "mentions": []
            },
            "external": false,
            "custodyAddress": "0xda80ebef09c431a19a70a24c8b3342301c5a8735",
            "displayName": "ash",
            "username": "ashrafstakala",
            "registeredAt": 1693453451333,
            "isFollowing": null,
            "isFollowedBy": null
         },
         "parentAuthor": null,
         "timestamp": 1696833919000,
         "replies": {
            "count": 1
         },
         "reactions": {
            "count": 1
         },
         "recasts": {
            "count": 0,
            "recasters": []
         },
         "isSelfLike": null,
         "isSelfRecast": null
      }
   },
   "source": "v2"
}

All Casts in Thread Endpoint

curl -X GET \
  -H "API-KEY: DEMO_REPLACE_WITH_FREE_API_KEY" \
  https://protocol.wield.co/farcaster/v2/all-casts-in-thread?threadHash=0x96fe9d465ceefea38fca19bbe2c122f24f9bda1b

Query Parameter	Description
`threadHash`	Hash value to identify the thread.

JSON Result (Expandable)

{
  "result": {
    "casts": [
      {
        "hash": "0x96fe9d465ceefea38fca19bbe2c122f24f9bda1b",
        "threadHash": "0x96fe9d465ceefea38fca19bbe2c122f24f9bda1b",
        "text": "Warp. Drop the cast, it’s cleaner.",
        "embeds": { "images": [], "urls": [] },
        "mentions": [],
        "mentionsPositions": [],
        "external": false,
        "author": {
          "fid": "12938",
          "followingCount": 170,
          "followerCount": 95,
          "pfp": {
            "url": "https://i.seadn.io/gae/ubYLLsa1-2w9N4wqOhantwsSmfoad7TuOHjtyWs7NdLIo1TtXLOWqKcC4J8YlTa1TPJfegZ4OhdvF8rr7z1JpZsepNxAYglv57cFOQ?w=500&auto=format",
            "verified": false
          },
          "bio": {
            "text": "Building products in Africa 🌍 Working on Paie https://paie.money",
            "mentions": []
          },
          "external": false,
          "custodyAddress": "0xda80ebef09c431a19a70a24c8b3342301c5a8735",
          "displayName": "ash",
          "username": "ashrafstakala",
          "registeredAt": 1693453451333,
          "isFollowing": null,
          "isFollowedBy": null
        },
        "parentAuthor": null,
        "timestamp": 1696833919000,
        "replies": { "count": 1 },
        "reactions": { "count": 1 },
        "recasts": { "count": 0, "recasters": [] },
        "isSelfLike": null,
        "isSelfRecast": null
      },
      {
        "hash": "0x96fe9d465ceefea38fca19bbe2c122f24f9bda1b",
        "threadHash": "0x96fe9d465ceefea38fca19bbe2c122f24f9bda1b",
        "text": "Warp. Drop the cast, it’s cleaner.",
        "embeds": { "images": [], "urls": [] },
        "mentions": [],
        "mentionsPositions": [],
        "external": false,
        "author": {
          "fid": "12938",
          "followingCount": 170,
          "followerCount": 95,
          "pfp": {
            "url": "https://i.seadn.io/gae/ubYLLsa1-2w9N4wqOhantwsSmfoad7TuOHjtyWs7NdLIo1TtXLOWqKcC4J8YlTa1TPJfegZ4OhdvF8rr7z1JpZsepNxAYglv57cFOQ?w=500&auto=format",
            "verified": false
          },
          "bio": {
            "text": "Building products in Africa 🌍 Working on Paie https://paie.money",
            "mentions": []
          },
          "external": false,
          "custodyAddress": "0xda80ebef09c431a19a70a24c8b3342301c5a8735",
          "displayName": "ash",
          "username": "ashrafstakala",
          "registeredAt": 1693453451333,
          "isFollowing": null,
          "isFollowedBy": null
        },
        "parentAuthor": null,
        "timestamp": 1696833919000,
        "replies": { "count": 1 },
        "reactions": { "count": 1 },
        "recasts": { "count": 0, "recasters": [] },
        "isSelfLike": null,
        "isSelfRecast": null
      },
      {
        "hash": "0x0ca15e1e726bc626b15cc0146ffc1a696d58b10c",
        "parentHash": "0x96fe9d465ceefea38fca19bbe2c122f24f9bda1b",
        "parentFid": "12938",
        "threadHash": "0x96fe9d465ceefea38fca19bbe2c122f24f9bda1b",
        "text": "You forgot \"Oh, and one more thing\"",
        "embeds": { "images": [], "urls": [] },
        "mentions": [],
        "mentionsPositions": [],
        "external": false,
        "author": {
          "fid": "10694",
          "followingCount": 416,
          "followerCount": 357,
          "pfp": {
            "url": "https://i.imgur.com/28se29B.jpg",
            "verified": false
          },
          "bio": {
            "text": "0.2x guy, building the good for all mankind. Very serious \"ethical bribery\" expert.",
            "mentions": []
          },
          "external": false,
          "custodyAddress": "0x63c0df9ccb039241bf53baac41cc1d281ef95b63",
          "username": "chukwukaosakwe",
          "displayName": "Chukwuka Osakwe",
          "registeredAt": 1693456351921,
          "isFollowing": null,
          "isFollowedBy": null
        },
        "parentAuthor": {
          "fid": "12938",
          "followingCount": 170,
          "followerCount": 95,
          "pfp": {
            "url": "https://i.seadn.io/gae/ubYLLsa1-2w9N4wqOhantwsSmfoad7TuOHjtyWs7NdLIo1TtXLOWqKcC4J8YlTa1TPJfegZ4OhdvF8rr7z1JpZsepNxAYglv57cFOQ?w=500&auto=format",
            "verified": false
          },
          "bio": {
            "text": "Building products in Africa 🌍 Working on Paie https://paie.money",
            "mentions": []
          },
          "external": false,
          "custodyAddress": "0xda80ebef09c431a19a70a24c8b3342301c5a8735",
          "displayName": "ash",
          "username": "ashrafstakala",
          "registeredAt": 1693453451333
        },
        "timestamp": 1696845536000,
        "replies": { "count": 0 },
        "reactions": { "count": 1 },
        "recasts": { "count": 0, "recasters": [] },
        "isSelfLike": null,
        "isSelfRecast": null
      }
    ]
  },
  "source": "v2"
}

Casts Endpoint

curl -X GET \
  -H "API-KEY: DEMO_REPLACE_WITH_FREE_API_KEY" \
  https://protocol.wield.co/farcaster/v2/casts?fid=4163

Query Parameter	Description
`fid`	Farcaster ID.
`parentChain`	Parent chain identifier (cast hash, optional).
`limit`	Number of items to return. Default is 10.
`cursor`	Pagination cursor (optional).

JSON Result (Expandable)

{
   "result": {
      "casts": [
         {
            "hash": "0xefa960b8150e02f2a00a4fa8996bd59641f6e477",
            "parentUrl": "chain://eip155:7777777/erc721:0x4f86113fc3e9783cf3ec9a552cbb566716a57628",
            "threadHash": "0xefa960b8150e02f2a00a4fa8996bd59641f6e477",
            "text": "Looking for a list of apps that have capability to create new FC users. Register FID, buy Storage, register signer key, and support user profile setup (bio, avatar..)\n\nDoes @farquest do this? Any others?",
            "embeds": {
               "images": [],
               "urls": []
            },
            "mentions": [
               {
                  "fid": "12741",
                  "followingCount": 2430,
                  "followerCount": 1174,
                  "pfp": {
                     "url": "https://i.imgur.com/mXqdcF5.jpg",
                     "verified": false
                  },
                  "bio": {
                     "text": "Complete quests on Farcaster for FarPoints and FarLoot! Built by @n and @jc, grab a free pass at far.quest and join our telegram: t.me/+Q_cmS_jf8w1lZjQx",
                     "mentions": [
                        "n",
                        "jc"
                     ]
                  },
                  "external": false,
                  "custodyAddress": "0x72d9471869bf52d0da523fa9437d2d8ea077d2b6",
                  "username": "farquest",
                  "displayName": "far.quest",
                  "registeredAt": 1693464920777
               }
            ],
            "mentionsPositions": [
               173
            ],
            "external": false,
            "author": {
               "fid": "4163",
               "followingCount": 1414,
               "followerCount": 1481,
               "pfp": {
                  "url": "https://openseauserdata.com/files/12cc9c02bf8d37d0a097745d9e39ae7b.svg",
                  "verified": false
               },
               "bio": {
                  "text": "Normalizing typos one cast at a time. ",
                  "mentions": []
               },
               "external": false,
               "custodyAddress": "0x85f9886c48b17b534f3a64f2460dd9c04ab9a236",
               "username": "kmacb.eth",
               "displayName": "KMac🍌🥝🧃",
               "registeredAt": 1693500430064,
               "isFollowing": null,
               "isFollowedBy": null
            },
            "parentAuthor": null,
            "timestamp": 1696783975000,
            "replies": {
               "count": 2
            },
            "reactions": {
               "count": 4
            },
            "recasts": {
               "count": 0,
               "recasters": []
            },
            "isSelfLike": null,
            "isSelfRecast": null,
            "childCast": {
               "hash": "0xb14ddcd41bf4780525dddeeedad5507752f7e2da",
               "parentHash": "0xefa960b8150e02f2a00a4fa8996bd59641f6e477",
               "parentFid": "4163",
               "threadHash": "0xefa960b8150e02f2a00a4fa8996bd59641f6e477",
               "text": "Our @farquest roadmap isn’t public, stay tuned :)\n\nLet’s just say we aren’t working on a long weekend for no reason!",
               "embeds": {
                  "images": [],
                  "urls": []
               },
               "mentions": [
                  {
                     "fid": "12741",
                     "followingCount": 2430,
                     "followerCount": 1174,
                     "pfp": {
                        "url": "https://i.imgur.com/mXqdcF5.jpg",
                        "verified": false
                     },
                     "bio": {
                        "text": "Complete quests on Farcaster for FarPoints and FarLoot! Built by @n and @jc, grab a free pass at far.quest and join our telegram: t.me/+Q_cmS_jf8w1lZjQx",
                        "mentions": [
                           "n",
                           "jc"
                        ]
                     },
                     "external": false,
                     "custodyAddress": "0x72d9471869bf52d0da523fa9437d2d8ea077d2b6",
                     "username": "farquest",
                     "displayName": "far.quest",
                     "registeredAt": 1693464920777
                  }
               ],
               "mentionsPositions": [
                  4
               ],
               "external": false,
               "author": {
                  "fid": "251",
                  "followingCount": 917,
                  "followerCount": 10669,
                  "pfp": {
                     "url": "https://i.imgur.com/VxvEKrw.jpg",
                     "verified": false
                  },
                  "bio": {
                     "text": "Building @farquest, wield.co, investing @ miy.com. ex-Meta, ex-Coinbase // cryptojcdenton.twitter",
                     "mentions": [
                        "farquest"
                     ]
                  },
                  "external": false,
                  "custodyAddress": "0xe686a5c11ba86c36bb490765f9eb1e84379168ac",
                  "displayName": "jcdenton.cast",
                  "username": "jc",
                  "registeredAt": 1693452101654,
                  "isFollowing": null,
                  "isFollowedBy": null
               },
               "parentAuthor": {
                  "fid": "4163",
                  "followingCount": 1414,
                  "followerCount": 1481,
                  "pfp": {
                     "url": "https://openseauserdata.com/files/12cc9c02bf8d37d0a097745d9e39ae7b.svg",
                     "verified": false
                  },
                  "bio": {
                     "text": "Normalizing typos one cast at a time. ",
                     "mentions": []
                  },
                  "external": false,
                  "custodyAddress": "0x85f9886c48b17b534f3a64f2460dd9c04ab9a236",
                  "username": "kmacb.eth",
                  "displayName": "KMac🍌🥝🧃",
                  "registeredAt": 1693500430064
               },
               "timestamp": 1696790866000,
               "replies": {
                  "count": 0
               },
               "reactions": {
                  "count": 2
               },
               "recasts": {
                  "count": 0,
                  "recasters": []
               },
               "isSelfLike": null,
               "isSelfRecast": null
            },
            "childrenCasts": [
               {
                  "hash": "0xb14ddcd41bf4780525dddeeedad5507752f7e2da",
                  "parentHash": "0xefa960b8150e02f2a00a4fa8996bd59641f6e477",
                  "parentFid": "4163",
                  "threadHash": "0xefa960b8150e02f2a00a4fa8996bd59641f6e477",
                  "text": "Our @farquest roadmap isn’t public, stay tuned :)\n\nLet’s just say we aren’t working on a long weekend for no reason!",
                  "embeds": {
                     "images": [],
                     "urls": []
                  },
                  "mentions": [
                     {
                        "fid": "12741",
                        "followingCount": 2430,
                        "followerCount": 1174,
                        "pfp": {
                           "url": "https://i.imgur.com/mXqdcF5.jpg",
                           "verified": false
                        },
                        "bio": {
                           "text": "Complete quests on Farcaster for FarPoints and FarLoot! Built by @n and @jc, grab a free pass at far.quest and join our telegram: t.me/+Q_cmS_jf8w1lZjQx",
                           "mentions": [
                              "n",
                              "jc"
                           ]
                        },
                        "external": false,
                        "custodyAddress": "0x72d9471869bf52d0da523fa9437d2d8ea077d2b6",
                        "username": "farquest",
                        "displayName": "far.quest",
                        "registeredAt": 1693464920777
                     }
                  ],
                  "mentionsPositions": [
                     4
                  ],
                  "external": false,
                  "author": {
                     "fid": "251",
                     "followingCount": 917,
                     "followerCount": 10669,
                     "pfp": {
                        "url": "https://i.imgur.com/VxvEKrw.jpg",
                        "verified": false
                     },
                     "bio": {
                        "text": "Building @farquest, wield.co, investing @ miy.com. ex-Meta, ex-Coinbase // cryptojcdenton.twitter",
                        "mentions": [
                           "farquest"
                        ]
                     },
                     "external": false,
                     "custodyAddress": "0xe686a5c11ba86c36bb490765f9eb1e84379168ac",
                     "displayName": "jcdenton.cast",
                     "username": "jc",
                     "registeredAt": 1693452101654,
                     "isFollowing": null,
                     "isFollowedBy": null
                  },
                  "parentAuthor": {
                     "fid": "4163",
                     "followingCount": 1414,
                     "followerCount": 1481,
                     "pfp": {
                        "url": "https://openseauserdata.com/files/12cc9c02bf8d37d0a097745d9e39ae7b.svg",
                        "verified": false
                     },
                     "bio": {
                        "text": "Normalizing typos one cast at a time. ",
                        "mentions": []
                     },
                     "external": false,
                     "custodyAddress": "0x85f9886c48b17b534f3a64f2460dd9c04ab9a236",
                     "username": "kmacb.eth",
                     "displayName": "KMac🍌🥝🧃",
                     "registeredAt": 1693500430064
                  },
                  "timestamp": 1696790866000,
                  "replies": {
                     "count": 0
                  },
                  "reactions": {
                     "count": 2
                  },
                  "recasts": {
                     "count": 0,
                     "recasters": []
                  },
                  "isSelfLike": null,
                  "isSelfRecast": null
               }
            ]
         }
      ]
   },
   "next": "1696790866000-6523488d5c1497c0ef5274f3",
   "source": "v2"
}

Cast Reactions Endpoint

curl -X GET \
  -H "API-KEY: DEMO_REPLACE_WITH_FREE_API_KEY" \
  https://protocol.wield.co/farcaster/v2/cast-reactions?castHash=0xb14ddcd41bf4780525dddeeedad5507752f7e2da

GET

Query Parameter	Description
`castHash`	Hash value to identify the cast.
`limit`	Number of items to return. Default is 100.
`cursor`	Pagination cursor (optional).

JSON Result (Expandable)

{
   "result": {
      "reactions": [
         {
            "fid": "10694",
            "followingCount": 416,
            "followerCount": 357,
            "pfp": {
               "url": "https://i.imgur.com/28se29B.jpg",
               "verified": false
            },
            "bio": {
               "text": "0.2x guy, building the good for all mankind. Very serious \"ethical bribery\" expert.",
               "mentions": []
            },
            "external": false,
            "custodyAddress": "0x63c0df9ccb039241bf53baac41cc1d281ef95b63",
            "username": "chukwukaosakwe",
            "displayName": "Chukwuka Osakwe",
            "registeredAt": 1693456351921
         }
      ],
      "next": null
   },
   "source": "v2"
}

Cast Likes Endpoint

curl -X GET \
  -H "API-KEY: DEMO_REPLACE_WITH_FREE_API_KEY" \
  https://protocol.wield.co/farcaster/v2/cast-likes?castHash=0xb14ddcd41bf4780525dddeeedad5507752f7e2da

Query Parameter	Description
`castHash`	Hash value to identify the cast.
`limit`	Number of items to return. Default is 100.
`cursor`	Pagination cursor (optional).

JSON Result (Expandable)

{
   "result": {
      "likes": [
         {
            "fid": "10694",
            "followingCount": 416,
            "followerCount": 357,
            "pfp": {
               "url": "https://i.imgur.com/28se29B.jpg",
               "verified": false
            },
            "bio": {
               "text": "0.2x guy, building the good for all mankind. Very serious \"ethical bribery\" expert.",
               "mentions": []
            },
            "external": false,
            "custodyAddress": "0x63c0df9ccb039241bf53baac41cc1d281ef95b63",
            "username": "chukwukaosakwe",
            "displayName": "Chukwuka Osakwe",
            "registeredAt": 1693456351921
         }
      ],
      "next": null
   },
   "source": "v2"
}

Cast Recasters Endpoint

curl -X GET \
  -H "API-KEY: DEMO_REPLACE_WITH_FREE_API_KEY" \
  https://protocol.wield.co/farcaster/v2/cast-recasters?castHash=0xb14ddcd41bf4780525dddeeedad5507752f7e2da

Query Parameter	Description
`castHash`	Hash value to identify the cast.
`limit`	Number of items to return. Default is 100.
`cursor`	Pagination cursor (optional).

JSON Result (Expandable)

{
   "result": {
      "users": [
         {
            "fid": "251",
            "followingCount": 917,
            "followerCount": 10669,
            "pfp": {
               "url": "https://i.imgur.com/VxvEKrw.jpg",
               "verified": false
            },
            "bio": {
               "text": "Building @farquest, wield.co, investing @ miy.com. ex-Meta, ex-Coinbase // cryptojcdenton.twitter",
               "mentions": [
                  "farquest"
               ]
            },
            "external": false,
            "custodyAddress": "0xe686a5c11ba86c36bb490765f9eb1e84379168ac",
            "displayName": "jcdenton.cast",
            "username": "jc",
            "registeredAt": 1693452101654
         },
         {
            "fid": "12741",
            "followingCount": 2430,
            "followerCount": 1174,
            "pfp": {
               "url": "https://i.imgur.com/mXqdcF5.jpg",
               "verified": false
            },
            "bio": {
               "text": "Complete quests on Farcaster for FarPoints and FarLoot! Built by @n and @jc, grab a free pass at far.quest and join our telegram: t.me/+Q_cmS_jf8w1lZjQx",
               "mentions": [
                  "n",
                  "jc"
               ]
            },
            "external": false,
            "custodyAddress": "0x72d9471869bf52d0da523fa9437d2d8ea077d2b6",
            "username": "farquest",
            "displayName": "far.quest",
            "registeredAt": 1693464920777
         }
      ],
      "next": "1696621301000-6520b87718f4a3019afd4cdc"
   },
   "source": "v2"
}

Followers Endpoint

curl -X GET \
  -H "API-KEY: DEMO_REPLACE_WITH_FREE_API_KEY" \
  https://protocol.wield.co/farcaster/v2/followers?fid=251

Query Parameter	Description
`fid`	Farcaster ID.
`limit`	Number of items to return. Default is 100.
`cursor`	Pagination cursor (optional).

JSON Result (Expandable)

{
   "result": {
      "users": [
         {
            "fid": "20812",
            "followingCount": 66,
            "followerCount": 0,
            "pfp": {
               "url": "https://i.imgur.com/AioiiPz.jpg",
               "verified": false
            },
            "bio": {
               "text": "I'm a little teapot who didn't fill out my bio",
               "mentions": []
            },
            "external": false,
            "username": "boyu",
            "displayName": "Bo",
            "registeredAt": 1696842240571
         },
         {
            "fid": "19582",
            "followingCount": 64,
            "followerCount": 1,
            "pfp": {
               "url": "https://i.imgur.com/T0thqA2.jpg",
               "verified": false
            },
            "bio": {
               "text": "Founder gobob.xyz. Build on Bitcoin.",
               "mentions": []
            },
            "external": false,
            "username": "dom0",
            "displayName": "Dom",
            "registeredAt": 1693468296379
         },
         {
            "fid": "20810",
            "followingCount": 65,
            "followerCount": 1,
            "pfp": {
               "url": "https://i.imgur.com/ig1egBS.jpg",
               "verified": false
            },
            "bio": {
               "text": "Cryypto dude. 2014",
               "mentions": []
            },
            "external": false,
            "username": "dizzy-hill",
            "displayName": "Dizzy Hill",
            "registeredAt": 1696833775762
         }
      ],
      "next": "1696833834000-6523a12c4108cb58a867efb6"
   },
   "source": "v2"
}

Following Endpoint

curl -X GET \
  -H "API-KEY: DEMO_REPLACE_WITH_FREE_API_KEY" \
  https://protocol.wield.co/farcaster/v2/following?fid=251

Query Parameter	Description
`fid`	Farcaster ID.
`limit`	Number of items to return. Default is 100.
`cursor`	Pagination cursor (optional).

JSON Result (Expandable)

{
   "result": {
      "users": [
         {
            "fid": "8555",
            "followingCount": 460,
            "followerCount": 421,
            "pfp": {
               "url": "https://i.imgur.com/GmnvPqz.jpg",
               "verified": false
            },
            "bio": {
               "text": "፨ Legal & Regulatory Frameworks for DAOs (Decentralized Autonomous Organizations) & Web3 💼 Founder of MIDAO 🎙️Host of Just DAO It! Podcast nf.td/thethriller",
               "mentions": []
            },
            "external": false,
            "custodyAddress": "0x341f97bd6ea1e8b23d11087f786dc71dfe055b4d",
            "username": "thethriller",
            "displayName": "Adam Miller",
            "registeredAt": 1693456377908
         },
         {
            "fid": "7589",
            "followingCount": 107,
            "followerCount": 278,
            "pfp": {
               "url": "https://i.imgur.com/lJgoSQq.jpg",
               "verified": false
            },
            "bio": {
               "text": "Building Covariance| D2D hacker | biz dev | Growth | web3 social | Future of Work is here & it's tokenized.\n\nSeason 1 application open soon:\nCovariance.network",
               "mentions": []
            },
            "external": false,
            "custodyAddress": "0xb8878994dc25597dd0848cd03bf12f2ff36fa213",
            "username": "lior",
            "displayName": "Lior",
            "registeredAt": 1693695265147
         },
         {
            "fid": "1918",
            "followingCount": 331,
            "followerCount": 1891,
            "pfp": {
               "url": "https://i.imgur.com/t0HMNTm.jpg",
               "verified": false
            },
            "bio": {
               "text": "zoz: A new slang term for \"lol\". More of a sarcastic way to say something isn't funny. https://github.com/0xZOZ",
               "mentions": []
            },
            "external": false,
            "custodyAddress": "0xac31f53d4bb5c8d62b95f4a93e5c977cccc5d111",
            "username": "zoz.eth",
            "displayName": "zoz",
            "registeredAt": 1693500429936
         }
      ],
      "next": "1696730376000-652348824108cb58a830dde1"
   },
   "source": "v2"
}

User by Connected Address Endpoint

curl -X GET \
  -H "API-KEY: DEMO_REPLACE_WITH_FREE_API_KEY" \
  https://protocol.wield.co/farcaster/v2/user-by-connected-address?address=0x997b0CcEd542b6d2A7e0Bae5649aFd9d0861CB4e

GET

Query Parameter	Description
`address`	Connected address.

JSON Result (Expandable)

{
   "result": {
      "user": {
         "fid": "251",
         "followingCount": 917,
         "followerCount": 10670,
         "pfp": {
            "url": "https://i.imgur.com/VxvEKrw.jpg",
            "verified": false
         },
         "bio": {
            "text": "Building @farquest, wield.co, investing @ miy.com. ex-Meta, ex-Coinbase // cryptojcdenton.twitter",
            "mentions": [
               "farquest"
            ]
         },
         "external": false,
         "custodyAddress": "0xe686a5c11ba86c36bb490765f9eb1e84379168ac",
         "displayName": "jcdenton.cast",
         "username": "jc",
         "registeredAt": 1693452101654
      }
   },
   "source": "v2"
}

User by Custody Address Endpoint

curl -X GET \
  -H "API-KEY: DEMO_REPLACE_WITH_FREE_API_KEY" \
  https://protocol.wield.co/farcaster/v2/user-by-custody-address?address=0xe686a5c11ba86c36bb490765f9eb1e84379168ac

Query Parameter	Description
`address`	Custody address.

JSON Result (Expandable)

{
   "result": {
      "user": {
         "fid": "251",
         "followingCount": 917,
         "followerCount": 10670,
         "pfp": {
            "url": "https://i.imgur.com/VxvEKrw.jpg",
            "verified": false
         },
         "bio": {
            "text": "Building @farquest, wield.co, investing @ miy.com. ex-Meta, ex-Coinbase // cryptojcdenton.twitter",
            "mentions": [
               "farquest"
            ]
         },
         "external": false,
         "custodyAddress": "0xe686a5c11ba86c36bb490765f9eb1e84379168ac",
         "displayName": "jcdenton.cast",
         "username": "jc",
         "registeredAt": 1693452101654
      }
   },
   "source": "v2"
}

User Endpoint

curl -X GET \
  -H "API-KEY: DEMO_REPLACE_WITH_FREE_API_KEY" \
  https://protocol.wield.co/farcaster/v2/user?fid=251

Query Parameter	Description
`fid`	Farcaster ID.

JSON Result (Expandable)

{
   "result": {
      "user": {
         "fid": "251",
         "followingCount": 917,
         "followerCount": 10669,
         "pfp": {
            "url": "https://i.imgur.com/VxvEKrw.jpg",
            "verified": false
         },
         "bio": {
            "text": "Building @farquest, wield.co, investing @ miy.com. ex-Meta, ex-Coinbase // cryptojcdenton.twitter",
            "mentions": [
               "farquest"
            ]
         },
         "external": false,
         "custodyAddress": "0xe686a5c11ba86c36bb490765f9eb1e84379168ac",
         "displayName": "jcdenton.cast",
         "username": "jc",
         "registeredAt": 1693452101654,
         "isFollowing": null,
         "isFollowedBy": null
      }
   },
   "source": "v2"
}

User by Username Endpoint

curl -X GET \
  -H "API-KEY: DEMO_REPLACE_WITH_FREE_API_KEY" \
  https://protocol.wield.co/farcaster/v2/user?username=jc

Query Parameter	Description
`username`	User's username.

JSON Result (Expandable)

{
   "result": {
      "user": {
         "fid": "251",
         "followingCount": 917,
         "followerCount": 10669,
         "pfp": {
            "url": "https://i.imgur.com/VxvEKrw.jpg",
            "verified": false
         },
         "bio": {
            "text": "Building @farquest, wield.co, investing @ miy.com. ex-Meta, ex-Coinbase // cryptojcdenton.twitter",
            "mentions": [
               "farquest"
            ]
         },
         "external": false,
         "custodyAddress": "0xe686a5c11ba86c36bb490765f9eb1e84379168ac",
         "displayName": "jcdenton.cast",
         "username": "jc",
         "registeredAt": 1693452101654
      }
   },
   "source": "v2"
}

Get Farcaster Storage Endpoint

curl -X GET \
  -H "API-KEY: DEMO_REPLACE_WITH_FREE_API_KEY" \
  https://protocol.wield.co/farcaster/v2/user?fid=251

Query Parameter	Description
`fid`	User's FID.

JSON Result (Expandable)

{
  "result": {
    "data": [
      {
        "timestamp": "2023-08-29T22:23:43.000Z",
        "fid": "274",
        "units": 2,
        "expiry": "2024-08-28T22:23:43.000Z"
      }
    ]
  }
}

Farcaster API Endpoints (Write)

To do writes, you'll need to submit messages to a Farcaster hub via Hub HTTP APIs (opens in a new tab): we run a free public hub at arena.wield.co:2283! We do our best to keep this hub alive and we use it for testing!

Join our Developer Telegram (opens in a new tab) to report any issues. =======

Farcaster L1 API Write Endpoints

To do Farcaster L1 writes, we run a free public hub at arena.wield.co:2283 - we do our best to keep this hub alive and we use it for testing! Join our Developer Telegram (opens in a new tab) to report any issues.

You can also run a hub for only ~$50/month (before credits)!

Other Free Read/Write Hubs

Farcaster L2 API Write Endpoints

Cast is built as the first Farcaster Layer 2, functioning as an open-source, federated hub (opens in a new tab). To authenticate with our Farcaster L2 APIs, you need to both create a GraphQL auth token and a signer, following these steps:

The endpoint to complete writes is as follows, please use https://protocol.wield.co/graphql as your GraphQL endpoint:

Message Endpoint

POST https://protocol.wield.co/farcaster/v2/message

This endpoint allows for sending messages to the Farcaster L2 network.

Field	Type	Description
`isExternal`	Boolean	Indicates whether the message is external (set to true).
`externalFid`	String	The Farcaster Cast address of the user (required).
`message`	JSON	The message content in JSON format (required).
`bodyOverrides`	JSON	Overrides on message data due to L1 libraries (optional).

JSON Result (Expandable)

{
   "result": {
      "fid": "0x0000000000000000000000000000000000000000",
      "createdAt": "2023-11-07T12:00:00Z",
      "updatedAt": "2023-11-07T12:00:00Z",
      "messageType": "messageTypeValue",
      "timestamp": "2023-11-07T12:00:00Z",
      "hash": "messageHashValue",
      "hashScheme": "schemeValue",
      "signature": "signatureValue",
      "signatureScheme": "schemeValue",
      "signer": "signerValue",
      "raw": "rawMessageValue",
      "external": true,
      "unindexed": true,
   },
   "source": "v2"
}

Step 1: Retrieve Sign-in Message

Obtain a sign-in message using your external account (such as one managed by Metamask) and not a signer account. Use the GET_ACCOUNT_SIGNIN_MESSAGE query with your custody address and chainId set to 1.

import { gql, useQuery } from "@apollo/client";
 
export const GET_ACCOUNT_SIGNIN_MESSAGE = gql`
  query GET_ACCOUNT_SIGNIN_MESSAGE($address: String!, $chainId: Int!) {
    AccountQuery {
      getAccountSigninMessage(address: $address, chainId: $chainId)
    }
  }
`;
const { data, refetch } = useQuery(GET_ACCOUNT_SIGNIN_MESSAGE, {
  skip: !currentAddress,
  variables: {
    address: currentAddress,
    chainId: 1,
  },
});

Step 2: Sign the Message

Use the eth_personalsign method to sign the message you retrieved in the previous step.

import { useSignMessage } from "wagmi";
const { signMessage, isError, isLoading } = useSignMessage({
  message: signature,
  onSuccess: (token) => {
    callback?.({ token, address: currentAddress, type: "SIGNATURE" });
  },
});

Step 3: Exchange the Signature for an AccessToken

After signing the message, use the AUTH_BY_SIGNATURE mutation to exchange the signature for an accessToken. This token will be used for subsequent authenticated API requests.

import { gql, useMutation } from "@apollo/client";
 
const CORE_ACCOUNT_FIELDS = gql`
  fragment CoreAccountFields on Account {
    _id
    username
    profileImage {
      _id
      src
      isVerified
      verificationExternalUrl
    }
    bio {
      raw
      json
    }
    address {
      _id
      address
      chain {
        chainId
        name
      }
    }
  }
`;
 
export const AUTH_BY_SIGNATURE = gql`
  ${CORE_ACCOUNT_FIELDS}
  mutation AUTH_BY_SIGNATURE(
    $address: String!
    $chainId: Int!
    $signature: String!
  ) {
    authBySignature(
      address: $address
      chainId: $chainId
      signature: $signature
    ) {
      code
      success
      message
      accessToken
    }
  }
`;
const [
  _onSignin,
  { loading: signinLoading, data: signinData, error: signinError },
] = useMutation(AUTH_BY_SIGNATURE);
Cookies.set(config.AUTH_KEY, data.authBySignature.accessToken, {
  domain: config.COOKIE_DOMAIN,
  expires: 180,
});

Step 4: Create a localStorage signer

import * as ed from "@noble/ed25519";
import { gql, useMutation } from "@apollo/client";
 
async function generateAndStoreKeyPair(key) {
  try {
    const privateKey = ed.utils.randomPrivateKey();
    const publicKey = await ed.getPublicKeyAsync(privateKey);
 
    // Prepare the object to store
    const keyPair = {
      publicKey: Buffer.from(publicKey).toString("hex"),
      privateKey: Buffer.from(privateKey).toString("hex"),
    };
 
    // Store the key pair in local storage
    localStorage.setItem(key, JSON.stringify(keyPair));
 
    return keyPair;
  } catch (error) {
    console.error("Error generating or storing key pair:", error);
  }
}
 
export const ADD_RECOVERER = gql`
  ${CORE_ACCOUNT_FIELDS}
  mutation ADD_RECOVERER(
    $address: String
    $signature: String
    $type: String
    $id: String
  ) {
    addRecoverer(
      address: $address
      signature: $signature
      type: $type
      id: $id
    ) {
      code
      success
      message
      account {
        ...CoreAccountFields
      }
    }
  }
`;
const [_onAddRecoverer, { loading: addRecovererLoading }] =
  useMutation(ADD_RECOVERER);

Step 5: Send messages

// Helper function to make requests
export const makeRequest = async (
  messageType,
  body,
  fid,
  overrides = {},
  bodyOverrides = {}
) => {
  const message = await makeMessage({
    messageType,
    body,
    fid,
    overrides,
  });
  let isExternal = fid?.slice(0, 2) === "0x" ? true : false;
  if (!isExternal) {
    // it can also be external if any of the keys or subkeys of bodyOverrides contains 0x
    isExternal = Object.keys(bodyOverrides).some((key) => {
      if (typeof bodyOverrides[key] === "object") {
        return Object.keys(bodyOverrides[key]).some((subkey) => {
          return bodyOverrides[key][subkey]?.slice(0, 2) === "0x";
        });
      }
      return bodyOverrides[key]?.slice?.(0, 2) === "0x";
    });
  }
  const token = Cookies.get(config.AUTH_KEY);
  const response = await fetchWithoutAuth(
    "https://protocol.wield.co/farcaster/v2/message",
    {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        authorization: token ? `Bearer ${token}` : "",
      },
      body: JSON.stringify({
        isExternal,
        message,
        bodyOverrides,
      }),
    }
  );

Support and Updates

Join our Developer Telegram (opens in a new tab) to get help and follow along!

Legal Disclaimer

You agree to our Terms of Service (opens in a new tab) when using our free APIs or free hub.

Wield Overview