Farcaster Docs

https://docs.farcaster.xyz/
Admin
Farcaster Docs provides documentation for building and distributing permissionless social apps on...
Tokens:86,058
Snippets:498
Trust Score:9.3
Update:10 months ago
Show doc for...
Tokens:
Raw
### Server-Side Sign-In with Farcaster AuthKit and NextAuth.js

Source: https://docs.farcaster.xyz/auth-kit/examples

A Next.js application that handles Farcaster sign-in and session management on the server-side. It utilizes Farcaster AuthKit and NextAuth.js. To run this demo, you need to clone a repository, install dependencies, and start the development server.

```bash
git clone https://github.com/farcasterxyz/auth-monorepo.git &&  
cd auth-monorepo/examples/with-next-auth &&  
yarn install &&  
yarn dev
```

--------------------------------

### Setup Farcaster Constants in TypeScript

Source: https://docs.farcaster.xyz/developers/guides/basics/hello-world

Configures essential constants for interacting with the Farcaster network, including contract addresses, ABIs, network settings, and RPC provider URLs. Requires Farcaster hub access and an ETH wallet with Optimism ETH.

```typescript
import {
  ID_GATEWAY_ADDRESS,
  idGatewayABI,
  KEY_GATEWAY_ADDRESS,
  keyGatewayABI,
  ID_REGISTRY_ADDRESS,
  idRegistryABI,
  FarcasterNetwork,
} from '@farcaster/hub-web';
import { zeroAddress } from 'viem';
import { optimism } from 'viem/chains';

/**
 * Populate the following constants with your own values
 */
const MNEMONIC = '<REQUIRED>';
const OP_PROVIDER_URL = '<REQUIRED>'; // Alchemy or Infura url
const RECOVERY_ADDRESS = zeroAddress; // Optional, using the default value means the account will not be recoverable later if the mnemonic is lost
const ACCOUNT_KEY_PRIVATE_KEY: Hex = zeroAddress; // Optional, using the default means a new account key will be created each time

// Note: hoyt is the Farcaster team's mainnet hub, which is password protected to prevent abuse. Use a 3rd party hub
// provider like https://neynar.com/ Or, run your own mainnet hub and broadcast to it permissionlessly.
const HUB_URL = 'hoyt.farcaster.xyz:3383'; // URL + Port of the Hub
const HUB_USERNAME = ''; // Username for auth, leave blank if not using TLS
const HUB_PASS = ''; // Password for auth, leave blank if not using TLS
const USE_SSL = false; // set to true if talking to a hub that uses SSL (3rd party hosted hubs or hubs that require auth)
const FC_NETWORK = FarcasterNetwork.MAINNET; // Network of the Hub

const CHAIN = optimism;

const IdGateway = {
  abi: idGatewayABI,
  address: ID_GATEWAY_ADDRESS,
  chain: CHAIN,
};
const IdContract = {
  abi: idRegistryABI,
  address: ID_REGISTRY_ADDRESS,
  chain: CHAIN,
};
const KeyContract = {
  abi: keyGatewayABI,
  address: KEY_GATEWAY_ADDRESS,
  chain: CHAIN,
};
```

--------------------------------

### Client-Side Sign-In with Farcaster AuthKit and Vite

Source: https://docs.farcaster.xyz/auth-kit/examples

A frontend-only application demonstrating Farcaster sign-in functionality using AuthKit and Vite. It allows users to sign in and displays their profile picture and username. This example requires cloning a repository, installing dependencies, and running a development server.

```bash
git clone https://github.com/farcasterxyz/auth-monorepo.git &&  
cd auth-monorepo/examples/frontend-only &&  
yarn install &&  
yarn dev
```

--------------------------------

### Auth Client - Installation

Source: https://docs.farcaster.xyz/auth-kit/client/introduction

Installs the @farcaster/auth-client library and its peer dependency viem using npm.

```APIDOC
## Installation

Install the Auth client and its peer dependency viem.

```sh
npm install @farcaster/auth-client viem
```
```

--------------------------------

### Get Starter Pack Members (curl)

Source: https://docs.farcaster.xyz/reference/farcaster/api

Example using curl to fetch members of a starter pack, identified by its ID. This demonstrates a GET request to the starter pack members endpoint.

```bash
curl 'https://api.farcaster.xyz/fc/starter-pack-members?id=Underrated-CT-1y7n9b'
```

--------------------------------

### Install Farcaster Auth Client and Peer Dependencies

Source: https://docs.farcaster.xyz/auth-kit/client/introduction

Installs the @farcaster/auth-client library along with its peer dependency 'viem' using npm. This is the initial step to integrate Farcaster authentication into your application.

```shell
npm install @farcaster/auth-client viem

```

--------------------------------

### Example: Get Channel Invites (cURL)

Source: https://docs.farcaster.xyz/reference/farcaster/api

An example using cURL to fetch channel invites for the channel with ID 'memes' from the Farcaster API.

```bash
curl 'https://api.farcaster.xyz/fc/channel-invites?channelId=memes'
```

--------------------------------

### Example: Get Channels a User is Following (cURL)

Source: https://docs.farcaster.xyz/reference/farcaster/api

An example using cURL to fetch the channels a user with FID '3' is following from the Farcaster API.

```bash
curl 'https://api.farcaster.xyz/v1/user-following-channels?fid=3'
```

--------------------------------

### Install Farcaster Auth Kit and Viem

Source: https://docs.farcaster.xyz/auth-kit/installation

Installs the auth-kit library and its peer dependency, viem, using npm. This is the initial step for integrating Farcaster authentication into a React application.

```sh
npm install @farcaster/auth-kit viem
```

