openapi: 3.1.0
info:
  title: SuperRare Marketplace Collections NFTs 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: NFTs
  description: Search, retrieve, and manage NFT tokens and metadata
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'
components:
  schemas:
    ChainId:
      type: integer
      description: Supported blockchain network id
      example: 1
    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
    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'
    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'
    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'
    EthereumAddress:
      type: string
      description: Checksummed Ethereum address
      pattern: ^0x[0-9a-fA-F]{40}$
      example: '0xba5BDe662c17e2aDFF1075610382B9B691296350'
    Currency:
      type: object
      properties:
        address:
          type: string
          example: '0x0000000000000000000000000000000000000000'
        symbol:
          type: string
          example: ETH
        decimals:
          type: integer
          example: 18
        chainId:
          type: integer
          example: 1
    LastSale:
      type: object
      nullable: true
      properties:
        eventId:
          type: string
          example: evt_123
        price:
          $ref: '#/components/schemas/CryptoValue'
    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'
    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'
    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'
    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
    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
    CryptoValue:
      type: object
      properties:
        cryptoAmount:
          type: string
          example: '1000000000000000000'
        currency:
          $ref: '#/components/schemas/Currency'
        usdAmount:
          type: number
          nullable: true
          example: 3500
    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
    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'
    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
    UniversalTokenId:
      type: string
      description: Canonical NFT identifier in chainId-contractAddress-tokenId format
      example: 1-0xb932a70a57673d89f4acffbe830e8ed7f75fb9e0-12345
    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
    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'
externalDocs:
  description: SuperRare Developer Documentation
  url: https://developer.superrare.com/