openapi: 3.1.0
info:
  title: SuperRare Marketplace Collections Merkle Roots API
  description: 'REST API providing programmatic access to SuperRare NFT metadata, artist profiles, auction data, collection information, sales history, and Merkle root/proof flows for batch operations on the SuperRare NFT marketplace built on Ethereum.

    '
  version: 1.0.0
  contact:
    name: SuperRare Support
    url: https://help.superrare.com/
  termsOfService: https://campaigns.superrare.com/terms
  license:
    name: SuperRare Terms of Service
    url: https://campaigns.superrare.com/terms
servers:
- url: https://api.superrare.com
  description: SuperRare Production API
tags:
- name: Merkle Roots
  description: Generate and manage Merkle roots and proofs for batch operations
paths:
  /v1/merkle-roots/nfts:
    post:
      summary: Generate NFT Merkle Root
      description: Generate and store an NFT merkle root via the pipelines service
      operationId: generateNftMerkleRoot
      tags:
      - Merkle Roots
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenerateNftMerkleRootRequest'
      responses:
        '200':
          description: NFT merkle root generated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenerateNftMerkleRootResponse'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '502':
          description: Pipelines request failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /v1/merkle-roots/addresses:
    post:
      summary: Generate Address Merkle Root
      description: Generate and store an address merkle root via the pipelines service
      operationId: generateAddressMerkleRoot
      tags:
      - Merkle Roots
      requestBody:
        required: true
        content:
          application/json:
            schema:
              oneOf:
              - $ref: '#/components/schemas/GenerateAddressMerkleRootJsonRequest'
            examples:
              json:
                summary: JSON request with address list
                value:
                  addresses:
                  - '0xba5BDe662c17e2aDFF1075610382B9B691296350'
                  storageTarget: both
      responses:
        '200':
          description: Address merkle root generated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenerateAddressMerkleRootResponse'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '502':
          description: Pipelines request failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /v1/merkle-roots/nfts/proof:
    post:
      summary: Generate NFT Merkle Proof
      description: 'Resolve an NFT Merkle root and generate a token proof from the stored Merkle list

        '
      operationId: generateNftMerkleProof
      tags:
      - Merkle Roots
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenerateNftMerkleProofRequest'
      responses:
        '200':
          description: NFT Merkle proof generated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenerateNftMerkleProofResponse'
        '404':
          description: Merkle root or NFT entry not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Multiple matching roots were found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /v1/merkle-roots/addresses/proof:
    post:
      summary: Generate Address Merkle Proof
      description: Generate an address proof from a stored Merkle root list
      operationId: generateAddressMerkleProof
      tags:
      - Merkle Roots
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenerateAddressMerkleProofRequest'
      responses:
        '200':
          description: Address Merkle proof generated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenerateAddressMerkleProofResponse'
        '404':
          description: Merkle root or address entry not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Multiple matching roots were found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    GenerateNftMerkleRootRequest:
      type: object
      required:
      - nfts
      properties:
        nfts:
          type: array
          items:
            type: object
            required:
            - contractAddress
            - tokenId
            properties:
              contractAddress:
                $ref: '#/components/schemas/EthereumAddress'
              tokenId:
                oneOf:
                - type: string
                - type: integer
                example: '12345'
    GenerateNftMerkleProofResponse:
      type: object
      properties:
        root:
          type: string
          example: '0xcf6398559ea0e93d7d7233ca93b09912da8ff57b45ebe7a3ede9c74d17a76f13'
        contractAddress:
          type: string
          example: '0x8Db4B93Fa258E1c265d46f861ae9EbDE0B938670'
        tokenId:
          type: string
          example: '12345'
        leaf:
          type: string
          example: '0x83a68bd27e04afae4b40e8647019086ae8b4915bb243a4cf186f6271e1e65341'
        proof:
          type: array
          items:
            type: string
    GenerateAddressMerkleRootJsonRequest:
      type: object
      required:
      - addresses
      properties:
        addresses:
          type: array
          items:
            $ref: '#/components/schemas/EthereumAddress'
        storageTarget:
          $ref: '#/components/schemas/MerkleRootStorageTarget'
    GenerateAddressMerkleProofResponse:
      type: object
      properties:
        root:
          type: string
          example: '0xcf6398559ea0e93d7d7233ca93b09912da8ff57b45ebe7a3ede9c74d17a76f13'
        address:
          type: string
          example: '0x8Db4B93Fa258E1c265d46f861ae9EbDE0B938670'
        leaf:
          type: string
          example: '0x83a68bd27e04afae4b40e8647019086ae8b4915bb243a4cf186f6271e1e65341'
        proof:
          type: array
          items:
            type: string
    GenerateNftMerkleProofRequest:
      type: object
      required:
      - chainId
      - contractAddress
      - tokenId
      properties:
        chainId:
          type: integer
          example: 1
        contractAddress:
          $ref: '#/components/schemas/EthereumAddress'
        tokenId:
          oneOf:
          - type: string
          - type: integer
          example: '12345'
        root:
          type: string
          example: '0xcf6398559ea0e93d7d7233ca93b09912da8ff57b45ebe7a3ede9c74d17a76f13'
        context:
          $ref: '#/components/schemas/NftMerkleProofContext'
        creator:
          $ref: '#/components/schemas/EthereumAddress'
    MerkleRootStorageTarget:
      type: string
      description: Storage destination for address merkle roots
      enum:
      - batch-listing
      - collection-allowlist
      - both
      default: both
      example: both
    NftMerkleProofContext:
      type: string
      description: Market state context used when resolving a root from Typesense
      enum:
      - batch-listing
      - batch-auction
      - batch-offer
      example: batch-listing
    MerkleRootProofStorageTarget:
      type: string
      description: Storage source for address merkle proof generation
      enum:
      - batch-listing
      - collection-allowlist
      default: collection-allowlist
      example: collection-allowlist
    ErrorResponse:
      type: object
      properties:
        error:
          type: string
    GenerateAddressMerkleRootResponse:
      type: object
      properties:
        merkleRoot:
          type: string
          example: '0xcf6398559ea0e93d7d7233ca93b09912da8ff57b45ebe7a3ede9c74d17a76f13'
        locations:
          type: array
          items:
            type: object
            properties:
              storageTarget:
                type: string
                enum:
                - batch-listing
                - collection-allowlist
              bucket:
                type: string
              key:
                type: string
              publicUrl:
                type: string
                format: uri
    GenerateNftMerkleRootResponse:
      type: object
      properties:
        merkleRoot:
          type: string
          example: '0xcf6398559ea0e93d7d7233ca93b09912da8ff57b45ebe7a3ede9c74d17a76f13'
        key:
          type: string
          example: 0xcf6398559ea0e93d7d7233ca93b09912da8ff57b45ebe7a3ede9c74d17a76f13.json
    EthereumAddress:
      type: string
      description: Checksummed Ethereum address
      pattern: ^0x[0-9a-fA-F]{40}$
      example: '0xba5BDe662c17e2aDFF1075610382B9B691296350'
    GenerateAddressMerkleProofRequest:
      type: object
      required:
      - root
      - address
      properties:
        root:
          type: string
          example: '0xcf6398559ea0e93d7d7233ca93b09912da8ff57b45ebe7a3ede9c74d17a76f13'
        address:
          $ref: '#/components/schemas/EthereumAddress'
        storageTarget:
          $ref: '#/components/schemas/MerkleRootProofStorageTarget'
externalDocs:
  description: SuperRare Developer Documentation
  url: https://developer.superrare.com/