Skip to content

API

Documentation for gRPC endpoints exposed by Hubble.

We recommend using a library like hub-nodejs to interact with Hubble's gRPC APIs.

1. OnChainEvents Service

Used to retrieve on chain events (id registry, signers, storage rent)

Method NameRequest TypeResponse TypeDescription
GetOnChainSignerSignerRequestOnChainEventReturns the onchain event for an active signer for an Fid
GetOnChainSignersByFidFidRequestOnChainEventResponseReturns all active signers add events for a Fid
GetIdRegistryOnChainEventFidRequestOnChainEventReturns the most recent register/transfer on chain event for a fid
GetIdRegistryOnChainEventByAddressIdRegistryEventByAddressRequestOnChainEventReturns the registration/transfer event by address if it exists (allows looking up fid by address)
GetCurrentStorageLimitsByFidFidRequestStorageLimitsResponseReturns current storage limits for all stores for a Fid
GetOnChainEventsOnChainEventRequestOnChainEventResponseReturns all on chain events filtered by type for an Fid (includes inactive signers and expired rent events)
GetFidsFidsRequestFidsResponseReturns the most recent Fids that were registered

Signer Request

FieldTypeLabelDescription
fiduint64Farcaster ID of the user who generated the Signer
signerbytesPublic Key of the Signer

Fid Request

FieldTypeLabelDescription
fiduint64Farcaster ID of the user
page_sizeuint32(optional) Type of the Link being requested
page_tokenbytes(optional)Type of the Link being requested
reverseboolean(optional) Ordering of the response

FidsRequest

FieldTypeLabelDescription
page_sizeuint32optional
page_tokenbytesoptional
reversebooloptional

Fids Response

FieldTypeLabelDescription
fidsuint64repeatedFid of the user
next_page_tokenbytesoptional

IdRegistryEventByAddressRequest

FieldTypeLabelDescription
addressbytes

StorageLimitsResponse

FieldTypeLabelDescription
limitsStorageLimitrepeatedStorage limits per store type

StorageLimit

FieldTypeLabelDescription
store_typeStoreTypeThe specific type being managed by the store
limituint64The limit of the store type, scaled by the user's rent

OnChainEventResponse

FieldTypeLabelDescription
eventsOnChainEventrepeated
next_page_tokenbytesoptional

2. UserData Service

Users to retrieve the current metadata associated with a user

Method NameRequest TypeResponse TypeDescription
GetUserDataUserDataRequestMessageReturns a specific UserData for an Fid
GetUserDataByFidFidRequestMessagesResponseReturns all UserData for an Fid
GetAllUserDataMessagesByFidFidRequestMessagesResponseReturns all UserData for an Fid

UserData Request

FieldTypeLabelDescription
fiduint64Farcaster ID of the user who generated the UserData
user_data_typeUserDataTypeType of UserData being requested

Messages Response

FieldTypeLabelDescription
messagesMessagerepeatedFarcaster Message
next_page_tokenbytesoptional

3. Cast Service

Used to retrieve valid casts or tombstones for deleted casts

Method NameRequest TypeResponse TypeDescription
GetCastCastIdMessageReturns a specific Cast
GetCastsByFidFidRequestMessagesResponseReturns CastAdds for an Fid in reverse chron order
GetCastsByParentCastIdMessagesResponseReturns CastAdd replies to a given Cast in reverse chron order
GetCastsByMentionFidRequestMessagesResponseReturns CastAdds that mention an Fid in reverse chron order
GetAllCastMessagesByFidFidRequestMessagesResponseReturns Casts for a Fid in reverse chron order

CastsByParentRequest

FieldTypeLabelDescription
parent_cast_idCastId
parent_urlstring
page_sizeuint32optional
page_tokenbytesoptional
reversebooloptional

4. Reaction Service

Method NameRequest TypeResponse TypeDescription
GetReactionReactionRequestMessageReturns a specific Reaction
GetReactionsByFidReactionsByFidRequestMessagesResponseReturns Reactions made by an Fid in reverse chron order
GetReactionsByCastReactionsByCastRequestMessagesResponseReturns ReactionAdds for a given Cast in reverse chron order
GetReactionsByTargetReactionsByTargetRequestMessagesResponseReturns ReactionAdds for a given Cast in reverse chron order
GetAllReactionMessagesByFidFidRequestMessagesResponseReturns Reactions made by a Fid in reverse chron order

Reaction Request

Users to retrieve valid or revoked reactions

