Farcaster Reference

https://docs.farcaster.xyz/reference/
Admin
Farcaster Reference documents the APIs, standards, and protocols for Farcaster developers, covering...
Tokens:47,759
Snippets:203
Trust Score:9.3
Update:11 months ago
Show doc for...
Tokens:
Raw
### Get Developer Reward Winners - JSON/Bash

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

Provides the history of developer reward winners for a given period (week), paginated in rank order, refreshed every Wednesday at 17:00 UTC. No authentication required. The JSON example demonstrates the response structure with period timestamps and winners list including fid, domain, frame name, score, rank, and reward details. The Bash example includes a curl command to query the endpoint with optional periodsAgo parameter. Limitations include weekly data refresh and potential missing wallet addresses for unverified users.

```json
{
  "result": {
    "periodStartTimestamp": 1738080000000,
    "periodEndTimestamp": 1738684800000,
    "winners": [
      {
        "fid": 1,
        "domain": "example.com",
        "frameName": "App Name",
        "score": 10,
        "rank": 1,
        "rewardCents": 1000,
        "walletAddress": "0x0000000000000000000000000000000000000000",
      },
      {
        "fid": 420,
        "domain": "example.com",
        "frameName": "App Name",
        "score": 1,
        "rank": 2,
        "rewardCents": 500,
        "walletAddress": "0x0000000000000000000000000000000000000001",
      },
      ...
    ]
  },
  "next": { "cursor": "..." }
}
```

```bash
curl 'https://api.farcaster.xyz/v1/developer-rewards-winner-history'
```

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

### GET /key_registry/keysOf

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

Lists all public keys for a specific Farcaster ID (fid).  Use pagination with `startIdx` and `batchSize`.

```APIDOC
## GET /key_registry/keysOf

### Description
Lists all public keys for a specific Farcaster ID (fid). Use pagination with `startIdx` and `batchSize`.

### Method
GET

### Endpoint
/key_registry/keysOf

### Parameters
#### Path Parameters
- **fid** (uint256) - Required - Farcaster ID to look up.
#### Query Parameters
- **state** (uint8) - Required - State of the key (1 for Added, 2 for Removed).
- **startIdx** (uint256) - Optional - Start index for pagination.
- **batchSize** (uint256) - Optional - Batch size for pagination.

### Request Example
No request body.

### Response
#### Success Response (200)
- **keys** (bytes[]) - An array of public keys.

#### Response Example
{
  "keys": ["0x...", "0x..."]
}

**WARNING:** Don't call this onchain! This function is very gas intensive. It's meant to be called by offchain tools, not by other contracts.
```

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

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

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

Retrieves a paginated list of members for a specific starter pack. Members are ordered by their addition time to the pack in descending order.

```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 starter pack metadata.

### Response
#### Success Response (200)
- **members** (array) - An array of starter pack 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": "..."
  }
}
```
```

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

### List Account Verifications - JSON/Bash

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

Fetches a list of account verifications attested by the Farcaster client, ordered by verification time in descending order and paginated. Requires no authentication. The JSON example shows the response structure with verifications array including fid, platform details, and timestamps. The Bash example demonstrates a curl command to query the endpoint with optional fid and platform parameters. Limitations include beta status with potential breaking changes and default platform of 'x'.

```json
{
  "result": {
    "verifications": [
      {
        "fid": 3,
        "platform": "x",
        "platformId": "9615352",
        "platformUsername": "dwr",
        "verifiedAt": 1728505748
      },
      {
        "fid": 3,
        "platform": "github",
        "platformId": "86492",
        "platformUsername": "danromero",
        "verifiedAt": 1728505748
      },
      ...
    ]
  },
  "next": { "cursor": "..." }
}
```

```bash
curl 'https://api.farcaster.xyz/fc/account-verifications'
```

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

### GET /v2/discover-actions

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

Retrieve a paginated list of Farcaster actions. The endpoint is public and does not require authentication.

```APIDOC
## GET /v2/discover-actions

### Description
Retrieve a list of Farcaster actions. The results are paginated and the endpoint does not require authentication.

