openapi.yml

openapi: '3.0.0'
info:
  title: Unlock Locksmith
  version: '2'
  description: Locksmith provides backend functionality for enabling ticketing, metadata storage, and notification hooks.
  license:
    name: MIT

servers:
  - url: https://locksmith.unlock-protocol.com
    description: Production Server
  - url: https://staging-locksmith.unlock-protocol.com
    description: Staging Server

components:
  securitySchemes:
    User:
      type: http
      scheme: bearer
      bearerFormat: JWT

    Application:
      type: apiKey
      name: api-key
      in: query

  schemas:
    Auth:
      required:
        - 'walletAddress'
      type: object
      properties:
        walletAddress:
          type: string
          nullable: false

    AuthResult:
      required:
        - 'accessToken'
        - 'walletAddress'

      type: object
      properties:
        walletAddress:
          type: string
          nullable: true

        accessToken:
          type: string
          nullable: false

    Application:
      type: object
      nullable: false
      properties:
        id:
          type: number
          nullable: false

        name:
          type: string
          nullable: false

        key:
          type: string
          nullable: true

        walletAddress:
          type: string
          nullable: false

    ApplicationBody:
      type: object
      nullable: false
      properties:
        name:
          type: string
          nullable: false

        key:
          type: string
          nullable: true

        walletAddress:
          type: string
          nullable: false

    CheckoutConfig:
      type: object
      required:
        - 'id'
        - 'by'
        - 'config'
        - 'name'
      properties:
        id:
          type: string
        name:
          type: string
        by:
          type: string
        config:
          type: object
          additionalProperties: true

        createdAt:
          type: string
          format: date-time

        updatedAt:
          type: string
          format: date-time

    Verifier:
      type: object
      nullable: false
      properties:
        address:
          type: string
          nullable: false

        lockAddress:
          type: string
          nullable: false

        lockManager:
          type: string
          nullable: false

        network:
          type: integer
          nullable: false

    KeyMetadata:
      type: object
      nullable: false
      properties:
        token:
          type: string
          nullable: false

        lockName:
          type: string
          nullable: false

        lockAddress:
          type: string
          nullable: false

        expiration:
          type: integer
          nullable: false

        keyHolderAddress:
          type: string
          nullable: false

    UserMetadataInput:
      type: object
      nullable: false
      properties:
        public:
          type: object
          nullable: true
          default: {}
          additionalProperties: true

        protected:
          type: object
          nullable: true
          default: {}
          additionalProperties: true

    UserMetadata:
      type: object
      nullable: false
      required:
        - 'lockAddress'
        - 'userAddress'
        - 'metadata'
        - 'network'
      properties:
        network:
          type: integer
          nullable: false

        lockAddress:
          type: string
          nullable: false

        userAddress:
          type: string
          nullable: false

        metadata:
          $ref: '#/components/schemas/UserMetadataInput'

    LockContractOptions:
      type: object
      nullable: false
      properties:
        name:
          type: string

        expirationDuration:
          type: string
          nullable: true

        maxNumberOfKeys:
          type: string
          nullable: true

        keyPrice:
          type: string

        creator:
          type: string
          nullable: true

        currencyContractAddress:
          type: string
          nullable: true

        publicLockVersion:
          type: number
          nullable: true

    NotAuthenticated:
      type: object
      nullable: false
      properties:
        message:
          type: string
          default: 'You are not authorized or authenticated to perform this action.'
          nullable: false

    GenericInvalidBodyError:
      type: object
      nullable: false
      properties:
        message:
          type: string
          default: Response body schema is invalid.
          nullable: false

        error:
          type: string
          nullable: true

    GenericServerError:
      type: object
      nullable: false
      properties:
        message:
          type: string
          default: There was an error in fullfiling the request.
          nullable: false

    GenericSuccess:
      type: object
      nullable: false
      properties:
        message:
          type: string
          default: 'Successfully fulfilled the request.'
          nullable: false

    GenericNotFound:
      type: object
      nullable: false
      properties:
        message:
          type: string
          default: 'resource not found'
          nullable: false

    PaymentMethod:
      type: object
      properties:
        id:
          type: string
        object:
          type: string
        billing_details:
          type: object
          properties:
            address:
              type: object
              properties:
                city:
                  type: string
                  format: nullable
                country:
                  type: string
                line1:
                  type: string
                  format: nullable
                line2:
                  type: string
                  format: nullable
                postal_code:
                  type: string
                  format: nullable
                state:
                  type: string
                  format: nullable
            email:
              type: string
              format: nullable
            name:
              type: string
            phone:
              type: string
              format: nullable
        card:
          type: object
          properties:
            brand:
              type: string
            checks:
              type: object
              properties:
                address_line1_check:
                  type: string
                  format: nullable
                address_postal_code_check:
                  type: string
                  format: nullable
                cvc_check:
                  type: string
            country:
              type: string
            exp_month:
              type: number
            exp_year:
              type: number
            fingerprint:
              type: string
            funding:
              type: string
            generated_from:
              type: string
              format: nullable
            last4:
              type: string
            networks:
              type: object
              properties:
                available:
                  type: array
                  items:
                    type: string
                preferred:
                  type: string
                  format: nullable
            three_d_secure_usage:
              type: object
              properties:
                supported:
                  type: boolean
            wallet:
              type: string
              format: nullable
        created:
          type: number
        customer:
          type: string
        livemode:
          type: boolean
        metadata:
          type: object
          additionalProperties: true

        type:
          type: string

  parameters:
    Network:
      in: path
      name: network
      required: true
      description: Network id.
      schema:
        type: integer

    LockAddress:
      in: path
      name: lockAddress
      required: true
      description: Lock address.
      schema:
        type: string

    UserAddress:
      in: path
      name: userAddress
      required: true
      description: User address.
      schema:
        type: string

    VerifierAddress:
      in: path
      name: verifierAddress
      required: true
      description: User address to use as verifier
      schema:
        type: string

    KeyId:
      in: path
      name: keyId
      required: true
      description: Key Id.
      schema:
        type: string

    Hash:
      in: path
      name: hash
      required: true
      description: Hash
      schema:
        type: string

    TemplateId:
      in: path
      name: template
      required: true
      description: Template id for email
      schema:
        type: string

  responses:
    200.GenericSuccess:
      description: 'Successfully completed the request.'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/GenericSuccess'

    204.Empty:
      description: No response. Request acknowledged.

    400.Invalid:
      description: Invalid input received. Bad request.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/GenericInvalidBodyError'

    401.NotAuthenticated:
      description: User is not authenticated.
      content:
        application:
          schema:
            $ref: '#/components/schemas/GenericServerError'

    403.NotAuthenticatedOrAuthorized:
      description: User is not authorized to perform this action.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/NotAuthenticated'

    404.NotFound:
      description: The item you are making request for does not exist.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/GenericNotFound'

    409.Conflict:
      description: There is a conflict. The resource already exist.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/GenericServerError'

    500.InternalError:
      description: Unable to fullfil request due to internal server error.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/GenericServerError'