--------------------------------

### Get Starter Pack Members (JSON Response)

Source: https://docs.farcaster.xyz/reference/farcaster/api

Example JSON response for the 'Get Starter Pack Members' endpoint. It includes a list of members, each with their FID and the 'memberAt' timestamp, along with pagination information.

```json
{
  "result": {
    "members": [
      {
        "fid": 3,
        "memberAt": 1740172669691
      },
      {
        "fid": 296646,
        "memberAt": 1740172669691
      },
      ...
    ]
  },
  "next": { "cursor": "..." }
}
```

--------------------------------

### Example: Get Cast Moderation Actions (cURL)

Source: https://docs.farcaster.xyz/reference/farcaster/api

An example using cURL to retrieve moderation actions for the channel with ID 'welcome' from the Farcaster API.

```bash
curl 'https://api.farcaster.xyz/fc/moderated-casts?channelId=welcome'
```

--------------------------------

### Full Example: Create Farcaster Address Verification (TypeScript)

Source: https://docs.farcaster.xyz/developers/guides/writing/verify-address

A comprehensive TypeScript example demonstrating the complete process of creating a Farcaster address verification. It includes setting up signers, signing the verification message, and constructing the final message to send to a Hub.

```typescript
import {
  NobleEd25519Signer,
  ViemLocalEip712Signer,
  FarcasterNetwork,
  makeVerificationAddEthAddress,
} from '@farcaster/hub-nodejs';
import { createPublicClient, http } from 'viem';
import { privateKeyToAccount } from 'viem/accounts';
import { optimism } from 'viem/chains';

const publicClient = createPublicClient({
  chain: optimism,
  transport: http(),
});

const alice = privateKeyToAccount('0xab..12');
const eip712Signer = new ViemLocalEip712Signer(alice);

const ed25519Signer = new NobleEd25519Signer('0xcd..34');

const latestBlock = await publicClient.getBlock();

const fid = 1n;
const network = FarcasterNetwork.MAINNET;
const address = alice.address;
const blockHash = latestBlock.blockhash;

const ethSignature = eip712Signer.signVerificationEthAddressClaim({
  fid,
  address,
  network,
  blockHash,
});

if (ethSignature.isOk()) {
  const message = await makeVerificationAddEthAddress(
    {
      address,
      blockHash,
      ethSignature,
    },
    { fid, network },
    ed25519Signer
  );
}
```

--------------------------------

### Example cURL for Fname Registration

Source: https://docs.farcaster.xyz/reference/fname/api

Provides an example of how to use `curl` to register or transfer an FName via a POST request to the `/transfers` endpoint. Includes necessary headers and a JSON payload.

```bash
curl -X POST https://fnames.farcaster.xyz/transfers \
  -H "Content-Type: application/json" \
  -d \
'{"name": "farcaster", "owner": "0x...", "signature": "0x...", "from": 0, "to": 1000, "timestamp": 1641234567, fid: 1000}'
```

--------------------------------

### Direct Cast Intents URL Examples - Bash

Source: https://docs.farcaster.xyz/reference/farcaster/direct-casts

Examples of direct cast intent URLs, demonstrated using bash syntax. These URLs allow developers to direct authenticated users to a pre-filled direct cast composer. The format includes the user's fid and the message text.

```bash
https://farcaster.xyz/~/inbox/create/[fid]?text=[message]
```

```bash
https://farcaster.xyz/~/inbox/create/1?text=gm
```

--------------------------------

### GET /fc/starter-pack-members

Source: https://docs.farcaster.xyz/reference/farcaster/api

Retrieves a paginated list of members for a specific starter pack. Members are ordered by the time they were added, descending.

```APIDOC
## GET /fc/starter-pack-members

### Description
Starter pack members. Ordered by the time when they were added to the pack, descending. Paginated. Not authenticated.

### Method
GET

### Endpoint
/fc/starter-pack-members

### Parameters
#### Query Parameters
- **id** (string) - Required - The starter pack ID, found in the public pack URL or metadata.

### Response
#### Success Response (200)
- **members** (array) - An array of members.
  - **fid** (integer) - Account Farcaster ID.
  - **memberAt** (integer) - Time when the member was added to the starter pack, in milliseconds.
- **next** (object) - Pagination information.
  - **cursor** (string) - Cursor for fetching the next page of results.

#### Response Example
```json
{
  "result": {
    "members": [
      {
        "fid": 3,
        "memberAt": 1740172669691
      },
      {
        "fid": 296646,
        "memberAt": 1740172669691
      }
    ]
  },
  "next": {
    "cursor": "..."
  }
}
```
```

--------------------------------

### Example: Get Channel Members (cURL)

Source: https://docs.farcaster.xyz/reference/farcaster/api

An example using cURL to retrieve members of the channel with ID 'memes' from the Farcaster API.

```bash
curl 'https://api.farcaster.xyz/fc/channel-members?channelId=memes'
```

--------------------------------

### Setup Viem Clients and Farcaster Account Keys (TypeScript)

Source: https://docs.farcaster.xyz/developers/guides/accounts/create-account

Initializes Viem clients for Optimism, sets up local Ethereum accounts for the app and a user (Alice), and creates Farcaster EIP-712 signers. Includes setting a signature deadline.