### Method
GET

### Endpoint
/v2/discover-actions

### Parameters
#### Query Parameters
- **list** (string) - Required - The list to retrieve. Must be `'top'` to get actions ordered by total users.\n### Request Example
```bash
curl 'https://api.farcaster.xyz/v2/discover-actions?list=top&limit=10'
```

### Response
#### Success Response (200)
- **actions** (array) - List of action objects with the following fields:
  - **name** (string) - Action name.
  - **icon** (string) - Octicon identifying the action.
  - **description** (string) - Short description of the action.
  - **aboutUrl** (string) - External link for additional instructions or source code.
  - **actionUrl** (string) - URL to retrieve action metadata.
  - **action.actionType** (string) - Action type, only `'post'`.
  - **action.postUrl** (string) - URL to POST signed for the action.

### Response Example
```json
{
  "result": {
    "actions": [
      {
        "name": "Upthumb",
        "icon": "thumbsup",
        "description": "Give casts 'upthumbs' and see them on a leaderboard.",
        "aboutUrl": "https://github.com/horsefacts/upthumbs",
        "actionUrl": "https://upthumbs.app/api/upthumb",
        "action": {
          "actionType": "post",
          "postUrl": "https://upthumbs.app/api/upthumb"
        }
      }
    ]
  },
  "next": { "cursor": "..." }
}
```
```

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

### Get Farcaster Actions (GET /v2/discover-actions)

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

Retrieves a paginated list of Farcaster actions, ordered by total users. This endpoint does not require authentication and accepts a `list` query parameter, typically set to 'top'.

```json
{
  "result": {
    "actions": [
      {
        "name": "Upthumb",
        "icon": "thumbsup",
        "description": "Give casts 'upthumbs' and see them on a leaderboard.",
        "aboutUrl": "https://github.com/horsefacts/upthumbs",
        "actionUrl": "https://upthumbs.app/api/upthumb",
        "action": {
          "actionType": "post",
          "postUrl": "https://upthumbs.app/api/upthumb"
        }
      },
      ...
    ]
  },
  "next": { "cursor": "..." }
}
```

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

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

### GET /v1/user-following-channels

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

Lists all channels a user is following, ordered by follow time (descending). This endpoint is paginated and does not require authentication.

```APIDOC
## GET /v1/user-following-channels

### Description
List all channels a user is following. Ordered by the time when the channel was followed, descending. Paginated. Not authenticated.

### Method
GET

### Endpoint
/v1/user-following-channels

#### Query Parameters
- **fid** (integer) - Required - The fid of the user

### Response
#### Success Response (200)
- **channels** (array) - An array of channel objects, each with properties like id, url, name, description, imageUrl, leadFid, moderatorFid, moderatorFids, createdAt, followerCount, and followedAt.
- **next** (object) - Contains cursor for pagination.

#### Response Example
```json
{
  "result": {
    "channels": [
      {
        "id": "fc-updates",
        "url": "https://farcaster.xyz/~/channel/fc-updates",
        "name": "fc-updates",
        "description": "Important updates about things happening in Farcaster",
        "imageUrl": "https://i.imgur.com/YnnrPaH.png",
        "leadFid": 2,
        "moderatorFid": 5448,
        "moderatorFids": [
          5448,
          3
        ],
        "createdAt": 1712162074,
        "followerCount": 17034,
        "followedAt": 1712162620
      }
    ]
  },
  "next": { "cursor": "..." }
}
```
```

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

### GET /key-gateway/nonces

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

Retrieves the next available nonce for a given address. This nonce is used for generating EIP-712 signatures when adding keys.

```APIDOC
## GET /key-gateway/nonces

### Description
Returns the next available nonce for an address. Used for generating EIP-712 signatures in addFor.

### Method
GET

### Endpoint
/key-gateway/nonces

### Parameters
#### Query Parameters
- **owner** (address) - Required - The address to query the nonce for

### Response
#### Success Response (200)
- **nonce** (uint256) - The next available nonce.

