openapi: 3.1.0
info:
  title: OpenSea Account Endpoints Collection Endpoints API
  description: The API for OpenSea
  contact:
    name: OpenSea
    url: https://www.opensea.io
    email: contact@opensea.io
  version: 2.0.0
servers:
- url: https://api.opensea.io
  description: Production server
security:
- ApiKeyAuth: []
tags:
- name: Collection Endpoints
  description: Collection endpoints to retrieve collection details, traits, and trending data
paths:
  /api/v2/collections/batch:
    post:
      tags:
      - Collection Endpoints
      summary: Get collections by slugs
      description: Retrieve multiple collections in a single request by providing a list of slugs. Results are returned in the same order as the input slugs. Not-found collections are silently omitted.
      operationId: get_collections_batch
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BatchCollectionsRequest'
        required: true
      responses:
        '200':
          description: OK
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/CollectionBatchResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v2/traits/{slug}:
    get:
      tags:
      - Collection Endpoints
      summary: Get collection traits
      description: Get all available traits for a collection with their value counts and data types.
      operationId: get_collection_traits
      parameters:
      - name: slug
        in: path
        description: Unique identifier for the specific collection
        required: true
        schema:
          type: string
        example: doodles-official
      responses:
        '200':
          description: Collection traits with categories and counts
          content:
            application/json:
              examples:
                TraitsResponse:
                  description: Example response showing both string and numeric trait types
                  value:
                    categories:
                      face: string
                      background: string
                      level: number
                    counts:
                      face:
                        glasses: 4
                        sunglasses: 2
                      background:
                        red: 6
                      level:
                        min: 1
                        max: 99
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v2/collections:
    get:
      tags:
      - Collection Endpoints
      summary: Get multiple collections
      description: Get a list of collections with filters and sorting options.
      operationId: list_collections
      parameters:
      - name: limit
        in: query
        description: Number of items to return per page
        required: false
        schema:
          type: integer
          format: int32
          description: Number of items to return per page
          example: 20
          maximum: 200
          minimum: 1
        example: 20
      - name: next.value
        in: query
        required: false
        schema:
          type: string
      - name: chain
        in: query
        description: Blockchain to filter by
        required: false
        schema:
          type: string
      - name: creator_username
        in: query
        description: Username of collection creator to filter by
        required: false
        schema:
          type: string
      - name: include_hidden
        in: query
        description: Include hidden collections in results
        required: false
        schema:
          type: boolean
      - name: order_by
        in: query
        description: Field to order results by
        required: false
        schema:
          type: string
        example: created_date
      responses:
        '200':
          description: OK
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/CollectionPaginatedResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v2/collections/{slug}:
    get:
      tags:
      - Collection Endpoints
      summary: Get a single collection
      description: Get a single collection including details such as fees, traits, and links.
      operationId: get_collection
      parameters:
      - name: slug
        in: path
        description: Unique identifier for the specific collection
        required: true
        schema:
          type: string
        example: doodles-official
      responses:
        '200':
          description: OK
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/CollectionDetailedResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v2/collections/{slug}/stats:
    get:
      tags:
      - Collection Endpoints
      summary: Get collection stats
      description: Get comprehensive statistics for a collection including volume, floor price, and trading metrics.
      operationId: get_collection_stats
      parameters:
      - name: slug
        in: path
        description: Unique identifier for the specific collection
        required: true
        schema:
          type: string
        example: doodles-official
      responses:
        '200':
          description: OK
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/CollectionStatsResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v2/collections/{slug}/offer_aggregates:
    get:
      tags:
      - Collection Endpoints
      summary: Get collection offer aggregates
      description: Get aggregated offer buckets grouped by price level for a collection.
      operationId: get_collection_offer_aggregates
      parameters:
      - name: slug
        in: path
        description: Collection slug
        required: true
        schema:
          type: string
        example: boredapeyachtclub
      - name: limit
        in: query
        description: 'Number of results to return (default: 20, max: 100)'
        required: false
        schema:
          type: integer
          format: int32
          default: 20
        example: 20
      - name: cursor
        in: query
        description: Pagination cursor for next page
        required: false
        schema:
          type: string
      - name: sort_direction
        in: query
        description: Sort direction (asc or desc)
        required: false
        schema:
          type: string
          default: desc
        example: desc
      responses:
        '200':
          description: Collection offer aggregates
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/CollectionOfferAggregatesPaginatedResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v2/collections/{slug}/holders:
    get:
      tags:
      - Collection Endpoints
      summary: Get collection holders
      description: Get a paginated list of holders for a collection.
      operationId: get_collection_holders
      parameters:
      - name: slug
        in: path
        description: Collection slug
        required: true
        schema:
          type: string
        example: boredapeyachtclub
      - name: limit
        in: query
        description: 'Number of results to return (default: 20, max: 100)'
        required: false
        schema:
          type: integer
          format: int32
          default: 20
        example: 20
      - name: cursor
        in: query
        description: Pagination cursor for next page
        required: false
        schema:
          type: string
      - name: sort_direction
        in: query
        description: Sort direction (asc or desc)
        required: false
        schema:
          type: string
          default: desc
        example: desc
      - name: owned_by
        in: query
        description: Filter by owner address
        required: false
        schema:
          type: string
      responses:
        '200':
          description: Collection holders
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/CollectionHoldersPaginatedResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v2/collections/{slug}/floor_prices:
    get:
      tags:
      - Collection Endpoints
      summary: Get collection floor price history
      description: Get time-series floor price data for a collection.
      operationId: get_collection_floor_prices
      parameters:
      - name: slug
        in: path
        description: Collection slug
        required: true
        schema:
          type: string
        example: boredapeyachtclub
      - name: timeframe
        in: query
        description: 'Time window for floor price history. Options: one_minute, five_minutes, fifteen_minutes, one_hour, one_day, seven_days, thirty_days, one_year, all_time'
        required: false
        schema:
          type: string
          default: one_day
        example: one_day
      - name: resolution
        in: query
        description: Number of data points to return
        required: false
        schema:
          type: integer
          format: int32
      responses:
        '200':
          description: Floor price history
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/FloorPriceHistoryResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v2/collections/trending:
    get:
      tags:
      - Collection Endpoints
      summary: Get trending collections
      description: Get a list of trending NFT collections sorted by sales activity over a specified timeframe. Trending is determined by sales volume and activity metrics. Available timeframes range from 1 minute to all time. For the one_day timeframe without a chain filter, collections are sorted by a composite trending score; all other timeframes sort by raw sales count. Results are filtered to verified, non-spam, non-NSFW collections with minimum volume thresholds.
      operationId: get_trending_collections
      parameters:
      - name: timeframe
        in: query
        description: 'Time window for trending calculation. Options: one_minute, five_minutes, fifteen_minutes, one_hour, one_day, seven_days, thirty_days, one_year, all_time.'
        required: false
        schema:
          type: string
          default: one_day
        example: one_day
      - name: chains
        in: query
        description: Blockchain(s) to filter by. Comma-separated list of chain identifiers. Unsupported chains are silently ignored; a 400 is returned only if all specified chains are unsupported.
        required: false
        schema:
          type: array
          items:
            $ref: '#/components/schemas/ChainIdentifier'
        example: ethereum,base
      - name: category
        in: query
        description: Category to filter by (e.g. art, gaming, memberships, music, pfps, photography, domain-names, virtual-worlds, sports-collectibles, physical-collectibles).
        required: false
        schema:
          type: string
        example: pfps
      - name: limit
        in: query
        description: Maximum number of collections to return (1-100).
        required: false
        schema:
          type: integer
          format: int32
          default: 20
        example: 20
      - name: cursor
        in: query
        description: Cursor for pagination. Use the 'next' value from a previous response.
        required: false
        schema:
          type: string
      responses:
        '200':
          description: Trending collections
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/CollectionPaginatedResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v2/collections/top:
    get:
      tags:
      - Collection Endpoints
      summary: Get top collections
      description: 'Get top NFT collections ranked by various stats (sorted descending). Unlike /trending, results are not filtered by verification status; spam-tagged collections are excluded via trust-safety enforcement states. Available sort options: one_day_volume, seven_days_volume, thirty_days_volume, floor_price, one_day_sales, seven_days_sales, thirty_days_sales, total_volume, total_sales.'
      operationId: get_top_collections
      parameters:
      - name: sort_by
        in: query
        description: 'The stat to sort collections by (always sorted descending). Options: one_day_volume, seven_days_volume, thirty_days_volume, floor_price, one_day_sales, seven_days_sales, thirty_days_sales, total_volume, total_sales'
        required: false
        schema:
          type: string
          default: one_day_volume
        example: one_day_volume
      - name: chains
        in: query
        description: Blockchain(s) to filter by. Comma-separated list of chain identifiers. Unsupported chains are silently ignored; a 400 is returned only if all specified chains are unsupported.
        required: false
        schema:
          type: array
          items:
            $ref: '#/components/schemas/ChainIdentifier'
        example: ethereum,base
      - name: category
        in: query
        description: Category to filter by (e.g. art, gaming, memberships, music, pfps, photography, domain-names, virtual-worlds, sports-collectibles, physical-collectibles).
        required: false
        schema:
          type: string
        example: pfps
      - name: limit
        in: query
        description: Maximum number of collections to return (1-100).
        required: false
        schema:
          type: integer
          format: int32
          default: 50
        example: 50
      - name: cursor
        in: query
        description: Cursor for pagination
        required: false
        schema:
          type: string
      responses:
        '200':
          description: Top collections list
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/CollectionPaginatedResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v2/chain/{chain}/contract/{address}/nfts/{identifier}/collection:
    get:
      tags:
      - Collection Endpoints
      summary: Get collection by NFT
      description: Get the collection that an NFT belongs to. This is useful for multi-contract collections like Art Blocks where the item ID disambiguates which collection the NFT belongs to.
      operationId: get_nft_collection
      parameters:
      - name: chain
        in: path
        description: The blockchain on which to filter the results
        required: true
        schema:
          type: string
        example: ethereum
      - name: address
        in: path
        description: The unique public blockchain identifier for the contract
        required: true
        schema:
          type: string
        example: 0x8ba1f109551bD432803012645Hac136c94C19D6e
      - name: identifier
        in: path
        description: The NFT token id
        required: true
        schema:
          type: string
        example: 1
      responses:
        '200':
          description: OK
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/CollectionDetailedResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
components:
  schemas:
    CollectionBatchResponse:
      type: object
      properties:
        collections:
          type: array
          items:
            $ref: '#/components/schemas/CollectionResponse'
      required:
      - collections
    CollectionStatsResponse:
      type: object
      properties:
        total:
          $ref: '#/components/schemas/Total'
        intervals:
          type: array
          items:
            $ref: '#/components/schemas/IntervalStat'
      required:
      - intervals
      - total
    CollectionDetailedResponse:
      type: object
      properties:
        collection:
          type: string
        name:
          type: string
        description:
          type: string
        image_url:
          type: string
        banner_image_url:
          type: string
        owner:
          type: string
        safelist_status:
          type: string
        category:
          type: string
        is_disabled:
          type: boolean
        is_nsfw:
          type: boolean
        trait_offers_enabled:
          type: boolean
        collection_offers_enabled:
          type: boolean
        opensea_url:
          type: string
        project_url:
          type: string
        wiki_url:
          type: string
        discord_url:
          type: string
        telegram_url:
          type: string
        twitter_username:
          type: string
        instagram_username:
          type: string
        contracts:
          type: array
          items:
            $ref: '#/components/schemas/Contract'
        editors:
          type: array
          items:
            type: string
        fees:
          type: array
          items:
            $ref: '#/components/schemas/Fee'
        required_zone:
          type: string
        rarity:
          $ref: '#/components/schemas/CollectionRarity'
        total_supply:
          type: integer
          format: int64
        unique_item_count:
          type: integer
          format: int64
        created_date:
          type: string
          format: date-time
        pricing_currencies:
          $ref: '#/components/schemas/PricingCurrencies'
      required:
      - collection
      - collection_offers_enabled
      - contracts
      - created_date
      - editors
      - fees
      - is_disabled
      - is_nsfw
      - name
      - opensea_url
      - pricing_currencies
      - safelist_status
      - total_supply
      - trait_offers_enabled
      - unique_item_count
    PricingCurrencies:
      type: object
      properties:
        listing_currency:
          $ref: '#/components/schemas/PaymentToken'
        offer_currency:
          $ref: '#/components/schemas/PaymentToken'
      required:
      - listing_currency
      - offer_currency
    CollectionHoldersPaginatedResponse:
      type: object
      description: Paginated list of collection holders
      properties:
        holders:
          type: array
          description: List of holders
          items:
            $ref: '#/components/schemas/CollectionHolderResponse'
        next:
          type: string
          description: Cursor for the next page of results
      required:
      - holders
    BatchCollectionsRequest:
      type: object
      description: Request body for batch collection retrieval by slugs
      properties:
        slugs:
          type: array
          description: List of collection slugs to retrieve
          example:
          - boredapeyachtclub
          - doodles-official
          items:
            type: string
      required:
      - slugs
    FloorPriceHistoryResponse:
      type: object
      description: Floor price history for a collection
      properties:
        floor_prices:
          type: array
          description: List of floor price data points
          items:
            $ref: '#/components/schemas/FloorPricePointResponse'
      required:
      - floor_prices
    Contract:
      type: object
      properties:
        address:
          type: string
        chain:
          type: string
      required:
      - address
      - chain
    PaymentToken:
      type: object
      properties:
        symbol:
          type: string
        address:
          type: string
        chain:
          type: string
        image:
          type: string
        name:
          type: string
        decimals:
          type: integer
          format: int32
        eth_price:
          type: string
        usd_price:
          type: string
      required:
      - address
      - chain
      - decimals
      - eth_price
      - image
      - name
      - symbol
      - usd_price
    BidderResponse:
      type: object
      description: A bidder in an offer aggregate
      properties:
        address:
          type: string
          description: Wallet address of the bidder
        quantity:
          type: integer
          format: int32
          description: Number of offers from this bidder
      required:
      - address
      - quantity
    CollectionPaginatedResponse:
      type: object
      properties:
        collections:
          type: array
          items:
            $ref: '#/components/schemas/CollectionResponse'
        next:
          type: string
      required:
      - collections
    ChainIdentifier:
      type: string
      default: ethereum
      description: Blockchain chain identifier. Use the chain slug (e.g., 'ethereum', 'polygon', 'arbitrum', 'optimism', 'base')
      enum:
      - blast
      - base
      - ethereum
      - zora
      - arbitrum
      - sei
      - avalanche
      - polygon
      - optimism
      - ape_chain
      - flow
      - b3
      - soneium
      - ronin
      - bera_chain
      - solana
      - shape
      - unichain
      - gunzilla
      - abstract
      - animechain
      - hyperevm
      - somnia
      - monad
      - hyperliquid
      - megaeth
      - ink
      example: ethereum
    CollectionResponse:
      type: object
      properties:
        collection:
          type: string
        name:
          type: string
        description:
          type: string
        image_url:
          type: string
        banner_image_url:
          type: string
        owner:
          type: string
        safelist_status:
          type: string
        category:
          type: string
        is_disabled:
          type: boolean
        is_nsfw:
          type: boolean
        trait_offers_enabled:
          type: boolean
        collection_offers_enabled:
          type: boolean
        opensea_url:
          type: string
        project_url:
          type: string
        wiki_url:
          type: string
        discord_url:
          type: string
        telegram_url:
          type: string
        twitter_username:
          type: string
        instagram_username:
          type: string
        contracts:
          type: array
          items:
            $ref: '#/components/schemas/Contract'
      required:
      - collection
      - collection_offers_enabled
      - contracts
      - is_disabled
      - is_nsfw
      - name
      - opensea_url
      - safelist_status
      - trait_offers_enabled
    CollectionHolderResponse:
      type: object
      description: A collection holder
      properties:
        address:
          type: string
          description: Wallet address of the holder
        quantity:
          type: integer
          format: int32
          description: Number of items held
        percentage:
          type: number
          format: float
          description: Ownership percentage of the collection
      required:
      - address
      - percentage
      - quantity
    CollectionOfferAggregatesPaginatedResponse:
      type: object
      description: Paginated list of collection offer aggregates
      properties:
        offer_aggregates:
          type: array
          description: List of offer aggregates
          items:
            $ref: '#/components/schemas/CollectionOfferAggregateResponse'
        next:
          type: string
          description: Cursor for the next page of results
      required:
      - offer_aggregates
    CollectionOfferAggregateResponse:
      type: object
      description: An aggregated offer bucket
      properties:
        offer_price:
          $ref: '#/components/schemas/OfferAggregatePriceResponse'
          description: Offer price level
        total_value:
          $ref: '#/components/schemas/OfferAggregatePriceResponse'
          description: Total value of offers at this level
        total_offers:
          type: integer
          format: int32
          description: Total number of offers at this level
        bidders:
          type: array
          description: Bidders at this price level
          items:
            $ref: '#/components/schemas/BidderResponse'
      required:
      - bidders
      - offer_price
      - total_offers
      - total_value
    IntervalStat:
      type: object
      properties:
        interval:
          type: string
        volume:
          type: number
          format: double
        sales:
          type: integer
          format: int32
      required:
      - interval
      - sales
      - volume
    CollectionRarity:
      type: object
      properties:
        calculated_at:
          type: string
        max_rank:
          type: integer
          format: int32
        total_supply:
          type: integer
          format: int64
        strategy_id:
          type: string
        strategy_version:
          type: string
      required:
      - calculated_at
      - max_rank
      - strategy_id
      - strategy_version
      - total_supply
    FloorPricePointResponse:
      type: object
      description: A floor price data point
      properties:
        time:
          type: string
          format: date-time
          description: Timestamp of the data point
        usd_price:
          type: string
          description: Floor price in USD
        token_unit:
          type: number
          format: double
          description: Floor price in token units
        symbol:
          type: string
          description: Payment token symbol
        chain:
          type: string
          description: Blockchain chain
      required:
      - time
    Total:
      type: object
      properties:
        volume:
          type: number
          format: double
        sales:
          type: integer
          format: int32
        num_owners:
          type: integer
          format: int64
        floor_price:
          type: number
          format: double
        floor_price_symbol:
          type: string
      required:
      - floor_price
      - floor_price_symbol
      - num_owners
      - sales
      - volume
    Fee:
      type: object
      properties:
        fee:
          type: number
          format: double
        recipient:
          type: string
        required:
          type: boolean
      required:
      - fee
      - recipient
      - required
    OfferAggregatePriceResponse:
      type: object
      description: Price information for an offer aggregate
      properties:
        usd_price:
          type: string
          description: Price in USD
        token_unit:
          type: number
          format: double
          description: Price in token units
        symbol:
          type: string
          description: Payment token symbol
        chain:
          type: string
          description: Blockchain chain
      required:
      - chain
      - token_unit
      - usd_price
  responses:
    NotFound:
      description: Resource not found
    BadRequest:
      description: For error reasons, review the response data.
    InternalError:
      description: Internal server error. Please open a support ticket so OpenSea can investigate.
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      description: API key required for authentication
      name: x-api-key
      in: header
x-tagGroups:
- name: Data & Discovery
  tags:
  - Chain Endpoints
  - Account Endpoints
  - Collection Endpoints
  - NFT Endpoints
  - Contract Endpoints
  - Token Endpoints
  - Search Endpoints
- name: Marketplace & Trading
  tags:
  - Listing Endpoints
  - Offer Endpoints
  - Order Endpoints
  - Swap Endpoints
  - Drops Endpoints
- name: Analytics & Events
  tags:
  - Analytics Endpoints
- name: Tools [Beta]
  tags:
  - Tool Endpoints [Beta]
- name: Transactions
  tags:
  - Transaction Endpoints