Developer Center

How To Programmatically Interact With The Farcaster Decentralized Social Network Using Python

How To Programmatically Interact With The Farcaster Decentralized Social Network Using Python


Farcaster is a decentralized social network (DeSoc) built on the Interplanetary File System (IPFS) and the Ethereum blockchain. Unlike traditional social media platforms, Farcaster empowers users to own their data and content, fostering a more equitable and secure online experience.

This article delves into programmatically interacting with Farcaster using Python, enabling developers to automate tasks, build custom applications, and explore the possibilities of this innovative DeSoc platform.


To complete this tutorial, ensure you have the following essentials:

  • A non-root user with sudo privileges on a Linux-based operating system. If you don’t have this setup locally, you can achieve this by following our How To Set Up an Ubuntu Server on a DigitalOcean Droplet guide.

  • Python 3 installed and a programming environment setup on your computer or server. Suppose you don’t have a Python 3 programming environment setup. In that case, you can refer to our installation guide to set up a Python 3 programming environment on your server appropriate for your operating system (Ubuntu, CentOS, Debian, etc.). In this tutorial, we’ll call our project directory farcaster-example.

  • A Farcaster account. You can create one for free at

  • Familiarity with a terminal environment. If you’re unfamiliar with a terminal environment, you may find the article An Introduction to the Linux Terminal useful for becoming better oriented with the terminal.

With your environment and user setup, you are ready to begin.

Installing the Essential Python Libraries

In this step, you’ll install the Farcaster-py library, a Python Standard Development Kit (SDK) for the Farcaster protocol, using the pip package installer.

If you haven’t already activated your programming environment, make sure you’re in your project’s (farcaster-example) parent directory and use the following command to activate the environment.

source env/bin/activate

Once your programming environment is activated, your prompt will now be prefixed with the name of your environment; in this case, it is called ^env^. Depending on what flavor of Linux you’re running, your prefix may appear somewhat differently, but the name of your environment in parentheses should be the first thing you see on your line:


This prefix is an indication that the environment env is currently active, which might have another name depending on how you named it during creation.

Now, let’s install the Python packages we’ll need during this tutorial using the pip command.

To install farcaster-py, run the following command:

  1. pip install -U farcaster

The farcaster-py SDK leverages the Warpcast Application Programming Interface (API). Warpcast is one of the many Farcaster clients, and to use the Warpcast API, you’ll need a Farcaster account.

Note: Within the virtual environment, you can use the command python instead of python3, and pip instead of pip3 if you would prefer.

Next, let’s install the dotenv library, which will be used to load environment variables from the .env file.

  1. pip install python-dotenv

Once we have farcaster-py and dotenv successfully installed, we’re good to move on to the next step.

Connecting to Farcaster

In this step, you’ll use the mnemonic or private key of the Farcaster custody account (provided by Warpcast) to connect to the API.

First, save your Farcaster mnemonic or private key to a .env file. You can do this by opening up the .env file using the command below:

  1. nano .env

Within the .env file, type the following line, replacing YOUR_MNEMONIC_HERE with your actual mnemonic phrase:


Press Ctrl + O to save, followed by Enter to confirm the filename, and finally Ctrl + X to exit the editor.

As a security precaution, you can execute the command below to prevent unauthorized access to the sensitive mnemonic. This sets permissions to read and write for the owner only.

  1. chmod 600 .env

Now, let’s enter the Python command-line shell and start interacting with Farcaster. Launch the shell using the python command:

  1. python

You should see an output that is similar to what’s below. This indicates that you have successfully entered the Python shell.

Python 3.9.2 (default, Feb 28 2021, 17:03:44) [GCC 10.2.1 20210110] on linux Type "help", "copyright", "credits" or "license" for more information. >>>

Once we’ve entered the shell, we’ll begin typing out our code. First, let’s import the os library, the Warpcast, and the load_dotenv objects from the farcaster and dotenv libraries respectively.

  1. import os
  2. from farcaster import Warpcast
  3. from dotenv import load_dotenv