#### Response Example
```json
{
  "nonce": "12345"
}
```
```

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

### GET /fc/account-verifications

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

Lists account verifications attested by the Farcaster client. This endpoint is in beta and may change. It is paginated and does not require authentication.

```APIDOC
## GET /fc/account-verifications

### Description
List of account verifications attested by the Farcaster client. Ordered by the time when the verification occurred, descending. Paginated. Not authenticated.

### Method
GET

### Endpoint
/fc/account-verifications

### Query Parameters
- **fid** (string) - Optional - Limit the response to specific user.
- **platform** (string) - Optional - Limit the response to specific platform (`'x' | 'github' | 'discord'`). Defaults to `'x'` for backwards compatibility.

### Response
#### Success Response (200)
- **verifications** (array) - An array of verification objects.
  - **fid** (number) - Account Farcaster ID.
  - **platform** (string) - Platform of the verification (`'x' | 'github' | 'discord'`).
  - **platformId** (string) - String value representing platform identifier (generated by the platform, not the Farcaster client).
  - **platformUsername** (string) - String value representing platform username.
  - **verifiedAt** (number) - UNIX time when verification took place, in seconds.

#### Response Example
```json
{
  "result": {
    "verifications": [
      {
        "fid": 3,
        "platform": "x",
        "platformId": "9615352",
        "platformUsername": "dwr",
        "verifiedAt": 1728505748
      },
      {
        "fid": 3,
        "platform": "github",
        "platformId": "86492",
        "platformUsername": "danromero",
        "verifiedAt": 1728505748
      }
    ]
  },
  "next": { "cursor": "..." }
}
```
```

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

### Generate Sponsorship Signature with Viem

Source: https://docs.farcaster.xyz/reference/warpcast/signer-requests

Example of generating a sponsorship signature using the Viem library. It signs a message derived from the initial signed key request signature using the sponsoring FID's account.

```typescript
// sponsoringAccount is Viem account instance for the sponsoring FID's custody address
// signedKeyRequestSignature is the EIP-712 signature signed by the requesting FID
const sponsorSignature = sponsoringAccount.signMessage({
  message: { raw: signedKeyRequestSignature },
});
```

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

### GET /price

Source: https://docs.farcaster.xyz/reference/contracts/reference/bundler

Retrieves the cost in wei to register a new Farcaster ID (fid) and includes the price for one unit of storage. Additional storage units can be factored into the price by specifying the `extraStorage` parameter.

```APIDOC
## GET /price

### Description
Get the price in wei to register an fid, including 1 storage unit. To add additional storage units to the calculation, use the `extraStorage` parameter.

### Method
GET

### Endpoint
/price

### Query Parameters
- **extraStorage** (uint256) - Optional - Number of extra units to include in the price

### Response
#### Success Response (200)
- **price** (string) - The price in wei for registration and storage.
```

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

### GET /v1/channel-followers

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

Fetches a list of users who follow a specified Farcaster channel. The results are ordered by the follow time in descending order and are paginated. Authentication is not required.

```APIDOC
## Get 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

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

### Response
#### Success Response (200)
- **users** (array) - An array of user objects.
  - **fid** (integer) - the fid of the user
  - **followedAt** (integer) - UNIX time when channel was followed, in seconds
- **next** (object) - Contains cursor for pagination.
  - **cursor** (string) - cursor for the next page of results

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

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

### Get All Channels (Bash)

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

Retrieves a list of all available channels. This endpoint requires no parameters and is not authenticated or paginated.  The response is a JSON array of channel objects, each containing details like ID, URL, name, and description.

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

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

### GET /price

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

Retrieves the price in wei to register an Farcaster ID, including the cost of 1 storage unit. Optional extraStorage parameter can be used to include additional storage units in the total price calculation.

```APIDOC
## GET /price

### Description
Get the price in wei to register an fid. This includes the price of 1 storage unit. Use the `extraStorage` parameter to include extra storage units in the total price.

### Method
GET

### Endpoint
/price

### Parameters
#### Query Parameters
- **extraStorage** (`uint256`, optional) - The number of additional storage units

### Response
#### Success Response (200)
- **price** (`uint256`) - Price in wei to register an fid

#### Response Example
```json
{
  "price": "1000000000000000"
}
```
```

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