paths:
  /v2/auth/nonce:
    get:
      operationId: nonce
      description: 'Provide a unique nonce for using in sign in with ethereum'
      parameters: []
      responses:
        200:
          description: Unique nonce.
          content:
            html/text:
              schema:
                type: string
                nullable: false

        500:
          $ref: '#/components/responses/500.InternalError'

  /v2/auth/login:
    post:
      operationId: login
      description: 'Login as a user using Sign in with Ethereum message signed by the wallet address.'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                message:
                  type: string
                signature:
                  type: string
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthResult'

        400:
          $ref: '#/components/responses/400.Invalid'

        404:
          $ref: '#/components/responses/404.NotFound'

        500:
          $ref: '#/components/responses/500.InternalError'

  /v2/auth/logout:
    post:
      operationId: logout
      security:
        - User: []
      description: Logout from locksmith. This will invalidate all your session tokens.

      responses:
        200:
          $ref: '#/components/responses/200.GenericSuccess'

        500:
          $ref: '#/components/responses/500.InternalError'

  /v2/auth/revoke:
    post:
      operationId: revoke
      security:
        - User: []
      description: Invalidate a session.
      responses:
        200:
          $ref: '#/components/responses/200.GenericSuccess'

        500:
          $ref: '#/components/responses/500.InternalError'

  /v2/auth/user:
    get:
      operationId: user
      description: Get user details.
      security:
        - User: []
      responses:
        200:
          description: Return the user details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Auth'
        500:
          $ref: '#/components/responses/500.InternalError'

  /v2/applications/list:
    get:
      operationId: applications
      security:
        - User: []
      description: List applications created the user.
      responses:
        200:
          description: List of applications owned by the authenticated user.
          content:
            application/json:
              schema:
                type: object
                properties:
                  results:
                    type: array
                    items:
                      $ref: '#/components/schemas/Application'

        403:
          $ref: '#/components/responses/403.NotAuthenticatedOrAuthorized'

        500:
          $ref: '#/components/responses/500.InternalError'

  /v2/applications:
    post:
      operationId: createApplication
      security:
        - User: []
      description: Create application associated with user wallet.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ApplicationBody'

      responses:
        201:
          description: Created application.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Application'

        403:
          $ref: '#/components/responses/403.NotAuthenticatedOrAuthorized'

        400:
          $ref: '#/components/responses/400.Invalid'

        500:
          $ref: '#/components/responses/500.InternalError'

  /v2/applications/:id:
    delete:
      operationId: deleteApplication
      security:
        - User: []

      description: Delete application by id.
      parameters:
        - in: path
          required: true
          schema:
            type: string
          name: id
          description: Application id.
      responses:
        200:
          description: Deleted application.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericSuccess'

        403:
          $ref: '#/components/responses/403.NotAuthenticatedOrAuthorized'

        400:
          $ref: '#/components/responses/400.Invalid'

        404:
          $ref: '#/components/responses/404.NotFound'

        500:
          $ref: '#/components/responses/500.InternalError'

    put:
      parameters:
        - in: path
          required: true
          schema:
            type: string
          name: id
          description: Application id.
      operationId: updateApplication
      security:
        - User: []
      description: Update application by id.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ApplicationBody'
      responses:
        200:
          description: Updated application.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Application'
        403:
          $ref: '#/components/responses/403.NotAuthenticatedOrAuthorized'

        400:
          $ref: '#/components/responses/400.Invalid'

        404:
          $ref: '#/components/responses/404.NotFound'

        500:
          $ref: '#/components/responses/500.InternalError'

  /v2/api/verifier/list/{network}/{lockAddress}:
    get:
      operationId: verifiers
      security:
        - User: ['lockManager']
      description: List of verifiers for the lock address.
      parameters:
        - $ref: '#/components/parameters/Network'
        - $ref: '#/components/parameters/LockAddress'
      responses:
        200:
          description: 'list of verifier address.'
          content:
            application/json:
              schema:
                type: object
                properties:
                  results:
                    type: array
                    items:
                      $ref: '#/components/schemas/Verifier'

        204:
          $ref: '#/components/responses/204.Empty'

        403:
          $ref: '#/components/responses/403.NotAuthenticatedOrAuthorized'

        500:
          $ref: '#/components/responses/500.InternalError'

  /v2/api/verifier/{network}/{lockAddress}/{verifierAddress}:
    put:
      operationId: createVerifier
      security:
        - User: ['lockManager']
      description: Create verifier.
      parameters:
        - $ref: '#/components/parameters/Network'
        - $ref: '#/components/parameters/LockAddress'
        - $ref: '#/components/parameters/VerifierAddress'
      responses:
        201:
          description: Added verifier.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Verifier'

        403:
          $ref: '#/components/responses/403.NotAuthenticatedOrAuthorized'

        409:
          $ref: '#/components/responses/409.Conflict'

        500:
          $ref: '#/components/responses/500.InternalError'

    delete:
      operationId: deleteVerifier
      security:
        - User: []
      description: Remove verifier.
      parameters:
        - $ref: '#/components/parameters/Network'
        - $ref: '#/components/parameters/LockAddress'
        - $ref: '#/components/parameters/VerifierAddress'
      responses:
        200:
          description: List of remaining verifiers.
          content:
            application/json:
              schema:
                type: object
                properties:
                  results:
                    type: array
                    items:
                      $ref: '#/components/schemas/Verifier'
        403:
          $ref: '#/components/responses/403.NotAuthenticatedOrAuthorized'

        404:
          $ref: '#/components/responses/404.NotFound'

        500:
          $ref: '#/components/responses/500.InternalError'

  /v2/api/verifier/{network}/lock/{lockAddress}/address/{verifierAddress}:
    get:
      operationId: verifier
      security:
        - User: ['lockManager']
      description: Check if an address is a verifier of the lock.
      parameters:
        - $ref: '#/components/parameters/Network'
        - $ref: '#/components/parameters/LockAddress'
        - $ref: '#/components/parameters/VerifierAddress'
      responses:
        200:
          description: Address is a verifier on the lock address.
          content:
            application/json:
              schema:
                type: object
                properties:
                  enabled:
                    type: boolean
                    default: true
        403:
          $ref: '#/components/responses/403.NotAuthenticatedOrAuthorized'

        404:
          $ref: '#/components/responses/404.NotFound'

        500:
          $ref: '#/components/responses/500.InternalError'

  /v2/api/ticket/{network}/{lockAddress}/{keyId}/sign:
    get:
      operationId: signTicket
      security:
        - User: ['keyOwner']
      description: Generate signature to prove validity of token.
      parameters:
        - $ref: '#/components/parameters/Network'
        - $ref: '#/components/parameters/LockAddress'
        - $ref: '#/components/parameters/KeyId'
      responses:
        200:
          description: Returns signature and payload.
          content:
            application/json:
              schema:
                type: object
                properties:
                  payload:
                    type: string
                    nullable: false
                  signature:
                    type: string
                    nullable: false
        403:
          $ref: '#/components/responses/403.NotAuthenticatedOrAuthorized'

        404:
          $ref: '#/components/responses/404.NotFound'

        500:
          $ref: '#/components/responses/500.InternalError'

  /v2/api/ticket/{network}/lock/{lockAddress}/key/{keyId}/check:
    put:
      operationId: checkTicket
      security:
        - User: ['Verifier']
      description: Mark a ticket as checked in.
      parameters:
        - $ref: '#/components/parameters/Network'
        - $ref: '#/components/parameters/LockAddress'
        - $ref: '#/components/parameters/KeyId'
      responses:
        202:
          description: Ticket is checked in.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericSuccess'
        403:
          $ref: '#/components/responses/403.NotAuthenticatedOrAuthorized'

        404:
          $ref: '#/components/responses/404.NotFound'

        409:
          $ref: '#/components/responses/409.Conflict'

        500:
          $ref: '#/components/responses/500.InternalError'

  /v2/api/ticket/{network}/{lockAddress}/{keyId}/email:
    post:
      operationId: emailTicket
      security:
        - User: ['LockManager']
      description: Send QR code by email.
      parameters:
        - $ref: '#/components/parameters/Network'
        - $ref: '#/components/parameters/LockAddress'
        - $ref: '#/components/parameters/KeyId'
      responses:
        200:
          description: Email sent.
          content:
            application/json:
              schema:
                type: object
                properties:
                  sent:
                    type: boolean
                    default: true
                    nullable: false
        403:
          $ref: '#/components/responses/403.NotAuthenticatedOrAuthorized'

        404:
          $ref: '#/components/responses/404.NotFound'

        500:
          $ref: '#/components/responses/500.InternalError'

  /v2/api/ticket/{network}/{lockAddress}/{keyId}/qr:
    get:
      operationId: ticketQRCode
      security:
        - User: ['user', 'lockManager']
      description: Get QR code for the key.
      parameters:
        - $ref: '#/components/parameters/Network'
        - $ref: '#/components/parameters/LockAddress'
        - $ref: '#/components/parameters/KeyId'
      responses:
        200:
          description: QR code image.
          content:
            'image/gif':
              schema:
                nullable: true
        403:
          $ref: '#/components/responses/403.NotAuthenticatedOrAuthorized'

        404:
          $ref: '#/components/responses/404.NotFound'

        500:
          $ref: '#/components/responses/500.InternalError'

  /v2/api/ticket/{network}/{lockAddress}/{keyId}/verification:
    get:
      operationId: ticketVerificationUrl
      security:
        - User: ['user', 'lockManager']
      description: Get the verification URL for the key.
      parameters:
        - $ref: '#/components/parameters/Network'
        - $ref: '#/components/parameters/LockAddress'
        - $ref: '#/components/parameters/KeyId'
      responses:
        200:
          description: JSON object containing the verification url
          content:
            application/json:
              schema:
                nullable: false
                type: object
                properties:
                  verificationUrl:
                    type: string
                    nullable: false

        403:
          $ref: '#/components/responses/403.NotAuthenticatedOrAuthorized'

        404:
          $ref: '#/components/responses/404.NotFound'

        500:
          $ref: '#/components/responses/500.InternalError'

  /v2/api/metadata/{network}/locks/{lockAddress}:
    get:
      operationId: lockMetadata
      description: Get metadata for lock address.
      parameters:
        - $ref: '#/components/parameters/Network'
        - $ref: '#/components/parameters/LockAddress'
      responses:
        200:
          description: JSON metadata containing name, description, and custom properties for lock.
          content:
            application/json:
              schema:
                nullable: false
                type: object
                additionalProperties: true

        404:
          $ref: '#/components/responses/404.NotFound'

        500:
          $ref: '#/components/responses/500.InternalError'
    put:
      operationId: updateLockMetadata
      security:
        - User: ['lockManager']
      description: Update or create metadata for lock address.
      parameters:
        - $ref: '#/components/parameters/Network'
        - $ref: '#/components/parameters/LockAddress'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              description: JSON metadata inside metadata field will be saved.
              type: object
              nullable: false
              properties:
                metadata:
                  type: object
                  additionalProperties: true
      responses:
        201:
          description: JSON metadata containing name, description, and custom properties for lock address.
          content:
            application/json:
              schema:
                nullable: false
                type: object
                additionalProperties: true

        204:
          description: JSON metadata containing name, description, and custom properties for lock address.
          content:
            application/json:
              schema:
                nullable: false
                type: object
                additionalProperties: true

        404:
          $ref: '#/components/responses/404.NotFound'

        500:
          $ref: '#/components/responses/500.InternalError'

  /v2/api/metadata/{network}/locks/{lockAddress}/keys/{keyId}:
    get:
      operationId: keyMetadata
      security:
        - User: []
        - {}
      parameters:
        - $ref: '#/components/parameters/Network'
        - $ref: '#/components/parameters/LockAddress'
        - $ref: '#/components/parameters/KeyId'
      description: Get key and user metadata.
      responses:
        200:
          description: JSON metadata containing name, description, custom properties and user metadata if authenticated for a key.
          content:
            application/json:
              schema:
                nullable: false
                type: object
                properties:
                  keyId:
                    type: string
                    nullable: false
                  lockAddress:
                    type: string
                    nullable: false
                  network:
                    type: integer
                    nullable: false
                additionalProperties: true

    put:
      operationId: updateKeyMetadata
      security:
        - User: ['lockManager']
      description: Update or create metadata for key.
      parameters:
        - $ref: '#/components/parameters/Network'
        - $ref: '#/components/parameters/LockAddress'
        - $ref: '#/components/parameters/KeyId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              description: JSON metadata inside metadata field will be saved.
              type: object
              nullable: false
              properties:
                metadata:
                  type: object
                  additionalProperties: true
      responses:
        201:
          description: JSON metadata containing name, description, and custom properties for key.
          content:
            application/json:
              schema:
                nullable: false
                type: object
                additionalProperties: true

        403:
          $ref: '#/components/responses/403.NotAuthenticatedOrAuthorized'

        404:
          $ref: '#/components/responses/404.NotFound'

        500:
          $ref: '#/components/responses/500.InternalError'

  /v2/api/metadata/{network}/locks/{lockAddress}/users/{userAddress}:
    put:
      operationId: updateUserMetadata
      security:
        - User: ['user', 'lockManager']

      description: Update or create user metadata for lock.
      parameters:
        - $ref: '#/components/parameters/Network'
        - $ref: '#/components/parameters/LockAddress'
        - $ref: '#/components/parameters/UserAddress'

      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                metadata:
                  $ref: '#/components/schemas/UserMetadataInput'

      responses:
        204:
          description: Return user metadata saved.
          content:
            application/json:
              schema:
                type: object
                nullable: false
                additionalProperties: true

        400:
          $ref: '#/components/responses/400.Invalid'

        401:
          $ref: '#/components/responses/401.NotAuthenticated'

        404:
          $ref: '#/components/responses/404.NotFound'

        409:
          $ref: '#/components/responses/409.Conflict'

        500:
          $ref: '#/components/responses/500.InternalError'

  /v2/api/metadata/users:
    put:
      operationId: updateUsersMetadata
      security:
        - User: []
        - {}
      description: Update or create user metadata for lock.
      requestBody:
        required: true
        description: users array containing user metadata.
        content:
          application/json:
            schema:
              type: object
              nullable: false
              properties:
                users:
                  type: array
                  items:
                    $ref: '#/components/schemas/UserMetadata'

      responses:
        201:
          description: Array containing user metadata which was created. If the user already has metadata, it will not be updated and present in the array.
          content:
            application/json:
              schema:
                type: object
                nullable: false
                properties:
                  result:
                    type: array
                    items:
                      $ref: '#/components/schemas/UserMetadata'

                  error:
                    description: Array containing user addresses for which metadata was not created.
                    type: array
                    items:
                      type: string
        400:
          $ref: '#/components/responses/400.Invalid'

        404:
          $ref: '#/components/responses/404.NotFound'

        500:
          $ref: '#/components/responses/500.InternalError'

  /v2/api/{network}/locks/{lockAddress}/keys:
    get:
      operationId: keys
      security:
        - User: []
        - Application: []

      description: List of lock keys by network with additional metadata if the caller is the lockManager
      parameters:
        - $ref: '#/components/parameters/Network'
        - $ref: '#/components/parameters/LockAddress'
        - in: query
          name: query
          required: false
          schema:
            type: string
          description: Query you want to search for.
        - in: query
          name: filterKey
          required: false
          schema:
            type: string
          description: The key you want to search on.
        - in: query
          name: expiration
          schema:
            type: string
          description: Expiration time
        - in: query
          name: page
          schema:
            type: integer
          description: Pagination
      responses:
        200:
          description: List of keys matching the query
          content:
            application/json:
              schema:
                nullable: false
                type: array
                items:
                  $ref: '#/components/schemas/KeyMetadata'

        404:
          $ref: '#/components/responses/404.NotFound'

        500:
          $ref: '#/components/responses/500.InternalError'

  /purchase:
    get:
      operationId: balance
      responses:
        200:
          description: Balances for purchaser addresses on each network.
          content:
            application/json:
              schema:
                nullable: false
                type: object
                additionalProperties:
                  type: object
                  nullable: true
                  properties:
                    address:
                      type: string

                    name:
                      type: string

                    balance:
                      type: string
        500:
          $ref: '#/components/responses/500.InternalError'
  /v2/api/{network}/price:
    get:
      operationId: price
      parameters:
        - $ref: '#/components/parameters/Network'

        - in: query
          name: amount
          required: false
          description: Amount of tokens you want to get the price for in USD.
          schema:
            type: number

        - in: query
          name: address
          required: false
          description: The erc20 address you want to get the price for. If nothing is passed, the API will return the native token price.
          schema:
            type: string
      responses:
        200:
          description: Get price for the native token or any erc20 on the network.
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    type: object
                    properties:
                      decimals:
                        type: number
                        nullable: true
                      price:
                        type: number
                      timestamp:
                        type: number
                      symbol:
                        type: string
                      confidence:
                        type: number
                      priceInAmount:
                        type: number
                        nullable: true
        500:
          $ref: '#/components/responses/500.InternalError'

  /v2/api/contracts/{network}/lock:
    post:
      operationId: createLockContract
      security:
        - User: []
        - Application: []

      parameters:
        - $ref: '#/components/parameters/Network'
        - name: captcha
          in: header
          required: true
          description: Recaptcha value to pass.
          schema:
            type: string

      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LockContractOptions'

      responses:
        201:
          description: Transaction hash of the lock creation transaction.
          content:
            application/json:
              schema:
                type: object
                properties:
                  transactionHash:
                    type: string
        404:
          $ref: '#/components/responses/404.NotFound'

        500:
          $ref: '#/components/responses/500.InternalError'

  /v2/purchase/intent/{network}/locks/{lockAddress}:
    post:
      operationId: purchase
      security:
        - User: []
      description: Create purchase intent for stripe.
      parameters:
        - $ref: '#/components/parameters/Network'
        - $ref: '#/components/parameters/LockAddress'

      requestBody:
        required: true
        content:
          application/json:
            schema:
              required:
                - recipients
                - stripeTokenId
                - pricing

              type: object
              properties:
                recipients:
                  type: array
                  items:
                    type: string
                  minItems: 1
                stripeTokenId:
                  type: string
                pricing:
                  type: number
                recurring:
                  type: number
                  nullable: true

      responses:
        200:
          description: Created payment intent client secret, account, and other details.
          content:
            application/json:
              schema:
                type: object
                properties:
                  clientSecret:
                    type: string
                  stripeAccount:
                    type: string
                  totalPriceInDents:
                    type: number
                  pricing:
                    nullable: true
                    type: object
                    properties:
                      keyPrice:
                        type: number
                        nullable: true
                      unlockServiceFee:
                        type: number
                        nullable: true
                      creditCardProcessing:
                        type: number
                        nullable: true
        400:
          $ref: '#/components/responses/400.Invalid'

  /v2/subscriptions/{network}/locks/{lockAddress}/keys/{keyId}:
    delete:
      operationId: cancelSubscription
      description: Cancel a fiat subscription.
      security:
        - User: []
      parameters:
        - $ref: '#/components/parameters/Network'
        - $ref: '#/components/parameters/LockAddress'
        - $ref: '#/components/parameters/KeyId'

      responses:
        204:
          description: Successfully deleted the subscription.

        401:
          $ref: '#/components/responses/401.NotAuthenticated'

    get:
      operationId: getSubscription
      description: Get an active subscription associated with the key. It can be fiat or crypto.
      security:
        - User: []
      parameters:
        - $ref: '#/components/parameters/Network'
        - $ref: '#/components/parameters/LockAddress'
        - $ref: '#/components/parameters/KeyId'

      responses:
        200:
          description: Any active subscription.
          content:
            application/json:
              schema:
                type: object
                properties:
                  subscriptions:
                    type: array
                    items:
                      type: object
                      properties:
                        next:
                          type: number
                          nullable: true

                        balance:
                          type: object
                          properties:
                            symbol:
                              type: string

                            amount:
                              type: string

                            decimals:
                              type: number

                        price:
                          type: object
                          properties:
                            symbol:
                              type: string

                            amount:
                              type: string

                            decimals:
                              type: number

                        approvedRenewals:
                          type: string
                          description: Approved number of renewals by user.

                        possibleRenewals:
                          type: string
                          description: Possible number of renewals based on the user account balance.

                        type:
                          enum:
                            - crypto
                            - fiat
                          description: The type of payment method used for the subscription.
        401:
          $ref: '#/components/responses/401.NotAuthenticated'

  /v2/claim/{network}/locks/{lockAddress}:
    post:
      security:
        - User: []
      operationId: claim
      description: Claim a membership key for a lock. If not authenticated, requires an email in the body.
      parameters:
        - $ref: '#/components/parameters/Network'
        - $ref: '#/components/parameters/LockAddress'
        - name: captcha
          in: header
          required: true
          description: Recaptcha value to pass.
          schema:
            type: string

      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                data:
                  type: string
                email:
                  type: string
                  description: Email address of the recipient

      responses:
        200:
          description: Successfully claimed the key.
          content:
            application/json:
              schema:
                type: object
                properties:
                  transactionHash:
                    type: string
                  owner:
                    type: string

        401:
          $ref: '#/components/responses/401.NotAuthenticated'

  /v2/purchase/setup:
    post:
      operationId: setupPayment
      security:
        - User: []
      description: Setup a payment method for user.

      responses:
        200:
          description: Created setup intent client secret.
          content:
            application/json:
              schema:
                type: object
                properties:
                  clientSecret:
                    type: string

        401:
          $ref: '#/components/responses/401.NotAuthenticated'

  /v2/purchase/list:
    get:
      operationId: listPaymentMethods
      security:
        - User: []
      description: List payment methods for user.
      responses:
        200:
          description: Stripe payment methods for user.
          content:
            application/json:
              schema:
                type: object
                properties:
                  methods:
                    type: array
                    items:
                      $ref: '#/components/schemas/PaymentMethod'
        401:
          $ref: '#/components/responses/401.NotAuthenticated'

  /v2/api/ticket/{network}/lock/{lockAddress}/key/{keyId}/generate:
    get:
      operationId: generateTicket
      security:
        - User: []
      description: Generate a ticket for a key.
      parameters:
        - $ref: '#/components/parameters/Network'
        - $ref: '#/components/parameters/LockAddress'
        - $ref: '#/components/parameters/KeyId'
      responses:
        200:
          description: Successfully generated the ticket.

        401:
          $ref: '#/components/responses/401.NotAuthenticated'

  /v2/api/ticket/{network}/lock/{lockAddress}/key/{keyId}:
    get:
      operationId: getTicket
      security:
        - User: []
      description: get a ticket for a key.
      parameters:
        - $ref: '#/components/parameters/Network'
        - $ref: '#/components/parameters/LockAddress'
        - $ref: '#/components/parameters/KeyId'
      responses:
        200:
          description: Successfully retrieved the ticket.
          content:
            application/json:
              schema:
                nullable: false
                required:
                  - name
                  - lockAddress
                  - keyId
                  - publicLockVersion
                  - userMetadata
                  - isVerifier
                  - attributes
                  - image
                  - description
                  - owner
                  - expiration

                type: object
                properties:
                  keyId:
                    type: string
                  name:
                    type: string
                  owner:
                    type: string
                  lockAddress:
                    type: string
                  image:
                    type: string
                  description:
                    type: string
                  checkedInAt:
                    type: number
                  userMetadata:
                    type: object
                    additionalProperties: true
                  expiration:
                    type: string
                  attributes:
                    type: array
                    items:
                      type: object
                      required:
                        - 'value'
                      properties:
                        trait_type:
                          type: string
                        value:
                          type: string
                        display_type:
                          type: string
                  publicLockVersion:
                    type: string
                  isVerifier:
                    description: Whether the user who requested the ticket can verify the ticket.
                    type: boolean

        401:
          $ref: '#/components/responses/401.NotAuthenticated'

  /{network}/lock/{lockAddress}/stripe:
    delete:
      operationId: disconnectStripe
      security:
        - User: []
      description: Disconnect stripe account.
      parameters:
        - $ref: '#/components/parameters/Network'
        - $ref: '#/components/parameters/LockAddress'
      responses:
        200:
          description: Successfully disconnected stripe account.

        401:
          $ref: '#/components/responses/401.NotAuthenticated'

  /v2/images/upload:
    post:
      operationId: uploadImages
      security:
        - User: []
      description: Upload images to locksmith

      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                images:
                  type: array
                  items:
                    type: string
                    format: binary
      responses:
        201:
          description: Successfully uploaded images.
          content:
            application/json:
              schema:
                type: object
                properties:
                  results:
                    type: array
                    items:
                      type: object
                      properties:
                        url:
                          type: string
                        publicUrl:
                          type: string
                        originamName:
                          type: string
                        mimetype:
                          type: string
                        contentType:
                          type: string
                        size:
                          type: number
                        key:
                          type: string
                        metadata:
                          type: object
                          properties:
                            fieldName:
                              type: string
                            createdBy:
                              type: string
                        encoding:
                          type: string
        401:
          $ref: '#/components/responses/401.NotAuthenticated'

  /v2/transfer/{network}/locks/{lockAddress}/keys/{keyId}:
    post:
      operationId: createTransferCode
      security:
        - User: []
      description: Create a transfer code to transfer an airdropped key to an email address.
      parameters:
        - $ref: '#/components/parameters/Network'
        - $ref: '#/components/parameters/LockAddress'
        - $ref: '#/components/parameters/KeyId'

      responses:
        200:
          description: Successfully created transfer code and sent an email to the recipient.
          content:
            application/json:
              schema:
                type: object
                required:
                  - 'owner'
                  - 'lock'
                  - 'token'
                  - 'deadline'
                  - 'transferCode'
                properties:
                  owner:
                    type: string
                  lock:
                    type: string
                  token:
                    type: string
                  deadline:
                    type: number
                  transferCode:
                    type: string
                    description: Part of the transfer code that is required to be used with the part sent to the recipient.

        404:
          description: Key not found.
          content:
            application/json:
              schema:
                type: object
                required:
                  - 'message'
                properties:
                  message:
                    type: string
        401:
          $ref: '#/components/responses/401.NotAuthenticated'

  /v2/transfer/done:
    post:
      operationId: transferDone
      security:
        - User: []
      description: Finalize the transfer of a key to a recipient. This is to copy over any locksmith related data to the recipient's account.
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - 'transferSignature'
                - 'owner'
                - 'lock'
                - 'token'
                - 'network'
                - 'deadline'
              properties:
                transferSignature:
                  type: string
                  description: The signature of the transfer code sent to the recipient.
                owner:
                  type: string
                lock:
                  type: string
                token:
                  type: string
                network:
                  type: number
                deadline:
                  type: number
      responses:
        200:
          description: Successfully transferred key to recipient.
          content:
            application/json:
              schema:
                type: object
                required:
                  - 'message'
                properties:
                  message:
                    type: string
        403:
          description: Transfer not authorized by locksmith
          content:
            application/json:
              schema:
                type: object
                required:
                  - 'message'
                properties:
                  message:
                    type: string
        404:
          description: Key not found.
          content:
            application/json:
              schema:
                type: object
                required:
                  - 'message'
                properties:
                  message:
                    type: string
        401:
          $ref: '#/components/responses/401.NotAuthenticated'

  /v2/receipts/{network}/{lockAddress}/{hash}:
    get:
      operationId: getReceipt
      security:
        - User: []
      description: Get receipt details
      parameters:
        - $ref: '#/components/parameters/Network'
        - $ref: '#/components/parameters/LockAddress'
        - $ref: '#/components/parameters/Hash'

      responses:
        200:
          description: Successfully receipt details.
          content:
            application/json:
              schema:
                type: object
                properties:
                  purchaser:
                    type: object
                    properties:
                      fullname:
                        type: string
                      businessName:
                        type: string
                      addressLine1:
                        type: string
                      addressLine2:
                        type: string
                      city:
                        type: string
                      state:
                        type: string
                      zip:
                        type: string
                      country:
                        type: string
                  supplier:
                    type: object
                    properties:
                      supplierName:
                        type: string
                      vat:
                        type: string
                      servicePerformed:
                        type: string
                      addressLine1:
                        type: string
                      addressLine2:
                        type: string
                      city:
                        type: string
                      state:
                        type: string
                      zip:
                        type: string
                      country:
                        type: string
                  receipt:
                    type: object
                    properties:
                      id:
                        type: string
                      timestamp:
                        type: number
                      sender:
                        type: string
                      payer:
                        type: string
                      lockAddress:
                        type: string
                      tokenAddress:
                        type: string
                      gasTotal:
                        type: number
                      amountTransferred:
                        type: number

        500:
          description: Failed to retrieve receipt details.
          content:
            application/json:
              schema:
                type: object
                required:
                  - 'message'
                properties:
                  message:
                    type: string
        401:
          $ref: '#/components/responses/401.NotAuthenticated'

        404:
          description: Impossible to retrieve receipt details.

    post:
      operationId: saveReceipt
      security:
        - User: []
      description: Create purchaser details
      parameters:
        - $ref: '#/components/parameters/Network'
        - $ref: '#/components/parameters/LockAddress'
        - $ref: '#/components/parameters/Hash'

      responses:
        200:
          description: Successfully creates purchaser details.
          content:
            application/json:
              schema:
                type: object
                properties:
                  fullname:
                    type: string
                  businessName:
                    type: string
                  addressLine1:
                    type: string
                  addressLine2:
                    type: string
                  city:
                    type: string
                  state:
                    type: string
                  zip:
                    type: string
                  country:
                    type: string

        500:
          description: Failed to update or create purchaser details.
          content:
            application/json:
              schema:
                type: object
                required:
                  - 'message'
                properties:
                  message:
                    type: string
        401:
          $ref: '#/components/responses/401.NotAuthenticated'

  /v2/receipts-base/{network}/{lockAddress}:
    get:
      operationId: getReceiptsBase
      security:
        - User: []
      description: Get supplier details
      parameters:
        - $ref: '#/components/parameters/Network'
        - $ref: '#/components/parameters/LockAddress'

      responses:
        200:
          description: Successfully get supplier details.
          content:
            application/json:
              schema:
                type: object
                properties:
                  supplierName:
                    type: string
                  vat:
                    type: string
                  servicePerformed:
                    type: string
                  addressLine1:
                    type: string
                  addressLine2:
                    type: string
                  city:
                    type: string
                  state:
                    type: string
                  zip:
                    type: string
                  country:
                    type: string

        500:
          description: Failed to retrieve supplier details.
          content:
            application/json:
              schema:
                type: object
                required:
                  - 'message'
                properties:
                  message:
                    type: string
        401:
          $ref: '#/components/responses/401.NotAuthenticated'

        404:
          description: Impossible to retrieve supplier details.

    post:
      operationId: saveReceiptsBase
      security:
        - User: []
      description: Create supplier details.
      parameters:
        - $ref: '#/components/parameters/Network'
        - $ref: '#/components/parameters/LockAddress'

      responses:
        200:
          description: Successfully creates supplier details.
          content:
            application/json:
              schema:
                type: object
                properties:
                  supplierName:
                    type: string
                  vat:
                    type: string
                  servicePerformed:
                    type: string
                  addressLine1:
                    type: string
                  addressLine2:
                    type: string
                  city:
                    type: string
                  state:
                    type: string
                  zip:
                    type: string
                  country:
                    type: string

        500:
          description: Failed to update or create supplier details.
          content:
            application/json:
              schema:
                type: object
                required:
                  - 'message'
                properties:
                  message:
                    type: string
        401:
          $ref: '#/components/responses/401.NotAuthenticated'

  /v2/email/{network}/locks/{lockAddress}/custom/{template}:
    get:
      operationId: getCustomEmailContent
      security:
        - User: []
      description: Get custom email content for a specific template and lock details
      parameters:
        - $ref: '#/components/parameters/Network'
        - $ref: '#/components/parameters/LockAddress'
        - $ref: '#/components/parameters/TemplateId'

      responses:
        200:
          description: Successfully get custom template content
          content:
            application/json:
              schema:
                type: object
                properties:
                  lockAddress:
                    type: string
                  network:
                    type: number
                  template:
                    type: string
                  content:
                    type: string

        500:
          description: Could not get custom email content.
          content:
            application/json:
              schema:
                type: object
                required:
                  - 'message'
                properties:
                  message:
                    type: string
        401:
          $ref: '#/components/responses/401.NotAuthenticated'

        404:
          description: Custom email content not found for this template.

    post:
      operationId: saveCustomEmailContent
      security:
        - User: []
      description: Save custom email content for a specif lock.
      parameters:
        - $ref: '#/components/parameters/Network'
        - $ref: '#/components/parameters/LockAddress'
        - $ref: '#/components/parameters/TemplateId'

      responses:
        200:
          description: Custom email content successfully saved.
          content:
            application/json:
              schema:
                type: object
                properties:
                  lockAddress:
                    type: string
                  network:
                    type: number
                  template:
                    type: string
                  content:
                    type: string

        500:
          description: Could not save custom email content.
          content:
            application/json:
              schema:
                type: object
                required:
                  - 'message'
                properties:
                  message:
                    type: string
        401:
          $ref: '#/components/responses/401.NotAuthenticated'

  /v2/checkout/{id}:
    delete:
      operationId: deleteCheckoutConfig
      security:
        - User: []
      description: Delete a checkout config
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: The id of the checkout config

      responses:
        200:
          description: Checkout config deleted
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string

        401:
          $ref: '#/components/responses/401.NotAuthenticated'
    get:
      operationId: getCheckoutConfig
      security:
        - User: []

      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: The id of the checkout config

      responses:
        200:
          description: Checkout config for the given id
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CheckoutConfig'

        401:
          $ref: '#/components/responses/401.NotAuthenticated'

    put:
      operationId: updateCheckoutConfig
      security:
        - User: []
      description: A new checkout config is created or updated if it already exists
      parameters:
        - name: id
          in: path
          required: true
          schema:
            nullable: true
            type: string
          description: This is optional. If you don't pass an ID, a new config will be created. If you pass an ID, the config will be created.

      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - 'config'
                - 'name'
              properties:
                name:
                  type: string
                config:
                  type: object
                  additionalProperties: true

      responses:
        200:
          description: Checkout config for the updated id.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CheckoutConfig'
        401:
          $ref: '#/components/responses/401.NotAuthenticated'

  /v2/checkout/list:
    get:
      operationId: listCheckoutConfigs
      security:
        - User: []
      description: A list of all checkout configs created by the user

      responses:
        200:
          description: Checkout config for the updated id.
          content:
            application/json:
              schema:
                properties:
                  results:
                    type: array
                    items:
                      $ref: '#/components/schemas/CheckoutConfig'

        401:
          $ref: '#/components/responses/401.NotAuthenticated'

  /v2/purchase/payment-methods:
    delete:
      operationId: removePaymentMethods
      security:
        - User: []
      description: Remove all payment methods for a user
      responses:
        200:
          description: Successfully removed all payment methods
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
        401:
          $ref: '#/components/responses/401.NotAuthenticated'

  /v2/stripe/connect/{network}/locks/{lockAddress}:
    post:
      operationId: connectStripeAccount
      security:
        - User: []
      description: Connect a stripe account to a lock
      parameters:
        - $ref: '#/components/parameters/Network'
        - $ref: '#/components/parameters/LockAddress'
      requestBody:
        content:
          application/json:
            schema:
              required:
                - baseUrl
              type: object
              properties:
                baseUrl:
                  type: string
      responses:
        200:
          description: Successfully connected stripe account
          content:
            application/json:
              schema:
                type: object
                properties:
                  # stripe account links
                  url: # The url to redirect the user to
                    type: string
                  created:
                    type: number
                  expiresAt:
                    type: number
                  object:
                    type: string

        400:
          description: Invalid request
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
        401:
          $ref: '#/components/responses/401.NotAuthenticated'

  /v2/lock-settings/{network}/locks/{lockAddress}:
    get:
      operationId: getLockSettings
      description: Get saved lock settings
      parameters:
        - $ref: '#/components/parameters/Network'
        - $ref: '#/components/parameters/LockAddress'

      responses:
        200:
          description: Successfully get settings for lock
          content:
            application/json:
              schema:
                type: object
                properties:
                  sendEmail:
                    type: boolean

        404:
          description: Setting not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string

        500:
          description: Invalid request
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string

    post:
      operationId: saveLockSetting
      security:
        - User: []
      description: Save lock settings

      parameters:
        - $ref: '#/components/parameters/Network'
        - $ref: '#/components/parameters/LockAddress'

      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                sendEmail:
                  type: boolean

      responses:
        200:
          description: Successfully saved settings for lock
          content:
            application/json:
              schema:
                type: object
                properties:
                  sendEmail:
                    type: boolean

        500:
          description: Invalid request
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
        401:
          $ref: '#/components/responses/401.NotAuthenticated'