Next, let’s load environment variables in .env by calling load_dotenv():

  1. load_dotenv()

A successful load of the environment variable will output True.

Now, instantiate the client using the Warpcast method with the MNEMONIC as the argument. Then call the get_healthcheck() method to check if the client is connected.

  1. client = Warpcast(mnemonic=os.environ.get(“MNEMONIC”))
  2. client.get_healthcheck()

A successful health check should output True. This means that our client is successfully instantiated and can interact with the Farcaster network.

In the next step, we shall interact with the Farcaster network by publishing casts, deleting casts, and getting our Farcaster ID (FID).

Interacting with Farcaster

Now, let’s publish a cast. A cast refers to content that is broadcast to a specific group of followers or subscribers on Farcaster. This is similar to how you send a post to your followers on

  1. broadcast = client.post_cast(text=”Hello World!”)
  2. hash = broadcast.cast.hash
  3. print(hash)

The code above publishes the text “Hello World!” as a cast to the Farcaster network, and the last line prints the cast’s hash as registered on the network.

Next, let’s read the cast we just published to the code. Since we have the hash, we can feed it as an argument into get_cast(), which will return the contents of the cast on success.

  1. read = client.get_cast(hash)
  2. text = read.cast.text
  3. print(text)

This should print the content of the cast that was previously published as “Hello World!”. Now that you are familiar with posting and getting the contents of a cast, you should try your hand at deleting a cast:

  1. is_deleted = client.delete_cast(hash)
  2. print(is_deleted)

If the cast was deleted, the code above will print the cast’s deleted status to be True.

As you may have noticed, one is required to create an account in order to post content (casts) on Farcaster. Behind the scenes, every user is assigned a Farcaster ID (FID) after creating an account. You can get your FID by running the lines of code below:

  1. user = client.get_me()
  2. fid = user.fid
  3. print(fid)

The get_me() method gets the current Farcaster user, which is you. If you wish to get information on other users, you can use either client.get_user(), which takes an FID, or client.get_user_username(), which takes a username as argument. Both methods return a model that contains the user object.

Farcaster offers various features beyond basic read/write functionalities. You can explore the following possibilities:

  • Track updates from other users with the follow_user() method.
  • Express appreciation for posts using the like_post() method.
  • Listen for real-time changes in your feed using stream_casts() method.

As Farcaster evolves, new opportunities will emerge, inviting developers to explore and learn within this exciting ecosystem.


This article provided a foundational understanding of how to interact with Farcaster using Python. By leveraging Python and Farcaster, developers like you can unlock the potential of this DeSoc platform by automating tasks, building custom applications, and contributing to the growth of a more decentralized and user-centric social web.

The author selected Direct Relief Program to receive a donation as part of the Write for DOnations program.

Thanks for learning with the DigitalOcean Community. Check out our offerings for compute, storage, networking, and managed databases.

Learn more about our products

About the authors

Default avatar

Sr Technical Writer

Still looking for an answer?

Ask a questionSearch for more help

Was this helpful?
Leave a comment

This textbox defaults to using Markdown to format your answer.

You can type !ref in this text area to quickly search our full set of tutorials, documentation & marketplace offerings and insert the link!

Try DigitalOcean for free

Click below to sign up and get $200 of credit to try our products over 60 days!

Sign up

Join the Tech Talk
Success! Thank you! Please check your email for further details.

Please complete your information!

Featured on Community

Get our biweekly newsletter

Sign up for Infrastructure as a Newsletter.

Hollie's Hub for Good

Working on improving health and education, reducing inequality, and spurring economic growth? We'd like to help.

Become a contributor

Get paid to write technical tutorials and select a tech-focused charity to receive a matching donation.

Welcome to the developer cloud

DigitalOcean makes it simple to launch in the cloud and scale up as you grow — whether you're running one virtual machine or ten thousand.

Learn more
DigitalOcean Cloud Control Panel