openapi: 3.0.4 info: title: Farcaster Hub API version: 2.35.0 description: > Perform basic queries of Farcaster state via the REST API of a Farcaster hub. See the [Neynar docs](https://docs.neynar.com/reference) for more details. contact: name: Neynar url: https://neynar.com/ email: team@neynar.com servers: - url: https://snapchain-api.neynar.com security: - ApiKeyAuth: [] tags: - name: Info description: Operations related to hub information. - name: Casts description: Operations related to casts. - name: Reactions description: Operations related to reactions. - name: Links description: Operations related to links. - name: UserData description: Operations related to user data. - name: Fids description: Operations related to FIDs. - name: Storage description: Operations related to storage limits. - name: Usernames description: Operations related to usernames. - name: Verifications description: Operations related to verifications. - name: OnChainEvents description: Operations related to on-chain events. - name: Message description: Operations related to messages. - name: HubEvents description: Operations related to hub events. paths: /v1/info: get: tags: - Info summary: Sync Methods description: Retrieve hub information. externalDocs: description: Farcaster Hub API url: https://docs.neynar.com/reference/lookup-hub-info operationId: lookup-hub-info parameters: - name: dbstats in: query description: >- Controls whether the response includes database statistics. When true, the response includes information about the hub's database state, storage usage, and performance metrics. required: true schema: type: boolean example: true # Include database statistics responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/HubInfoResponse" default: $ref: "#/components/responses/ErrorResponse" /v1/castById: get: tags: - Casts summary: By FID and Hash description: Lookup a cast by its FID and hash. externalDocs: description: Lookup a cast by its FID and hash url: https://docs.neynar.com/reference/lookup-cast-by-hash-and-fid operationId: lookup-cast-by-hash-and-fid parameters: - name: fid in: query description: The FID of the cast's creator required: true schema: $ref: "#/components/schemas/FidSchema" - name: hash in: query description: >- The unique hash identifier of the cast. This is a 40-character hexadecimal string prefixed with '0x' that uniquely identifies a specific cast in the Farcaster network. required: true schema: pattern: ^0x[0-9a-fA-F]{40}$ type: string example: "0x03aff391a6eb1772b20b4ead9a89f732be75fe27" responses: "200": description: The requested Cast. content: application/json: schema: $ref: "#/components/schemas/CastAdd" default: $ref: "#/components/responses/ErrorResponse" /v1/castsByFid: get: tags: - Casts summary: By FID description: Fetch user's casts. externalDocs: description: Fetch user's casts url: https://docs.neynar.com/reference/fetch-users-casts operationId: fetch-users-casts parameters: - name: fid in: query description: The FID of the casts' creator required: true schema: $ref: "#/components/schemas/FidSchema" - $ref: "#/components/parameters/pageSize" - $ref: "#/components/parameters/paginationReverse" - $ref: "#/components/parameters/pageToken" responses: "200": description: The requested Casts. content: application/json: schema: allOf: - type: object required: - messages properties: messages: type: array items: $ref: "#/components/schemas/CastAdd" - $ref: "#/components/schemas/PaginationResponse" default: $ref: "#/components/responses/ErrorResponse" /v1/castsByMention: get: tags: - Casts summary: Mentioning an FID description: Fetch casts mentioning a user. externalDocs: description: Fetch casts mentioning a user url: https://docs.neynar.com/reference/fetch-casts-mentioning-user operationId: fetch-casts-mentioning-user parameters: - name: fid in: query description: The FID that is mentioned in a cast required: true schema: type: integer example: 3 - $ref: "#/components/parameters/pageSize" - $ref: "#/components/parameters/paginationReverse" - $ref: "#/components/parameters/pageToken" responses: "200": description: The requested Casts. content: application/json: schema: allOf: - type: object required: - messages properties: messages: type: array items: $ref: "#/components/schemas/CastAdd" - $ref: "#/components/schemas/PaginationResponse" default: $ref: "#/components/responses/ErrorResponse" /v1/castsByParent: get: tags: - Casts summary: By parent cast description: >- Retrieve all reply casts (responses) to a specific parent cast in the Farcaster network. Parent casts can be identified using either a combination of FID and hash, or by their URL. This endpoint enables traversal of conversation threads and retrieval of all responses to a particular cast. externalDocs: description: Fetch casts by parent url: https://docs.neynar.com/reference/fetch-casts-by-parent operationId: fetch-casts-by-parent parameters: - name: fid in: query description: >- The Farcaster ID (FID) of the parent cast's creator. This parameter must be used together with the 'hash' parameter to uniquely identify a parent cast. Required only when using hash-based lookup instead of URL-based lookup. The FID is a unique identifier assigned to each Farcaster user. schema: type: integer format: uint64 minimum: 1 example: 194 - name: hash in: query description: >- The unique hash identifier of the parent cast. Must be used together with the 'fid' parameter when doing hash-based lookup. This is a 40-character hexadecimal string prefixed with '0x' that uniquely identifies the cast within the creator's posts. Not required if using URL-based lookup. schema: type: string pattern: ^0x[0-9a-fA-F]{40}$ example: "0x776593353e47dc4e7f4df3199a9b04cc8efa30d9" - name: url in: query description: Cast URL starting with 'chain://' schema: type: string format: uri example: chain://eip155:1/erc721:0x39d89b649ffa044383333d297e325d42d31329b2 - $ref: "#/components/parameters/pageSize" - $ref: "#/components/parameters/paginationReverse" - $ref: "#/components/parameters/pageToken" responses: "200": description: >- A successful response containing all reply casts to the specified parent cast, along with pagination information for traversing large result sets. content: application/json: schema: allOf: - type: object required: - messages properties: messages: description: >- An array of reply casts to the specified parent cast, ordered by oldest first. Each cast includes its content, timestamp, and other metadata. type: array items: $ref: "#/components/schemas/CastAdd" - $ref: "#/components/schemas/PaginationResponse" default: $ref: "#/components/responses/ErrorResponse" /v1/reactionById: get: tags: - Reactions summary: By FID or cast description: Lookup a reaction by its FID or cast. externalDocs: description: Lookup a reaction by its FID or cast url: https://docs.neynar.com/reference/lookup-reaction-by-id operationId: lookup-reaction-by-id parameters: - name: fid in: query description: The FID of the reaction's creator schema: type: integer required: true example: 616 - name: target_fid in: query description: The FID of the cast's creator schema: type: integer required: true example: 616 - name: target_hash in: query description: The cast's hash schema: type: string required: true example: "0xfec8fd3546e1f46cf5ad10a4ff9f5d53a3bbe9be" - name: reaction_type in: query schema: $ref: "#/components/schemas/ReactionType" required: true responses: "200": description: The requested Reaction. content: application/json: schema: $ref: "#/components/schemas/Reaction" default: $ref: "#/components/responses/ErrorResponse" /v1/reactionsByCast: get: tags: - Reactions summary: On cast description: >- Retrieve all reactions (likes or recasts) on a specific cast in the Farcaster network. The cast is identified by its creator's FID and unique hash. This endpoint helps track engagement metrics and user interactions with specific content. externalDocs: description: Fetch reactions on a cast url: https://docs.neynar.com/reference/fetch-cast-reactions operationId: fetch-cast-reactions parameters: - name: target_fid in: query description: >- The FID of the cast's creator. Required to uniquely identify the cast that received the reactions. Must be used in conjunction with target_hash. schema: $ref: "#/components/schemas/FidSchema" required: true - name: target_hash in: query description: >- The unique hash identifier of the cast that received the reactions. This is a 40-character hexadecimal string prefixed with '0x' that uniquely identifies the cast within the creator's posts. Must be used with target_fid. schema: type: string pattern: ^0x[0-9a-fA-F]{40}$ example: "0xfec8fd3546e1f46cf5ad10a4ff9f5d53a3bbe9be" required: true - name: reaction_type in: query schema: $ref: "#/components/schemas/ReactionType" required: true - $ref: "#/components/parameters/pageSize" - $ref: "#/components/parameters/paginationReverse" - $ref: "#/components/parameters/pageToken" responses: "200": description: The requested Reactions. content: application/json: schema: allOf: - type: object required: - messages properties: messages: type: array items: $ref: "#/components/schemas/Reaction" - $ref: "#/components/schemas/PaginationResponse" default: $ref: "#/components/responses/ErrorResponse" /v1/reactionsByFid: get: tags: - Reactions summary: By FID description: Fetch reactions by a user. externalDocs: description: Fetch reactions by a user url: https://docs.neynar.com/reference/fetch-user-reactions operationId: fetch-user-reactions parameters: - name: fid in: query description: The FID of the reaction's creator schema: $ref: "#/components/schemas/FidSchema" required: true - name: reaction_type in: query schema: $ref: "#/components/schemas/ReactionType" required: true - $ref: "#/components/parameters/pageSize" - $ref: "#/components/parameters/paginationReverse" - $ref: "#/components/parameters/pageToken" responses: "200": description: The requested Reactions. content: application/json: schema: allOf: - type: object required: - messages properties: messages: type: array items: $ref: "#/components/schemas/Reaction" - $ref: "#/components/schemas/PaginationResponse" default: $ref: "#/components/responses/ErrorResponse" /v1/reactionsByTarget: get: tags: - Reactions summary: To a target URL description: >- Fetch all reactions of a specific type (like or recast) that target a given URL. This endpoint is useful for tracking engagement with content across the Farcaster network. externalDocs: description: Fetch reactions by a target URL url: https://docs.neynar.com/reference/fetch-reactions-by-target operationId: fetch-reactions-by-target parameters: - name: url in: query description: Target URL starting with 'chain://'. schema: type: string example: chain://eip155:1/erc721:0x39d89b649ffa044383333d297e325d42d31329b2 required: true - name: reaction_type in: query schema: $ref: "#/components/schemas/ReactionType" - $ref: "#/components/parameters/pageSize" - $ref: "#/components/parameters/paginationReverse" - $ref: "#/components/parameters/pageToken" responses: "200": description: The requested Reactions. content: application/json: schema: allOf: - type: object required: - messages properties: messages: type: array items: $ref: "#/components/schemas/Reaction" - $ref: "#/components/schemas/PaginationResponse" default: $ref: "#/components/responses/ErrorResponse" /v1/linkById: get: tags: - Links summary: By its FID and target FID description: Lookup a link by its FID and target FID. externalDocs: description: Lookup a link by its FID and target FID url: https://docs.neynar.com/reference/lookup-user-relation operationId: lookup-user-relation parameters: - name: fid in: query description: The FID of the link's originator required: true schema: $ref: "#/components/schemas/FidSchema" - name: target_fid in: query description: The FID of the target user for this link required: true schema: $ref: "#/components/schemas/FidSchema" - name: link_type in: query required: true schema: $ref: "#/components/schemas/LinkType" responses: "200": description: The requested Link. content: application/json: schema: $ref: "#/components/schemas/LinkAdd" default: $ref: "#/components/responses/ErrorResponse" /v1/linksByFid: get: tags: - Links summary: From source FID description: Fetch a list of users that a user is following. externalDocs: description: Fetch a list of users that a user is following url: https://docs.neynar.com/reference/fetch-user-following operationId: fetch-user-following parameters: - name: fid in: query description: The FID of the link's originator required: true schema: $ref: "#/components/schemas/FidSchema" - name: link_type in: query schema: $ref: "#/components/schemas/LinkType" required: false - $ref: "#/components/parameters/pageSize" - $ref: "#/components/parameters/paginationReverse" - $ref: "#/components/parameters/pageToken" responses: "200": description: The requested Links. content: application/json: schema: allOf: - type: object required: - messages properties: messages: type: array items: $ref: "#/components/schemas/LinkAdd" - $ref: "#/components/schemas/PaginationResponse" default: $ref: "#/components/responses/ErrorResponse" /v1/linksByTargetFid: get: tags: - Links summary: To target FID description: Fetch a list of users that are following a user. externalDocs: description: Fetch a list of users that are following a user url: https://docs.neynar.com/reference/fetch-user-followers operationId: fetch-user-followers parameters: - name: target_fid in: query description: The FID of the target user for this link required: true schema: $ref: "#/components/schemas/FidSchema" - name: link_type in: query schema: $ref: "#/components/schemas/LinkType" required: false - $ref: "#/components/parameters/pageSize" - $ref: "#/components/parameters/paginationReverse" - $ref: "#/components/parameters/pageToken" responses: "200": description: The requested Links. content: application/json: schema: allOf: - type: object required: - messages properties: messages: type: array items: $ref: "#/components/schemas/LinkAdd" - $ref: "#/components/schemas/PaginationResponse" default: $ref: "#/components/responses/ErrorResponse" /v1/userDataByFid: get: tags: - UserData summary: Fetch UserData for a FID description: >- **Note:** one of two different response schemas is returned based on whether the caller provides the `user_data_type` parameter. If included, a single `UserDataAdd` message is returned (or a `not_found` error). If omitted, a paginated list of `UserDataAdd` messages is returned instead. externalDocs: description: Fetch user data for a user url: https://docs.neynar.com/reference/fetch-user-data operationId: fetch-user-data parameters: - name: fid in: query description: The FID that's being requested schema: type: integer required: true example: 3 - name: user_data_type in: query description: >- The type of user data, either as a numerical value or type string. If this is omitted, all user data for the FID is returned schema: $ref: "#/components/schemas/UserDataType" required: false - $ref: "#/components/parameters/pageSize" - $ref: "#/components/parameters/paginationReverse" - $ref: "#/components/parameters/pageToken" responses: "200": description: The requested UserData. content: application/json: schema: oneOf: - $ref: "#/components/schemas/UserDataAdd" - allOf: - type: object required: - messages properties: messages: type: array items: $ref: "#/components/schemas/UserDataAdd" - $ref: "#/components/schemas/PaginationResponse" default: $ref: "#/components/responses/ErrorResponse" /v1/fids: get: tags: - Fids summary: Fetch a list of all the FIDs description: Fetch a list of all the FIDs. externalDocs: description: Fetch a list of all the FIDs url: https://docs.neynar.com/reference/fetch-fids operationId: fetch-fids parameters: - name: shard_id in: query description: The shard ID to filter by schema: type: integer required: true example: 1 - $ref: "#/components/parameters/pageSize" - $ref: "#/components/parameters/paginationReverse" - $ref: "#/components/parameters/pageToken" responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/FidsResponse" default: $ref: "#/components/responses/ErrorResponse" /v1/storageLimitsByFid: get: tags: - Storage summary: FID's limits description: Fetch a user's storage limits. externalDocs: description: Fetch a user's storage limits url: https://docs.neynar.com/reference/lookup-user-storage-limit operationId: lookup-user-storage-limit parameters: - name: fid in: query required: true schema: type: integer example: 3 responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/StorageLimitsResponse" default: $ref: "#/components/responses/ErrorResponse" x-codegen-request-body-name: body /v1/userNameProofsByFid: get: tags: - Usernames summary: Proofs provided by an FID description: Fetch proofs provided by a user. externalDocs: description: Fetch proofs provided by a user url: https://docs.neynar.com/reference/fetch-username-proofs-by-fid operationId: fetch-username-proofs-by-fid parameters: - name: fid in: query schema: type: integer required: true description: The FID being requested example: 616 responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/UsernameProofsResponse" default: $ref: "#/components/responses/ErrorResponse" /v1/userNameProofByName: get: tags: - Usernames summary: Proof for a username description: Fetch a proof for a username. externalDocs: description: Fetch a proof for a username url: https://docs.neynar.com/reference/fetch-username-proof-by-name operationId: fetch-username-proof-by-name parameters: - name: name in: query schema: type: string required: true description: The Farcaster username or ENS address examples: username: value: rish ENS address: value: dwr.eth responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/UserNameProof" default: $ref: "#/components/responses/ErrorResponse" /v1/verificationsByFid: get: tags: - Verifications summary: Provided by an FID description: Fetch verifications provided by a user. externalDocs: description: Fetch verifications provided by a user url: https://docs.neynar.com/reference/fetch-verifications-by-fid operationId: fetch-verifications-by-fid parameters: - name: fid in: query required: true schema: type: integer description: The FID being requested example: 616 - name: address in: query required: false schema: type: string description: The optional ETH address to filter by - $ref: "#/components/parameters/pageSize" - $ref: "#/components/parameters/paginationReverse" - $ref: "#/components/parameters/pageToken" responses: "200": description: The requested Verifications. content: application/json: schema: required: - messages - nextPageToken type: object properties: messages: type: array items: $ref: "#/components/schemas/Verification" nextPageToken: pattern: ^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$ type: string format: byte default: $ref: "#/components/responses/ErrorResponse" x-codegen-request-body-name: body /v1/onChainIdRegistryEventByAddress: get: tags: - OnChainEvents summary: Fetch an on-chain ID Registry Event for a given Address description: Fetch an on-chain ID Registry Event for a given Address. externalDocs: description: Fetch an on-chain ID Registry Event for a given Address url: >- https://docs.neynar.com/reference/lookup-on-chain-id-registry-event-by-address operationId: lookup-on-chain-id-registry-event-by-address parameters: - name: address in: query required: true schema: type: string pattern: ^0x[0-9a-fA-F]{40}$ description: The ETH address being requested example: "0x6b0bda3f2ffed5efc83fa8c024acff1dd45793f1" responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/OnChainEventIdRegister" default: $ref: "#/components/responses/ErrorResponse" /v1/onChainEventsByFid: get: tags: - OnChainEvents summary: Fetch a list of on-chain events provided by an FID description: Fetch on-chain events provided by a user. externalDocs: description: Fetch on-chain events provided by a user url: https://docs.neynar.com/reference/fetch-user-on-chain-events operationId: fetch-user-on-chain-events parameters: - name: fid in: query required: true schema: type: integer description: The FID being requested example: 616 - name: event_type in: query schema: $ref: "#/components/schemas/OnChainEventType" description: The numeric or string value of the event type being requested required: true responses: "200": description: A successful response. content: application/json: schema: type: object properties: events: type: array items: $ref: "#/components/schemas/OnChainEvent" required: - events default: $ref: "#/components/responses/ErrorResponse" /v1/onChainSignersByFid: get: tags: - OnChainEvents summary: Fetch a list of signers provided by an FID description: >- **Note:** one of two different response schemas is returned based on whether the caller provides the `signer` parameter. If included, a single `OnChainEventSigner` message is returned (or a `not_found` error). If omitted, a non-paginated list of `OnChainEventSigner` messages is returned instead. externalDocs: description: Fetch on-chain signers provided by a user url: https://docs.neynar.com/reference/fetch-user-on-chain-signers operationId: fetch-user-on-chain-signers-events parameters: - name: fid in: query required: true schema: type: integer description: The FID being requested example: 616 - name: signer in: query schema: type: string description: The optional key of signer required: false example: "0x0852c07b5695ff94138b025e3f9b4788e06133f04e254f0ea0eb85a06e999cdd" responses: "200": description: A successful response. content: application/json: schema: oneOf: - $ref: "#/components/schemas/OnChainEventSigner" - type: object properties: events: type: array items: $ref: "#/components/schemas/OnChainEventSigner" required: - events default: $ref: "#/components/responses/ErrorResponse" /v1/submitMessage: post: tags: - Message summary: Submit signed message description: Submit a message to the Farcaster network. externalDocs: description: Submit a message to the Farcaster network url: https://docs.neynar.com/reference/submit-signed-message operationId: publish-message requestBody: description: > A Message is a delta operation on the Farcaster network. The message protobuf is an envelope that wraps a MessageData object and contains a hash and signature which can verify its authenticity. content: application/octet-stream: schema: type: string format: binary required: true responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/Message" default: $ref: "#/components/responses/ErrorResponse" x-codegen-request-body-name: body /v1/validateMessage: post: tags: - Message summary: Validate signed message description: Validate a message on the Farcaster network. externalDocs: description: Validate a message on the Farcaster network url: https://docs.neynar.com/reference/validate-message operationId: validate-message requestBody: description: > A Message is a delta operation on the Farcaster network. The message protobuf is an envelope that wraps a MessageData object and contains a hash and signature which can verify its authenticity. content: application/octet-stream: schema: type: string format: binary required: true responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/ValidateMessageResponse" default: $ref: "#/components/responses/ErrorResponse" x-codegen-request-body-name: body /v1/events: get: tags: - HubEvents summary: Page of events description: Fetch a list of events. externalDocs: description: Fetch a list of events url: https://docs.neynar.com/reference/fetch-events operationId: fetch-events parameters: - name: from_event_id in: query required: false schema: type: integer description: | An optional Hub Id to start getting events from. This is also returned from the API as nextPageEventId, which can be used to page through all the Hub events. Set it to 0 to start from the first event. example: 0 responses: "200": description: A successful response. content: application/json: schema: type: object properties: nextPageEventId: type: integer events: type: array items: $ref: "#/components/schemas/HubEvent" required: - nextPageEventId - events default: $ref: "#/components/responses/ErrorResponse" /v1/eventById: get: tags: - HubEvents summary: Event by ID description: Lookup an event by its ID. externalDocs: description: Lookup an event by its ID url: https://docs.neynar.com/reference/lookup-event operationId: lookup-event parameters: - name: event_id in: query required: true schema: type: integer description: The Hub Id of the event responses: "200": description: A successful response. content: application/json: schema: $ref: "#/components/schemas/HubEvent" default: $ref: "#/components/responses/ErrorResponse" components: securitySchemes: ApiKeyAuth: type: apiKey in: header name: x-api-key description: API key to authorize requests x-default: NEYNAR_API_DOCS parameters: pageSize: name: pageSize in: query description: Maximum number of messages to return in a single response schema: type: integer paginationReverse: name: reverse in: query description: Reverse the sort order, returning latest messages first schema: type: boolean pageToken: name: pageToken in: query description: >- The page token returned by the previous query, to fetch the next page. If this parameter is empty, fetch the first page schema: type: string schemas: PaginationResponse: type: object required: - nextPageToken properties: nextPageToken: type: string format: byte pattern: ^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$ description: >- Base64-encoded pagination token for fetching the next page of results. An empty value indicates there are no more pages to return. Used in conjunction with the pageSize parameter to implement pagination across large result sets. example: AuzO1V0DtaItCwwa10X6YsfStlynsGWT CastAdd: allOf: - $ref: "#/components/schemas/MessageCommon" - type: object properties: data: allOf: - $ref: "#/components/schemas/MessageDataCastAdd" - type: object properties: type: $ref: "#/components/schemas/MessageType" required: - type required: - data CastAddBody: description: Adds a new Cast type: object properties: embedsDeprecated: title: URLs to be embedded in the cast type: array items: type: string mentions: title: Fids mentioned in the cast type: array items: type: integer format: uint64 example: 2 parentCastId: $ref: "#/components/schemas/CastId" parentUrl: title: Parent URL type: string example: chain://eip155:1/erc721:0x39d89b649ffa044383333d297e325d42d31329b2 text: title: Text of the cast type: string mentionsPositions: title: Positions of the mentions in the text type: array items: type: integer format: int64 embeds: title: URLs or cast IDs to be embedded in the cast type: array items: $ref: "#/components/schemas/Embed" required: - embedsDeprecated - mentions - text - mentionsPositions - embeds CastEmbed: type: object properties: castId: $ref: "#/components/schemas/CastId" required: - castId CastId: description: >- A unique identifier for a cast (post) in the Farcaster network, consisting of the creator's FID and a hash of the cast's content. This combination ensures global uniqueness across all casts. required: - fid - hash type: object properties: fid: title: Fid of the user who created the cast description: >- The Farcaster ID (FID) of the user who created the cast. Required to uniquely identify the cast's author in the network. type: integer format: uint64 example: 2 hash: $ref: "#/components/schemas/CastHash" CastHash: description: >- A unique hash that identifies a specific cast within the creator's posts. Generated using HASH_SCHEME_BLAKE3 of the cast's content. pattern: ^0x[0-9a-fA-F]{40}$ type: string example: "0x03aff391a6eb1772b20b4ead9a89f732be75fe27" DbStats: required: - numFidEvents - numFnameEvents - numMessages type: object properties: numMessages: type: integer format: uint64 numFidEvents: type: integer format: uint64 numFnameEvents: type: integer format: uint64 Embed: oneOf: - $ref: "#/components/schemas/CastEmbed" - $ref: "#/components/schemas/UrlEmbed" ErrorResponse: required: - code - details - errCode - metadata - name - presentable type: object properties: errCode: type: string presentable: type: boolean name: type: string code: type: integer details: type: string metadata: required: - errcode type: object properties: errcode: type: array items: type: string FarcasterNetwork: type: string description: |- Farcaster network the message is intended for. - FARCASTER_NETWORK_MAINNET: Public primary network - FARCASTER_NETWORK_TESTNET: Public test network - FARCASTER_NETWORK_DEVNET: Private test network default: FARCASTER_NETWORK_MAINNET enum: - FARCASTER_NETWORK_MAINNET - FARCASTER_NETWORK_TESTNET - FARCASTER_NETWORK_DEVNET FidSchema: type: integer format: uint64 minimum: 1 description: > Farcaster ID (FID). A unique identifier assigned to each user in the Farcaster network. This number is permanent and cannot be changed. FIDs are assigned sequentially when users register on the network. example: 1 FidsResponse: allOf: - type: object properties: fids: type: array items: $ref: "#/components/schemas/FidSchema" required: - fids - $ref: "#/components/schemas/PaginationResponse" FrameActionBody: description: >- Contains the data for a user's interaction with a Farcaster Frame. Frames are interactive elements within casts that can have up to 4 clickable buttons, allowing users to engage with content in predefined ways. type: object properties: url: description: >- The URL associated with the frame action. This typically points to the frame's content or the destination that handles the interaction. type: string format: uri example: https://frames.farcaster.xyz/frame/123 buttonIndex: description: >- Identifies which button the user clicked in the frame. Frames can have up to 4 buttons, numbered from 1 to 4. title: Button Index type: integer format: int32 minimum: 1 maximum: 4 example: 1 # Primary action castId: description: "The unique identifier of the cast containing the frame that was interacted with." # Nesting $ref under allOf is necessary for any sibling fields to be effective allOf: - $ref: "#/components/schemas/CastId" required: - url - buttonIndex - castId HashScheme: type: string description: > Type of hashing scheme used to produce a digest of MessageData. - HASH_SCHEME_BLAKE3: Default scheme for hashing MessageData default: HASH_SCHEME_BLAKE3 enum: - HASH_SCHEME_BLAKE3 HubEvent: oneOf: - $ref: "#/components/schemas/HubEventMergeMessage" - $ref: "#/components/schemas/HubEventPruneMessage" - $ref: "#/components/schemas/HubEventRevokeMessage" - $ref: "#/components/schemas/HubEventMergeUsernameProof" - $ref: "#/components/schemas/HubEventMergeOnChainEvent" discriminator: propertyName: type mapping: HUB_EVENT_TYPE_MERGE_MESSAGE: "#/components/schemas/HubEventMergeMessage" HUB_EVENT_TYPE_PRUNE_MESSAGE: "#/components/schemas/HubEventPruneMessage" HUB_EVENT_TYPE_REVOKE_MESSAGE: "#/components/schemas/HubEventRevokeMessage" HUB_EVENT_TYPE_MERGE_USERNAME_PROOF: "#/components/schemas/HubEventMergeUsernameProof" HUB_EVENT_TYPE_MERGE_ON_CHAIN_EVENT: "#/components/schemas/HubEventMergeOnChainEvent" HubEventMergeMessage: type: object properties: type: type: string example: HUB_EVENT_TYPE_MERGE_MESSAGE id: type: integer format: uint64 mergeMessageBody: $ref: "#/components/schemas/MergeMessageBody" required: - type - id - mergeMessageBody HubEventMergeOnChainEvent: type: object properties: type: type: string example: HUB_EVENT_TYPE_MERGE_ON_CHAIN_EVENT id: type: integer format: uint64 mergeOnChainEventBody: $ref: "#/components/schemas/MergeOnChainEventBody" required: - type - id - mergeOnChainEventBody HubEventMergeUsernameProof: type: object properties: type: type: string example: HUB_EVENT_TYPE_MERGE_USERNAME_PROOF id: type: integer format: uint64 mergeUsernameProofBody: $ref: "#/components/schemas/MergeUserNameProofBody" required: - type - id - mergeUsernameProofBody HubEventPruneMessage: type: object properties: type: type: string example: HUB_EVENT_TYPE_PRUNE_MESSAGE id: type: integer format: uint64 pruneMessageBody: $ref: "#/components/schemas/PruneMessageBody" required: - type - id - pruneMessageBody HubEventRevokeMessage: type: object properties: type: type: string example: HUB_EVENT_TYPE_REVOKE_MESSAGE id: type: integer format: uint64 revokeMessageBody: $ref: "#/components/schemas/RevokeMessageBody" required: - type - id - revokeMessageBody HubInfoResponse: title: Response Types for the Sync RPC Methods required: - hubOperatorFid - isSyncing - nickname - peerId - rootHash - version type: object properties: version: type: string isSyncing: type: boolean nickname: type: string rootHash: type: string dbStats: $ref: "#/components/schemas/DbStats" peerId: type: string hubOperatorFid: type: integer format: uint64 IdRegisterEventBody: type: object properties: to: pattern: ^0x[a-fA-F0-9]*$ type: string example: "0x00000000fcd5a8e45785c8a4b9a718c9348e4f18" eventType: $ref: "#/components/schemas/IdRegisterEventType" from: pattern: ^0x[a-fA-F0-9]*$|^$ type: string example: "0x00000000fcd5a8e45785c8a4b9a718c9348e4f18" recoveryAddress: pattern: ^0x[a-fA-F0-9]*$ type: string example: "0x00000000fcd5a8e45785c8a4b9a718c9348e4f18" required: - to - from - eventType - recoveryAddress IdRegisterEventType: type: string default: ID_REGISTER_EVENT_TYPE_REGISTER enum: - ID_REGISTER_EVENT_TYPE_REGISTER - ID_REGISTER_EVENT_TYPE_TRANSFER - ID_REGISTER_EVENT_TYPE_CHANGE_RECOVERY LinkAdd: allOf: - $ref: "#/components/schemas/MessageCommon" - type: object properties: data: allOf: - $ref: "#/components/schemas/MessageDataLink" - type: object properties: type: $ref: "#/components/schemas/MessageType" required: - type required: - data LinkBody: description: >- Defines a social connection between users in the Farcaster network. Currently used to establish following relationships, allowing users to curate their content feed. type: object properties: type: $ref: "#/components/schemas/LinkType" displayTimestamp: title: Original Timestamp description: >- User-defined timestamp that preserves the original creation time when message.data.timestamp needs to be updated for compaction. Useful for maintaining chronological order in user feeds. type: integer format: int64 example: 48994466 targetFid: $ref: "#/components/schemas/FidSchema" required: - type - targetFid LinkType: type: string description: >- Defines the type of social connection between users. - follow: Establishes a following relationship where the user will receive updates from the target user in their feed default: follow enum: - follow example: follow MergeMessageBody: type: object properties: message: $ref: "#/components/schemas/Message" deletedMessages: type: array items: $ref: "#/components/schemas/Message" required: - message - deletedMessages MergeOnChainEventBody: type: object properties: onChainEvent: $ref: "#/components/schemas/OnChainEvent" required: - onChainEvent MergeUserNameProofBody: type: object properties: usernameProof: $ref: "#/components/schemas/UserNameProof" deletedUsernameProof: $ref: "#/components/schemas/UserNameProof" usernameProofMessage: $ref: "#/components/schemas/Message" deletedUsernameProofMessage: $ref: "#/components/schemas/Message" Message: allOf: - type: object properties: data: oneOf: - $ref: "#/components/schemas/MessageDataCastAdd" - $ref: "#/components/schemas/MessageDataCastRemove" - $ref: "#/components/schemas/MessageDataReaction" - $ref: "#/components/schemas/MessageDataLink" - $ref: "#/components/schemas/MessageDataVerificationAdd" - $ref: "#/components/schemas/MessageDataVerificationRemove" - $ref: "#/components/schemas/MessageDataUserDataAdd" - $ref: "#/components/schemas/MessageDataUsernameProof" - $ref: "#/components/schemas/MessageDataFrameAction" discriminator: propertyName: type mapping: MESSAGE_TYPE_CAST_ADD: "#/components/schemas/MessageDataCastAdd" MESSAGE_TYPE_CAST_REMOVE: "#/components/schemas/MessageDataCastRemove" MESSAGE_TYPE_REACTION_ADD: "#/components/schemas/MessageDataReaction" MESSAGE_TYPE_REACTION_REMOVE: "#/components/schemas/MessageDataReaction" MESSAGE_TYPE_LINK_ADD: "#/components/schemas/MessageDataLink" MESSAGE_TYPE_LINK_REMOVE: "#/components/schemas/MessageDataLink" MESSAGE_TYPE_VERIFICATION_ADD_ETH_ADDRESS: "#/components/schemas/MessageDataVerificationAdd" MESSAGE_TYPE_VERIFICATION_REMOVE: "#/components/schemas/MessageDataVerificationRemove" MESSAGE_TYPE_USER_DATA_ADD: "#/components/schemas/MessageDataUserDataAdd" MESSAGE_TYPE_USERNAME_PROOF: "#/components/schemas/MessageDataUsernameProof" MESSAGE_TYPE_FRAME_ACTION: "#/components/schemas/MessageDataFrameAction" required: - data - $ref: "#/components/schemas/MessageCommon" description: >- A Message is a delta operation on the Farcaster network that represents a state change. Messages are the fundamental unit of data in Farcaster and can represent various actions like: - Creating or removing casts (posts) - Adding or removing reactions - Following or unfollowing users - Updating profile data - Verifying Ethereum addresses Each message contains: - A MessageData object with the actual content - A hash of the content for integrity verification - A cryptographic signature to prove authenticity - The signer's public key for verification Messages are immutable once created and form an append-only log of all user actions on the network. MessageCommon: type: object properties: hash: title: Hash digest of data pattern: ^0x[0-9a-fA-F]{40}$ type: string example: "0xd2b1ddc6c88e865a33cb1a565e0058d757042974" hashScheme: $ref: "#/components/schemas/HashScheme" signature: title: Signature of the hash digest pattern: ^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$ type: string format: byte signatureScheme: $ref: "#/components/schemas/SignatureScheme" signer: title: Public key or address of the key pair that produced the signature pattern: ^0x[0-9a-fA-F]+$ type: string required: - hash - hashScheme - signature - signatureScheme - signer MessageDataCastAdd: description: >- Represents a new cast (post) being created in the Farcaster network. A cast can include text content, mentions of other users, embedded URLs, and references to parent posts for replies. allOf: - $ref: "#/components/schemas/MessageDataCommon" - type: object required: - castAddBody properties: castAddBody: description: "The content and metadata of the new cast, including the text, mentions, embeds, and any parent references for replies." # Nesting $ref under allOf is necessary for any sibling fields to be effective allOf: - $ref: "#/components/schemas/CastAddBody" MessageDataCastRemove: description: "Represents a request to remove (delete) a previously created cast. Only the original creator of a cast can remove it." allOf: - $ref: "#/components/schemas/MessageDataCommon" - type: object required: - targetHash properties: targetHash: title: Hash of the cast to remove description: >- The unique hash identifier of the cast to be removed. Must be a cast that was previously created by the same FID specified in the message. pattern: ^0x[0-9a-fA-F]{40}$ type: string example: "0x03aff391a6eb1772b20b4ead9a89f732be75fe27" MessageDataCommon: description: >- Common properties shared by all Farcaster message types. These properties provide essential metadata about the message's origin, timing, and network context. required: - fid - network - timestamp type: object properties: type: $ref: "#/components/schemas/MessageType" fid: title: Farcaster ID of the user producing the message description: >- The unique identifier (FID) of the user who created this message. FIDs are assigned sequentially when users register on the network and cannot be changed. type: integer format: uint64 example: 2 timestamp: description: >- Seconds since Farcaster Epoch (2021-01-01T00:00:00Z). Used to order messages chronologically and determine the most recent state. Must be within 10 minutes of the current time when the message is created. type: integer format: int64 example: 48994466 network: $ref: "#/components/schemas/FarcasterNetwork" MessageDataFrameAction: description: >- Represents a user's interaction with a Farcaster Frame, which is an interactive element embedded within a cast. Frames allow users to engage with content through clickable buttons, creating interactive experiences within the Farcaster network. allOf: - $ref: "#/components/schemas/MessageDataCommon" - type: object required: - frameActionBody properties: frameActionBody: description: "Contains the details of the frame interaction, including which button was pressed and the associated cast and URL." # Nesting $ref under allOf is necessary for any sibling fields to be effective allOf: - $ref: "#/components/schemas/FrameActionBody" MessageDataLink: description: >- Represents a social graph connection between users in the Farcaster network. Currently supports following relationships between users. allOf: - $ref: "#/components/schemas/MessageDataCommon" - type: object required: - linkBody properties: linkBody: description: "Contains the details of the social connection, including the type of relationship and the target user." # Nesting $ref under allOf is necessary for any sibling fields to be effective allOf: - $ref: "#/components/schemas/LinkBody" MessageDataReaction: description: >- Represents a user's reaction to content on the Farcaster network. Reactions can be likes or recasts of casts, allowing users to express appreciation or share content with their followers. allOf: - $ref: "#/components/schemas/MessageDataCommon" - type: object required: - reactionBody properties: reactionBody: description: "Contains the type of reaction (like/recast) and the target content being reacted to. The target can be specified either by castId or URL." # Nesting $ref under allOf is necessary for any sibling fields to be effective allOf: - $ref: "#/components/schemas/ReactionBody" MessageDataUserDataAdd: description: >- Represents a message that updates a user's profile metadata. This can include changes to profile picture, display name, bio, URL, or preferred username. Each update modifies a single profile field. allOf: - $ref: "#/components/schemas/MessageDataCommon" - type: object required: - userDataBody properties: userDataBody: description: "Contains the type of profile metadata being updated and its new value." # Nesting $ref under allOf is necessary for any sibling fields to be effective allOf: - $ref: "#/components/schemas/UserDataBody" MessageDataUsernameProof: allOf: - $ref: "#/components/schemas/MessageDataCommon" - type: object required: - usernameProofBody properties: usernameProofBody: $ref: "#/components/schemas/UserNameProof" MessageDataVerificationAdd: description: >- Represents a message that adds verification of ownership for an Ethereum or Solana address to a user's profile. This verification proves that the user controls the specified blockchain address. allOf: - $ref: "#/components/schemas/MessageDataCommon" - type: object required: - verificationAddEthAddressBody properties: verificationAddEthAddressBody: description: "Contains the blockchain address being verified, along with cryptographic proof of ownership through a signature." # Nesting $ref under allOf is necessary for any sibling fields to be effective allOf: - $ref: "#/components/schemas/VerificationAddEthAddressBody" MessageDataVerificationRemove: description: >- Represents a message that removes an existing blockchain address verification from a user's profile. This allows users to disassociate previously verified addresses from their account. allOf: - $ref: "#/components/schemas/MessageDataCommon" - type: object required: - verificationRemoveBody properties: verificationRemoveBody: description: "Contains the blockchain address for which the verification should be removed from the user's profile." # Nesting $ref under allOf is necessary for any sibling fields to be effective allOf: - $ref: "#/components/schemas/VerificationRemoveBody" MessageType: type: string description: >- Type of the MessageBody. - MESSAGE_TYPE_CAST_ADD: Add a new Cast - MESSAGE_TYPE_CAST_REMOVE: Remove an existing Cast - MESSAGE_TYPE_REACTION_ADD: Add a Reaction to a Cast - MESSAGE_TYPE_REACTION_REMOVE: Remove a Reaction from a Cast - MESSAGE_TYPE_LINK_ADD: Add a new Link - MESSAGE_TYPE_LINK_REMOVE: Remove an existing Link - MESSAGE_TYPE_VERIFICATION_ADD_ETH_ADDRESS: Add a Verification of an Ethereum Address - MESSAGE_TYPE_VERIFICATION_REMOVE: Remove a Verification - MESSAGE_TYPE_USER_DATA_ADD: Add metadata about a user - MESSAGE_TYPE_USERNAME_PROOF: Add or replace a username proof - MESSAGE_TYPE_FRAME_ACTION: A Farcaster Frame action default: MESSAGE_TYPE_CAST_ADD enum: - MESSAGE_TYPE_CAST_ADD - MESSAGE_TYPE_CAST_REMOVE - MESSAGE_TYPE_REACTION_ADD - MESSAGE_TYPE_REACTION_REMOVE - MESSAGE_TYPE_LINK_ADD - MESSAGE_TYPE_LINK_REMOVE - MESSAGE_TYPE_VERIFICATION_ADD_ETH_ADDRESS - MESSAGE_TYPE_VERIFICATION_REMOVE - MESSAGE_TYPE_USER_DATA_ADD - MESSAGE_TYPE_USERNAME_PROOF - MESSAGE_TYPE_FRAME_ACTION OnChainEvent: oneOf: - $ref: "#/components/schemas/OnChainEventSigner" - $ref: "#/components/schemas/OnChainEventSignerMigrated" - $ref: "#/components/schemas/OnChainEventIdRegister" - $ref: "#/components/schemas/OnChainEventStorageRent" discriminator: propertyName: type mapping: EVENT_TYPE_SIGNER: "#/components/schemas/OnChainEventSigner" EVENT_TYPE_SIGNER_MIGRATED: "#/components/schemas/OnChainEventSignerMigrated" EVENT_TYPE_ID_REGISTER: "#/components/schemas/OnChainEventIdRegister" EVENT_TYPE_STORAGE_RENT: "#/components/schemas/OnChainEventStorageRent" OnChainEventCommon: type: object properties: type: type: string example: EVENT_TYPE_SIGNER chainId: type: integer blockNumber: type: integer blockHash: type: string example: "0x75fbbb8b2a4ede67ac350e1b0503c6a152c0091bd8e3ef4a6927d58e088eae28" blockTimestamp: type: integer transactionHash: type: string example: "0x36ef79e6c460e6ae251908be13116ff0065960adb1ae032b4cc65a8352f28952" logIndex: type: integer txIndex: type: integer fid: type: integer required: - type - chainId - blockNumber - blockHash - blockTimestamp - transactionHash - logIndex - txIndex - fid OnChainEventIdRegister: allOf: - $ref: "#/components/schemas/OnChainEventCommon" - type: object properties: idRegisterEventBody: $ref: "#/components/schemas/IdRegisterEventBody" required: - idRegisterEventBody OnChainEventSigner: allOf: - $ref: "#/components/schemas/OnChainEventCommon" - type: object properties: signerEventBody: $ref: "#/components/schemas/SignerEventBody" required: - signerEventBody OnChainEventSignerMigrated: allOf: - $ref: "#/components/schemas/OnChainEventCommon" - type: object properties: signerMigratedEventBody: $ref: "#/components/schemas/SignerMigratedEventBody" required: - signerMigratedEventBody OnChainEventStorageRent: allOf: - $ref: "#/components/schemas/OnChainEventCommon" - type: object properties: storageRentEventBody: $ref: "#/components/schemas/StorageRentEventBody" required: - storageRentEventBody OnChainEventType: type: string default: EVENT_TYPE_SIGNER enum: - EVENT_TYPE_SIGNER - EVENT_TYPE_SIGNER_MIGRATED - EVENT_TYPE_ID_REGISTER - EVENT_TYPE_STORAGE_RENT PruneMessageBody: type: object properties: message: $ref: "#/components/schemas/Message" required: - message Reaction: allOf: - $ref: "#/components/schemas/MessageCommon" - type: object properties: data: allOf: - $ref: "#/components/schemas/MessageDataReaction" - type: object properties: type: $ref: "#/components/schemas/MessageType" required: - type required: - data ReactionBody: description: >- Specifies the details of a reaction to content on Farcaster. A reaction must specify its type (like/recast) and either a target cast ID or URL to react to. Only one target (either castId or URL) should be specified per reaction. type: object properties: type: $ref: "#/components/schemas/ReactionType" targetCastId: description: "The unique identifier of the cast being reacted to. Must be a valid CastId containing the creator's FID and the cast's hash." # Nesting $ref under allOf is necessary for any sibling fields to be effective allOf: - $ref: "#/components/schemas/CastId" targetUrl: title: URL to react to description: >- The URL being reacted to. Used when reacting to external content or when the cast ID is not available. type: string example: https://www.example.com/article required: - type ReactionType: type: string description: >- Type of interaction a user can have with content on the Farcaster network. - Like: Express appreciation for the target content. Similar to "likes" or "favorites" on other platforms. - Recast: Share the target content with the user's followers, similar to a "retweet" or "reblog". Helps increase content visibility. default: Like enum: - Like - Recast example: Like RevokeMessageBody: type: object properties: message: $ref: "#/components/schemas/Message" required: - message SignatureScheme: type: string description: |- Type of signature scheme used to sign the Message hash - SIGNATURE_SCHEME_ED25519: Ed25519 signature (default) - SIGNATURE_SCHEME_EIP712: ECDSA signature using EIP-712 scheme default: SIGNATURE_SCHEME_ED25519 enum: - SIGNATURE_SCHEME_ED25519 - SIGNATURE_SCHEME_EIP712 SignerEventBody: type: object properties: key: pattern: ^0x[a-fA-F0-9]{64}$ type: string keyType: type: integer format: int64 eventType: $ref: "#/components/schemas/SignerEventType" metadata: pattern: ^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$ type: string format: byte metadataType: type: integer format: int64 required: - key - keyType - eventType - metadata - metadataType SignerEventType: type: string default: SIGNER_EVENT_TYPE_ADD enum: - SIGNER_EVENT_TYPE_ADD - SIGNER_EVENT_TYPE_REMOVE - SIGNER_EVENT_TYPE_ADMIN_RESET SignerMigratedEventBody: type: object properties: migratedAt: type: integer format: int64 required: - migratedAt StorageLimit: type: object properties: storeType: $ref: "#/components/schemas/StoreType" limit: type: integer format: uint64 required: - storeType - limit StorageLimitsResponse: type: object properties: limits: type: array items: $ref: "#/components/schemas/StorageLimit" units: type: integer format: uint64 description: Total storage units bought by the user. example: 1 unitDetails: type: object properties: unitType: type: string enum: - UnitTypeLegacy - UnitType2024 unitSize: type: integer format: uint64 example: 1 tier_subscriptions: type: array description: >- List of subscription tiers for the user. Each entry describes a subscription tier and its expiration. items: type: object properties: tier_type: type: string description: The name of the subscription tier enum: - Pro expires_at: type: integer format: int64 description: Expiration time of the subscription tier as a Unix timestamp (seconds since epoch). example: 1749611663 required: - limits - units - unitDetails StorageRentEventBody: type: object properties: payer: pattern: ^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$ type: string format: byte units: type: integer format: int64 expiry: type: integer format: int64 required: - payer - units - expiry StoreType: type: string default: STORE_TYPE_CASTS enum: - STORE_TYPE_CASTS - STORE_TYPE_LINKS - STORE_TYPE_REACTIONS - STORE_TYPE_USER_DATA - STORE_TYPE_VERIFICATIONS - STORE_TYPE_USERNAME_PROOFS UrlEmbed: type: object properties: url: type: string format: uri required: - url UserDataAdd: allOf: - $ref: "#/components/schemas/MessageCommon" - type: object properties: data: allOf: - $ref: "#/components/schemas/MessageDataUserDataAdd" - type: object properties: type: $ref: "#/components/schemas/MessageType" required: - type required: - data UserDataBody: description: >- Contains the data for updating a specific field of a user's profile metadata. Each update operation modifies one profile field at a time, allowing granular control over profile information. type: object properties: type: description: "Specifies which profile field is being updated (e.g., profile picture, display name, bio)." # Nesting $ref under allOf is necessary for any sibling fields to be effective allOf: - $ref: "#/components/schemas/UserDataType" value: title: Profile Field Value description: >- The new value for the specified profile field. The format depends on the type: URLs for profile pictures, plain text for display names and bios, etc. type: string example: https://i.imgur.com/123abc.jpg required: - type - value UserDataType: type: string description: |- Specifies which field of a user's profile is being updated. - USER_DATA_TYPE_PFP: Profile Picture URL for the user's avatar - USER_DATA_TYPE_DISPLAY: Display Name shown on the user's profile - USER_DATA_TYPE_BIO: Biography or description of the user - USER_DATA_TYPE_URL: Website or social media link for the user - USER_DATA_TYPE_USERNAME: Preferred username for the user default: USER_DATA_TYPE_PFP enum: - USER_DATA_TYPE_PFP - USER_DATA_TYPE_DISPLAY - USER_DATA_TYPE_BIO - USER_DATA_TYPE_URL - USER_DATA_TYPE_USERNAME UserNameProof: type: object properties: timestamp: description: Seconds since Unix Epoch which began on Jan 1, 1970 00:00:00 UTC type: integer format: uint64 name: type: string example: neynar owner: pattern: ^0x[0-9a-fA-F]{40}$ type: string signature: pattern: ^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$ type: string format: byte fid: description: "The FID of the user who owns this username proof" # Nesting $ref under allOf is necessary for any sibling fields to be effective allOf: - $ref: "#/components/schemas/FidSchema" type: $ref: "#/components/schemas/UserNameType" required: - timestamp - name - owner - signature - fid - type UsernameProofsResponse: type: object properties: proofs: type: array items: $ref: "#/components/schemas/UserNameProof" required: - proofs UserNameType: type: string default: USERNAME_TYPE_FNAME enum: - USERNAME_TYPE_FNAME - USERNAME_TYPE_ENS_L1 ValidateMessageResponse: type: object properties: valid: type: boolean message: $ref: "#/components/schemas/Message" required: - valid - message Verification: allOf: - $ref: "#/components/schemas/MessageCommon" - type: object properties: data: allOf: - $ref: "#/components/schemas/MessageDataVerificationAdd" - type: object properties: type: $ref: "#/components/schemas/MessageType" required: - type required: - data VerificationAddEthAddressBody: description: >- Contains the data required to verify ownership of an Ethereum or Solana address. The verification process requires a cryptographic signature from the blockchain address and includes the block hash at the time of signing for timestamp verification. type: object properties: address: title: Blockchain Address description: >- The Ethereum (0x-prefixed) or Solana address that the user is claiming ownership of. Must match the address that produced the signature. pattern: ^(?:0x[a-fA-F0-9]{40}|[1-9A-HJ-NP-Za-km-z]{32,44})$ type: string example: "0x1234567890123456789012345678901234567890" ethSignature: title: Cryptographic Signature description: >- Base64-encoded signature produced by the blockchain address, proving ownership. For Ethereum, this is an ECDSA signature of a specific message format. pattern: ^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$ type: string format: byte example: >- 4mGN6TACFqXUVU9RpwLDGCqgqiV1GidEFk9eKF0L0h6JNqmN3kRM9NMPnjUnkh8oL6+jFeQJ9YVuKX4F9EqGiAE= blockHash: title: Block Hash description: >- The hash of the most recent block when the signature was created. Used to verify the approximate time of signature creation. pattern: ^(0x[a-fA-F0-9]{64}|[1-9A-HJ-NP-Za-km-z]{44})$ type: string example: "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef" required: - address - ethSignature - blockHash VerificationRemoveBody: description: >- Contains the data required to remove a previously added blockchain address verification from a user's profile. This operation permanently removes the verification until explicitly re-added. type: object properties: address: title: Blockchain Address description: >- The Ethereum address (0x-prefixed) for which the verification should be removed. Must match a previously verified address in the user's profile. pattern: ^0x[A-Za-z0-9]{40}$ type: string example: "0x1234567890123456789012345678901234567890" required: - address responses: ErrorResponse: description: An unexpected error response. content: application/json: schema: $ref: "#/components/schemas/ErrorResponse"