openapi: 3.0.3
info:
  title: OpenAPI definition Charts NFT Data and Historical Statistics API
  version: v0.1
  description: '# Exciting News


    Hey there, amazing developers! 👋


    We''ve got some fantastic news to share that will make your experience with our product even better. We''re thrilled to announce the implementation of API-Keys, which brings a new level of control and convenience to your development process. So, let''s dive right into the details! ✨


    ## API-Keys for Enhanced Functionality 🔑


    Starting now, we have introduced API-Keys to streamline your interactions with our methods. You might have noticed a slight change while making requests – now, all you need to do is include the parameter `X-API-KEY` in the Header of your request. Simple as that!


    ## Get Your API-Key in a Snap! ⚡️


    Securing your API-Key is a breeze. We''ve made the process super user-friendly to ensure you can get started quickly. Just head over to our website and fill out a simple form. Once you''ve done that, your shiny new API-Key will be delivered straight to your email inbox. Easy peasy! 📧


    [Get Your API-Key Here](https://api.rarible.org/registration)

    [Configure SDK with API-key](https://github.com/rarible/sdk#api-querying)


    ## Unlock the Power of the Rarible Protocol 🔓


    As passionate developers, we know you''re always hungry for knowledge and eager to explore new frontiers. That''s why we invite you to discover the incredible world of the Rarible Protocol. By visiting our dedicated protocol page, you''ll gain access to a treasure trove of useful information, tips, and insights that will elevate your development skills to new heights. 🚀


    [Explore the Rarible Protocol](https://rarible.org)


    So, buckle up and get ready for an enhanced development journey with our API-Keys. We''re excited to see what you''ll create using our revamped system! 💪🚀


    Stay curious, keep innovating, and happy coding! ✨


    [P.S. Join our Discord Server to stay up to date and ask questions](https://discord.gg/rarifoundation)

    '
servers:
- url: https://{environment}.rarible.org
  description: Production (Mainnet)
  variables:
    environment:
      enum:
      - api
      - testnet-api
      default: api
security:
- ApiKeyAuth: []
tags:
- name: NFT Data and Historical Statistics
  x-controller: DataController
paths:
  /v0.1/data/rankings/{entity}/volume:
    get:
      tags:
      - NFT Data and Historical Statistics
      summary: Get user volume
      description: Users (top buyers/sellers) leaderboard. Calculated as traded worth for the period.
      operationId: getUserRankingByVolume
      parameters:
      - name: entity
        in: path
        description: Type of users in leaderboard
        required: true
        schema:
          $ref: '#/components/schemas/OlapUserType'
      - name: blockchain
        in: query
        description: Blockchain
        required: false
        schema:
          $ref: '#/components/schemas/OlapBlockchain'
      - name: source
        in: query
        description: Source
        required: false
        schema:
          $ref: '#/components/schemas/OlapPlatformSource'
      - name: period
        in: query
        description: 'Time period of leaderboard. Default: D7'
        required: false
        schema:
          $ref: '#/components/schemas/OlapLeaderboardPeriod'
      - name: limit
        in: query
        description: Limit of records in leaderboard
        required: false
        schema:
          type: integer
          format: int32
          default: 10
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OlapUserVolumeRankingResponse'
              example:
                result:
                - id: ETHEREUM:0x57f1887a8bf19b14fc0df6fd9b2acc9af147ea85
                  items: 178
                  transactions: 11
                  volumeUsd:
                    currency: USD
                    value: 1000
                  volumeNative:
                    currency: ETH
                    value: 0.75
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OlapError'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OlapError'
  /v0.1/data/rankings/collections/volume:
    get:
      tags:
      - NFT Data and Historical Statistics
      summary: Get NFT Collections volume
      description: Collections leaderboard by trade activity
      operationId: getCollectionRankingByVolume
      parameters:
      - name: source
        in: query
        description: Group of platform used for volume calculation and collection ranging.
        required: false
        schema:
          $ref: '#/components/schemas/OlapTradesLeaderboardSourceGroup'
      - name: blockchain
        in: query
        description: Blockchain
        required: false
        schema:
          $ref: '#/components/schemas/OlapBlockchain'
      - name: ids
        in: query
        description: Collection ids
        required: false
        schema:
          type: array
          items:
            type: string
      - name: period
        in: query
        description: Time period for aggregation
        required: false
        schema:
          $ref: '#/components/schemas/OlapLeaderboardPeriod'
      - name: minFloorPriceNative
        in: query
        description: Show collections which floor price (native currency) more or equal than specified value
        required: false
        schema:
          type: number
          format: bigdecimal
      - name: maxFloorPriceNative
        in: query
        description: Show collections which floor price (native currency) less or equal than specified value
        required: false
        schema:
          type: number
          format: bigdecimal
      - name: sort
        in: query
        description: Collections sorting
        required: false
        schema:
          $ref: '#/components/schemas/OlapTradesLeaderboardSort'
      - name: limit
        in: query
        description: Limit of records in leaderboard
        required: false
        schema:
          type: integer
          format: int32
          default: 10
      - name: continuation
        in: query
        description: Page reference. Taken from previous response
        required: false
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OlapCollectionVolumeRankingResponse'
              example:
                continuation: 45325.07_ETHEREUM:0xe8f88d16f24255fcfab25959705d724406d67d9d
                result:
                - id: ETHEREUM:0xe8f88d16f24255fcfab25959705d724406d67d9d
                  volumeUsd:
                    currency: USD
                    value: 45325.07
                    changePercent: -51.196335
                  volumeNative:
                    currency: ETH
                    value: 23.95
                  itemsBought: 1
                  floorPrice:
                    currency: ETH
                    value: 24.0
                    changePercent: -13.5332
                  listed: 33
                  totalItemSupply: 250
                  ownersCount: 187
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OlapError'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OlapError'
  /v0.1/data/collections/{collection}/transactions:
    get:
      tags:
      - NFT Data and Historical Statistics
      summary: Get NFT Collection tx stats
      description: Get historical statistics about Collection transactions
      operationId: getTransactions
      parameters:
      - name: collection
        in: path
        description: Identifier of collection
        required: true
        schema:
          type: string
      - name: filters
        in: query
        description: Filters of statistics
        required: false
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OlapStatsGraphResponse'
              example:
                historicalDates:
                - '2022-05-05'
                - '2022-05-06'
                - '2022-05-07'
                historicalValues:
                - 3602
                - 2566
                - 285
                currentValue: 260
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OlapError'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OlapError'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OlapError'
  /v0.1/data/collections/{collection}/stats:
    get:
      tags:
      - NFT Data and Historical Statistics
      summary: Get NFT Collection stats
      description: Get general statistics about Collection
      operationId: getCollectionStats
      deprecated: true
      parameters:
      - name: collection
        in: path
        description: Identifier of collection
        required: true
        schema:
          type: string
      - name: currency
        in: query
        description: Currency of statistics
        required: false
        schema:
          $ref: '#/components/schemas/OlapCurrencyType'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OlapGeneralStatsResponse'
              example:
                highestSale: 43.71
                floorPrice: 1.45
                marketCap: 14529
                items: 10020
                owners: 6472
                volume: 41913.50477591493
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OlapError'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OlapError'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OlapError'
  /v0.1/data/collections/{collection}/statistics:
    get:
      tags:
      - NFT Data and Historical Statistics
      summary: Get NFT Collection statistics
      description: Get statistics about a collection
      operationId: getCollectionStatistics
      parameters:
      - name: collection
        in: path
        description: Identifier of collection
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OlapCollectionStatisticsResponse'
              example:
                listed: 5
                items: 10020
                owners: 6472
                highestSale:
                - currency: USD
                  value: 37.66
                - currency: ETH
                  value: 0.009
                floorPrice:
                - currency: USD
                  value: 2635
                - currency: ETH
                  value: 1
                marketCap:
                - currency: USD
                  value: 12195397
                - currency: ETH
                  value: 4627
                volume:
                - currency: USD
                  value: 37.66
                - currency: ETH
                  value: 0.009
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OlapError'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OlapError'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OlapError'
  /v0.1/data/collections/{collection}/sellers:
    get:
      tags:
      - NFT Data and Historical Statistics
      summary: Get NFT Collection seller stats
      description: Get historical statistics about Collection sellers
      operationId: getSellers
      parameters:
      - name: collection
        in: path
        description: Identifier of collection
        required: true
        schema:
          type: string
      - name: filters
        in: query
        description: Filters of statistics
        required: false
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OlapStatsGraphResponse'
              example:
                historicalDates:
                - '2022-05-05'
                - '2022-05-06'
                - '2022-05-07'
                historicalValues:
                - 2744
                - 5487
                - 895
                currentValue: 1767
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OlapError'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OlapError'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OlapError'
  /v0.1/data/collections/{collection}/gmv:
    get:
      tags:
      - NFT Data and Historical Statistics
      summary: Get NFT Collections GVM
      description: Get historical statistics about Collection gross merchandise value
      operationId: getGmv
      parameters:
      - name: collection
        in: path
        description: Identifier of collection
        required: true
        schema:
          type: string
      - name: currency
        in: query
        description: Currency of statistics
        required: false
        schema:
          $ref: '#/components/schemas/OlapCurrencyType'
      - name: period
        in: query
        description: 'Time period of statistics. Default: D1'
        required: false
        schema:
          $ref: '#/components/schemas/OlapPeriod'
      - name: filters
        in: query
        description: Filters of statistics
        required: false
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OlapStatsGraphResponse'
              example:
                historicalDates:
                - '2022-05-05'
                - '2022-05-06'
                - '2022-05-07'
                historicalValues:
                - 10934.527094503102
                - 7876.5886882554005
                - 1164.1458323599143
                currentValue: 498.19370351666873
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OlapError'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OlapError'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OlapError'
  /v0.1/data/collections/{collection}/floorPrice:
    get:
      tags:
      - NFT Data and Historical Statistics
      summary: Get NFT Collection floor price
      description: Get historical statistics about Collection's NFT floor price
      operationId: getFloorPrice
      parameters:
      - name: collection
        in: path
        description: Identifier of collection
        required: true
        schema:
          type: string
      - name: currency
        in: query
        description: Currency of statistics
        required: false
        schema:
          $ref: '#/components/schemas/OlapCurrencyType'
      - name: filters
        in: query
        description: Filters of statistics
        required: false
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OlapStatsGraphResponse'
              example:
                historicalDates:
                - '2022-05-05'
                - '2022-05-06'
                - '2022-05-07'
                historicalValues:
                - 1.7
                - 1.69
                - 1.9
                currentValue: 1.45
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OlapError'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OlapError'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OlapError'
  /v0.1/data/collections/{collection}/buyers:
    get:
      tags:
      - NFT Data and Historical Statistics
      summary: Get NFT Collection buyer stats
      description: Get historical statistics about Collection buyers
      operationId: getBuyers
      parameters:
      - name: collection
        in: path
        description: Identifier of collection
        required: true
        schema:
          type: string
      - name: filters
        in: query
        description: Filters of statistics
        required: false
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OlapStatsGraphResponse'
              example:
                historicalDates:
                - '2022-05-08'
                - '2022-05-09'
                - '2022-05-10'
                historicalValues:
                - 524
                - 791
                - 1619
                currentValue: 1767
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OlapError'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OlapError'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OlapError'
  /v0.1/data/collections/{collection}/listed:
    get:
      tags:
      - NFT Data and Historical Statistics
      summary: Get NFT Collection listing stats
      description: Get historical statistics of collection listed count
      operationId: getListed
      parameters:
      - name: collection
        in: path
        description: Identifier of collection
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OlapStatsGraphResponse'
              example:
                historicalDates:
                - '2022-05-08'
                - '2022-05-09'
                - '2022-05-10'
                historicalValues:
                - 524
                - 791
                - 1619
                currentValue: 1767
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OlapError'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OlapError'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OlapError'
components:
  schemas:
    OlapStatsGraphResponse:
      required:
      - historicalDates
      - historicalValues
      type: object
      properties:
        historicalDates:
          type: array
          description: Dates of historical statistics
          items:
            type: string
            description: Dates of historical statistics
        historicalValues:
          type: array
          description: Values of historical statistics
          items:
            type: number
            description: Values of historical statistics
            format: bigdecimal
        currentValue:
          type: number
          description: Current value
          format: bigdecimal
    OlapLeaderboardPeriod:
      type: string
      enum:
      - MIN5
      - MIN30
      - H1
      - H6
      - D1
      - D7
      - D30
      - ALL
      description: "Period:\n  * `MIN5` - Last 5 minutes\n  * `MIN30` - Last 30 minutes\n  * `H1` - Last 1 hour\n  * `H6` - Last 6 hours\n  * `D1` - Last 1 day\n  * `D7` - Last 7 days\n  * `D30` - Last 30 days\n  * `ALL` - For all time\n"
    OlapBlockchain:
      type: string
      enum:
      - ETHEREUM
      - POLYGON
      - SOLANA
      - ARBITRUM
      - CHILIZ
      - LIGHTLINK
      - ZKSYNC
      - BASE
      - RARI
      - APTOS
      - ZKLINK
      - QUAI
      - ECLIPSE
      - ELECTRONEUM
      - SAAKURU
      - OASIS
      - MATCH
      - MOONBEAM
      - ETHERLINK
      - ZKCANDY
      - BERACHAIN
      - ABSTRACT
      - SHAPE
      - TELOS
      - HEDERAEVM
      - VICTION
      - SETTLUS
      - GOAT
      - HYPEREVM
      - MEGAETH
      - MEGAETHTESTNET
      - MEGAETHTESTNETV2
      - BASECAMP
      - CAMP
      - SOMNIA
      - ARENAZ
      - INJECTIVE
      - INJECTIVETESTNET
      - APECHAIN
      - BLOCKCHAINKEK
      - STELLAR
      - ZILLIQA
      - FRAXTAL
      - XLAYER
      - MONAD
    OlapUserType:
      type: string
      enum:
      - sellers
      - buyers
    OlapCollectionStatisticsResponse:
      required:
      - highestSale
      - items
      - listed
      - owners
      - volume
      - marketCap
      - floorPrice
      type: object
      properties:
        highestSale:
          description: Highest worth transaction in collection
          type: array
          items:
            $ref: '#/components/schemas/OlapCurrencyAmount'
        floorPrice:
          description: Minimal price of nft in this collection available on rarible
          type: array
          items:
            $ref: '#/components/schemas/OlapCurrencyAmount'
        marketCap:
          description: Market cap of collection (floor price * total item supply)
          type: array
          items:
            $ref: '#/components/schemas/OlapCurrencyAmount'
        volume:
          description: Total worth of all transactions were made with nfts in this collection
          type: array
          items:
            $ref: '#/components/schemas/OlapCurrencyAmount'
        listed:
          type: integer
          description: Amount of currently listed items
          format: int32
        items:
          type: integer
          description: Total item supply of all nfts in the collection
          format: int32
        owners:
          type: integer
          description: Current amount of unique owners who hold nfts of this collection
          format: int32
    OlapCurrencyAmount:
      required:
      - currency
      - value
      type: object
      properties:
        currency:
          $ref: '#/components/schemas/OlapCurrencyType'
        value:
          type: number
          description: Amount of currency
          format: bigdecimal
    OlapUserLeaderboardEntry:
      required:
      - id
      - items
      - transactions
      - volumeNative
      - volumeUsd
      type: object
      properties:
        id:
          type: string
          description: Identifier of user
        volumeUsd:
          $ref: '#/components/schemas/OlapCurrencyAmount'
        volumeNative:
          $ref: '#/components/schemas/OlapCurrencyAmount'
        items:
          type: integer
          description: (non-unique) amount of traded items
          format: int64
        transactions:
          type: integer
          description: Amount of transactions were made
          format: int64
    OlapCurrencyType:
      type: string
      default: USD
      enum:
      - USD
      - ETH
      - ETN
      - XTZ
      - MATIC
      - POL
      - SOL
      - CHZ
      - APT
      - QUAI
      - ROSE
      - BNB
      - GLMR
      - BERA
      - TLOS
      - HBAR
      - VIC
      - BTC
      - HYPE
      - CAMP
      - INJ
      - APE
      - XLM
      - ZIL
      - SOMNIA
      - FRAX
      - OAS
      - OKB
      - MON
    OlapUserVolumeRankingResponse:
      type: object
      properties:
        result:
          type: array
          items:
            $ref: '#/components/schemas/OlapUserLeaderboardEntry'
    OlapPeriod:
      type: string
      enum:
      - MIN5
      - MIN30
      - H1
      - H6
      - D1
      - D7
      - D30
      - D180
      - D365
      - ALL
      description: "Period:\n  * `MIN5` - Last 5 minutes\n  * `MIN30` - Last 30 minutes\n  * `H1` - Last 1 hour\n  * `H6` - Last 6 hours\n  * `D1` - Last 1 day\n  * `D7` - Last 7 days\n  * `D30` - Last 30 days\n  * `D180` - Last 180 days (roughly 6 months)\n  * `D365` - Last 365 days (roughly 1 year)\n  * `ALL` - For all time\n"
    OlapCollectionVolumeRankingResponse:
      type: object
      properties:
        continuation:
          type: string
        result:
          type: array
          items:
            $ref: '#/components/schemas/OlapCollectionLeaderboardEntry'
    OlapCollectionLeaderboardEntry:
      required:
      - id
      - itemsBought
      - listed
      - ownersCount
      - totalItemSupply
      - volumeNative
      - volumeUsd
      type: object
      properties:
        id:
          type: string
          description: Identifier of collection
        volumeUsd:
          $ref: '#/components/schemas/OlapCurrencyAmountWithChange'
        volumeNative:
          $ref: '#/components/schemas/OlapCurrencyAmount'
        itemsBought:
          type: integer
          format: int32
        floorPrice:
          $ref: '#/components/schemas/OlapCurrencyAmountWithChange'
        listed:
          type: integer
          format: int32
        totalItemSupply:
          type: integer
          format: int32
        ownersCount:
          type: integer
          format: int32
    OlapPlatformSource:
      type: string
      enum:
      - RARIBLE
      - OPEN_SEA
    OlapError:
      required:
      - code
      - message
      type: object
      properties:
        code:
          type: string
          description: Code
          enum:
          - INVALID_INPUT
          - NOT_FOUND
          - UNKNOWN
        message:
          type: string
          description: Message
    OlapTradesLeaderboardSort:
      type: string
      default: VOLUME_USD_DESC
      enum:
      - VOLUME_USD_ASC
      - VOLUME_USD_DESC
      - COLLECTION_ASC
      - COLLECTION_DESC
      description: "Sort order:\n  * `VOLUME_USD_ASC` - sort by usd collection volume, ascending order\n  * `VOLUME_USD_DESC` - sort by usd collection volume, descending order\n  * `COLLECTION_ASC` - sort by collection id, ascending order\n  * `COLLECTION_DESC` - sort by collection id, descending order\n"
    OlapTradesLeaderboardSourceGroup:
      type: string
      enum:
      - RARIBLE
      - EXTERNAL
      description: "Source group:\n  * `RARIBLE` - source group includes rarible sources (rarible.com + all communities)\n  * `EXTERNAL` - source group includes external marketplaces as sources\n"
    OlapCurrencyAmountWithChange:
      required:
      - currency
      - value
      type: object
      properties:
        currency:
          $ref: '#/components/schemas/OlapCurrencyType'
        value:
          type: number
          description: Amount of currency
          format: bigdecimal
        changePercent:
          type: number
          description: Change in percent. Calculated as <current period value> / <previous period value> - 1
          format: bigdecimal
    OlapGeneralStatsResponse:
      required:
      - highestSale
      - items
      - listed
      - owners
      - volume
      type: object
      properties:
        highestSale:
          type: number
          description: Highest worth transaction in collection
          format: bigdecimal
        floorPrice:
          type: number
          description: Minimal price of nft in this collection available on rarible
          format: bigdecimal
        marketCap:
          type: number
          description: Market cap of collection (floor price * total item supply)
          format: bigdecimal
        listed:
          type: integer
          description: Amount of currently listed items
          format: int32
        items:
          type: integer
          description: Total item supply of all nfts in the collection
          format: int32
        owners:
          type: integer
          description: Current amount of unique owners who hold nfts of this collection
          format: int32
        volume:
          type: number
          description: Total worth of all transactions were made with nfts in this collection
          format: bigdecimal
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-KEY
      x-default: 11111111-1111-1111-1111-111111111111