Farcaster Development Kit

An SDK to easily create Farcaster Frames, manage frame analytics and pin images to IPFS using Pinata.

View the full documentation here.

Getting Started

$3

``javascript
npm i pinata-fdk
`
`javascript
yarn add pinata-fdk
`

$3

If you want to leverage IPFS pinning capabilities, you must enter your Pinata JWT and a Pinata gateway during intialization.
`javascript
import { PinataFDK } from "pinata-fdk";
const fdk = new PinataFDK({
pinata_jwt: "",
pinata_gateway: ""},
);
`
If you are only using the frame metadata functionality, you do not need to enter your credentials.
`javascript
import { PinataFDK } from "pinata-fdk";
const fdk = new PinataFDK();
`

Farcaster Auth

The FDK makes it easy to give your Farcaster app write access for users so you can do things like sending casts or following other users. To get a better concept of the flow of Farcaster Auth, check out the guide here.

createSigner

This function will create a signer with Farcaster Auth, sign the key with your Farcaster App mnemonic phrase and FID, then send a request to Warpcast to register the signer. For more info on those please see these docs.

In order to use it make sure the mnemonic and FID are included with the PinataFDK instance.

`typescript
import { PinataFDK } from "pinata-fdk"

const fdk = new PinataFDK({
pinata_jwt: 'YOUR_PINATA_JWT',
pinata_gateway: 'YOUR_GATEWAY',
app_fid: 'APP_FID',
app_mnemonic: 'APP_MNEMONIC'
})
`

$3


`typescript
import { PinataFDK } from "pinata-fdk"

const fdk = new PinataFDK({
pinata_jwt: ${process.env.PINATA_JWT},
pinata_gateway: "",
app_fid: ${process.env.APP_FID}
app_mnemonic: ${process.env.FARCASTER_DEVELOPER_MNEMONIC}
})

const signerData: WarpcastPayload = await fdk.createSigner()
`

After creating the signer the user would visit the signerData.deep_link_url which would open Warpcast on their account to approve the signer. The user will have to pay warps since it is not sponsored.

$3

`typescript
{
signer_id: "ba2d9f6d-7514-4967-8b52-5a040b7da4a1",
token: "0xe3bffad26b16cf825f3d062d",
deep_link_url: "farcaster://signed-key-request?token=0xe3bffad26b16cf825f3d062d",
status: "pending_approval"
}
`

createSponsoredSigner

Sponsored signers is very similar to createSigner except the end user will not have to pay warps to approve the signer. However there may be limits to how many sponsored signers you can use based on your Pinata plan. You still need the app_mnemonic to sign the key being used.

`typescript
import { PinataFDK } from "pinata-fdk"

const fdk = new PinataFDK({
pinata_jwt: 'YOUR_PINATA_JWT',
pinata_gateway: 'YOUR_GATEWAY',
app_fid: 'APP_FID',
app_mnemonic: 'APP_MNEMONIC'
})
`

$3

`typescript
import { PinataFDK } from "pinata-fdk"

const fdk = new PinataFDK({
pinata_jwt: ${process.env.PINATA_JWT},
pinata_gateway: "",
app_fid: ${process.env.APP_FID},
app_mnemonic: ${process.env.FARCASTER_DEVELOPER_MNEMONIC}
})

const signerData: WarpcastPayload = await fdk.createSponsoredSigner()
`

After creating the signer the user would visit the signerData.deep_link_url which would open Warpcast on their account to approve the signer. Since it is sponsored the user will not have to pay warps to sign in, however it will show Pinata as the app.

$3

`typescript
{
signer_id: "ba2d9f6d-7514-4967-8b52-5a040b7da4a1",
token: "0x21658c8fa560aca0f35a5e4a",
deep_link_url: "farcaster://signed-key-request?token=0x21658c8fa560aca0f35a5e4a",
status: "pending_approval"
}
`

pollSigner

After creating a signer and giving the user the deep_link_url you will want to poll the signer to see if they have approved it and record the response to your account.

$3

pollSigner takes a parameter of token which is provided in either createSigner or createSponsoredSigner.

$3

`typescript
import { PinataFDK } from "pinata-fdk"