### Setup Viem Clients in TypeScript

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

Creates Viem public and wallet clients for the Optimism chain, supporting HTTP transport for reads and custom transport for writes. Includes account retrieval from MetaMask or generation from private key. Dependencies: Viem library and Optimism chain config. Outputs client instances and account address; supports both JSON-RPC and local accounts.

```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 Creator Reward Winners - JSON/Bash

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

Retrieves the history of creator reward winners for a given period (week), paginated in rank order, refreshed every Tuesday at 17:00 UTC. No authentication required. The JSON example illustrates the response with period timestamps, winners list including fid, username, score, rank, and reward details. The Bash example shows a curl command to access the endpoint with optional periodsAgo parameter. Limitations include weekly data refresh and optional wallet address verification for winners.

```json
{
  "result": {
    "history": {
      "periodStartTimestamp": 1738080000000,
      "periodEndTimestamp": 1738684800000,
      "winners": [
        {
          "fid": 12345,
          "score": 50000,
          "rank": 1,
          "rewardCents": 60000,
          "username": "alice.eth",
          "walletAddress": "0x0000000000000000000000000000000000000001"
        },
        {
          "fid": 67890,
          "score": 45000,
          "rank": 2,
          "rewardCents": 60000,
          "username": "bob",
          "walletAddress": "0x0000000000000000000000000000000000000002"
        },
        ...
      ]
    }
  },
  "next": { "cursor": "..." }
}
```

```bash
curl 'https://api.farcaster.xyz/v1/creator-rewards-winner-history'
```

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

### Viem Client Initialization (Public and Wallet)

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

This snippet demonstrates the initialization of Viem clients for interacting with the Ethereum blockchain, specifically the Optimism network. It sets up both a `publicClient` for read-only operations and a `walletClient` for signing transactions, using different account types (JSON-RPC and local).

```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...');

```

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

### Farcaster API Pagination Example

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

Demonstrates how to handle paginated responses from the Farcaster API. It shows the structure of a paginated response, including the `next.cursor` field, and explains how to use this cursor in subsequent requests to fetch the next page of results. An optional `limit` parameter for controlling page size is also mentioned.

```json
{
  "result": {
    ...
  },
  "next": {
    "cursor": "eyJwYWdlIjoxLCJsaW1pdCI6MTAwfQ"
  }
}
```

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

### GET /v2/signed-key-request

Source: https://docs.farcaster.xyz/reference/warpcast/signer-requests

Get the current state of a signed key request. This endpoint allows checking the status of a previously created key request.

```APIDOC
## GET /v2/signed-key-request

### Description
Get the state of a signed key request to monitor its progress.

### Method
GET

### Endpoint
/v2/signed-key-request

### Parameters
#### Query Parameters
- **token** (string) - Required - Token identifying the request

### Response
#### Success Response (200)
- **token** (string) - Token identifying the request
- **deeplinkUrl** (string) - URL where the user can complete the request
- **key** (string) - Requested key to add
- **state** (string) - State of the request: `pending` - no action taken by user, `approved` - user has approved but onchain transaction is not confirmed, `completed` - onchain transaction is confirmed
- **userFid** (number) - Optional - FID of the user who approved the request

#### Response Examples

##### Pending State
{
  "result": {
    "signedKeyRequest": {
      "token": "0xa241e6b1287a07f4d3f9c5bd",
      "deeplinkUrl": "farcaster://signed-key-request?token=0xa241e6b1287a07f4d3f9c5bd",
      "key": "0x48b0c7a6deff69bad7673357df43274f3a08163a6440b7a7e3b3cb6b6623faa7",
      "state": "pending"
    }
  }
}

##### Approved State
{
  "result": {
    "signedKeyRequest": {
      "token": "0xa241e6b1287a07f4d3f9c5bd",
      "deeplinkUrl": "farcaster://signed-key-request?token=0xa241e6b1287a07f4d3f9c5bd",
      "key": "0x48b0c7a6deff69bad7673357df43274f3a08163a6440b7a7e3b3cb6b6623faa7",
      "state": "approved",
      "userFid": 1
    }
  }
}

