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 Signer API
  version: 3.176.0
servers:
- url: https://api.neynar.com
security:
- ApiKeyAuth: []
tags:
- description: Operations related to signer
  externalDocs:
    description: More info about signer
    url: https://docs.neynar.com/reference/signer-operations
  name: Signer
paths:
  /v2/farcaster/login/authorize/:
    get:
      description: Fetch authorization url (Fetched authorized url useful for SIWN login operation)
      externalDocs:
        url: https://docs.neynar.com/reference/fetch-authorization-url
      operationId: fetch-authorization-url
      parameters:
      - in: query
        name: client_id
        required: true
        schema:
          format: uuid
          type: string
      - in: query
        name: response_type
        required: true
        schema:
          enum:
          - code
          title: AuthorizationUrlResponseType
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthorizationUrlResponse'
          description: Success
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRes'
          description: Bad Request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRes'
          description: Unauthorized
      summary: Fetch authorization url
      tags:
      - Signer
  /v2/farcaster/message/:
    post:
      description: Publish a message to farcaster. The message must be signed by a signer managed by the developer. Use the @farcaster/core library to construct and sign the message. Use the Message.toJSON method on the signed message and pass the JSON in the body of this POST request.
      externalDocs:
        url: https://docs.neynar.com/reference/publish-message-to-farcaster
      operationId: publish-message-to-farcaster
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PublishMessageReqBody'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublishMessageResponse'
          description: Success
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRes'
          description: Bad Request
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRes'
          description: Server Error
      summary: Publish message
      tags:
      - Signer
  /v2/farcaster/signer/:
    get:
      description: Gets information status of a signer by passing in a signer_uuid (Use post API to generate a signer)
      externalDocs:
        url: https://docs.neynar.com/reference/lookup-signer
      operationId: lookup-signer
      parameters:
      - description: 'UUID of the signer.

          `signer_uuid` is paired with API key, can''t use a `uuid` made with a different API key.'
        in: query
        name: signer_uuid
        required: true
        schema:
          example: 19d0c5fd-9b33-4a48-a0e2-bc7b0555baec
          title: SignerUUID
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Signer'
          description: Success
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRes'
          description: Bad Request
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRes'
          description: Forbidden
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRes'
          description: Resource not found
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRes'
          description: Server Error
      summary: Status
      tags:
      - Signer
    post:
      description: "Creates a signer and returns the signer status. \n\n**Note**: While tesing please reuse the signer, it costs money to approve a signer."
      externalDocs:
        url: https://docs.neynar.com/reference/create-signer
      operationId: create-signer
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Signer'
          description: Success
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRes'
          description: Server Error
      summary: Create signer
      tags:
      - Signer
  /v2/farcaster/signer/developer_managed/:
    get:
      description: Fetches the status of a developer managed signer by public key
      externalDocs:
        url: https://docs.neynar.com/reference/lookup-developer-managed-signer
      operationId: lookup-developer-managed-signer
      parameters:
      - description: Ed25519 public key
        in: query
        name: public_key
        required: true
        schema:
          example: '0x3daa8f99c5f760688a3c9f95716ed93dee5ed5d7722d776b7c4deac957755f22'
          pattern: ^0x[a-fA-F0-9]{64}$
          title: Ed25519PublicKey
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeveloperManagedSigner'
          description: Success
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRes'
          description: Bad Request
      summary: Status by public key
      tags:
      - Signer
  /v2/farcaster/signer/developer_managed/signed_key/:
    post:
      description: Registers an signed key and returns the developer managed signer status with an approval url.
      externalDocs:
        url: https://docs.neynar.com/reference/register-signed-key-for-developer-managed-signer
      operationId: register-signed-key-for-developer-managed-signer
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RegisterDeveloperManagedSignedKeyReqBody'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeveloperManagedSigner'
          description: Success
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRes'
          description: Bad Request
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRes'
          description: Server Error
      summary: Register Signed Key
      tags:
      - Signer
  /v2/farcaster/signer/list/:
    get:
      description: Fetches a list of signers for a custody address
      externalDocs:
        url: https://docs.neynar.com/reference/fetch-signers
      operationId: fetch-signers
      parameters:
      - description: A Sign-In with Ethereum (SIWE) message that the user's Ethereum wallet signs. This message includes details such as the domain, address, statement, URI, nonce, and other relevant information following the EIP-4361 standard. It should be structured and URL-encoded.
        in: query
        name: message
        required: true
        schema:
          example: example.com%20wants%20you%20to%20sign%20in%20with%20your%20Ethereum%20account%3A%5Cn0x23A...F232%5Cn%5CnSign%20in%20to%20continue.%5Cn%5CnURI%3A%20example.com%5CnVersion%3A%201%5CnChain%20ID%3A%201%5CnNonce%3A%20xyz123%5CnIssued%20At%3A%202021-09-01T14%3A52%3A07Z
          type: string
      - description: The digital signature produced by signing the provided SIWE message with the user's Ethereum private key. This signature is used to verify the authenticity of the message and the identity of the signer.
        in: query
        name: signature
        required: true
        schema:
          example: 0x25f8...1cf
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SignerListResponse'
          description: Success
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRes'
          description: Bad Request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRes'
          description: Unauthorized
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRes'
          description: Server Error
      summary: List signers
      tags:
      - Signer
  /v2/farcaster/signer/signed_key/:
    post:
      description: Registers an app FID, deadline and a signature. Returns the signer status with an approval url.
      externalDocs:
        url: https://docs.neynar.com/reference/register-signed-key
      operationId: register-signed-key
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RegisterSignerKeyReqBody'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Signer'
          description: Success
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRes'
          description: Bad Request
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRes'
          description: Forbidden
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRes'
          description: Resource not found
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorRes'
          description: Server Error
      summary: Register Signed Key
      tags:
      - Signer