const fdk = new PinataFDK({
pinata_jwt: ${process.env.PINATA_JWT},
pinata_gateway: "",
app_fid: ${process.env.APP_FID}
})

const pollData = await fdk.pollSigner("0x21658c8fa560aca0f35a5e4a")
`

$3

`typescript
{
token: "0x321bbb927d9009232a7c26d6",
deeplinkUrl: "farcaster://signed-key-request?token=0x321bbb927d9009232a7c26d6",
key: "0x858e9ed1af97ec0c1cf06e7d769a2bca9ec324c152f320ee34b253af27b486f4",
requestFid: 20918,
state: "pending",
isSponsored: false
}
`

getSigner

After you have created a signer and it has been polled as complete, you can fetch the signer at any time using getSigner

$3

- fid - A number/integer of the FID you want to query. (Optional)

$3

`typescript
import { PinataFDK } from "pinata-fdk"

const fdk = new PinataFDK({
pinata_jwt: ${process.env.PINATA_JWT},
pinata_gateway: "",
app_fid: ${process.env.APP_FID}
})

const pollData = await fdk.getSigner(6023)
`


$3

`typescript
{
signers: [
{
id: 57,
signer_uuid: "ba2d9f6d-7514-4967-8b52-5a040b7da4a1",
fid: 6023,
public_key: "dad973170c63739f7c812d188fab1df074eb1cd48facf6556e2ef9cbb76b4c18",
signer_approved: true,
revoked: false
}
],
next_page_token: "eyJvZmZzZXQiOiI1NyJ9"
}
`

Farcaster Writes

These methods can be used to create casts, react to them, or even follow users. All of them require a signerId which is a result of using Farcaster Auth, as well as the PinataFDK initialization with a Pinata JWT.

All of these methods also return the same response, which is the direct response from the Pinata Hub.

`typescript
type CastResponse = {
data: {
type: string;
fid: number;
timestamp: number;
network: string;
castAddBody: {
embedsDeprecated: any[];
mentions: any[];
text: string;
mentionsPositions: any[];
embeds: any[];
};
};
hash: string;
hashScheme: string;
signature: string;
signatureScheme: string;
signer: string;
dataBytes: string;
};
`




$3

With the sendCast method you can effortlessly post to Farcaster using a signerId.

#### Params

- CastRequest - An object that contains the signerId and the castAddBody which follows the Farcaster Hub standard for sending casts.

`typescript
type CastRequest = {
signerId: string;
castAddBody: CastBody;
}

type CastBody = {
embedsDeprecated?: string[];
mentions?: number[];
parentCastId?: CastId | null;
parentUrl?: string | null;
text?: string | null;
mentionsPositions?: number[] | null;
embeds?: Embed[] | null;
}

type CastId = {
fid: number;
hash: string;
}

type Embed = {
url?: string | null;
castId?: CastId | null;
}
`

#### Example

`typescript
import { CastResponse, PinataFDK } from "pinata-fdk";

const fdk = new PinataFDK({
pinata_jwt: ${process.env.PINATA_JWT},
pinata_gateway: "",
});

const res: CastResponse = await fdk.sendCast({
castAddBody: {
text: "Hello World from !",
mentions: [6023],
mentionsPositions: [18],
parentUrl: "https://warpcast.com/~/channel/pinata",
embeds: [
{
url: "https://pinata.cloud"
},
{
castId: {
fid: 6023
hash: "0xcae8abd9badbb60c9b610ec264f42ed9f1785c6f",
}
}
],
parentCastId: {
fid: 6023,
hash: "0xcae8abd9badbb60c9b610ec264f42ed9f1785c6f"
}
},
signerId: "ba2d9f6d-7514-4967-8b52-5a040b7da4a1"
});
`

$3

This method can delete a cast with a provided target hash.

#### Params

- hash - Target hash of the cast that needs to be deleted
- signerId - Signer for the cast

`typescript
type CastDelete = {
hash: string;
signerId: string;
}
`

#### Example

`typescript
import { CastResponse, PinataFDK } from "pinata-fdk";