##### Completed State
{
  "result": {
    "signedKeyRequest": {
      "token": "0xa241e6b1287a07f4d3f9c5bd",
      "deeplinkUrl": "farcaster://signed-key-request?token=0xa241e6b1287a07f4d3f9c5bd",
      "key": "0x48b0c7a6deff69bad7673357df43274f3a08163a6440b7a7e3b3cb6b6623faa7",
      "state": "completed",
      "userFid": 1
    }
  }
}
```

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

### Get Blocked Users (GET /fc/blocked-users)

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

Fetches a list of users blocked by a specific `blockerFid` or all blocked users if `blockerFid` is not provided. The response is paginated and ordered by block creation time. Not authenticated.

```json
{
  "result": {
    "blockedUsers": [
      {
        "blockerFid": 5,
        "blockedFid": 10,
        "createdAt": 1724854521
      },
      ...
    ]
  },
  "next": { "cursor": "..." }
}
```

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

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

### Storage Registry Write API

Source: https://docs.farcaster.xyz/reference/contracts/reference/storage-registry

Provides endpoints for renting storage units for Farcaster accounts, either individually or in batches.

```APIDOC
## POST /storage-registry/rent

### Description
Rents a specific number of storage units for a given Farcaster ID (fid). Excess ether sent will be returned to the caller. Rented units are valid for 1 year from the time of registration.

### Method
POST

### Endpoint
/storage-registry/rent

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **fid** (`uint256`) - Required - The Farcaster ID to credit the storage units to.
- **units** (`uint256`) - Required - The number of units of storage to rent.
- **msg.value** (`wei`) - Required - The payment amount in wei.

### Request Example
```json
{
  "fid": 123,
  "units": 2,
  "msg.value": "20000000000000000"
}
```

### Response
#### Success Response (200)
- **message** (`string`) - Confirmation message indicating successful rental.

#### Response Example
```json
{
  "message": "Successfully rented 2 storage units for fid 123."
}
```

## POST /storage-registry/batchRent

### Description
Rents storage for multiple Farcaster IDs (fids) in a single transaction. The caller must send enough ether to cover the total cost of all units. Like single-unit rental, extra ether is returned, and units are valid for 1 year.

### Method
POST

### Endpoint
/storage-registry/batchRent

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **fids** (`uint256[]`) - Required - An array of Farcaster IDs to rent storage for.
- **units** (`uint256[]`) - Required - An array of unit quantities, corresponding to each fid in the `fids` array.
- **msg.value** (`wei`) - Required - The total payment amount in wei for all units.

### Request Example
```json
{
  "fids": [123, 456],
  "units": [1, 3],
  "msg.value": "50000000000000000"
}
```

### Response
#### Success Response (200)
- **message** (`string`) - Confirmation message indicating successful batch rental.

#### Response Example
```json
{
  "message": "Successfully rented storage for multiple fids."
}
```
```

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

### Get Signed Key Request Status (GET /v2/signed-key-request)

Source: https://docs.farcaster.xyz/reference/warpcast/signer-requests

Retrieves the current state of a signed key request using its token. Returns the token, a deep link URL, the requested key, and the request state (pending, approved, or completed). May include the user's FID upon approval.

```json
{
  "result": {
    "signedKeyRequest": {
      "token": "0xa241e6b1287a07f4d3f9c5bd",
	    "deeplinkUrl": "farcaster://signed-key-request?token=0xa241e6b1287a07f4d3f9c5bd"
      "key": "0x48b0c7a6deff69bad7673357df43274f3a08163a6440b7a7e3b3cb6b6623faa7",
			"state": "pending"
    }
  }
}
```

```json
{
  "result": {
    "signedKeyRequest": {
      "token": "0xa241e6b1287a07f4d3f9c5bd",
      "deeplinkUrl": "farcaster://signed-key-request?token=0xa241e6b1287a07f4d3f9c5bd"
      "key": "0x48b0c7a6deff69bad7673357df43274f3a08163a6440b7a7e3b3cb6b6623faa7",
      "state": "approved",
      "userFid": 1
    }
  }
}
```

```json
{
  "result": {
    "signedKeyRequest": {
      "token": "0xa241e6b1287a07f4d3f9c5bd",
	  "deeplinkUrl": "farcaster://signed-key-request?token=0xa241e6b1287a07f4d3f9c5bd"
      "key": "0x48b0c7a6deff69bad7673357df43274f3a08163a6440b7a7e3b3cb6b6623faa7",
	  "state": "completed",
	  "userFid": 1
    }
  }
}
```

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

### Sign Add Transaction with ViemWalletEip712Signer

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

This snippet demonstrates how to sign an 'Add' transaction using the `ViemWalletEip712Signer` from the '@farcaster/hub-web' library. It requires pre-configured wallet client, account, and helper functions for obtaining public key, metadata, nonce, and deadline. The output is an EIP-712 signature.

```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 /key_registry/totalKeys

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

