Neynar Message API

openapi: 3.0.4
info:
  contact:
    email: team@neynar.com
    name: Neynar
    url: https://neynar.com/
  description: The Neynar API allows you to interact with the Farcaster protocol among other things. See the [Neynar docs](https://docs.neynar.com/reference) for more details.
  title: Neynar Action Message API
  version: 3.176.0
servers:
- url: https://api.neynar.com
security:
- ApiKeyAuth: []
tags:
- name: Message
  description: Operations related to messages.
paths:
  /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
components:
  schemas:
    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.
            allOf:
            - $ref: '#/components/schemas/LinkBody'
    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.
            allOf:
            - $ref: '#/components/schemas/VerificationRemoveBody'
    MessageDataUsernameProof:
      allOf:
      - $ref: '#/components/schemas/MessageDataCommon'
      - type: object
        required:
        - usernameProofBody
        properties:
          usernameProofBody:
            $ref: '#/components/schemas/UserNameProof'
    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.'
    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
        castId:
          description: The unique identifier of the cast containing the frame that was interacted with.
          allOf:
          - $ref: '#/components/schemas/CastId'
      required:
      - url
      - buttonIndex
      - castId
    CastEmbed:
      type: object
      properties:
        castId:
          $ref: '#/components/schemas/CastId'
      required:
      - castId
    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
    Embed:
      oneOf:
      - $ref: '#/components/schemas/CastEmbed'
      - $ref: '#/components/schemas/UrlEmbed'
    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
    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
    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
    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
    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.
            allOf:
            - $ref: '#/components/schemas/UserDataBody'
    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
    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).
          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
    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
    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.
            allOf:
            - $ref: '#/components/schemas/VerificationAddEthAddressBody'
    UrlEmbed:
      type: object
      properties:
        url:
          type: string
          format: uri
      required:
      - url
    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
    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
    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
    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'
    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.
            allOf:
            - $ref: '#/components/schemas/ReactionBody'
    UserNameType:
      type: string
      default: USERNAME_TYPE_FNAME
      enum:
      - USERNAME_TYPE_FNAME
      - USERNAME_TYPE_ENS_L1
    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'
    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
    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
    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.
          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
    ValidateMessageResponse:
      type: object
      properties:
        valid:
          type: boolean
        message:
          $ref: '#/components/schemas/Message'
      required:
      - valid
      - message
    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.
            allOf:
            - $ref: '#/components/schemas/CastAddBody'
    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.
            allOf:
            - $ref: '#/components/schemas/FrameActionBody'
    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
    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
          allOf:
          - $ref: '#/components/schemas/FidSchema'
        type:
          $ref: '#/components/schemas/UserNameType'
      required:
      - timestamp
      - name
      - owner
      - signature
      - fid
      - type
    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'
    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
  responses:
    ErrorResponse:
      description: An unexpected error response.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  securitySchemes:
    ApiKeyAuth:
      description: API key to authorize requests
      in: header
      name: x-api-key
      type: apiKey
      x-default: NEYNAR_API_DOCS