FieldTypeLabelDescription
fiduint64Farcaster ID of the user who generated the Reaction
reaction_typeReactionTypeType of the Reaction being requested
target_cast_idCastId(optional) Identifier of the Cast whose reactions are being requested
target_urlstring(optional) Identifier of the Url whose reactions are being requested

ReactionsByFid Request

FieldTypeLabelDescription
fiduint64Farcaster ID of the user who generated the Reaction
reaction_typeReactionTypeType of the Reaction being requested
page_sizeuint32(optional) Type of the Link being requested
page_tokenbytes(optional)Type of the Link being requested
reverseboolean(optional) Ordering of the response

ReactionsByCast Request

FieldTypeLabelDescription
cast_idCastIdIdentifier of the Cast whose reactions are being requested
reaction_typeReactionTypeType of the Reaction being requested
page_sizeuint32(optional) Type of the Link being requested
page_tokenbytes(optional)Type of the Link being requested
reverseboolean(optional) Ordering of the response

ReactionsByTargetRequest

FieldTypeLabelDescription
target_cast_idCastId
target_urlstring
reaction_typeReactionTypeoptional
page_sizeuint32optional
page_tokenbytesoptional
reversebooloptional
Method NameRequest TypeResponse TypeDescription
GetLinkLinkRequestMessageReturns a specific Link
GetLinksByFidLinksByFidRequestMessagesResponseReturns Links made by an fid in reverse chron order
GetLinksByTargetLinksByTargetRequestMessagesResponseReturns LinkAdds for a given target in reverse chron order
GetAllLinkMessagesByFidFidRequestMessagesResponseReturns Links made by an fid in reverse chron order
GetLinkCompactStateMessageByFidFidRequestMessagesResponseReturns the LinkCompactState message made by a fid
FieldTypeLabelDescription
fiduint64Farcaster ID of the user who generated the Link
link_typestringType of the Link being requested
target_fiduint64Fid of the target

LinksByFid Request

FieldTypeLabelDescription
fiduint64Farcaster ID of the user who generated the Link
link_typestringType of the Link being requested
page_sizeuint32(optional) Type of the Link being requested
page_tokenbytes(optional)Type of the Link being requested
reverseboolean(optional) Ordering of the response

LinksByTarget Request

FieldTypeLabelDescription
target_fiduint64Farcaster ID of the user who generated the Link
link_typestring(optional) Type of the Link being requested
page_sizeuint32(optional) Type of the Link being requested
page_tokenbytes(optional)Type of the Link being requested
reverseboolean(optional) Ordering of the response
FieldTypeLabelDescription
uint64
link_typestring
page_sizeuint32optional
page_tokenbytesoptional
reversebooloptional

6. Verification Service

Used to retrieve valid or revoked proof of ownership of an Ethereum Address.

Method NameRequest TypeResponse TypeDescription
GetVerificationVerificationRequestMessageReturns a VerificationAdd for an Ethereum Address
GetVerificationsByFidFidRequestMessagesResponseReturns all VerificationAdds made by an Fid
GetAllVerificationMessagesByFidFidRequestMessagesResponseReturns all Verifications made by an Fid

Verification Request

FieldTypeLabelDescription
fiduint64Farcaster ID of the user who generated the Verification
addressbytesEthereum Address being verified

7. Event Service

Used to subscribe to real-time event updates from the Farcaster Hub

Method NameRequest TypeResponse TypeDescription
SubscribeSubscribeRequeststream HubEventStreams new Events as they occur
GetEventEventRequestHubEventStreams new Events as they occur

SubscribeRequest

FieldTypeLabelDescription
event_typesEventTyperepeatedTypes of events to subscribe to
from_iduint64optionalEvent ID to start streaming from

EventRequest

FieldTypeLabelDescription
iduint64

8. Submit Service

Method NameRequest TypeResponse TypeDescription
SubmitMessageMessageMessageSubmits a Message to the Hub

10. Username Proofs Service

Method NameRequest TypeResponse TypeDescription
GetUsernameProofUsernameProofRequestUserNameProofUsername Proof
GetUserNameProofsByFidFidRequestUsernameProofsResponse

UsernameProofRequest

FieldTypeLabelDescription
namebytes

UsernameProofsResponse

FieldTypeLabelDescription
proofsUserNameProofrepeated

UserNameProof

FieldTypeLabelDescription
timestampuint64
namebytes
ownerbytes
signaturebytes
fiduint64
typeUserNameType

UserNameProof