Retrieves the number of active keys for a specific Farcaster ID (fid).

```APIDOC
## GET /key_registry/totalKeys

### Description
Retrieves the number of active keys for a specific Farcaster ID (fid).

### Method
GET

### Endpoint
/key_registry/totalKeys

### Parameters
#### Path Parameters
- **fid** (uint256) - Required - Farcaster ID to look up.
#### Query Parameters
- **state** (uint8) - Required - State of the key (1 for Added, 2 for Removed).

### Request Example
No request body.

### Response
#### Success Response (200)
- **count** (uint256) - The number of active keys.

#### Response Example
{
  "count": 123
}
```

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

### Storage Registry Read API

Source: https://docs.farcaster.xyz/reference/contracts/reference/storage-registry

Provides endpoints to check the cost of renting storage units on the Farcaster network.

```APIDOC
## GET /storage-registry/unitPrice

### Description
Gets the price in wei (`uint256`) to register one unit of storage.

### Method
GET

### Endpoint
/storage-registry/unitPrice

### Parameters
#### Query Parameters
None

#### Path Parameters
None

### Request Example
None

### Response
#### Success Response (200)
- **price** (`uint256`) - The price in wei for one storage unit.

#### Response Example
```json
{
  "price": "10000000000000000"
}
```

## GET /storage-registry/price

### Description
Gets the price in wei (`uint256`) to register a specific number of storage units.

### Method
GET

### Endpoint
/storage-registry/price

### Parameters
#### Query Parameters
- **units** (`uint256`) - Required - The number of storage units to rent.

#### Path Parameters
None

### Request Example
None

### Response
#### Success Response (200)
- **price** (`uint256`) - The total price in wei for the specified number of storage units.

#### Response Example
```json
{
  "price": "100000000000000000"
}
```
```

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

### GET /key_registry/keyDataOf

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

Returns the state and keyType of a particular key for a given Farcaster ID (fid).

```APIDOC
## GET /key_registry/keyDataOf

### Description
Returns the state and keyType of a particular key for a given Farcaster ID (fid).

### Method
GET

### Endpoint
/key_registry/keyDataOf

### Parameters
#### Path Parameters
- **fid** (uint256) - Required - Farcaster ID to look up.
#### Query Parameters
- **key** (bytes) - Required - Public key to check.

### Request Example
No request body.

### Response
#### Success Response (200)
- **state** (uint8) - The state of the key.
- **keyType** (uint32) - The type of the key.

#### Response Example
{
  "state": 1,
  "keyType": 0
}
```

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

### POST /register

Source: https://docs.farcaster.xyz/reference/contracts/reference/bundler

Registers a Farcaster ID (fid), adds one or more keys, and rents storage in a single atomic transaction. This endpoint is designed for a streamlined user signup process.

