openapi: 3.1.0
info:
  title: SuperRare Marketplace 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
externalDocs:
  description: SuperRare Developer Documentation
  url: https://developer.superrare.com/
servers:
  - url: https://api.superrare.com
    description: SuperRare Production API
tags:
  - name: NFTs
    description: Search, retrieve, and manage NFT tokens and metadata
  - name: Collections
    description: List, retrieve, and import NFT collections
  - name: Users
    description: Retrieve user profile information
  - name: Tokens
    description: Retrieve token price data
  - name: Merkle Roots
    description: Generate and manage Merkle roots and proofs for batch operations
  - name: Media
    description: Upload and process NFT media assets to IPFS
paths:
  /v1/nfts:
    get:
      summary: List NFTs
      description: Search, filter, and list NFTs with rich query parameters
      operationId: listNfts
      tags:
        - NFTs
      parameters:
        - name: page
          in: query
          schema:
            type: integer
            minimum: 1
            default: 1
        - name: perPage
          in: query
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 20
        - name: q
          in: query
          description: Full-text search query
          schema:
            type: string
        - name: creatorAddress
          in: query
          description: Checksummed Ethereum address of the NFT creator
          schema:
            $ref: '#/components/schemas/EthereumAddress'
        - name: ownerAddress
          in: query
          description: Checksummed Ethereum address of the NFT owner
          schema:
            $ref: '#/components/schemas/EthereumAddress'
        - name: contractAddress
          in: query
          description: Checksummed Ethereum contract address
          schema:
            $ref: '#/components/schemas/EthereumAddress'
        - name: collectionId
          in: query
          schema:
            type: string
        - name: chainId
          in: query
          description: Supported blockchain network id
          schema:
            $ref: '#/components/schemas/ChainId'
        - name: listingType
          in: query
          schema:
            type: string
            enum:
              - SALE_PRICE
              - BATCH_SALE_PRICE
        - name: hasAuction
          in: query
          schema:
            type: boolean
            nullable: true
        - name: auctionState
          in: query
          schema:
            type: string
            enum:
              - PENDING
              - RUNNING
              - UNSETTLED
        - name: auctionType
          in: query
          schema:
            type: string
            enum:
              - RESERVE_AUCTION
              - BATCH_RESERVE_AUCTION
              - SCHEDULED_AUCTION
        - name: auctionCreatorAddress
          in: query
          description: Checksummed Ethereum address of the auction creator
          schema:
            $ref: '#/components/schemas/EthereumAddress'
        - name: auctionBidderAddress
          in: query
          description: Checksummed Ethereum address of the auction bidder
          schema:
            $ref: '#/components/schemas/EthereumAddress'
        - name: hasListing
          in: query
          schema:
            type: boolean
            nullable: true
        - name: hasOffer
          in: query
          schema:
            type: boolean
            nullable: true
        - name: offerBuyerAddress
          in: query
          description: Checksummed Ethereum address of the offer buyer
          schema:
            $ref: '#/components/schemas/EthereumAddress'
        - name: isPrimarySale
          in: query
          schema:
            type: boolean
            nullable: true
        - name: isSecondarySale
          in: query
          schema:
            type: boolean
            nullable: true
        - name: priceMin
          in: query
          schema:
            type: number
            nullable: true
        - name: priceMax
          in: query
          schema:
            type: number
            nullable: true
        - name: currency
          in: query
          description: Checksummed Ethereum address of the currency token
          schema:
            $ref: '#/components/schemas/EthereumAddress'
        - name: mediaType
          in: query
          schema:
            type: string
            enum:
              - AUDIO
              - HTML
              - IMAGE
              - THREE_D
              - VIDEO
        - name: tags
          in: query
          schema:
            oneOf:
              - type: array
                items:
                  type: string
              - type: string
        - name: sortBy
          in: query
          schema:
            type: string
            enum:
              - newest
              - oldest
              - priceAsc
              - priceDesc
              - recentlySold
              - auctionEndingSoon
              - recentActivity
              - bidAsc
              - bidDesc
      responses:
        '200':
          description: List of NFTs
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Nft'
                  pagination:
                    $ref: '#/components/schemas/Pagination'

  /v1/nfts/{universalTokenId}:
    get:
      summary: Get NFT
      description: Get a single NFT by its universal token ID
      operationId: getNft
      tags:
        - NFTs
      parameters:
        - name: universalTokenId
          in: path
          required: true
          description: Canonical NFT identifier in chainId-contractAddress-tokenId format
          schema:
            $ref: '#/components/schemas/UniversalTokenId'
      responses:
        '200':
          description: NFT detail
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/Nft'
        '404':
          description: NFT not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /v1/nfts/{universalTokenId}/events:
    get:
      summary: List NFT events
      description: Get events for a specific NFT
      operationId: listNftEvents
      tags:
        - NFTs
      parameters:
        - name: universalTokenId
          in: path
          required: true
          description: Canonical NFT identifier in chainId-contractAddress-tokenId format
          schema:
            $ref: '#/components/schemas/UniversalTokenId'
        - name: page
          in: query
          schema:
            type: integer
            minimum: 1
            default: 1
        - name: perPage
          in: query
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 20
        - name: eventType
          in: query
          schema:
            type: array
            items:
              type: string
              enum:
                - CANCEL_AUCTION
                - CANCEL_OFFER
                - CLOSE_AUCTION
                - CREATE_NFT
                - CREATE_NFT_SUPPLY
                - CREATE_RESERVE_AUCTION
                - CREATE_SCHEDULED_AUCTION
                - END_AUCTION
                - MAKE_AUCTION_BID
                - MAKE_LISTING
                - MAKE_OFFER
                - SETTLE_AUCTION
                - START_AUCTION
                - TAKE_LISTING
                - TAKE_OFFER
                - TRANSFER_NFT
                - TRANSFER_NFT_SUPPLY
        - name: sortBy
          in: query
          schema:
            type: string
            enum:
              - newest
              - oldest
      responses:
        '200':
          description: List of NFT events
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/NftEvent'
                  pagination:
                    $ref: '#/components/schemas/Pagination'

  /v1/nfts/metadata:
    post:
      summary: Pin NFT Metadata
      description: Assemble NFT metadata JSON from media assets and pin to IPFS via Filebase
      operationId: pinNftMetadata
      tags:
        - Media
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateNftMetadataRequest'
      responses:
        '201':
          description: Metadata pinned to IPFS
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateNftMetadataResponse'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /v1/nfts/metadata/media/uploads:
    post:
      summary: Create Media Upload
      description: >
        Initiate a multipart upload to Filebase/IPFS, returning presigned URLs for each part
      operationId: createMediaUpload
      tags:
        - Media
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateMediaUploadRequest'
      responses:
        '201':
          description: Multipart upload initiated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateMediaUploadResponse'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /v1/nfts/metadata/media/uploads/complete:
    post:
      summary: Complete Media Upload
      description: Complete a multipart upload, resolve IPFS CID, and return IPFS/gateway URLs
      operationId: completeMediaUpload
      tags:
        - Media
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CompleteMediaUploadRequest'
      responses:
        '200':
          description: Upload completed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IpfsUploadResponse'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /v1/nfts/metadata/media/generate:
    post:
      summary: Generate Media Metadata
      description: >
        Call pipelines to extract media metadata (dimensions, size, type) from a URI
      operationId: generateMediaMetadata
      tags:
        - Media
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenerateMediaRequest'
      responses:
        '200':
          description: Media metadata generated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenerateMediaResponse'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /v1/collections:
    get:
      summary: List collections
      description: Search, filter, and list NFT collections
      operationId: listCollections
      tags:
        - Collections
      parameters:
        - name: page
          in: query
          schema:
            type: integer
            minimum: 1
            default: 1
        - name: perPage
          in: query
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 20
        - name: q
          in: query
          description: Full-text search query
          schema:
            type: string
        - name: ownerAddress
          in: query
          description: Checksummed Ethereum address of the collection owner
          schema:
            $ref: '#/components/schemas/EthereumAddress'
        - name: chainId
          in: query
          description: Supported blockchain network id
          schema:
            $ref: '#/components/schemas/ChainId'
        - name: sortBy
          in: query
          schema:
            type: string
            enum:
              - newest
              - oldest
      responses:
        '200':
          description: List of collections
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Collection'
                  pagination:
                    $ref: '#/components/schemas/Pagination'

  /v1/collections/{id}:
    get:
      summary: Get collection
      description: Get a single collection by ID
      operationId: getCollection
      tags:
        - Collections
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Collection detail
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/Collection'
        '404':
          description: Collection not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /v1/collections/{id}/events:
    get:
      summary: List collection events
      description: Get events across all NFTs in a collection
      operationId: listCollectionEvents
      tags:
        - Collections
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
        - name: page
          in: query
          schema:
            type: integer
            minimum: 1
            default: 1
        - name: perPage
          in: query
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 20
        - name: eventType
          in: query
          schema:
            type: array
            items:
              type: string
              enum:
                - CANCEL_AUCTION
                - CANCEL_OFFER
                - CLOSE_AUCTION
                - CREATE_NFT
                - CREATE_NFT_SUPPLY
                - CREATE_RESERVE_AUCTION
                - CREATE_SCHEDULED_AUCTION
                - END_AUCTION
                - MAKE_AUCTION_BID
                - MAKE_LISTING
                - MAKE_OFFER
                - SETTLE_AUCTION
                - START_AUCTION
                - TAKE_LISTING
                - TAKE_OFFER
                - TRANSFER_NFT
                - TRANSFER_NFT_SUPPLY
        - name: sortBy
          in: query
          schema:
            type: string
            enum:
              - newest
              - oldest
      responses:
        '200':
          description: List of collection events
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/NftEvent'
                  pagination:
                    $ref: '#/components/schemas/Pagination'

  /v1/collections/import:
    post:
      summary: Import ERC-721 Collection
      description: >
        Validate an ERC-721 contract on-chain and register it for indexing via pipelines
      operationId: importCollection
      tags:
        - Collections
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ImportCollectionRequest'
      responses:
        '200':
          description: Collection imported or already exists
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ImportCollectionResponse'
        '400':
          description: Validation failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Collection already indexed
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                  collectionId:
                    type: string

  /v1/users/{address}:
    get:
      summary: Get user
      description: Get a user profile by Ethereum address
      operationId: getUser
      tags:
        - Users
      parameters:
        - name: address
          in: path
          required: true
          description: Checksummed Ethereum address
          schema:
            $ref: '#/components/schemas/EthereumAddress'
      responses:
        '200':
          description: User profile
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/UserProfile'
        '404':
          description: User not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /v1/tokens/price/{symbol}:
    get:
      summary: Get Token Price
      description: Fetch the current USD price for a token by symbol (e.g., rare, eth, usdc)
      operationId: getTokenPrice
      tags:
        - Tokens
      parameters:
        - name: symbol
          in: path
          required: true
          description: Token symbol (case-insensitive)
          schema:
            $ref: '#/components/schemas/TokenSymbol'
      responses:
        '200':
          description: Token price
          headers:
            Cache-Control:
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokenPriceResponse'
        '404':
          description: Token not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /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:
    EthereumAddress:
      type: string
      description: Checksummed Ethereum address
      pattern: '^0x[0-9a-fA-F]{40}$'
      example: '0xba5BDe662c17e2aDFF1075610382B9B691296350'

    ChainId:
      type: integer
      description: Supported blockchain network id
      example: 1

    UniversalTokenId:
      type: string
      description: Canonical NFT identifier in chainId-contractAddress-tokenId format
      example: '1-0xb932a70a57673d89f4acffbe830e8ed7f75fb9e0-12345'

    TokenSymbol:
      type: string
      description: Token symbol (case-insensitive)
      example: rare

    ErrorResponse:
      type: object
      properties:
        error:
          type: string

    Pagination:
      type: object
      properties:
        page:
          type: integer
          example: 1
        perPage:
          type: integer
          example: 20
        totalCount:
          type: integer
          example: 100
        totalPages:
          type: integer
          example: 5

    User:
      type: object
      properties:
        address:
          type: string
          example: '0xba5BDe662c17e2aDFF1075610382B9B691296350'
        username:
          type: string
          nullable: true
          example: satoshi
        avatar:
          type: string
          nullable: true
          example: 'https://example.com/avatar.png'
        fullName:
          type: string
          nullable: true
          example: Satoshi Nakamoto

    UserProfile:
      type: object
      properties:
        address:
          type: string
          example: '0xba5BDe662c17e2aDFF1075610382B9B691296350'
        username:
          type: string
          example: satoshi
        fullName:
          type: string
          nullable: true
          example: Satoshi Nakamoto
        stats:
          type: object
          properties:
            created:
              type: integer
              example: 42
            owned:
              type: integer
              example: 15
            followerCount:
              type: integer
              example: 1000
            isCollector:
              type: boolean
              example: true
            isCreator:
              type: boolean
              example: true

    Currency:
      type: object
      properties:
        address:
          type: string
          example: '0x0000000000000000000000000000000000000000'
        symbol:
          type: string
          example: ETH
        decimals:
          type: integer
          example: 18
        chainId:
          type: integer
          example: 1

    CryptoValue:
      type: object
      properties:
        cryptoAmount:
          type: string
          example: '1000000000000000000'
        currency:
          $ref: '#/components/schemas/Currency'
        usdAmount:
          type: number
          nullable: true
          example: 3500

    Listing:
      type: object
      properties:
        contractAddress:
          type: string
          example: '0x1234567890abcdef1234567890abcdef12345678'
        type:
          type: string
          enum:
            - SALE_PRICE
            - BATCH_SALE_PRICE
          example: SALE_PRICE
        price:
          $ref: '#/components/schemas/CryptoValue'
        seller:
          type: string
          example: '0xba5BDe662c17e2aDFF1075610382B9B691296350'
        merkleRoot:
          type: string
          example: '0xcf6398559ea0e93d7d7233ca93b09912da8ff57b45ebe7a3ede9c74d17a76f13'
        allowlist:
          type: object
          nullable: true
          properties:
            root:
              type: string

    Offer:
      type: object
      properties:
        contractAddress:
          type: string
          example: '0x1234567890abcdef1234567890abcdef12345678'
        type:
          type: string
          enum:
            - OFFER
            - BATCH_OFFER
          example: OFFER
        price:
          $ref: '#/components/schemas/CryptoValue'
        buyer:
          $ref: '#/components/schemas/User'
        buyerAddress:
          type: string
          example: '0xba5BDe662c17e2aDFF1075610382B9B691296350'

    Auction:
      type: object
      properties:
        contractAddress:
          type: string
          example: '0x1234567890abcdef1234567890abcdef12345678'
        type:
          type: string
          enum:
            - RESERVE_AUCTION
            - BATCH_RESERVE_AUCTION
            - SCHEDULED_AUCTION
          example: RESERVE_AUCTION
        state:
          type: string
          enum:
            - PENDING
            - RUNNING
            - UNSETTLED
          example: RUNNING
        startTime:
          type: string
          nullable: true
          example: '2024-01-01T00:00:00.000Z'
        endTime:
          type: string
          nullable: true
          example: '2024-01-02T00:00:00.000Z'
        currencyAddress:
          type: string
          example: '0x0000000000000000000000000000000000000000'
        sellerAddress:
          type: string
          example: '0xba5BDe662c17e2aDFF1075610382B9B691296350'
        currentBid:
          $ref: '#/components/schemas/CryptoValue'
        reservePrice:
          $ref: '#/components/schemas/CryptoValue'
        highestBidder:
          $ref: '#/components/schemas/User'
        merkleRoot:
          type: string
          example: '0xcf6398559ea0e93d7d7233ca93b09912da8ff57b45ebe7a3ede9c74d17a76f13'

    LastSale:
      type: object
      nullable: true
      properties:
        eventId:
          type: string
          example: evt_123
        price:
          $ref: '#/components/schemas/CryptoValue'

    Nft:
      type: object
      properties:
        universalTokenId:
          type: string
          example: '1-0xb932a70a57673d89f4acffbe830e8ed7f75fb9e0-12345'
        contractAddress:
          type: string
          example: '0xb932a70a57673d89f4acffbe830e8ed7f75fb9e0'
        chainId:
          type: string
          example: '1'
        tokenId:
          type: string
          example: '12345'
        type:
          type: string
          enum:
            - ERC721
            - ERC1155
          example: ERC721
        creator:
          $ref: '#/components/schemas/User'
        owner:
          $ref: '#/components/schemas/User'
        owners:
          type: array
          items:
            type: object
            properties:
              address:
                type: string
                example: '0xba5BDe662c17e2aDFF1075610382B9B691296350'
              balance:
                type: string
                example: '1'
        metadata:
          type: object
          properties:
            name:
              type: string
              nullable: true
              example: Genesis
            description:
              type: string
              nullable: true
              example: A unique digital artwork
            tags:
              type: array
              items:
                type: string
              example:
                - art
                - digital
            mediaType:
              type: string
              nullable: true
              example: image/png
            imageUri:
              type: string
              nullable: true
              example: 'https://example.com/image.png'
            videoUri:
              type: string
              nullable: true
        market:
          type: object
          properties:
            listings:
              type: array
              items:
                $ref: '#/components/schemas/Listing'
            offers:
              type: array
              items:
                $ref: '#/components/schemas/Offer'
            auctions:
              type: array
              items:
                $ref: '#/components/schemas/Auction'
        lastSale:
          $ref: '#/components/schemas/LastSale'
        attributes:
          type: array
          items:
            type: object
            properties:
              property:
                type: string
                example: Background
              value:
                type: string
                example: Blue
        createdAt:
          type: integer
          example: 1704067200

    NftEvent:
      oneOf:
        - $ref: '#/components/schemas/SaleEvent'
        - $ref: '#/components/schemas/TransferEvent'
        - $ref: '#/components/schemas/CreationEvent'
        - $ref: '#/components/schemas/ListingEvent'
        - $ref: '#/components/schemas/OfferEvent'
        - $ref: '#/components/schemas/AuctionBidEvent'
        - $ref: '#/components/schemas/AuctionLifecycleEvent'
      discriminator:
        propertyName: eventType

    SaleEvent:
      type: object
      properties:
        eventId:
          type: string
          example: evt_123
        createdAt:
          type: string
          example: '2024-01-01T00:00:00.000Z'
        transactionHash:
          type: string
          nullable: true
          example: '0xabc123'
        blockNumber:
          type: integer
          nullable: true
          example: 12345678
        eventType:
          type: string
          enum:
            - SETTLE_AUCTION
            - TAKE_LISTING
            - TAKE_OFFER
        buyer:
          $ref: '#/components/schemas/User'
        seller:
          $ref: '#/components/schemas/User'
        price:
          $ref: '#/components/schemas/CryptoValue'

    TransferEvent:
      type: object
      properties:
        eventId:
          type: string
          example: evt_123
        createdAt:
          type: string
          example: '2024-01-01T00:00:00.000Z'
        transactionHash:
          type: string
          nullable: true
          example: '0xabc123'
        blockNumber:
          type: integer
          nullable: true
          example: 12345678
        eventType:
          type: string
          enum:
            - TRANSFER_NFT
            - TRANSFER_NFT_SUPPLY
        from:
          $ref: '#/components/schemas/User'
        to:
          $ref: '#/components/schemas/User'
        amount:
          type: string
          example: '1'

    CreationEvent:
      type: object
      properties:
        eventId:
          type: string
          example: evt_123
        createdAt:
          type: string
          example: '2024-01-01T00:00:00.000Z'
        transactionHash:
          type: string
          nullable: true
          example: '0xabc123'
        blockNumber:
          type: integer
          nullable: true
          example: 12345678
        eventType:
          type: string
          enum:
            - CREATE_NFT
            - CREATE_NFT_SUPPLY
        creator:
          $ref: '#/components/schemas/User'
        amount:
          type: string
          example: '100'

    ListingEvent:
      type: object
      properties:
        eventId:
          type: string
          example: evt_123
        createdAt:
          type: string
          example: '2024-01-01T00:00:00.000Z'
        transactionHash:
          type: string
          nullable: true
          example: '0xabc123'
        blockNumber:
          type: integer
          nullable: true
          example: 12345678
        eventType:
          type: string
          enum:
            - MAKE_LISTING
        price:
          $ref: '#/components/schemas/CryptoValue'
        targetBuyer:
          $ref: '#/components/schemas/User'

    OfferEvent:
      type: object
      properties:
        eventId:
          type: string
          example: evt_123
        createdAt:
          type: string
          example: '2024-01-01T00:00:00.000Z'
        transactionHash:
          type: string
          nullable: true
          example: '0xabc123'
        blockNumber:
          type: integer
          nullable: true
          example: 12345678
        eventType:
          type: string
          enum:
            - MAKE_OFFER
            - CANCEL_OFFER
        buyer:
          $ref: '#/components/schemas/User'
        price:
          $ref: '#/components/schemas/CryptoValue'

    AuctionBidEvent:
      type: object
      properties:
        eventId:
          type: string
          example: evt_123
        createdAt:
          type: string
          example: '2024-01-01T00:00:00.000Z'
        transactionHash:
          type: string
          nullable: true
          example: '0xabc123'
        blockNumber:
          type: integer
          nullable: true
          example: 12345678
        eventType:
          type: string
          enum:
            - MAKE_AUCTION_BID
        bidder:
          $ref: '#/components/schemas/User'
        price:
          $ref: '#/components/schemas/CryptoValue'
        previousBidder:
          $ref: '#/components/schemas/User'
        extendsAuction:
          type: boolean
          example: false

    AuctionLifecycleEvent:
      type: object
      properties:
        eventId:
          type: string
          example: evt_123
        createdAt:
          type: string
          example: '2024-01-01T00:00:00.000Z'
        transactionHash:
          type: string
          nullable: true
          example: '0xabc123'
        blockNumber:
          type: integer
          nullable: true
          example: 12345678
        eventType:
          type: string
          enum:
            - CREATE_RESERVE_AUCTION
            - CREATE_SCHEDULED_AUCTION
            - START_AUCTION
            - END_AUCTION
            - CANCEL_AUCTION
            - CLOSE_AUCTION
        seller:
          $ref: '#/components/schemas/User'
        buyer:
          $ref: '#/components/schemas/User'
        price:
          $ref: '#/components/schemas/CryptoValue'
        minimumBid:
          $ref: '#/components/schemas/CryptoValue'
        startTime:
          type: string
          nullable: true
          example: '2024-01-01T00:00:00.000Z'

    Collection:
      type: object
      properties:
        collectionId:
          type: string
          example: col_123
        name:
          type: string
          nullable: true
          example: SuperRare Genesis
        description:
          type: string
          nullable: true
          example: The original SuperRare collection
        symbol:
          type: string
          nullable: true
          example: SUPR
        bannerImage:
          type: string
          nullable: true
          example: 'https://example.com/banner.png'
        previewImage:
          type: string
          nullable: true
          example: 'https://example.com/preview.png'
        owner:
          $ref: '#/components/schemas/User'
        stats:
          type: object
          properties:
            tokenCount:
              type: integer
              example: 1000
            collectorCount:
              type: integer
              example: 250
            floorPriceUsd:
              type: number
              nullable: true
              example: 500
            topOfferUsd:
              type: number
              nullable: true
              example: 10000
            saleVolumeUsd:
              type: number
              nullable: true
              example: 5000000
        attributes:
          type: array
          items:
            type: string
          example:
            - Background
            - Eyes
            - Mouth
        chainIds:
          type: array
          items:
            type: integer
          example:
            - 1
        createdAt:
          type: integer
          example: 1704067200

    ImportCollectionRequest:
      type: object
      required:
        - chainId
        - contractAddress
        - ownerAddress
      properties:
        chainId:
          $ref: '#/components/schemas/ChainId'
        contractAddress:
          $ref: '#/components/schemas/EthereumAddress'
        ownerAddress:
          $ref: '#/components/schemas/EthereumAddress'

    ImportCollectionResponse:
      type: object
      properties:
        imported:
          type: boolean
        collection:
          type: object
          properties:
            name:
              type: string
            symbol:
              type: string

    TokenPriceResponse:
      type: object
      properties:
        data:
          type: object
          properties:
            symbol:
              type: string
            priceUsd:
              type: number
            decimals:
              type: integer
            chainId:
              type: integer
            address:
              type: string

    CreateNftMetadataRequest:
      type: object
      required:
        - name
        - description
        - tags
        - nftMedia
      properties:
        name:
          type: string
          example: My NFT
        description:
          type: string
          example: A beautiful artwork
        tags:
          type: array
          items:
            type: string
          example:
            - art
            - digital
        attributes:
          type: array
          items:
            type: object
            properties:
              trait_type:
                type: string
              value:
                oneOf:
                  - type: string
                  - type: number
                  - type: boolean
              display_type:
                type: string
        nftMedia:
          $ref: '#/components/schemas/NftMediaInput'

    NftMediaInput:
      type: object
      required:
        - image
      properties:
        image:
          $ref: '#/components/schemas/MediaAsset'
        video:
          $ref: '#/components/schemas/MediaAsset'
        threeD:
          $ref: '#/components/schemas/MediaAsset'
        html:
          $ref: '#/components/schemas/MediaAsset'

    MediaAsset:
      type: object
      required:
        - url
        - mimeType
        - size
      properties:
        url:
          type: string
          format: uri
          example: 'ipfs://QmExample'
        mimeType:
          type: string
          example: image/png
        size:
          type: integer
          example: 1024000
        dimensions:
          type: object
          properties:
            width:
              type: integer
            height:
              type: integer

    CreateNftMetadataResponse:
      type: object
      properties:
        cid:
          type: string
        ipfsUrl:
          type: string
        gatewayUrl:
          type: string
        metadata:
          type: object
          properties:
            name:
              type: string
            description:
              type: string
            image:
              type: string
            media:
              type: object
              properties:
                uri:
                  type: string
                mimeType:
                  type: string
                size:
                  type: integer
                dimensions:
                  type: string
            animation_url:
              type: string
            tags:
              type: array
              items:
                type: string
            attributes:
              type: array
              items:
                type: object
                properties:
                  trait_type:
                    type: string
                  value:
                    oneOf:
                      - type: string
                      - type: number
                      - type: boolean
                  display_type:
                    type: string

    CreateMediaUploadRequest:
      type: object
      required:
        - fileSize
      properties:
        fileSize:
          type: integer
          example: 5000000
        filename:
          type: string
          example: artwork.png

    CreateMediaUploadResponse:
      type: object
      properties:
        uploadId:
          type: string
          example: abc123
        key:
          type: string
          example: a1b2c3d4/artwork.png
        bucket:
          type: string
          example: superrare-ipfs
        partSize:
          type: integer
          example: 10000000
        presignedUrls:
          type: array
          items:
            type: string
        gatewayBaseUrl:
          type: string
          example: 'https://superrare.myfilebase.com'

    CompleteMediaUploadRequest:
      type: object
      required:
        - key
        - uploadId
        - bucket
        - parts
      properties:
        key:
          type: string
          example: a1b2c3d4/artwork.png
        uploadId:
          type: string
          example: abc123
        bucket:
          type: string
          example: superrare-ipfs
        parts:
          type: array
          items:
            type: object
            properties:
              ETag:
                type: string
              PartNumber:
                type: integer

    IpfsUploadResponse:
      type: object
      properties:
        cid:
          type: string
          example: QmExampleCid
        ipfsUrl:
          type: string
          example: 'ipfs://QmExampleCid'
        gatewayUrl:
          type: string
          example: 'https://superrare.myfilebase.com/ipfs/QmExampleCid'

    GenerateMediaRequest:
      type: object
      required:
        - uri
        - mimeType
      properties:
        uri:
          type: string
          example: 'ipfs://QmMediaCid'
        mimeType:
          type: string
          example: image/png

    GenerateMediaResponse:
      type: object
      properties:
        media:
          type: object
          properties:
            uri:
              type: string
            mimeType:
              type: string
            size:
              type: integer
            dimensions:
              type: string

    MerkleRootStorageTarget:
      type: string
      description: Storage destination for address merkle roots
      enum:
        - batch-listing
        - collection-allowlist
        - both
      default: both
      example: both

    MerkleRootProofStorageTarget:
      type: string
      description: Storage source for address merkle proof generation
      enum:
        - batch-listing
        - collection-allowlist
      default: collection-allowlist
      example: collection-allowlist

    NftMerkleProofContext:
      type: string
      description: Market state context used when resolving a root from Typesense
      enum:
        - batch-listing
        - batch-auction
        - batch-offer
      example: batch-listing

    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'

    GenerateNftMerkleRootResponse:
      type: object
      properties:
        merkleRoot:
          type: string
          example: '0xcf6398559ea0e93d7d7233ca93b09912da8ff57b45ebe7a3ede9c74d17a76f13'
        key:
          type: string
          example: '0xcf6398559ea0e93d7d7233ca93b09912da8ff57b45ebe7a3ede9c74d17a76f13.json'

    GenerateAddressMerkleRootJsonRequest:
      type: object
      required:
        - addresses
      properties:
        addresses:
          type: array
          items:
            $ref: '#/components/schemas/EthereumAddress'
        storageTarget:
          $ref: '#/components/schemas/MerkleRootStorageTarget'

    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

    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'

    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

    GenerateAddressMerkleProofRequest:
      type: object
      required:
        - root
        - address
      properties:
        root:
          type: string
          example: '0xcf6398559ea0e93d7d7233ca93b09912da8ff57b45ebe7a3ede9c74d17a76f13'
        address:
          $ref: '#/components/schemas/EthereumAddress'
        storageTarget:
          $ref: '#/components/schemas/MerkleRootProofStorageTarget'

    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