const fdk = new PinataFDK({
pinata_jwt: ${process.env.PINATA_JWT},
pinata_gateway: "",
});

const deleteReq: CastResponse = await fdk.deleteCast({
hash: "0x490889854a4f3233433b1ad0560f016f04feeeff",
signerId: "ba2d9f6d-7514-4967-8b52-5a040b7da4a1",
};
`

$3

This method can like a cast based on the provided target hash.

#### Params

- hash - Hash of the target cast to be liked
- signerId - Signer of the user liking the cast

`typescript
type LikeCast = {
hash: string,
signerId: string
}
`

#### Example

`typescript
import { CastResponse, PinataFDK } from "pinata-fdk";

const fdk = new PinataFDK({
pinata_jwt: ${process.env.PINATA_JWT},
pinata_gateway: "",
});

const likeReq: CastResponse = await fdk.likeCast({
hash: "0x490889854a4f3233433b1ad0560f016f04feeeff",
signerId: "ba2d9f6d-7514-4967-8b52-5a040b7da4a1",
};
`

$3

If a cast is already liked by the user, this method will unlike it.

#### Params

- hash - Hash of the target cast to be unliked
- signerId - Signer of the user unliking the cast

`typescript
type LikeCast = {
hash: string,
signerId: string
}
`

#### Example

`typescript
import { CastResponse, PinataFDK } from "pinata-fdk";

const fdk = new PinataFDK({
pinata_jwt: ${process.env.PINATA_JWT},
pinata_gateway: "",
});

const unlikeReq: CastResponse = await fdk.unlikeCast({
hash: "0x490889854a4f3233433b1ad0560f016f04feeeff",
signerId: "ba2d9f6d-7514-4967-8b52-5a040b7da4a1",
};
`

$3

This method will recast a cast based on the target hash.

#### Params

- hash - Hash of the target cast to be recast
- signerId - Signer of the user recasting target cast

`typescript
type RecastCast = {
hash: string;
signerId: string;
}
`

#### Example

`typescript
import { CastResponse, PinataFDK } from "pinata-fdk";

const fdk = new PinataFDK({
pinata_jwt: ${process.env.PINATA_JWT},
pinata_gateway: "",
});

const recastCastReq: CastResponse = await fdk.recastCast({
hash: "0x490889854a4f3233433b1ad0560f016f04feeeff",
signerId: "ba2d9f6d-7514-4967-8b52-5a040b7da4a1",
};
`

$3

Works just like recastCast but removes an existing recast based on a hash of the target cast.

#### Params

- hash - Hash of the target cast to remove recast
- signerId - Signer of the user removing the recast

`typescript
type RecastCast = {
hash: string;
signerId: string;
}
`

#### Example

`typescript
import { CastResponse, PinataFDK } from "pinata-fdk";

const fdk = new PinataFDK({
pinata_jwt: ${process.env.PINATA_JWT},
pinata_gateway: "",
});

const removeRecastReq: CastResponse = await fdk.removeRecast({
hash: "0x490889854a4f3233433b1ad0560f016f04feeeff",
signerId: "ba2d9f6d-7514-4967-8b52-5a040b7da4a1",
};
`

$3

Follows a target user based on their FID.

#### Params

- fid - The FID of the target user to follow
- signerId - The signer for the user following the target user

`typescript
type FollowUser = {
fid: number;
signerId: string;
}
`

#### Example

`typescript
import { CastResponse, PinataFDK } from "pinata-fdk";

const fdk = new PinataFDK({
pinata_jwt: ${process.env.PINATA_JWT},
pinata_gateway: "",
});

const followUserReq: CastResponse = await fdk.followUser({
fid: 6023,
signerId: "ba2d9f6d-7514-4967-8b52-5a040b7da4a1",
};
`

$3

Unfollows a user that the signer is already following.

#### Params

- fid - The FID of the target user to unfollow
- signerId - The signer for the user unfollowing the target user

`typescript
type FollowUser = {
fid: number;
signerId: string;
}
`

#### Example

`typescript
import { CastResponse, PinataFDK } from "pinata-fdk";

const fdk = new PinataFDK({
pinata_jwt: ${process.env.PINATA_JWT},
pinata_gateway: "",
});

const unfollowUserReq: CastResponse = await fdk.unfollowUser({
fid: 6023,
signerId: "ba2d9f6d-7514-4967-8b52-5a040b7da4a1",
};
`

Frames

$3

You can use this function to easily create the Farcaster specific metadata needed for your frame.
The only required input is cid or image.

#### Params

- buttons - An array of button specifications (max 4). (Optional)
- image - A string for a valid hosted image url.
- cid - A string representing the cid of an IPFS pinned image.
- input - A string representing the text displayed for text input. (Optional)
- post_url - A string which contains a valid URL to send the Signature Packet to. (Optional)
- refresh_period - A string representing the refresh period for the image used. (Optional)
- aspect_ratio - A string representing the aspect ratio for the image used. (Optional)
- state - An object (e.g. JSON) representing the state data for the frame. (Optional)

Note: state should only be included in response frames, not initial frames.

`javascript
type FrameHTMLType = {
buttons?: [FrameButtonMetadata, ...FrameButtonMetadata[]];
image?: {url: string};
cid?: string;
input?: FrameInputMetadata;
post_url?: string;
refresh_period?: number;
aspect_ratio?: "1.91:1" | "1:1",
state?: object
} & (
{ image: {url: string}}| { cid: string }
);
`
`javascript
type FrameButtonMetadata = {
label: string;
action?: "post" | "post_redirect" | "mint" | "link" | "tx";
target?: string;
}
`
`javascript
type FrameInputMetadata = {
text: string;
};
`

#### Example Code
`javascript
const frameMetadata = fdk.getFrameMetadata({
post_url: /api/test,
input: {text: "Hello, world!"},
aspectRatio: "1.91:1",
buttons: [
{ label: 'Click me', action: 'post'},
{ label: 'Button 2', action: "post_redirect"},
{ label: 'Button 3', action: "mint" },
{ label: 'Button 4', action: "link" },
],
cid: "",
state: {counter: 1}
});
`
#### Response
`javascript















`

#### Images for getFrameMetadata
There are two different ways to set the images of your frame metadata.

⚡️ Raw URL

⚡️ CID


#### Raw URL
Specify a hosted url image link.

`javascript
const frameMetadata = fdk.getFrameMetadata({
image: { url: ""}
});
`

#### CID
Specify a CID from your Pinata account.

`javascript
const frameMetadata = fdk.getFrameMetadata({
cid: "QmX63EYiDk9cExrv4GDmZ5soJKkgqoUJv9LbtPyugLBtV2"
});

//Must insert Pinata credentials when intializing SDK.
`

$3

Uploads an image to IPFS from a url. This url may be passed to the getFrameMetadata function.
#### Params

- url - A string for a valid hosted url image.

#### Example Code

`javascript
const ipfsUrl = await fdk.convertUrlToIPFS("https://example.com");
const frameMetadata = fdk.getFrameMetadata({
image: { url: ipfsUrl}
});
`
#### Response
`javascript
https:///ipfs/
`




$3

Returns a Promise that indicates wether a message signature is valid by querying Pinata's Farcaster hub.

#### Params

- body - An object representing the raw payload of an action frame produced by Farcaster.
`
{
untrustedData: {
fid: 2,
url: "https://fcpolls.com/polls/1",
messageHash: "0xd2b1ddc6c88e865a33cb1a565e0058d757042974",
timestamp: 1706243218,
network: 1,
buttonIndex: 2,
inputText: "hello world", // "" if requested and no input, undefined if input not requested
castId: {
fid: 226,
hash: "0xa48dd46161d8e57725f5e26e34ec19c13ff7f3b9",
},
},
trustedData: {
messageBytes: "d2b1ddc6c88e865a33cb1a565e0058d757042974...",
},
};
`
#### Example Code

`javascript
const { isValid, message } = await fdk.validateFrameMessage(body);
`

#### Response
` javascript
{
isValid: true,
message: {
data: {
type: 13,
fid: 15974,
timestamp: 98469569,
network: 1,
castAddBody: undefined,
castRemoveBody: undefined,
reactionBody: undefined,
verificationAddAddressBody: undefined,
verificationRemoveBody: undefined,
userDataBody: undefined,
linkBody: undefined,
usernameProofBody: undefined,
frameActionBody: [Object]
},
hash: ,
hashScheme: 1,
signature: ,
signatureScheme: 1,
signer: ,
dataBytes: undefined
}
}
`

$3

Returns the connected Ethereum address for an FID.

#### Params

- fid - A number representing the fid of the user.

#### Example Code

`javascript
const address = await fdk.getAddressForFid(15974);
`

#### Response
`
"0x9b7c18a71a98acd2f1271e2d1fe63750a70bc52b"
`

$3

Returns the user datadata for an FID.

#### Params

- fid - A number representing the fid of the user.

#### Example Code

`javascript
const userData = await fdk.getUserByFid(20591);
`

#### Response

`
{
fid: 20591,
username: 'kyletut',
pfp: 'https://i.imgur.com/TLMFnH6.jpg',
bio: 'Everyone is from somewhere. Cofounder and CEO of Pinata. https://www.pinata.cloud/farcaster'
}
`

Frame Analytics

To get started visit the Integrations page by clicking on the profile button in the top right, then selecting Integrations.

Note: You must have Warpcast integrated in the web app to use this functionality.

In any of your POST endpoints for frames, you can send analytics like this:*

$3

Sends data to Pinata analytics for a specific frame.

#### Params

- frame_data - An object representing the raw payload of an action frame produced by Farcaster.
- frame_id - A string representing the frame you want to track.
- custom_id: A string representing a unique identifier to segment requests within the specified frame. (Optional)

#### Example Code

`javascript
// This should be the raw payload from the frame action
const frame_data = {
untrustedData: {
fid: 2,
url: "https://fcpolls.com/polls/1",
messageHash: "0xd2b1ddc6c88e865a33cb1a565e0058d757042974",
timestamp: 1706243218,
network: 1,
buttonIndex: 2,
inputText: "hello world", // "" if requested and no input, undefined if input not requested
castId: {
fid: 226,
hash: "0xa48dd46161d8e57725f5e26e34ec19c13ff7f3b9",
},
},
trustedData: {
messageBytes: "d2b1ddc6c88e865a33cb1a565e0058d757042974...",
},
};
const frame_id = "my-unique-frame-name"
const custom_id = "my_custom_id"


await fdk.sendAnalytics(frame_id, frame_data, custom_id)
`

#### Response
`
{success: true}
`

After this is deployed you will see the analytics on the Frame Analytics Page.

$3

If you are using the Frog framework, you can utilize Pinata Frame analytics by importing our custom middleware function analyticsMiddleware.

` typescript
import { PinataFDK } from "pinata-fdk";
const fdk = new PinataFDK({
pinata_jwt: "",
pinata_gateway: ""},
);

const app = new Frog({
basePath: '/api',
// hubApiUrl: "https://hub.pinata.cloud"
})

app.use("/", fdk.analyticsMiddleware({ frameId: "frame_id", customId: "custom_id"}));
`




Pin Files from CLI

$3

Pin files directly from your src folder using the pinata-fdk npx pin command.

Create a pins folder located under your src folder

`jsx
src
-pins/
`

Add any images you want uploaded to IPFS!

`jsx
src
-pins/
--image.png
`

Run the command:

`jsx
npx pin
`

Check your src/pins folder for a pins_list.json file. Here you can easily access your CID to input into getFrameMetadata`.