FieldTypeLabelDescription
timestampuint64
namebytes
ownerbytes
signaturebytes
fiduint64
typeUserNameType

11. Sync Service

Method NameRequest TypeResponse TypeDescription
GetInfoHubInfoRequestHubInfoResponseReturns metadata about the hub's state.
GetSyncStatusSyncStatusRequestSyncStatusResponseReturns the hub's sync status.
GetAllSyncIdsByPrefixTrieNodePrefixSyncIdsTBD
GetAllMessagesBySyncIdsSyncIdsMessagesResponseTBD
GetSyncMetadataByPrefixTrieNodePrefixTrieNodeMetadataResponseTBD
GetSyncSnapshotByPrefixTrieNodePrefixTrieNodeSnapshotResponseTBD
StreamSyncstream StreamSyncRequeststream StreamSyncResponseEnables sync related operations over a constant stream.
StreamFetchstream StreamFetchRequeststream StreamFetchResponseEnables reconciliation fetch operations over a constant stream.

HubInfoRequest

FieldTypeLabelDescription
db_statsbool

HubInfoResponse

Response Types for the Sync RPC Methods

FieldTypeLabelDescription
versionstring
is_syncingbool
nicknamestring
root_hashstring
db_statsDbStats

SyncStatusRequest

FieldTypeLabelDescription
peerIdstringoptional

SyncStatusResponse

FieldTypeLabelDescription
is_syncingbool
sync_statusSyncStatusrepeated

SyncStatus

FieldTypeLabelDescription
peerIdstring
inSyncstring
shouldSyncbool
divergencePrefixstring
divergenceSecondsAgoint32
theirMessagesuint64
ourMessagesuint64
lastBadSyncint64

TrieNodePrefix

FieldTypeLabelDescription
prefixbytes

SyncIds

FieldTypeLabelDescription
sync_idsbytesrepeated

TrieNodeMetadataResponse

FieldTypeLabelDescription
prefixbytes
num_messagesuint64
hashstring
childrenTrieNodeMetadataResponserepeated

TrieNodeSnapshotResponse

FieldTypeLabelDescription
prefixbytes
excluded_hashesstringrepeated
num_messagesuint64
root_hashstring

DbStats

FieldTypeLabelDescription
num_messagesuint64
num_fid_eventsuint64
num_fname_eventsuint64

StreamError

FieldTypeLabelDescription
errCodestring
messagestring
requeststring

StreamFetchRequest

FieldTypeLabelDescription
idempotency_keystring
cast_messages_by_fidFidTimestampRequest
reaction_messages_by_fidFidTimestampRequest
verification_messages_by_fidFidTimestampRequest
user_data_messages_by_fidFidTimestampRequest
link_messages_by_fidFidTimestampRequest

StreamFetchResponse

FieldTypeLabelDescription
idempotency_keystring
messagesMessagesResponse
errorStreamError

StreamSyncRequest

FieldTypeLabelDescription
get_infoHubInfoRequest
get_current_peersEmpty
stop_syncEmpty
force_syncSyncStatusRequest
get_sync_statusSyncStatusRequest
get_all_sync_ids_by_prefixTrieNodePrefix
get_all_messages_by_sync_idsSyncIds
get_sync_metadata_by_prefixTrieNodePrefix
get_sync_snapshot_by_prefixTrieNodePrefix
get_on_chain_eventsOnChainEventRequest
get_on_chain_signers_by_fidFidRequest

StreamSyncResponse

FieldTypeLabelDescription
get_infoHubInfoResponse
get_current_peersContactInfoResponse
stop_syncSyncStatusResponse
force_syncSyncStatusResponse
get_sync_statusSyncStatusResponse
get_all_sync_ids_by_prefixSyncIds
get_all_messages_by_sync_idsMessagesResponse
get_sync_metadata_by_prefixTrieNodeMetadataResponse
get_sync_snapshot_by_prefixTrieNodeSnapshotResponse
get_on_chain_eventsOnChainEventResponse
get_on_chain_signers_by_fidOnChainEventResponse
errorStreamError

12. Storage Service

Method NameRequest TypeResponse TypeDescription
GetRentRegistryEvents.RentRegistryEventsRequest.RentRegistryEventsResponse

13. Admin Service

Method NameRequest TypeResponse TypeDescription
RebuildSyncTrie.Empty.Empty
DeleteAllMessagesFromDb.Empty.Empty
SubmitOnChainEvent.OnChainEvent.IdRegistryEvent