```typescript
import * as ed from '@noble/ed25519';
import {
  ID_GATEWAY_ADDRESS,
  ID_REGISTRY_ADDRESS,
  ViemLocalEip712Signer,
  idGatewayABI,
  idRegistryABI,
  NobleEd25519Signer,
  BUNDLER_ADDRESS,
  bundlerABI,
  KEY_GATEWAY_ADDRESS,
  keyGatewayABI,
} from '@farcaster/hub-nodejs';
import { bytesToHex, createPublicClient, createWalletClient, http } from 'viem';
import { privateKeyToAccount } from 'viem/accounts';
import { optimism } from 'viem/chains';

const APP_PRIVATE_KEY = '0x00';
const ALICE_PRIVATE_KEY = '0x00';

const publicClient = createPublicClient({
  chain: optimism,
  transport: http(),
});

const walletClient = createWalletClient({
  chain: optimism,
  transport: http(),
});

const app = privateKeyToAccount(APP_PRIVATE_KEY);
const appAccountKey = new ViemLocalEip712Signer(app as any);

const alice = privateKeyToAccount(ALICE_PRIVATE_KEY);
const aliceAccountKey = new ViemLocalEip712Signer(alice as any);

const deadline = BigInt(Math.floor(Date.now() / 1000) + 3600); // Set the signatures' deadline to 1 hour from now

const FARCASTER_RECOVERY_PROXY = '0x00000000FcB080a4D6c39a9354dA9EB9bC104cd7';

```

--------------------------------

### Setup Viem Clients and Farcaster Account Key (TypeScript)

Source: https://docs.farcaster.xyz/developers/guides/accounts/create-account-key

Initializes Viem clients for OP Mainnet and sets up Farcaster account keys using ViemLocalEip712Signer for local accounts. This step is crucial for interacting with Farcaster contracts and services. It defines constants for private keys, RPC transport, and chain configurations.

```typescript
import * as ed from '@noble/ed25519';
import {
  ID_GATEWAY_ADDRESS,
  ID_REGISTRY_ADDRESS,
  ViemLocalEip712Signer,
  idGatewayABI,
  idRegistryABI,
  NobleEd25519Signer,
  KEY_GATEWAY_ADDRESS,
  keyGatewayABI,
} from '@farcaster/hub-nodejs';
import { bytesToHex, createPublicClient, createWalletClient, http } from 'viem';
import { privateKeyToAccount } from 'viem/accounts';
import { optimism } from 'viem/chains';

const APP_PRIVATE_KEY = '0x00';
const ALICE_PRIVATE_KEY = '0x00';

const publicClient = createPublicClient({
  chain: optimism,
  transport: http(),
});

const walletClient = createWalletClient({
  chain: optimism,
  transport: http(),
});

const app = privateKeyToAccount(APP_PRIVATE_KEY);
const appAccountKey = new ViemLocalEip712Signer(app as any);

const alice = privateKeyToAccount(ALICE_PRIVATE_KEY);
const aliceAccountKey = new ViemLocalEip712Signer(alice as any);

const deadline = BigInt(Math.floor(Date.now() / 1000) + 3600); // Set the signatures' deadline to 1 hour from now

const FARCASTER_RECOVERY_PROXY = '0x00000000FcB080a4D6c39a9354dA9EB9bC104cd7';

```

--------------------------------

### Example: Get User Following Channel Status (cURL)

Source: https://docs.farcaster.xyz/reference/farcaster/api

An example using cURL to check if a user with FID '3' is following the channel with ID 'books' on the Farcaster API.

```bash
curl 'https://api.farcaster.xyz/v1/user-channel?fid=3&channelId=books'
```

--------------------------------

### Get Blocked Users (Bash)

Source: https://docs.farcaster.xyz/reference/farcaster/api

Retrieves a list of blocked users from the Farcaster API. This example shows a simple GET request to the `fc/blocked-users` endpoint without any specific filtering.

```bash
curl 'https://api.farcaster.xyz/fc/blocked-users'
```

--------------------------------

### Auth Client - Create Client

Source: https://docs.farcaster.xyz/auth-kit/client/introduction

Demonstrates how to set up an AppClient with a relay server URL and an Ethereum connector. This client is used for building connected applications and logging in users.

```APIDOC
## Create a client

Set up a client with a relay server URL and Ethereum connector.

```tsx
import { createAppClient, viemConnector } from '@farcaster/auth-client';

const appClient = createAppClient({
  relay: 'https://relay.farcaster.xyz',
  ethereum: viemConnector(),
});
```

**Note:** Depending on the type of app you're building, you may use an `AppClient` or a `WalletClient`. If you're building a connected app and logging in users, use an _app client_. If you're building a Farcaster wallet app, use a _wallet client_.
```

--------------------------------

### Viem Client and Account Setup (TypeScript)

Source: https://docs.farcaster.xyz/reference/contracts/reference/id-gateway

Sets up Viem clients for interacting with the Ethereum blockchain, specifically the Optimism network. It configures both a public client for read operations and a wallet client for signing transactions, supporting both browser-based wallets (like MetaMask) and local accounts derived from private keys.

```typescript
import { createWalletClient, createPublicClient, custom, http } from 'viem';
import { privateKeyToAccount } from 'viem/accounts';
import { optimism } from 'viem/chains';

export const publicClient = createPublicClient({
  chain: optimism,
  transport: http(),
});

export const walletClient = createWalletClient({
  chain: optimism,
  transport: custom(window.ethereum),
});

// JSON-RPC Account
export const [account] = await walletClient.getAddresses();

// Local Account
export const account = privateKeyToAccount('0x...');

```

--------------------------------

### Sign Add with ViemWalletEip712Signer

Source: https://docs.farcaster.xyz/reference/contracts/reference/key-gateway

Demonstrates signing an 'Add' operation using ViemWalletEip712Signer from the '@farcaster/hub-web' library. It requires wallet client, account, public key, metadata, nonce, and deadline.