components:
  schemas:
    SharedSignerPermission:
      enum:
      - WRITE_ALL
      - READ_ONLY
      - NONE
      - PUBLISH_CAST
      - DELETE_CAST
      - PUBLISH_REACTION
      - DELETE_REACTION
      - UPDATE_PROFILE
      - FOLLOW_USER
      - UNFOLLOW_USER
      - FOLLOW_CHANNEL
      - UNFOLLOW_CHANNEL
      - ADD_VERIFICATION
      - REMOVE_VERIFICATION
      - WRITE_FRAME_ACTION
      title: SharedSignerPermission
      type: string
    Signer:
      properties:
        fid:
          $ref: '#/components/schemas/Fid'
        object:
          enum:
          - signer
          type: string
        permissions:
          items:
            $ref: '#/components/schemas/SharedSignerPermission'
          type: array
        public_key:
          $ref: '#/components/schemas/Ed25519PublicKey'
        signer_approval_url:
          type: string
        signer_uuid:
          $ref: '#/components/schemas/SignerUUID'
        status:
          enum:
          - generated
          - pending_approval
          - approved
          - revoked
          type: string
      required:
      - signer_uuid
      - public_key
      - status
      title: Signer
      type: object
    PublishMessageResponse:
      properties: {}
      title: PublishMessageResponse
      type: object
    RegisterDeveloperManagedSignedKeyReqBody:
      properties:
        app_fid:
          $ref: '#/components/schemas/Fid'
        deadline:
          description: unix timestamp in seconds that controls how long the signed key request is valid for. (24 hours from now is recommended)
          type: integer
        public_key:
          $ref: '#/components/schemas/Ed25519PublicKey'
        redirect_url:
          description: 'Url to redirect to after the signer is approved.

            **Note** : This should only be used when requesting a signer from a native mobile application.'
          type: string
        signature:
          description: Signature generated by the custody address of the app. Signed data includes app_fid, deadline, signer's public key
          example: '0x7867e84cb6a64bf6e1954e52884133f1114eb3fd97f63ff55fa76c77c80beb6434eea9d3736b59caa3130d63121177acc752dc8a2561e9edf700642f390f92d11b'
          type: string
        sponsor:
          $ref: '#/components/schemas/SignedKeyRequestSponsor'
      required:
      - public_key
      - signature
      - app_fid
      - deadline
      title: RegisterDeveloperManagedSignedKeyReqBody
      type: object
    AuthorizationUrlResponse:
      properties:
        authorization_url:
          format: uri
          type: string
      required:
      - authorization_url
      title: AuthorizationUrlResponse
      type: object
    Ed25519PublicKey:
      description: Ed25519 public key
      example: '0x3daa8f99c5f760688a3c9f95716ed93dee5ed5d7722d776b7c4deac957755f22'
      pattern: ^0x[a-fA-F0-9]{64}$
      title: Ed25519PublicKey
      type: string
    RegisterSignerKeyReqBody:
      properties:
        app_fid:
          $ref: '#/components/schemas/Fid'
        deadline:
          description: unix timestamp in seconds that controls how long the signed key request is valid for. (24 hours from now is recommended)
          type: integer
        redirect_url:
          description: 'Url to redirect to after the signer is approved.

            **Note** : This should only be used when requesting a signer from a native mobile application.'
          type: string
        signature:
          description: Signature generated by the custody address of the app. Signed data includes app_fid, deadline, signer's public key
          type: string
        signer_uuid:
          $ref: '#/components/schemas/SignerUUID'
        sponsor:
          $ref: '#/components/schemas/SignedKeyRequestSponsor'
      required:
      - signer_uuid
      - signature
      - app_fid
      - deadline
      title: RegisterSignerKeyReqBody
      type: object
    SignerListResponse:
      properties:
        signers:
          items:
            $ref: '#/components/schemas/Signer'
          type: array
      required:
      - signers
      title: SignerListResponse
      type: object
    ErrorRes:
      description: Details for the error response
      properties:
        code:
          type: string
        message:
          type: string
        property:
          type: string
        status:
          format: int32
          type: integer
      required:
      - message
      title: ErrorRes
      type: object
    PublishMessageReqBody:
      properties: {}
      title: PublishMessageReqBody
      type: object
    SignerUUID:
      description: 'UUID of the signer.

        `signer_uuid` is paired with API key, can''t use a `uuid` made with a different API key.'
      example: 19d0c5fd-9b33-4a48-a0e2-bc7b0555baec
      title: SignerUUID
      type: string
    SignedKeyRequestSponsor:
      properties:
        fid:
          $ref: '#/components/schemas/Fid'
        signature:
          description: Signature generated by the fid of the sponsor and the signature generated from signKeyRequest for the app.
          type: string
        sponsored_by_neynar:
          description: 'Neynar will sponsor the signer if set to true.

            **Note: ** If sponsor.fid and sponsor.signature are provided along with sponsored_by_neynar set to true,

            the sponsor.fid and sponsor.signature will be ignored.

            Neynar will sponsor the signer on behalf of the user. The developer will get charged in credits.'
          type: boolean
      title: SignedKeyRequestSponsor
      type: object
    DeveloperManagedSigner:
      properties:
        fid:
          $ref: '#/components/schemas/Fid'
        public_key:
          $ref: '#/components/schemas/Ed25519PublicKey'
        signer_approval_url:
          type: string
        status:
          enum:
          - pending_approval
          - approved
          - revoked
          type: string
      required:
      - public_key
      - status
      title: DeveloperManagedSigner
      type: object
    Fid:
      description: The unique identifier of a farcaster user or app (unsigned integer)
      example: 3
      format: int32
      minimum: 0
      title: Fid
      type: integer
  securitySchemes:
    ApiKeyAuth:
      description: API key to authorize requests
      in: header
      name: x-api-key
      type: apiKey
      x-default: NEYNAR_API_DOCS