Warpcast API Reference
This page documents public APIs provided by Warpcast with information that is not available on the protocol.
The hostname is always https://api.warpcast.com
.
Pagination
Paginated endpoints return a next.cursor
property next to the result
object. To fetch the next page, send the value as a cursor
query parameter. An optional limit
query parameter can be used to specify the page size.
{
"result": {
...
},
"next": {
"cursor": "eyJwYWdlIjoxLCJsaW1pdCI6MTAwfQ"
}
}
Authentication
Authenticated endpoints use a self-signed token, signed an an App Key for FID:
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.warpcast.com/fc/channel-follows",
{
body: { channelKey: 'evm' }
headers: {
'Content-Type': 'application/json',
'Authorization': 'Bearer ' + authToken;
}
}
)
Concepts
- Channels: Warpcast has the concept of channels which build upon FIP-2 (setting
parentUrl
on casts). You can read more about channels in the documentation.
Get All Channels
GET /v2/all-channels
List all channels. No parameters. Not paginated. Not authenticated.
Returns: a channels
array with properties:
id
- unique channel id that cannot be changed (called 'Name' when creating a channel)url
- FIP-2parentUrl
used for main casts in the channelname
- friendly name displayed to users (called 'Display name' when editing a channel)description
- description of the channel, if presentdescriptionMentions
- an array of the user fids mentioned in the description. Multiple mentions result in multiple entries.descriptionMentionsPositions
- the indexes within the description where the mentioned users (fromdescriptionMentions
) appear. This array is always the same size asdescriptionMentions
. The mention is placed to the left of any existing character at that index.leadFid
- fid of the user who created the channel, if presentmoderatorFids
- fids of the moderators (under new channel membership scheme)createdAt
- UNIX time when channel was created, in secondsfollowerCount
- number of users following the channelmemberCount
- number of members of the channel, including the owner and moderatorspinnedCastHash
- hash of the cast pinned in the channel, if presentpublicCasting
-true
/false
indicating whether channel allows anybody to cast into it, or only membersexternalLink
- external link that appears in the header in Warpcast, if present, with 2 properties:title
- title shown in the channel headerurl
- url of the link
{
"result": {
"channels": [
{
"id": "illustrations",
"url": "https://warpcast.com/~/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://warpcast.com/~/channel/creators-support"
}
},
...
]
}
}
Example:
curl 'https://api.warpcast.com/v2/all-channels'
Get a Channel
GET /v1/channel
Get a single channel. Not authenticated.
Query parameters:
channelId
- the id of the channel
Returns: a single channel object, as documented in the "Get All Channels" endpoint above.
{
"result": {
"channel": {
"id": "illustrations",
"url": "https://warpcast.com/~/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://warpcast.com/~/channel/creators-support"
}
}
}
}
curl 'https://api.warpcast.com/v1/channel?channelId=illustrations'
Get Channel Followers
GET /v1/channel-followers
List the followers of a channel. Ordered by the time when the channel was followed, descending. Paginated. Not authenticated.
Query Parameters:
channelId
- the id of the channel
Returns: a users
array with properties:
fid
- the fid of the userfollowedAt
- UNIX time when channel was followed, in seconds
{
"result": {
"users": [
{
"fid": 466624,
"followedAt": 1712685183
},
{
"fid": 469283,
"followedAt": 1712685067
},
...
],
},
"next": { "cursor": "..." }
}
Example:
curl 'https://api.warpcast.com/v1/channel-followers?channelId=books'
Get Channels a User is Following
GET /v1/user-following-channels
List all channels a user is following. Ordered by the time when the channel was followed, descending. Paginated. Not authenticated.
Parameters:
fid
- the fid of the user
Returns: a channels
array with properties:
- All properties documented in the "Get All Channels" endpoint above
followedAt
- UNIX time when channel was followed, in seconds
{
"result": {
"channels": [
{
"id": "fc-updates",
"url": "https://warpcast.com/~/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": "..." }
}
Example:
curl 'https://api.warpcast.com/v1/user-following-channels?fid=3'
Get User Following Channel Status
GET /v1/user-channel
Check whether a user is following a channel.
Query parameters:
fid
- the fid of the userchannelId
- the id of the channel
Returns: 2 properties:
following
- indicates whether the channel is followedfollowedAt
- UNIX time when channel was followed, in seconds (optional, only present when channel is followed)
{
"result": {
"following": true,
"followedAt": 1687943747
}
}
Example:
curl 'https://api.warpcast.com/v1/user-channel?fid=3&channelId=books'
Get Channel Members
GET /fc/channel-members
List the members of a channel. Ordered by the time when the user became a member, descending. Paginated. Not authenticated.
Query parameters:
channelId
- the id of the channelfid
- (optional) and fid of a user to filter by
Returns: a members
array:
fid
- the fid of the membermemberAt
- UNIX time when user became a member, in seconds
{
"result": {
"members": [
{
"fid": 466624,
"memberAt": 1712685183
},
{
"fid": 469283,
"memberAt": 1712685067
},
...
]
},
"next": { "cursor": "..." }
}
Example:
curl 'https://api.warpcast.com/fc/channel-members?channelId=memes'
Get Channel Invites
GET /fc/channel-invites
List outstanding invites to channels. Ordered by the time when the user was invited, descending. Paginated. Not authenticated.
There is max one outstanding invite per user (invitedFid
) and channel (channelId
).
Query parameters:
channelId
- (optional) an id of a channel to filter byfid
- (optional) an fid of a user to filter by
Returns: an invites
array:
channelId
- the id of the channel to which the user was inviterinvitedFid
- the fid of the user being invitedinvitedAt
- UNIX time when user was invited, in secondsinviterFid
- the fid of the user who created the inviterole
- the role the user was invited to,member
ormoderator
{
"result": {
"invites": [
{
"channelId": "coke-zero",
"invitedFid": 194,
"invitedAt": 1726879628,
"inviterFid": 18949,
"role": "member"
},
{
"channelId": "brain-teasers",
"invitedFid": 627785,
"invitedAt": 1726874566,
"inviterFid": 235128,
"role": "member"
},
...
]
},
"next": { "cursor": "..." }
}
Example:
curl 'https://api.warpcast.com/fc/channel-invites?channelId=memes'
Get Cast Moderation Actions
GET /fc/moderated-casts
List moderation actions. Ordered by the time when the action was taken, descending. Paginated. Not authenticated.
Query parameters:
channelId
- (optional) an id of a channel to filter by
Returns: a moderationActions
array:
castHash
- hash of the cast that was moderated (including0x
prefix)channelId
- id of the channel in which the cast residesaction
-hide
orunhide
moderatedAt
- UNIX time when moderation took place, in seconds
{
"result": {
"moderationActions": [
{
"castHash": "0x6b2253105ef8c1d1b984a5df87182b105a1f0b3a",
"channelId": "welcome",
"action": "hide",
"moderatedAt": 1727767637
},
...
]
},
"next": { "cursor": "..." }
}
Example:
curl 'https://api.warpcast.com/fc/moderated-casts?channelId=welcome'
Get Channel Restricted Users
GET /fc/channel-restricted-users
Get users restricted from joining channels via an invite link (they can still be manually invited). Users get into this state automatically after being removed as a member, and after being unbanned. Users get out of this state after being invited (even if they haven't accepted/declined the invite), and being banned. It is not possible to restrict or unrestrict users directly. Ordered by the time when the user was restricted, descending. Paginated. Not authenticated.
Note:
- Replies by restricted users are still visible below the fold
- This endpoint returns only actively restricted users. If a user was restricted and subsequently invited back or banned, the entry from this endpoint will disappear.
Query parameters:
channelId
- (optional) channel id to filter byfid
- (optional) user fid to filter by
Returns: a restrictedUsers
array:
fid
- the fid of the restricted userchannelId
- the id of the channel the user is restricted fromrestrictedAt
- UNIX time when the restriction started, in seconds
{
"result": {
"restrictedUsers": [
{
"fid": 1234,
"channelId": "welcome",
"restrictedAt": 1727767637
},
...
]
},
"next": { "cursor": "..." }
}
Example:
curl 'https://api.warpcast.com/fc/channel-restricted-users?channelId=memes'
Get Channel Banned Users
GET /fc/channel-bans
Get users banned from channels. Ordered by the time when the user was banned, descending. Paginated. Not authenticated.
Note:
- This endpoint returns only active bans. If a user is unbanned, the entry from this endpoint will disappear.
Query parameters:
channelId
- (optional) channel id to filter byfid
- (optional) user fid to filter by
Returns: a bannedUsers
array:
fid
- the fid of the banned userchannelId
- the id of the channel the user is banned frombannedAt
- UNIX time when the ban started, in seconds
{
"result": {
"bannedUsers": [
{
"fid": 1234,
"channelId": "welcome",
"bannedAt": 1727767637
},
...
]
},
"next": { "cursor": "..." }
}
Example:
curl 'https://api.warpcast.com/fc/channel-bans?channelId=memes'
Ban User From Channel
POST /fc/channel-bans
Ban a user from a channel. A banned user can no longer reply to channel casts, and all their existing replies are hidden. Authenticated.
The caller must own or moderate the channel.
Body parameters:
channelId
- the id of the channel to ban the user frombanFid
- the fid of the user to ban
Returns:
success: true
Example:
curl -X POST \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <Auth Token>' \
-d '{ "channelId": "memes", "banFid": 1234 }' \
https://api.warpcast.com/fc/channel-bans
Unban User From Channel
DELETE /fc/channel-bans
Unban a user from a channel. All the user's existing replies will become visible and they will be able to reply again (appearing below the fold). The user goes into restricted state. Authenticated.
The caller must own or moderate the channel.
Body parameters:
channelId
- the id of the channel to unban the user fromunbanFid
- the fid of the user to unban
Returns:
success: true
Example:
curl -X DELETE \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <Auth Token>' \
-d '{ "channelId": "memes", "banFid": 1234 }' \
https://api.warpcast.com/fc/channel-bans
Follow/Unfollow Channel
Allows following and unfollowing a channel. Authenticated.
POST /fc/channel-follows
DELETE /fc/channel-follows
Body parameters:
channelId
- id of channel to follow or unfollow
Examples
curl -X POST -H 'Content-Type: application/json' -H 'Authorization: Bearer <Auth Token>' -d '{ "channelId": "evm" }' https://api.warpcast.com/fc/channel-follows
curl -X DELETE -H 'Content-Type: application/json' -H 'Authorization: Bearer <Auth Token>' -d '{ "channelId": "evm" }' https://api.warpcast.com/fc/channel-follows
Invite to Channel
POST /fc/channel-invites
Invites a user to be either a member or moderator of a channel. It is idempotent, i.e. if there is already an outstanding invite or the user already has the desired role, the API returns success. Authenticated.
The caller must own or moderate the channel.
Note: we can allowlist bots that are ok to be directly added as moderators to channels. Any channel owner can then add the bot as an active mod without the requirement that the bot is first a member or that it has to accept an invite. Let us know if you’d like your bot to be allowlisted.
Rate limit: 100 calls per caller per channel per hour
Body parameters:
channelId
- id of channel to invite user toinviteFid
- fid of the user to inviterole
- either of:member
: invites the user to be a member. The user must already follow either the channel or the user calling the endpoint. The caller must be a channel moderator or the channel owner.moderator
: invites a user to be a moderator. The user must already be a channel member (i.e. has accepted a priormember
invitation). The caller must be the channel owner. The number of active moderators + outstanding moderator invites cannot go above 10 (you’ll get an error).
Returns:
success: true
Example:
curl -X POST \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <Auth Token>' \
-d '{ "channelId": "evm", "inviteFid": 341234, "role": "member" }' \
https://api.warpcast.com/fc/channel-invites
Remove from Channel
DELETE /fc/channel-invites
Removes a user from a channel role, including revoking any outstanding unaccepted invite. It is idempotent, i.e. if the user does not have an invite for the role or does not have the role, the API returns success. Authenticated.
The caller must own or moderate the channel.
Rate limit: 100 calls per caller per channel per hour
Body parameters:
channelId
- id of channel to remove user fromremoveFid
- fid of the user to removerole
- either of:member
: removes user from member role or revokes an existing member invitation. If the user was removed, the user is blocked from becoming a member again via a link (i.e. to become a member again, they have to be invited by a moderator). If only an invitation was revoked, the user is not blocked from becoming a member via a link. The caller must be a channel moderator or the channel owner.moderator
: removes user from moderator role or revokes an existing moderator invitation. The caller must be the channel owner.
Returns:
success: true
Example:
curl -X DELETE \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <Auth Token>' \
-d '{ "channelId": "evm", "removeFid": 341234, "role": "member" }' \
https://api.warpcast.com/fc/channel-invites
Respond to Channel Invite
PATCH /fc/channel-invites
Accept or decline an outstanding member/moderator channel invite. Once an invite has been accepted or declined, the response cannot be changed. Authenticated.
The caller must have an active invite.
Body parameters:
channelId
- id of channel to which user was invitedrole
- the role of the invite, eithermember
ormoderator
accept
- boolean,true
orfalse
, indicating accept/decline
Returns:
success: true
Example:
curl -X PATCH \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <Auth Token>' \
-d '{ "channelId": "evm", "role": "member", "accept": true }' \
https://api.warpcast.com/fc/channel-invites
Moderate Channel Cast
POST /fc/moderated-casts
Moderate (hide/unhide) a specific channel cast. Authenticated.
The cast must be in a channel the caller moderates or owns.
Body parameters:
castHash
- the hash of the cast (including0x
prefix)action
- eitherhide
orunhide
Returns:
success: true
Example:
curl -X POST \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <Auth Token>' \
-d '{ "castHash": "0x2694aa649f3608bd11fe6621946782d1eb0ae3c4", "action": "hide" }' \
https://api.warpcast.com/fc/moderate-cast
Pin Channel Cast
PUT /fc/pinned-casts
Pin (and optionally announce) a cast to a channel, replacing any currently pinned cast. If the provided cast is already pinned, nothing changes (and success is returned). Authenticated.
Body parameters:
castHash
- the hash of the cast to pin (including0x
prefix)notifyChannelFollowers
- (optional)true
/false
whether to send an announcement notification to all channel followers about the pinned cast. Defaults tofalse
Returns:
success: true
Example:
curl -X PUT \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <Auth Token>' \
-d '{ "castHash": "0x2694aa649f3608bd11fe6621946782d1eb0ae3c4", "notifyChannelFollowers": true }' \
https://api.warpcast.com/fc/pinned-casts
Unpin Channel Cast
DELETE /fc/pinned-casts
Unpin a cast from a channel. Does not remove existing announcement notifications. Authenticated.
Body parameters (provide only one of the two):
castHash
- the hash of the cast to unpin (including0x
prefix). Will unpin only if this exact cast is pinned.channelId
- the id of the channel to unpin from. Will unpin any pinned cast from the channel.
Returns:
success: true
Example:
curl -X DELETE \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <Auth Token>' \
-d '{ "channelId": "welcome" }' \
https://api.warpcast.com/fc/pinned-casts
Get Farcaster actions
GET /v2/discover-actions
Retrieve a list of Farcaster actions. Paginated. Not authenticated.
Query parameters:
list
- the list to retrieve. Must be'top'
, a list ordered by total users.
Returns: an array of action
objects with properties:
name
- action nameicon
- an Octicon identifying the actiondescription
- a short text description of the actionaboutUrl
- external link to a page with additional instructions or source codeactionUrl
- action metadata URL. Clients retrieve metadata with a GET to this URL.action.actionType
- action type, only'post'
action.postUrl
- action POST URL. Clients POSt signed messages to this URL.
{
"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": "..." }
}
Example:
curl 'https://api.warpcast.com/v2/discover-actions?list=top&limit=10'
Get Farcaster composer actions
GET /v2/discover-composer-actions
Retrieve a list of Farcaster composer actions. Paginated. Not authenticated.
Query parameters:
list
- the list to retrieve. Must be one of:'top'
, a list ordered by total users.'featured'
, a list curated by Warpcast.
Returns: an actions
array with properties:
name
- action nameicon
- an Octicon identifying the actiondescription
- a short text description of the actionaboutUrl
- external link to a page with additional instructions or source codeimageUrl
- external link to an action logo image.actionUrl
- action metadata URL. Clients retrieve metadata with a GET to this URL.action.actionType
- action type, only'post'
action.postUrl
- action POST URL. Clients POSt signed messages to this URL.
{
"result": {
"actions": [
{
"name": "Poll",
"icon": "list-unordered",
"description": "Create a poll",
"aboutUrl": "https://poll.example.com/",
"imageUrl": "https://poll.example.com/images/logo.png",
"actionUrl": "https://poll.example.com/api/action/",
"action": {
"actionType": "post",
"postUrl": "https://poll.ecample.com/api/action/"
}
}
]
},
"next": { "cursor": "..." }
}
Example:
curl 'https://api.warpcast.com/v2/discover-composer-actions?list=top&limit=10'
Get Blocked Users
GET /fc/blocked-users
Warpcast allows users to block others from replying, quoting and mentioning them.
This endpoint provides access to all blocked users. Paginated, in reverse chronological order by block creation time. Not authenticated.
Query parameters:
blockerFid
(optional) - limit the response to only blocks by a specific user
Returns: a blockedUsers
array with properties:
blockerFid
- the user who created the blockblockedFid
- the user who is blocked (cannot reply to, quote or mention theblockerFid
)createdAt
- UNIX time when channel was created, in seconds
{
"result": {
"blockedUsers": [
{
"blockerFid": 5,
"blockedFid": 10,
"createdAt": 1724854521
},
...
]
},
"next": { "cursor": "..." }
}
Example:
curl 'https://api.warpcast.com/fc/blocked-users'
Block User
POST /fc/blocked-users
Block a user. Authenticated.
Body parameters:
blockFid
- the fid of the user to block
Returns:
success: true
Example:
curl -X POST \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <Auth Token>' \
-d '{ "blockFid": 1234 }' \
https://api.warpcast.com/fc/blocked-users
Unblock User
DELETE /fc/blocked-users
Unblock a user. Authenticated.
Body parameters:
unblockFid
- the fid of the user to unblock
Returns:
success: true
Example:
curl -X DELETE \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <Auth Token>' \
-d '{ "unblockFid": 1234 }' \
https://api.warpcast.com/fc/blocked-users
Get Account Verifications
GET /fc/account-verifications
This endpoint is not stable (beta) and very likely to have breaking changes in the future.
List of account verifications attested by Warpcast. Ordered by the time when the verification occurred, descending. Paginated. Not authenticated.
Query parameters:
fid
(optional) - limit the response to specific user
Returns: a verifications
array:
fid
- account Farcaster idplatform
- platform of the verification'x'
platformId
- string value representing platform identifier (generated by the platform, not Warpcast)platformUsername
- string value representing platform usernameverifiedAt
- UNIX time when verification took place, in seconds
{
"result": {
"verifications": [
{
"fid": 3,
"platform": "x",
"platformId": "9615352",
"platformUsername": "dwr",
"verifiedAt": 1728505748
},
...
]
},
"next": { "cursor": "..." }
}
Example:
curl 'https://api.warpcast.com/fc/account-verifications'