Neynar Documentation

A message is the fundamental data type in the Farcaster network. When an account takes an action like casting a public message, changing its profile, or verifying an Ethereum account, it generates a new message.

1. Message

The message is a protobuf that contains the data, its hash and a signature from the author.

Field	Type	Description
data	MessageData	Contents of the message. Alternatively, you can use the data_bytes to serialize the `MessageData`
hash	bytes	Hash digest of data
hash_scheme	HashScheme	Hash scheme that produced the hash digest
signature	bytes	Signature of the hash digest
signature_scheme	SignatureScheme	Signature scheme that produced the signature
signer	bytes	Public key or address of the key pair that produced the signature
data_bytes	bytes	Alternate to the “data” field. If you are constructing the MessageData in a programming language other than Typescript, you can use this field to serialize the `MessageData` and calculate the `hash` and `signature` on these bytes. Optional.

1.1 MessageData

MessageData is a generic envelope that contains a type, fid, timestamp and network which must be present in all Farcaster messages. It also contains a body whose type is determined by the MessageType.

Field	Type	Label	Description
type	MessageType		Type of Message contained in the body
fid	uint64		Farcaster ID of the user producing the message
timestamp	uint32		Farcaster epoch timestamp in seconds
network	FarcasterNetwork		Farcaster network the message is intended for
body	CastAddBody, CastRemoveBody, ReactionBody, VerificationAddAddressBody, VerificationRemoveBody, UserDataBody, LinkBody, UserNameProof, FrameActionBody, LinkCompactStateBody	oneOf	Properties specific to the MessageType

1.2 HashScheme

Type of hashing scheme used to produce a digest of MessageData

Name	Number	Description
HASH_SCHEME_NONE	0
HASH_SCHEME_BLAKE3	1	Default scheme for hashing MessageData

1.3 Signature Scheme

Type of signature scheme used to sign the Message hash

Name	Number	Description
SIGNATURE_SCHEME_NONE	0
SIGNATURE_SCHEME_ED25519	1	Ed25519 signature (default)
SIGNATURE_SCHEME_EIP712	2	ECDSA signature using EIP-712 scheme

1.4 Message Type

Type of the MessageBody

Name	Number	Description
MESSAGE_TYPE_NONE	0	Invalid default value
MESSAGE_TYPE_CAST_ADD	1	Add a new Cast
MESSAGE_TYPE_CAST_REMOVE	2	Remove an existing Cast
MESSAGE_TYPE_REACTION_ADD	3	Add a Reaction to a Cast
MESSAGE_TYPE_REACTION_REMOVE	4	Remove a Reaction from a Cast
MESSAGE_TYPE_LINK_ADD	5	Add a Link to a target
MESSAGE_TYPE_LINK_REMOVE	6	Remove a Link from a target
MESSAGE_TYPE_VERIFICATION_ADD_ETH_ADDRESS	7	Add a Verification of an Address
MESSAGE_TYPE_VERIFICATION_REMOVE	8	Remove a Verification
MESSAGE_TYPE_USER_DATA_ADD	11	Add metadata about a user
MESSAGE_TYPE_USERNAME_PROOF	12	Add or replace a username proof
MESSAGE_TYPE_FRAME_ACTION	13	Frame action (not stored)
MESSAGE_TYPE_LINK_COMPACT_STATE	14	Compact state for links

1.5 Farcaster Network

Farcaster network the message is intended for

Name	Number	Description
FARCASTER_NETWORK_NONE	0
FARCASTER_NETWORK_MAINNET	1	Public primary network
FARCASTER_NETWORK_TESTNET	2	Public test network
FARCASTER_NETWORK_DEVNET	3	Private test network

2. UserData

A UserData message represents user metadata (e.g. a profile picture url) .

2.1 UserDataBody

Body of a UserData message

Field	Type	Label	Description
type	UserDataType		Type of metadata
value	string		Value of the metadata

2.2 UserDataType

Type of UserData message

Name	Number	Description
USER_DATA_TYPE_NONE	0	Invalid default value
USER_DATA_TYPE_PFP	1	Profile Picture for the user
USER_DATA_TYPE_DISPLAY	2	Display Name for the user
USER_DATA_TYPE_BIO	3	Bio for the user
USER_DATA_TYPE_URL	5	URL of the user
USER_DATA_TYPE_USERNAME	6	Preferred Farcaster Name for the user
USER_DATA_TYPE_LOCATION	7	Location for the user
USER_DATA_TYPE_TWITTER	8	Twitter username for the user
USER_DATA_TYPE_GITHUB	9	GitHub username for the user
USER_DATA_TYPE_BANNER	10	Banner image for the user
USER_DATA_PRIMARY_ADDRESS_ETHEREUM	11	Primary Ethereum address
USER_DATA_PRIMARY_ADDRESS_SOLANA	12	Primary Solana address

See FIP-196 for more information on Location. See FIP-19 for more information on Twitter/X and GitHub usernames.

3. Cast

A Cast message is a public post from a user.

3.1 CastAddBody

Adds a new Cast message.

Field	Type	Label	Description
embeds_deprecated	string	repeated	URLs to be embedded in the cast
mentions	uint64	repeated	Fids mentioned in the cast
parent_cast_id	CastId	oneOf parent	Parent cast of the cast
parent_url	string	oneOf parent	Parent URL of the cast
text	string		Text of the cast
mentions_positions	uint32	repeated	Positions of the mentions in the text
embeds	Embed	repeated	URLs or cast ids to be embedded in the cast
type	CastType		Type of cast (regular, long, etc.)

