Farcaster.js

A tool for interacting with the Farcaster social network.

• Setup
• Examples
  • Publish a Cast
  • Lookup a User
  • Fetch User Activity
  • Reply to a Cast
  • Follow a User
  • Parse an API Error Response
  • Use a User-Supplied Auth Token
• Documentation
  • Warpcast API Client
  • Hubs
  • User Registry

Setup

Install the library:

npm install @standard-crypto/farcaster-js

Then grab a copy of the private key or mnemonic registered to your Farcaster user for use in authenticating to the platform. In the app, this can be found within settings -> Recovery Phrase

Examples

Publish a Cast

import { publishCast } from "@standard-crypto/farcaster-js";
import { Wallet } from "ethers";

const wallet = Wallet.fromMnemonic("twelve words here");

const cast = await publishCast(wallet, "Hello, Farcaster!");

console.log(`New cast hash: ${cast.hash}`);

Lookup a User

import { MerkleAPIClient } from "@standard-crypto/farcaster-js";
import { Wallet } from "ethers";

const wallet = Wallet.fromMnemonic("twelve words here");
const client = new MerkleAPIClient(wallet);

// by farcaster ID ('fid')
await client.lookupUserByFid(3);

// by username
await client.lookupUserByUsername("dwr");

Fetch User Activity

import { MerkleAPIClient } from "@standard-crypto/farcaster-js";
import { Wallet } from "ethers";

// init
const wallet = Wallet.fromMnemonic("twelve words here");
const apiClient = new MerkleAPIClient(wallet);

// fetch handle to a user
const user = await apiClient.lookupUserByUsername("dwr");
if (user === undefined) throw new Error("no such user");

// fetch user's casts
for await (const cast of apiClient.fetchCastsForUser(user)) {
  console.log(cast.text);
}

Reply to a Cast

import { MerkleAPIClient } from "@standard-crypto/farcaster-js";
import { Wallet } from "ethers";

// init
const wallet = Wallet.fromMnemonic("twelve words here");
const apiClient = new MerkleAPIClient(wallet);

// fetch cast to reply to
const user = await apiClient.lookupUserByUsername("dwr");
if (user === undefined) throw new Error("no such user");
const replyTo = await apiClient.fetchLatestCastForUser(user);
if (replyTo === undefined) throw new Error("no such user");

// post a reply
await apiClient.publishCast("Replying to your cast!", replyTo);

Follow a User

import { MerkleAPIClient } from "@standard-crypto/farcaster-js";
import { Wallet } from "ethers";

// init
const wallet = Wallet.fromMnemonic("twelve words here");
const apiClient = new MerkleAPIClient(wallet);
const user = await apiClient.lookupUserByUsername("dwr");
if (user === undefined) throw new Error("no such user");

// follow an existing user
await apiClient.followUser(user);

Parse an API Error Response

import { MerkleAPIClient } from "@standard-crypto/farcaster-js";
import { Wallet } from "ethers";

// init
const wallet = Wallet.fromMnemonic("twelve words here");
const apiClient = new MerkleAPIClient(wallet);

// parse an error response from the API server
try {
  await apiClient.deleteCast("SomeInvalidCastHash");
} catch (error) {
  if (MerkleAPIClient.isApiErrorResponse(error)) {
    const apiErrors = error.response.data.errors;
    for (const apiError of apiErrors) {
      console.log(`API Error: ${apiError.message}`);
    }

    console.log(`Status code: ${error.response.status}`);
  }
}

Use a User-Supplied Auth Token

import { MerkleAPIClient } from "@standard-crypto/farcaster-js";

// use an auth token provided directly by a user
const apiClient = new MerkleAPIClient({
  secret: "MK-abc123...",
  expiresAt: 12345678900000, // optional
});

// lookup that user
const user = await apiClient.fetchCurrentUser();
console.log(user.displayName);

Documentation

Warpcast API Client

The Warpcast API is a collection of publicly exposed API endpoints provided by Merkle Manufactory, Inc for Farcaster V2. farcaster-js provides a set of typescript bindings for those endpoints, as well as exposing the raw swagger bindings directly if needed.

See here for full list of the methods supported.

Wrappers for the Warpcast API are based on a OpenAPI spec kept in the src directory that is no longer kept up-to-date by the Warpcast team. Many manual edits have been added to the output of the openapi-generator. To add wrappers for new API endpoints, the yarn:generate script can be used as a starting point.

Hubs

Support for direct interaction with Farcaster hubs coming soon.

User Registry

Support for direct interaction with the on-chain user registry coming soon.