```typescript
import { ViemWalletEip712Signer } from '@farcaster/hub-web';
import { walletClient, account } from './clients.ts';
import { getPublicKey } from './signer.ts';
import { readNonce, getDeadline } from './helpers.ts';

const publicKey = await getPublicKey();
const metadata = await getMetadata();
const nonce = await readNonce();
const deadline = getDeadline();

const eip712Signer = new ViemWalletEip712Signer(walletClient);
const signature = await eip712signer.signAdd({
  owner: account,
  keyType: 1,
  key: publicKey,
  metadataType: 1,
  metadata,
  nonce,
  deadline,
});

```

--------------------------------

### Get Single User Primary Address (curl)

Source: https://docs.farcaster.xyz/reference/farcaster/api

Example using curl to fetch the primary address for a specific Farcaster ID (FID) and protocol. Demonstrates how to make a GET request to the API endpoint.

```bash
curl 'https://api.farcaster.xyz/fc/primary-address?fid=12152&protocol=ethereum'
```

--------------------------------

### Setup Farcaster Hub Node.js Client

Source: https://docs.farcaster.xyz/developers/guides/writing/messages

Initializes the Farcaster hub-nodejs client with necessary credentials and network configuration. Requires a private key and FID for signing messages. Essential for all message creation operations.

```typescript
import {
  makeCastAdd,
  makeCastRemove,
  makeLinkAdd,
  makeLinkRemove,
  makeReactionAdd,
  makeReactionRemove,
  makeUserDataAdd,
  NobleEd25519Signer,
  FarcasterNetwork,
} from '@farcaster/hub-nodejs';

const ACCOUNT_PRIVATE_KEY: Hex = '0x...'; // Your account key's private key
const FID = -1; // Your fid
const ed25519Signer = new NobleEd25519Signer(ACCOUNT_PRIVATE_KEY);
const dataOptions = {
  fid: FID,
  network: FC_NETWORK,
};
const FC_NETWORK = FarcasterNetwork.MAINNET;
```

--------------------------------

### Get Multiple User Primary Addresses (curl)

Source: https://docs.farcaster.xyz/reference/farcaster/api

Example using curl to retrieve primary addresses for a list of Farcaster IDs (FIDs) and a specified protocol. Demonstrates batch fetching via a GET request.

```bash
curl 'https://api.farcaster.xyz/fc/primary-addresses?fids=12152,2,1315,39939393939&protocol=ethereum'
```

--------------------------------

### Get Single User Primary Address (JSON Response)

Source: https://docs.farcaster.xyz/reference/farcaster/api

Example JSON response structure for the 'Get User Primary Address' API endpoint. It includes the requested FID, protocol, and the resolved primary address.

```json
{
  "result": {
    "address": {
      "fid": 12152,
      "protocol": "ethereum",
      "address": "0x0BD6b1DFE1eA61C2b487806ECd06b5A95383a4e3"
    }
  }
}
```

--------------------------------

### Auth Client - Consume Actions

Source: https://docs.farcaster.xyz/auth-kit/client/introduction

Shows how to consume Farcaster Auth actions using the configured AppClient, including creating a channel token and watching the status of the authentication process.

```APIDOC
## Consume actions

Now that your client is set up, you can use it to interact with Farcaster Auth actions.

```tsx
const { data: { channelToken } } = await appClient.createChannel({
    siweUri: "https://example.com/login",
    domain: "example.com";
});

const status = await appClient.watchStatus({
    channelToken,
});
```
```

--------------------------------

### Get Multiple User Primary Addresses (JSON Response)

Source: https://docs.farcaster.xyz/reference/farcaster/api

Example JSON response for the 'Get Multiple User Primary Addresses' endpoint. It returns an array where each object indicates the success status and the primary address details for each requested FID.

```json
{
  "result": {
    "addresses": [
      {
        "fid": 12152,
        "success": true,
        "address": {
          "fid": 12152,
          "protocol": "ethereum",
          "address": "0x0BD6b1DFE1eA61C2b487806ECd06b5A95383a4e3"
        }
      },
      {
        "fid": 2,
        "success": true,
        "address": {
          "fid": 2,
          "protocol": "ethereum",
          "address": "0x661E2209B9C6B06C1F32A0639f60D3294185ab35"
        }
      },
      {
        "fid": 1315,
        "success": true,
        "address": {
          "fid": 1315,
          "protocol": "ethereum",
          "address": "0x0450a8545028547Df4129Aa5b4EC5794D5aF2409"
        }
      },
      {
        "fid": 39939393939,
        "success": false
      }
    ]
  }
}
```

--------------------------------

### Farcaster Auth Client Actions: Create Channel and Watch Status

Source: https://docs.farcaster.xyz/auth-kit/client/introduction

Demonstrates using the Farcaster `AppClient` to perform authentication actions. It includes creating a channel with a SIWE URI and domain, and then watching the status of that channel using the obtained channel token.

```typescript
const { data: { channelToken } } = await appClient.createChannel({
    siweUri: "https://example.com/login",
    domain: "example.com";
});

const status = await appClient.watchStatus({
    channelToken,
});

```

--------------------------------

### Viem Client Setup for OP Mainnet (TypeScript)

Source: https://docs.farcaster.xyz/developers/guides/accounts/change-custody

This snippet sets up `publicClient` and `walletClient` for interacting with the Optimism (OP) Mainnet using the `viem` library. It demonstrates creating both a public client (for reading data) and a wallet client (for signing transactions), connecting to the Optimism chain via HTTP and `window.ethereum` respectively. It also shows how to derive an account from `window.ethereum` and optionally how to create an account from a private key.