```APIDOC
## POST /register

### Description
Register an fid, add one or more keys, and rent storage in a single step. For a detailed usage example, see the signup demo app.

### Method
POST

### Endpoint
/register

### Parameters
#### Request Body
- **msg.value** (wei) - Required - Payment amount for registration
- **registerParams** (RegistrationParams) - Required - Registration related parameters and signature
- **signerParams** (SignerParams[]) - Optional - Key related parameters and signature
- **extraStorage** (uint256) - Optional - Additional storage units to rent

#### RegistrationParams struct
- **to** (address) - Required - Address to register the fid to
- **recovery** (address) - Required - Recovery address for the new fid
- **deadline** (uint256) - Required - Signature expiration timestamp
- **sig** (bytes) - Required - EIP-712 `Register` signature from the `to` address

#### SignerParams struct
- **keyType** (uint32) - Required - Must be set to `1`. This is currently the only supported `keyType`.
- **key** (bytes) - Required - Public key to add
- **metadataType** (uint8) - Required - Must be set to `1`. This is currently the only supported `metadataType`.
- **metadata** (bytes) - Required - Encoded `SignedKeyRequestMetadata`
- **deadline** (uint256) - Required - Signature expiration timestamp
- **sig** (bytes) - Required - EIP-712 `Add` signature from the `registrationParams.to` address

### Request Example
```json
{
  "msg.value": "1000000000000000000",
  "registerParams": {
    "to": "0x1234567890abcdef1234567890abcdef12345678",
    "recovery": "0xabcdef1234567890abcdef1234567890abcdef12",
    "deadline": 1678886400,
    "sig": "0x..."
  },
  "signerParams": [
    {
      "keyType": 1,
      "key": "0x...",
      "metadataType": 1,
      "metadata": "0x...",
      "deadline": 1678886400,
      "sig": "0x..."
    }
  ],
  "extraStorage": 5
}
```

### Response
#### Success Response (200)
- **fid** (uint256) - The newly registered Farcaster ID.
- **signer** (address) - The address of the added signer.

#### Response Example
```json
{
  "fid": 12345,
  "signer": "0x1234567890abcdef1234567890abcdef12345678"
}
```

#### Error Responses
- **InvalidPayment** (3c6b4b28) - The caller provided insufficient payment.
- **InvalidMetadata** (bcecb64a) - The signed metadata provided with the key is invalid.
- **InvalidSignature** (8baa579f) - The provided signature is invalid. It may be incorrectly formatted, or signed by the wrong address.
- **SignatureExpired** (0819bdcd) - The provided signature has expired. Collect a new signature from the signer with a later deadline timestamp.
```

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

### GET /transfers/current

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

Retrieves the most recent transfer event for a specific fid or fname.

```APIDOC
## GET /transfers/current

### Description
Retrieves the most recent transfer event for a specific fid or fname.

### Method
GET

### Endpoint
/transfers/current

### Parameters
#### Query Parameters
- **name** (string) - Optional - The fname to lookup
- **fid** (string) - Optional - The fid to lookup

### Response
#### Success Response (200)
- **transfers** (array) - List containing the most recent transfer object

#### Response Example
```json
{
  "transfers": [
    {
      "id": 1,
      "timestamp": 1628882891,
      "username": "farcaster",
      "owner": "0x8773442740c17c9d0f0b87022c722f9a136206ed",
      "from": 0,
      "to": 1,
      "user_signature": "0xa6fdd2a69deab5633636f32a30a54b21b27dff123e6481532746eadca18cd84048488a98ca4aaf90f4d29b7e181c4540b360ba0721b928e50ffcd495734ef8471b",
      "server_signature": "0xb7181760f14eda0028e0b647ff15f45235526ced3b4ae07fcce06141b73d32960d3253776e62f761363fb8137087192047763f4af838950a96f3885f3c2289c41b"
    }
  ]
}
```
```

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

### Sign Add Transaction with Wallet Client's signTypedData

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

This snippet shows how to sign an 'Add' transaction directly using the `walletClient.signTypedData` method provided by Viem. It utilizes the `KEY_GATEWAY_EIP_712_TYPES` from '@farcaster/hub-web' and requires helper functions for obtaining public key, metadata, nonce, and deadline. The output is an EIP-712 signature.

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

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

