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 Name | Request Type | Response Type | Description |
|---|---|---|---|
| GetOnChainSigner | SignerRequest | OnChainEvent | Returns the onchain event for an active signer for an Fid |
| GetOnChainSignersByFid | FidRequest | OnChainEventResponse | Returns all active signers add events for an Fid |
| GetIdRegistryOnChainEvent | FidRequest | OnChainEvent | Returns the most recent register/transfer on chain event for an fid |
| GetIdRegistryOnChainEventByAddress | IdRegistryEventByAddressRequest | OnChainEvent | Returns the registration/transfer event by address if it exists (allows looking up fid by address) |
| GetCurrentStorageLimitsByFid | FidRequest | StorageLimitsResponse | Returns current storage limits for all stores for an Fid |
| GetOnChainEvents | OnChainEventRequest | OnChainEventResponse | Returns all on chain events filtered by type for an Fid (includes inactive signers and expired rent events) |
| GetFids | FidsRequest | FidsResponse | Returns the most recent Fids that were registered |
Signer Request
| Field | Type | Label | Description |
|---|---|---|---|
| fid | uint64 | Farcaster ID of the user who generated the Signer | |
| signer | bytes | Public Key of the Signer |
Fid Request
| Field | Type | Label | Description |
|---|---|---|---|
| fid | uint64 | Farcaster ID of the user | |
| page_size | uint32 | (optional) Type of the Link being requested | |
| page_token | bytes | (optional)Type of the Link being requested | |
| reverse | boolean | (optional) Ordering of the response |
FidsRequest
| Field | Type | Label | Description |
|---|---|---|---|
| page_size | uint32 | optional | |
| page_token | bytes | optional | |
| reverse | bool | optional |
Fids Response
| Field | Type | Label | Description |
|---|---|---|---|
| fids | uint64 | repeated | Fid of the user |
| next_page_token | bytes | optional |
IdRegistryEventByAddressRequest
| Field | Type | Label | Description |
|---|---|---|---|
| address | bytes |
StorageLimitsResponse
| Field | Type | Label | Description |
|---|---|---|---|
| limits | StorageLimit | repeated | Storage limits per store type |
StorageLimit
| Field | Type | Label | Description |
|---|---|---|---|
| store_type | StoreType | The specific type being managed by the store | |
| limit | uint64 | The limit of the store type, scaled by the user's rent |
OnChainEventResponse
| Field | Type | Label | Description |
|---|---|---|---|
| events | OnChainEvent | repeated | |
| next_page_token | bytes | optional |
2. UserData Service
Users to retrieve the current metadata associated with a user
| Method Name | Request Type | Response Type | Description |
|---|---|---|---|
| GetUserData | UserDataRequest | Message | Returns a specific UserData for an Fid |
| GetUserDataByFid | FidRequest | MessagesResponse | Returns all UserData for an Fid |
| GetAllUserDataMessagesByFid | FidRequest | MessagesResponse | Returns all UserData for an Fid |
UserData Request
| Field | Type | Label | Description |
|---|---|---|---|
| fid | uint64 | Farcaster ID of the user who generated the UserData | |
| user_data_type | UserDataType | Type of UserData being requested |
Messages Response
| Field | Type | Label | Description |
|---|---|---|---|
| messages | Message | repeated | Farcaster Message |
| next_page_token | bytes | optional |
3. Cast Service
Used to retrieve valid casts or tombstones for deleted casts
| Method Name | Request Type | Response Type | Description |
|---|---|---|---|
| GetCast | CastId | Message | Returns a specific Cast |
| GetCastsByFid | FidRequest | MessagesResponse | Returns CastAdds for an Fid in reverse chron order |
| GetCastsByParent | CastId | MessagesResponse | Returns CastAdd replies to a given Cast in reverse chron order |
| GetCastsByMention | FidRequest | MessagesResponse | Returns CastAdds that mention an Fid in reverse chron order |
| GetAllCastMessagesByFid | FidRequest | MessagesResponse | Returns Casts for an Fid in reverse chron order |
CastsByParentRequest
| Field | Type | Label | Description |
|---|---|---|---|
| parent_cast_id | CastId | ||
| parent_url | string | ||
| page_size | uint32 | optional | |
| page_token | bytes | optional | |
| reverse | bool | optional |
4. Reaction Service
| Method Name | Request Type | Response Type | Description |
|---|---|---|---|
| GetReaction | ReactionRequest | Message | Returns a specific Reaction |
| GetReactionsByFid | ReactionsByFidRequest | MessagesResponse | Returns Reactions made by an Fid in reverse chron order |
| GetReactionsByCast | ReactionsByCastRequest | MessagesResponse | Returns ReactionAdds for a given Cast in reverse chron order |
| GetReactionsByTarget | ReactionsByTargetRequest | MessagesResponse | Returns ReactionAdds for a given Cast in reverse chron order |
| GetAllReactionMessagesByFid | FidRequest | MessagesResponse | Returns Reactions made by an Fid in reverse chron order |
Reaction Request
Users to retrieve valid or revoked reactions
| Field | Type | Label | Description |
|---|---|---|---|
| fid | uint64 | Farcaster ID of the user who generated the Reaction | |
| reaction_type | ReactionType | Type of the Reaction being requested | |
| target_cast_id | CastId | (optional) Identifier of the Cast whose reactions are being requested | |
| target_url | string | (optional) Identifier of the Url whose reactions are being requested |
ReactionsByFid Request
| Field | Type | Label | Description |
|---|---|---|---|
| fid | uint64 | Farcaster ID of the user who generated the Reaction | |
| reaction_type | ReactionType | Type of the Reaction being requested | |
| page_size | uint32 | (optional) Type of the Link being requested | |
| page_token | bytes | (optional)Type of the Link being requested | |
| reverse | boolean | (optional) Ordering of the response |
ReactionsByCast Request
| Field | Type | Label | Description |
|---|---|---|---|
| cast_id | CastId | Identifier of the Cast whose reactions are being requested | |
| reaction_type | ReactionType | Type of the Reaction being requested | |
| page_size | uint32 | (optional) Type of the Link being requested | |
| page_token | bytes | (optional)Type of the Link being requested | |
| reverse | boolean | (optional) Ordering of the response |
ReactionsByTargetRequest
| Field | Type | Label | Description |
|---|---|---|---|
| target_cast_id | CastId | ||
| target_url | string | ||
| reaction_type | ReactionType | optional | |
| page_size | uint32 | optional | |
| page_token | bytes | optional | |
| reverse | bool | optional |
5. Link Service
| Method Name | Request Type | Response Type | Description |
|---|---|---|---|
| GetLink | LinkRequest | Message | Returns a specific Link |
| GetLinksByFid | LinksByFidRequest | MessagesResponse | Returns Links made by an fid in reverse chron order |
| GetLinksByTarget | LinksByTargetRequest | MessagesResponse | Returns LinkAdds for a given target in reverse chron order |
| GetAllLinkMessagesByFid | FidRequest | MessagesResponse | Returns Links made by an fid in reverse chron order |
Link Request
| Field | Type | Label | Description |
|---|---|---|---|
| fid | uint64 | Farcaster ID of the user who generated the Link | |
| link_type | string | Type of the Link being requested | |
| target_fid | uint64 | Fid of the target |
LinksByFid Request
| Field | Type | Label | Description |
|---|---|---|---|
| fid | uint64 | Farcaster ID of the user who generated the Link | |
| link_type | string | Type of the Link being requested | |
| page_size | uint32 | (optional) Type of the Link being requested | |
| page_token | bytes | (optional)Type of the Link being requested | |
| reverse | boolean | (optional) Ordering of the response |
LinksByTarget Request
| Field | Type | Label | Description |
|---|---|---|---|
| target_fid | uint64 | Farcaster ID of the user who generated the Link | |
| link_type | string | (optional) Type of the Link being requested | |
| page_size | uint32 | (optional) Type of the Link being requested | |
| page_token | bytes | (optional)Type of the Link being requested | |
| reverse | boolean | (optional) Ordering of the response |
| Field | Type | Label | Description |
|---|---|---|---|
| uint64 | |||
| link_type | string | ||
| page_size | uint32 | optional | |
| page_token | bytes | optional | |
| reverse | bool | optional |
6. Verification Service
Used to retrieve valid or revoked proof of ownership of an Ethereum Address.
| Method Name | Request Type | Response Type | Description |
|---|---|---|---|
| GetVerification | VerificationRequest | Message | Returns a VerificationAdd for an Ethereum Address |
| GetVerificationsByFid | FidRequest | MessagesResponse | Returns all VerificationAdds made by an Fid |
| GetAllVerificationMessagesByFid | FidRequest | MessagesResponse | Returns all Verifications made by an Fid |
Verification Request
| Field | Type | Label | Description |
|---|---|---|---|
| fid | uint64 | Farcaster ID of the user who generated the Verification | |
| address | bytes | Ethereum Address being verified |
7. Event Service
Used to subscribe to real-time event updates from the Farcaster Hub
| Method Name | Request Type | Response Type | Description |
|---|---|---|---|
| Subscribe | SubscribeRequest | stream HubEvent | Streams new Events as they occur |
| GetEvent | EventRequest | HubEvent | Streams new Events as they occur |
SubscribeRequest
| Field | Type | Label | Description |
|---|---|---|---|
| event_types | EventType | repeated | Types of events to subscribe to |
| from_id | uint64 | optional | Event ID to start streaming from |
EventRequest
| Field | Type | Label | Description |
|---|---|---|---|
| id | uint64 |
8. Submit Service
| Method Name | Request Type | Response Type | Description |
|---|---|---|---|
| SubmitMessage | Message | Message | Submits a Message to the Hub |
10. Username Proofs Service
| Method Name | Request Type | Response Type | Description |
|---|---|---|---|
| GetUsernameProof | UsernameProofRequest | UserNameProof | Username Proof |
| GetUserNameProofsByFid | FidRequest | UsernameProofsResponse |
UsernameProofRequest
| Field | Type | Label | Description |
|---|---|---|---|
| name | bytes |
UsernameProofsResponse
| Field | Type | Label | Description |
|---|---|---|---|
| proofs | UserNameProof | repeated |
UserNameProof
| Field | Type | Label | Description |
|---|---|---|---|
| timestamp | uint64 | ||
| name | bytes | ||
| owner | bytes | ||
| signature | bytes | ||
| fid | uint64 | ||
| type | UserNameType |
UserNameProof
| Field | Type | Label | Description |
|---|---|---|---|
| timestamp | uint64 | ||
| name | bytes | ||
| owner | bytes | ||
| signature | bytes | ||
| fid | uint64 | ||
| type | UserNameType |
11. Sync Service
| Method Name | Request Type | Response Type | Description |
|---|---|---|---|
| GetInfo | HubInfoRequest | HubInfoResponse | Returns metadata about the hub's state. |
| GetSyncStatus | SyncStatusRequest | SyncStatusResponse | Returns the hub's sync status. |
| GetAllSyncIdsByPrefix | TrieNodePrefix | SyncIds | TBD |
| GetAllMessagesBySyncIds | SyncIds | MessagesResponse | TBD |
| GetSyncMetadataByPrefix | TrieNodePrefix | TrieNodeMetadataResponse | TBD |
| GetSyncSnapshotByPrefix | TrieNodePrefix | TrieNodeSnapshotResponse | TBD |
HubInfoRequest
| Field | Type | Label | Description |
|---|---|---|---|
| db_stats | bool |
HubInfoResponse
Response Types for the Sync RPC Methods
| Field | Type | Label | Description |
|---|---|---|---|
| version | string | ||
| is_syncing | bool | ||
| nickname | string | ||
| root_hash | string | ||
| db_stats | DbStats |
SyncStatusRequest
| Field | Type | Label | Description |
|---|---|---|---|
| peerId | string | optional |
SyncStatusResponse
| Field | Type | Label | Description |
|---|---|---|---|
| is_syncing | bool | ||
| sync_status | SyncStatus | repeated |
SyncStatus
| Field | Type | Label | Description |
|---|---|---|---|
| peerId | string | ||
| inSync | string | ||
| shouldSync | bool | ||
| divergencePrefix | string | ||
| divergenceSecondsAgo | int32 | ||
| theirMessages | uint64 | ||
| ourMessages | uint64 | ||
| lastBadSync | int64 |
TrieNodePrefix
| Field | Type | Label | Description |
|---|---|---|---|
| prefix | bytes |
SyncIds
| Field | Type | Label | Description |
|---|---|---|---|
| sync_ids | bytes | repeated |
TrieNodeMetadataResponse
| Field | Type | Label | Description |
|---|---|---|---|
| prefix | bytes | ||
| num_messages | uint64 | ||
| hash | string | ||
| children | TrieNodeMetadataResponse | repeated |
TrieNodeSnapshotResponse
| Field | Type | Label | Description |
|---|---|---|---|
| prefix | bytes | ||
| excluded_hashes | string | repeated | |
| num_messages | uint64 | ||
| root_hash | string |
DbStats
| Field | Type | Label | Description |
|---|---|---|---|
| num_messages | uint64 | ||
| num_fid_events | uint64 | ||
| num_fname_events | uint64 |
12. Storage Service
| Method Name | Request Type | Response Type | Description |
|---|---|---|---|
| GetRentRegistryEvents | .RentRegistryEventsRequest | .RentRegistryEventsResponse |
13. Admin Service
| Method Name | Request Type | Response Type | Description |
|---|---|---|---|
| RebuildSyncTrie | .Empty | .Empty | |
| DeleteAllMessagesFromDb | .Empty | .Empty | |
| SubmitOnChainEvent | .OnChainEvent | .IdRegistryEvent |