```typescript
import { createWalletClient, createPublicClient, custom, http } from 'viem';
import { privateKeyToAccount } from 'viem/accounts';
import { optimism } from 'viem/chains';

export const publicClient = createPublicClient({
  chain: optimism,
  transport: http(),
});

export const walletClient = createWalletClient({
  chain: optimism,
  transport: custom(window.ethereum),
});

// JSON-RPC Account
export const [account] = await walletClient.getAddresses();

// Local Account
export const account = privateKeyToAccount('0x...');
```

--------------------------------

### Get Farcaster Actions (Bash)

Source: https://docs.farcaster.xyz/reference/farcaster/api

Fetches a list of Farcaster actions, specifically requesting the 'top' list with a limit of 10 items. This command-line example demonstrates how to query the `discover-actions` endpoint.

```bash
curl 'https://api.farcaster.xyz/v2/discover-actions?list=top&limit=10'
```

--------------------------------

### Add Account Key to Key Registry (TypeScript)

Source: https://docs.farcaster.xyz/developers/guides/basics/hello-world

This function adds an account key to the key registry. It requires a signed metadata field from the app's FID. If an account key private key is already provided, it assumes the key is registered. Otherwise, it generates a new private key, signs the metadata, and adds the key to the registry. It returns the private key of the account key.

```typescript
const getOrRegisterAccountKey = async (fid: number) => {
  if (ACCOUNT_KEY_PRIVATE_KEY !== zeroAddress) {
    const privateKeyBytes = fromHex(ACCOUNT_KEY_PRIVATE_KEY, 'bytes');
    const publicKeyBytes = ed25519.getPublicKey(privateKeyBytes);
    return privateKeyBytes;
  }

  const privateKey = ed25519.utils.randomPrivateKey();
  const publicKey = toHex(ed25519.getPublicKey(privateKey));

  const eip712signer = new ViemLocalEip712Signer(appAccount);
  const metadata = await eip712signer.getSignedKeyRequestMetadata({
    requestFid: APP_FID,
    key: APP_PRIVATE_KEY,
    deadline: Math.floor(Date.now() / 1000) + 60 * 60, 
  });

  const { request: signerAddRequest } = await walletClient.simulateContract({
    ...KeyContract,
    functionName: 'add',
    args: [1, publicKey, 1, metadata], 
  });

  const accountKeyAddTxHash = await walletClient.writeContract(
    signerAddRequest
  );
  await walletClient.waitForTransactionReceipt({ hash: accountKeyAddTxHash });
  await new Promise((resolve) => setTimeout(resolve, 30000));
  return privateKey;
};

const accountPrivateKey = await getOrRegisterAccountKey(fid);
```

--------------------------------

### Fetch Profile using gRPC API Console (Bash)

Source: https://docs.farcaster.xyz/developers/guides/querying/fetch-profile

Fetches user profile data using the gRPC API through the `console` utility within the hub-monorepo. This method requires the hub-monorepo to be installed from source. Ensure you are in the `apps/hubble` directory and connect to the specified host and port. The `--insecure` flag should be removed if the host uses TLS.

```bash
# Ensure you are in the hubble sub directory
$ cd apps/hubble
# Remove `--insecure` if the host is using TLS
$ yarn console --insecure -s localhost:3383
> res = await rpcClient.getUserDataByFid({fid: 1})
Ok { value: { messages: [ [Object], [Object], [Object], [Object] ], nextPageToken: <Buffer > } }
> res.value.messages.map(m => m.data.userDataBody)
[ { type: 1, value: 'https://i.imgur.com/I2rEbPF.png' }, { type: 3, value: 'A sufficiently decentralized social network. farcaster.xyz' }, { type: 2, value: 'Farcaster' }, { type: 6, value: 'farcaster' } ]
```

--------------------------------

### Farcaster Id Registry Contract Setup (TypeScript)

Source: https://docs.farcaster.xyz/developers/guides/accounts/change-recovery

This code defines the Farcaster Id Registry contract details and client configurations for interacting with OP Mainnet. It includes ABI, gateway address, and chain information, along with examples for creating Viem public and wallet clients using both JSON-RPC and local accounts. These clients are essential for blockchain interactions.

```typescript
import {
  ID_REGISTRY_EIP_712_TYPES,
  idRegistryABI,
  ID_GATEWAY_ADDRESS,
} from '@farcaster/hub-web';
import { walletClient, account } from './clients.ts';

const IdContract = {
  abi: idRegistryABI,
  address: ID_GATEWAY_ADDRESS,
  chain: optimism,
};

import { createWalletClient, createPublicClient, custom, http } from 'viem';
import { privateKeyToAccount } from 'viem/accounts';
import { optimism } from 'viem/chains';

export const publicClient = createPublicClient({
  chain: optimism,
  transport: http(),
});

export const walletClient = createWalletClient({
  chain: optimism,
  transport: custom(window.ethereum),
});

// JSON-RPC Account
export const [account] = await walletClient.getAddresses();

// Local Account
export const account = privateKeyToAccount('0x...');
```

--------------------------------

### Setup Clients and Account Keys for Farcaster Verification (TypeScript)

Source: https://docs.farcaster.xyz/developers/guides/writing/verify-address

Initializes clients and account keys required for Farcaster address verification. It sets up Viem for Ethereum interaction and Farcaster specific signers. Dependencies include '@farcaster/hub-nodejs' and 'viem'.

```typescript
import {
  NobleEd25519Signer,
  ViemLocalEip712Signer,
  FarcasterNetwork,
  makeVerificationAddEthAddress,
} from '@farcaster/hub-nodejs';
import { createPublicClient, http } from 'viem';
import { privateKeyToAccount } from 'viem/accounts';
import { optimism } from 'viem/chains';

const publicClient = createPublicClient({
  chain: optimism,
  transport: http(),
});

const alice = privateKeyToAccount('0xab..12');
const eip712Signer = new ViemLocalEip712Signer(alice);

const ed25519Signer = new NobleEd25519Signer('0xcd..34');
```