const signature = await walletClient.signTypedData({
  account,
  ...KEY_GATEWAY_EIP_712_TYPES,
  primaryType: 'Add',
  message: {
    owner: account,
    keyType: 1,
    key: bytesToHex(publicKey),
    metadataType: 1,
    metadata,
    nonce,
    deadline,
  },
});

```

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

### Farcaster API Authentication with App Key Token (TypeScript)

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

Illustrates how to authenticate with Farcaster API endpoints using a self-signed App Key token. This TypeScript example shows the process of generating the token, which involves signing a header and payload with private and public keys, and then using this token in the Authorization header of an API request. Dependencies include `@farcaster/hub-nodejs` and `got`.

```typescript
import { NobleEd25519Signer } from "@farcaster/hub-nodejs";

// private / public keys of an App Key you are holding for an FID
const fid = 6841; //replace
const privateKey = 'secret'; // replace
const publicKey = 'pubkey'; // replace
const signer = new NobleEd25519Signer(new Uint8Array(Buffer.from(privateKey)));

const header = {
  fid,
  type: 'app_key',
  key: publicKey
};
const encodedHeader = Buffer.from(JSON.stringify(header)).toString('base64url');

const payload = { exp: Math.floor(Date.now() / 1000) + 300 }; // 5 minutes
const encodedPayload = Buffer.from(JSON.stringify(payload)).toString('base64url');

const signatureResult = await signer.signMessageHash(Buffer.from(`${encodedHeader}.${encodedPayload}`, 'utf-8'));
if (signatureResult.isErr()) {
  throw new Error("Failed to sign message");
}

const encodedSignature = Buffer.from(signatureResult.value).toString("base64url");

const authToken = encodedHeader + "." + encodedPayload + "." + encodedSignature;

await got.post(
  "https://api.farcaster.xyz/fc/channel-follows",
  {
	  body: { channelKey: 'evm' } // Example body, might vary based on endpoint
	  headers: {
	    'Content-Type': 'application/json',
	    'Authorization': 'Bearer ' + authToken;
	  }
	}
)
```

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

### GET /v1/user-channel

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

Checks if a user is following a specific channel. Returns the following status and the timestamp if followed.

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

### Description
Check whether a user is following a channel. 

### Method
GET

### Endpoint
/v1/user-channel

#### Query Parameters
- **fid** (integer) - Required - The fid of the user
- **channelId** (string) - Required - The id of the channel

### Response
#### Success Response (200)
- **following** (boolean) - Indicates whether the channel is followed.
- **followedAt** (integer) - UNIX time when channel was followed, in seconds (optional, only present when channel is followed).

#### Response Example
```json
{
  "result": {
    "following": true,
    "followedAt": 1687943747
  }
}
```
```

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

### Generate Signed Key Request Metadata

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

This snippet demonstrates how to generate signed metadata for a key request using `ViemLocalEip712Signer`. It requires an application's account (derived from a private key), the public key to be added, and a deadline. The function `getMetadata` returns the encoded `SignedKeyRequestMetadata` or undefined if an error occurs during signing.

```typescript
import { ViemLocalEip712Signer } from '@farcaster/hub-web';
import { privateKeyToAccount } from 'viem/accounts';
import { getDeadline } from './helpers.ts';
import { getPublicKey } from './signer.ts';

// App account
export const appAccount = privateKeyToAccount('0x...');

const deadline = getDeadline();
const publicKey = await getPublicKey();

export const getMetadata = async () => {
  const eip712signer = new ViemLocalEip712Signer(appAccount);
  const metadata = await eip712signer.getSignedKeyRequestMetadata({
    requestFid: 9152n, // App fid
    key: publicKey,
    deadline,
  });
  if (metadata.isOk()) {
    return metadata.value;
  }
};

```

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

### GET /v1/channel

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

Retrieves details for a specific Farcaster channel identified by its `channelId`. This endpoint does not require authentication.

```APIDOC
## Get a Channel 

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

### Method
GET

### Endpoint
/v1/channel

### Parameters
#### Query Parameters
- **channelId** (string) - Required - the id of the channel

### 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"
      }
    }
  }
}
```
```
Tokens:
Raw