Embed

Field	Type	Label	Description
url	string
cast_id	CastId

3.2 CastRemoveBody

Removes an existing Cast message.

Field	Type	Label	Description
target_hash	bytes		Hash of the cast to remove

3.3 CastId

Identifier used to look up a Cast

Field	Type	Label	Description
fid	uint64		Fid of the user who created the cast
hash	bytes		Hash of the cast

4. Reaction

A Reaction message creates a relationship between an account and a cast. (e.g. like)

4.1 ReactionBody

Adds or removes a Reaction from a Cast

Field	Type	Description
type	ReactionType	Type of reaction
target_cast_id	CastId	CastId of the Cast to react to
target_url	string	URL to react to

4.2 ReactionType

Type of Reaction

Name	Number	Description
REACTION_TYPE_NONE	0	Invalid default value
REACTION_TYPE_LIKE	1	Like the target cast
REACTION_TYPE_RECAST	2	Share target cast to the user’s audience

5. Link

A Link message creates a relationship between two users (e.g. follow)

5.1 LinkBody

Adds or removes a Link

Field	Type	Label	Description
type	string		Type of link, <= 8 characters
displayTimestamp	uint32	optional	User-defined timestamp that preserves original timestamp when message.data.timestamp needs to be updated for compaction
target_fid	uint64		The fid the link relates to

6. Verification

A Verification message is a proof of ownership of something.

6.1 VerificationAddAddressBody

Adds a bi-directional signature proving that an fid has control over an address (supports multiple protocols).

Field	Type	Description
address	bytes	Address being verified
claim_signature	bytes	Signature produced by the user’s address
block_hash	bytes	Hash of the latest block when the claim was produced
verification_type	uint32	Type of verification (0 = EOA, 1 = contract)
chain_id	uint32	Chain ID of the verification
protocol	Protocol	Protocol of the address (Ethereum, Solana, etc.)

6.2 VerificationRemoveBody

Removes a Verification of any type

Field	Type	Label	Description
address	bytes		Address of the Verification to remove

7. Frame Action

Represents an action performed by a user on a frame. This message is not stored on the nodes and cannot be submitted, only validated.

7.1 FrameActionBody

A user action on a frame

Field	Type	Description
url	bytes	The original url of the frame as embedded in the cast
button_index	uint32	The button that was pressed (indexed from 1)
cast_id	CastId	The cast id that hosted the frame
input_text	bytes	Any text the user input as part of the action
state	bytes	Serialized state passed from frame to server
transaction_id	bytes	Transaction ID for transaction frames
address	bytes	Address involved in the frame action

8. Protocol

Type of protocol for addresses

Name	Number	Description
PROTOCOL_ETHEREUM	0	Ethereum
PROTOCOL_SOLANA	1	Solana

9. CastType

Type of cast

Name	Number	Description
CAST	0	Regular cast
LONG_CAST	1	Extended length cast
TEN_K_CAST	2	Ten thousand character cast

10. LinkCompactStateBody

Compact state representation for links

Field	Type	Label	Description
type	string		Type of link
target_fids	uint64	repeated	Array of target fids

Overview

Guides

Data Types

gRPC API

HTTP API

Reference

Messages

1. Message

1.1 MessageData

1.2 HashScheme

1.3 Signature Scheme

1.4 Message Type

1.5 Farcaster Network

2. UserData

2.1 UserDataBody

2.2 UserDataType

3. Cast

3.1 CastAddBody

Embed

3.2 CastRemoveBody

3.3 CastId

4. Reaction

4.1 ReactionBody

4.2 ReactionType

5. Link

5.1 LinkBody

6. Verification

6.1 VerificationAddAddressBody

6.2 VerificationRemoveBody

7. Frame Action

7.1 FrameActionBody

8. Protocol

9. CastType

10. LinkCompactStateBody

​1. Message

​1.1 MessageData

​1.2 HashScheme

​1.3 Signature Scheme

​1.4 Message Type

​1.5 Farcaster Network

​2. UserData

​2.1 UserDataBody

​2.2 UserDataType

​3. Cast

​3.1 CastAddBody

​Embed

​3.2 CastRemoveBody

​3.3 CastId

​4. Reaction

​4.1 ReactionBody

​4.2 ReactionType

​5. Link

​5.1 LinkBody

​6. Verification

​6.1 VerificationAddAddressBody

​6.2 VerificationRemoveBody

​7. Frame Action

​7.1 FrameActionBody

​8. Protocol

​9. CastType

​10. LinkCompactStateBody

1. Message

1.1 MessageData

1.2 HashScheme

1.3 Signature Scheme

1.4 Message Type

1.5 Farcaster Network

2. UserData

2.1 UserDataBody

2.2 UserDataType

3. Cast

3.1 CastAddBody

Embed

3.2 CastRemoveBody

3.3 CastId

4. Reaction

4.1 ReactionBody

4.2 ReactionType

5. Link

5.1 LinkBody

6. Verification

6.1 VerificationAddAddressBody

6.2 VerificationRemoveBody

7. Frame Action

7.1 FrameActionBody

8. Protocol

9. CastType

10. LinkCompactStateBody