--------------------------------

### Farcaster Hub Web TypeScript Setup and FID Registration

Source: https://docs.farcaster.xyz/developers/guides/accounts/create-account-key

This snippet sets up Viem clients, local accounts for an app and a user (Alice), and generates necessary constants like deadlines and Farcaster addresses. It then proceeds to register an application-specific FID (Frame ID) by interacting with the IdGateway contract.

```typescript
import * as ed from '@noble/ed25519';
import {
  ID_GATEWAY_ADDRESS,
  ID_REGISTRY_ADDRESS,
  ViemLocalEip712Signer,
  idGatewayABI,
  idRegistryABI,
  NobleEd25519Signer,
  KEY_GATEWAY_ADDRESS,
  keyGatewayABI,
} from '@farcaster/hub-nodejs';
import { bytesToHex, createPublicClient, createWalletClient, http } from 'viem';
import { privateKeyToAccount } from 'viem/accounts';
import { optimism } from 'viem/chains';

const APP_PRIVATE_KEY = '0x00';
const ALICE_PRIVATE_KEY = '0x00';

/*******************************************************************************
 * Setup - Create local accounts, Viem clients, helpers, and constants.
 *******************************************************************************/

/**
 * Create Viem public (read) and wallet (write) clients.
 */
const publicClient = createPublicClient({
  chain: optimism,
  transport: http(),
});

const walletClient = createWalletClient({
  chain: optimism,
  transport: http(),
});

/**
 * A local account representing your app. You'll
 * use this to sign key metadata and send
 * transactions on behalf of users.
 */
const app = privateKeyToAccount(APP_PRIVATE_KEY);
const appAccountKey = new ViemLocalEip712Signer(app as any);
console.log('App:', app.address);

/**
 * A local account representing Alice, a user.
 */
const alice = privateKeyToAccount(ALICE_PRIVATE_KEY);
const aliceAccountKey = new ViemLocalEip712Signer(alice as any);
console.log('Alice:', alice.address);

/**
 * Generate a deadline timestamp one hour from now.
 * All Farcaster EIP-712 signatures include a deadline, a block timestamp
 * after which the signature is no longer valid.
 */
const deadline = BigInt(Math.floor(Date.now() / 1000) + 3600); // Set the signatures' deadline to 1 hour from now

const FARCASTER_RECOVERY_PROXY = '0x00000000FcB080a4D6c39a9354dA9EB9bC104cd7';

/*******************************************************************************
 * IdGateway - register - Register an app FID.
 *******************************************************************************/

/**
 *  Get the current price to register. We're not going to register any
 *  extra storage, so we pass 0n as the only argument.
 */
const price = await publicClient.readContract({
  address: ID_GATEWAY_ADDRESS,
  abi: idGatewayABI,
  functionName: 'price',
  args: [0n],
});

/**
 *  Call `register` to register an FID to the app account.
 */
const { request } = await publicClient.simulateContract({
  account: app,
  address: ID_GATEWAY_ADDRESS,
  abi: idGatewayABI,
  functionName: 'register',
  args: [FARCASTER_RECOVERY_PROXY, 0n],
  value: price,
});
await walletClient.writeContract(request);

/**
 *  Read the app FID from the Id Registry contract.
 */
const APP_FID = await publicClient.readContract({
  address: ID_REGISTRY_ADDRESS,
  abi: idRegistryABI,
  functionName: 'idOf',
  args: [app.address],
});

```

--------------------------------

### GET /v2/all-channels - Get All Channels

Source: https://docs.farcaster.xyz/reference/farcaster/api

Retrieves a list of all available Farcaster channels. This endpoint is not paginated and does not require authentication.

```APIDOC
## GET /v2/all-channels

### Description
List all channels. No parameters. Not paginated. Not authenticated.

### Method
GET

### Endpoint
/v2/all-channels

### Parameters
None

### Request Example
```bash
curl 'https://api.farcaster.xyz/v2/all-channels'
```

### Response
#### Success Response (200)
- **channels** (array) - An array of channel objects. Each channel object contains the following properties:
  - **id** (string) - Unique channel ID.
  - **url** (string) - FIP-2 `parentUrl` for main casts.
  - **name** (string) - User-facing channel name.
  - **description** (string, optional) - Description of the channel.
  - **descriptionMentions** (array<integer>, optional) - Array of user FIDs mentioned in the description.
  - **descriptionMentionsPositions** (array<integer>, optional) - Array of indexes within the description where mentions appear.
  - **leadFid** (integer, optional) - FID of the channel creator.
  - **moderatorFids** (array<integer>, optional) - FIDs of channel moderators.
  - **createdAt** (integer) - UNIX timestamp of channel creation.
  - **followerCount** (integer) - Number of users following the channel.
  - **memberCount** (integer) - Number of channel members.
  - **pinnedCastHash** (string, optional) - Hash of the pinned cast.
  - **publicCasting** (boolean) - Indicates if public casting is enabled.
  - **externalLink** (object, optional) - An external link object with `title` and `url` properties.

#### Response Example
```json
{
  "result": {
    "channels": [
      {
        "id": "illustrations",
        "url": "https://farcaster.xyz/~/channel/illustrations",
        "name": "illustrations",
        "description": "Share your wips, sketches, arts, drops, GMs, artworks you adore or collected — all content related to illustration, tag  to join ⊹ ࣪ ˖ cover by ",
        "descriptionMentions": [
          367850,
          335503
        ],
        "descriptionMentionsPositions": [
          122,
          151
        ],
        "imageUrl": "https://imagedelivery.net/BXluQx4ige9GuW0Ia56BHw/7721c951-b0ed-44ee-aa9c-c31507b69c00/original",
        "headerImageUrl": "https://imagedelivery.net/BXluQx4ige9GuW0Ia56BHw/64efe955-c3ab-4aad-969d-1aed978a3e00/original",
        "leadFid": 367850,
        "moderatorFids": [
          367850
        ],
        "createdAt": 1709753166,
        "followerCount": 2361,
        "memberCount": 300,
        "pinnedCastHash": "0x3ef52987ccacd89af096a753c07efcd55a93e143",
        "publicCasting": false,
        "externalLink": {
          "title": "/creatorssupport",
          "url": "https://farcaster.xyz/~/channel/creators-support"
        }
      }
    ]
  }
}
```
```

--------------------------------

### Initialize Farcaster App Client (TypeScript)

Source: https://docs.farcaster.xyz/auth-kit/client/app/client

Demonstrates how to initialize the AppClient using the `@farcaster/auth-client` library. It requires an Ethereum connector and optionally accepts a relay server URL and authentication version. The example uses the `viemConnector` for Ethereum interaction.

```typescript
import { createAppClient, viemConnector } from '@farcaster/auth-client';

const appClient = createAppClient({
  relay: 'https://relay.farcaster.xyz',
  ethereum: viemConnector(),
});
```

--------------------------------

### GET /v1/channel - Get a Channel

Source: https://docs.farcaster.xyz/reference/farcaster/api

Retrieves details for a specific Farcaster channel using its ID. This endpoint does not require authentication.

```APIDOC
## GET /v1/channel

### Description
Get a single channel. Not authenticated.

### Method
GET

### Endpoint
/v1/channel

### Parameters
#### Query Parameters
- **channelId** (string) - Required - The ID of the channel to retrieve.

### Request Example
```bash
curl 'https://api.farcaster.xyz/v1/channel?channelId=illustrations'
```

### Response
#### Success Response (200)
- **channel** (object) - A single channel object, with the same properties as documented in the 'Get All Channels' endpoint.

#### Response Example
```json
{
  "result": {
    "channel": {
      "id": "illustrations",
      "url": "https://farcaster.xyz/~/channel/illustrations",
      "name": "illustrations",
      "description": "Share your wips, sketches, arts, drops, GMs, artworks you adore or collected — all content related to illustration, tag  to join ⊹ ࣪ ˖ cover by ",
      "descriptionMentions": [
        367850,
        335503
      ],
      "descriptionMentionsPositions": [
        122,
        151
      ],
      "imageUrl": "https://imagedelivery.net/BXluQx4ige9GuW0Ia56BHw/7721c951-b0ed-44ee-aa9c-c31507b69c00/original",
      "headerImageUrl": "https://imagedelivery.net/BXluQx4ige9GuW0Ia56BHw/64efe955-c3ab-4aad-969d-1aed978a3e00/original",
      "leadFid": 367850,
      "moderatorFids": [
        367850
      ],
      "createdAt": 1709753166,
      "followerCount": 2361,
      "memberCount": 300,
      "pinnedCastHash": "0x3ef52987ccacd89af096a753c07efcd55a93e143",
      "publicCasting": false,
      "externalLink": {
        "title": "/creatorssupport",
        "url": "https://farcaster.xyz/~/channel/creators-support"
      }
    }
  }
}
```
```

--------------------------------

### Register Farcaster FID and Pay for Storage in TypeScript

Source: https://docs.farcaster.xyz/developers/guides/basics/hello-world

Implements a function to register a Farcaster ID (FID) and pay for necessary storage. It checks for an existing FID and ensures sufficient balance before initiating the registration transaction. Requires connected wallet client and defined Farcaster contracts.

```typescript
const getOrRegisterFid = async (): Promise<number> => {
  const balance = await walletClient.getBalance({ address: account.address });
  // Check if we already have an fid
  const existingFid = (await walletClient.readContract({
    ...IdContract,
    functionName: 'idOf',
    args: [account.address],
  })) as bigint;

  if (existingFid > 0n) {
    return parseInt(existingFid.toString());
  }

  const price = await walletClient.readContract({
    ...IdGateway,
    functionName: 'price',
  });
  if (balance < price) {
    throw new Error(
      `Insufficient balance to rent storage, required: ${price}, balance: ${balance}`
    );
  }
  const { request: registerRequest } = await walletClient.simulateContract({
    ...IdGateway,
    functionName: 'register',
    args: [RECOVERY_ADDRESS],
    value: price,
  });
  const registerTxHash = await walletClient.writeContract(registerRequest);
  const registerTxReceipt = await walletClient.waitForTransactionReceipt({
    hash: registerTxHash,
  });
  // Now extract the FID from the logs
  const registerLog = decodeEventLog({
    abi: idRegistryABI,
    data: registerTxReceipt.logs[0].data,
    topics: registerTxReceipt.logs[0].topics,
  });
  const fid = parseInt(registerLog.args['id']);
  return fid;
};

const fid = await getOrRegisterFid();
```

--------------------------------

### GET /v1/channel-followers - Get Channel Followers

Source: https://docs.farcaster.xyz/reference/farcaster/api

Retrieves a list of users who follow a specific Farcaster channel. The list is ordered by follow time (descending) and supports pagination. This endpoint does not require authentication.

```APIDOC
## GET /v1/channel-followers

### Description
List the followers of a channel. Ordered by the time when the channel was followed, descending. Paginated. Not authenticated.

### Method
GET

### Endpoint
/v1/channel-followers

### Parameters
#### Query Parameters
- **channelId** (string) - Required - The ID of the channel for which to retrieve followers.

### Request Example
```bash
curl 'https://api.farcaster.xyz/v1/channel-followers?channelId=books'
```

### Response
#### Success Response (200)
- **users** (array) - An array of user objects. Each user object contains:
  - **fid** (integer) - The FID of the user.
  - **followedAt** (integer) - UNIX timestamp of when the user followed the channel.
- **next** (object, optional) - Pagination information, containing a `cursor` property for fetching the next page.

#### Response Example
```json
{
  "result": {
    "users": [
      {
        "fid": 466624,
        "followedAt": 1712685183
      },
      {
        "fid": 469283,
        "followedAt": 1712685067
      }
    ]
  },
  "next": {
    "cursor": "..."
  }
}
```
```

--------------------------------

### Create Farcaster Auth Client Instance

Source: https://docs.farcaster.xyz/auth-kit/client/introduction

Initializes an `AppClient` for Farcaster authentication. Requires a relay server URL and an Ethereum connector, provided here using `viemConnector`. This client is suitable for connected applications managing user logins.

```typescript
import { createAppClient, viemConnector } from '@farcaster/auth-client';

const appClient = createAppClient({
  relay: 'https://relay.farcaster.xyz',
  ethereum: viemConnector(),
});

```

--------------------------------

### Get Account Profile

Source: https://docs.farcaster.xyz/developers/guides/querying/fetch-profile

This endpoint allows you to fetch profile details for a given user ID (fid). It returns various user data types such as profile picture, bio, display name, and username.

```APIDOC
## GET /v1/userDataByFid

### Description
Fetches profile details for a specific user identified by their FID.

### Method
GET

### Endpoint
`/v1/userDataByFid`

### Parameters
#### Query Parameters
- **fid** (integer) - Required - The user ID (Fid) for which to fetch profile data.

### Request Example
```bash
curl "http://localhost:3381/v1/userDataByFid?fid=1"
```

### Response
#### Success Response (200)
- **messages** (array) - An array of user data messages.
  - **data** (object)
    - **userDataBody** (object)
      - **type** (string) - The type of user data (e.g., USER_DATA_TYPE_PFP, USER_DATA_TYPE_BIO).
      - **value** (string) - The corresponding value for the user data type.

#### Response Example
```json
{
  "messages": [
    {
      "data": {
        "userDataBody": {
          "type": "USER_DATA_TYPE_PFP",
          "value": "https://i.imgur.com/I2rEbPF.png"
        }
      }
    },
    {
      "data": {
        "userDataBody": {
          "type": "USER_DATA_TYPE_BIO",
          "value": "A sufficiently decentralized social network. farcaster.xyz"
        }
      }
    },
    {
      "data": {
        "userDataBody": {
          "type": "USER_DATA_TYPE_DISPLAY",
          "value": "Farcaster"
        }
      }
    },
    {
      "data": {
        "userDataBody": {
          "type": "USER_DATA_TYPE_USERNAME",
          "value": "farcaster"
        }
      }
    }
  ]
}
```
```

--------------------------------

### Initialize Farcaster Wallet Client with Viem

Source: https://docs.farcaster.xyz/auth-kit/client/wallet/client

This snippet demonstrates how to create a WalletClient instance using the '@farcaster/auth-client' library and the viem connector. It's essential for applications that need to interact with Farcaster for authentication and signature requests. The client requires an Ethereum connector and can optionally be configured with a custom relay URL.

```typescript
import { createWalletClient, viemConnector } from '@farcaster/auth-client';

const walletClient = createWalletClient({
  relay: 'https://relay.farcaster.xyz',
  ethereum: viemConnector(),
});
```

--------------------------------

### Get a Specific Channel API Request

Source: https://docs.farcaster.xyz/reference/farcaster/api

This endpoint allows you to retrieve information for a single Farcaster channel by providing its unique ID. The response mirrors the structure of individual channel objects found in the 'Get All Channels' endpoint.

```bash
curl 'https://api.farcaster.xyz/v1/channel?channelId=illustrations'
```

--------------------------------

### Register Fname using Farcaster Offchain Registry (TypeScript)

Source: https://docs.farcaster.xyz/developers/guides/basics/hello-world

This function registers an Fname for a given FID using the Farcaster offchain Fname registry. It first checks if the FID already has an Fname. If not, it constructs an Fname based on the FID, generates a signature for the username proof, and posts the registration request to the Farcaster Fnames API. It returns the registered Fname.

```typescript
const registerFname = async (fid: number) => {
  try {
    const response = await axios.get(
      `https://fnames.farcaster.xyz/transfers/current?fid=${fid}`
    );
    const fname = response.data.transfer.username;
    return fname;
  } catch (e) {
    
  }

  const fname = `fid-${fid}`;
  const timestamp = Math.floor(Date.now() / 1000);
  const userNameProofSignature = await walletClient.signTypedData({
    domain: USERNAME_PROOF_DOMAIN,
    types: USERNAME_PROOF_TYPE,
    primaryType: 'UserNameProof',
    message: {
      name: fname,
      timestamp: BigInt(timestamp),
      owner: account.address,
    },
  });

  const response = await axios.post('https://fnames.farcaster.xyz/transfers', {
    name: fname, 
    from: 0, 
    to: fid, 
    fid: fid, 
    owner: account.address, 
    timestamp: timestamp, 
    signature: userNameProofSignature, 
  });
  return fname;
};

const fname = await registerFname(fid);
```
Tokens:
Raw