openapi: 3.1.0
info:
  title: Decentraland Marketplace Server API
  description: |
    ## Overview

    The Decentraland Marketplace API provides comprehensive access to the Decentraland NFT marketplace,
    enabling developers to build applications that interact with digital assets in the metaverse.

    ### Key Features

    - **NFT Management**: Browse, search, and query NFTs including wearables, emotes, LAND parcels, and ENS names
    - **Trading Operations**: Create and manage trades, place bids, and view active orders
    - **Marketplace Catalog**: Access the full marketplace catalog with advanced filtering and sorting
    - **Favorites & Lists**: Create and manage personalized item collections with privacy controls
    - **Analytics**: Access sales history, price data, trending items, rankings, and volume metrics
    - **Payment Integration**: Support for fiat-to-crypto gateways (Wert, Transak)

    ### Supported Networks

    - **Ethereum Mainnet**: Primary network for LAND, premium wearables, and high-value items
    - **Polygon**: Layer 2 solution for wearables, emotes, and lower-cost transactions

    ### Authentication

    Most endpoints support optional authentication using Decentraland's signed fetch mechanism.
    Authenticated requests provide access to:
    - Private user lists and favorites
    - Personalized recommendations
    - User-specific data and permissions

    Authentication uses the **SignedFetch** scheme (decentraland-crypto-middleware) with metadata validation
    following [ADR-44](http://adr.decentraland.org/adr/ADR-44). Required endpoints clearly indicate authentication
    in their documentation.    
        
    ### Base URLs

    - Production: `https://marketplace-api.decentraland.org`
    - Development: `https://marketplace-api.decentraland.zone`
  version: 1.0.0
  contact:
    name: Decentraland
    url: https://decentraland.org
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0.html
  x-api-id: marketplace-server-api
servers:
  - url: https://marketplace-api.decentraland.org
    description: Production server
  - url: https://marketplace-api.decentraland.zone
    description: Development server
security: []
tags:
  - name: Health
    description: Health check and service status endpoints
  - name: Catalog
    description: Browse and search marketplace catalog items
  - name: Trades
    description: Manage and view trading activity
  - name: NFTs
    description: Query and manage NFTs including wearables, emotes, and LAND
  - name: Items
    description: View marketplace items and collections
  - name: Orders
    description: Manage marketplace orders
  - name: Contracts
    description: Query smart contracts and collections available in the marketplace
  - name: Bids
    description: View and manage bids on marketplace items
  - name: Sales
    description: Query sales history and transactions
  - name: Prices
    description: Get current marketplace prices
  - name: Trending
    description: View trending items and collections
  - name: Statistics
    description: Access marketplace statistics and analytics
  - name: Rankings
    description: View marketplace rankings by various metrics
  - name: Volume
    description: Query trading volume data
  - name: Lists
    description: Manage user favorites lists (curated collections)
  - name: Picks
    description: Manage picks within favorites lists
  - name: Payments
    description: Payment gateway integration (Wert, Transak)
  - name: ENS
    description: ENS (Ethereum Name Service) utilities
  - name: Accounts
    description: Query account statistics and marketplace activity
  - name: Collections
    description: View and search marketplace collections
paths:
  /ping:
    get:
      tags:
        - Health
      summary: Health check endpoint
      description: |
        Simple health check endpoint that returns "pong" when the service is running and healthy.
        Used for monitoring and load balancer health checks.
      operationId: ping
      security: []
      responses:
        '200':
          description: Service is healthy and responding
          content:
            text/plain:
              schema:
                type: string
                example: pong
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                type: object
                properties: &ref_0
                  error:
                    type: string
                    description: Error message
                  code:
                    type: string
                    description: Error code
                required: &ref_1
                  - error
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
                properties: *ref_0
                required: *ref_1
  /v1/catalog:
    get:
      tags:
        - Catalog
      summary: Get marketplace catalog (v1)
      description: |
        Retrieves the marketplace catalog with items available for browsing and purchase.
        Supports filtering by category, price range, and various item attributes.
        Authentication is optional but recommended for personalized results.

        **Note**: Consider using /v2/catalog for enhanced features and performance.

        **Pagination:** Uses `first` and `skip` parameters.

        This endpoint shares all the same filter parameters as /v1/items, plus catalog-specific options.
      operationId: getCatalog
      security:
        - SignedFetch: []
        - {}
      parameters:
        - name: first
          in: query
          required: false
          description: 'Maximum number of items to return (default: 20)'
          schema:
            type: number
            default: 20
            example: 10
        - name: skip
          in: query
          required: false
          description: 'Number of items to skip for pagination (default: 0)'
          schema:
            type: number
            default: 0
            example: 0
        - name: sortBy
          in: query
          required: false
          description: Sort results by specified criteria
          schema:
            type: string
            enum:
              - newest
              - recently_sold
              - cheapest
              - most_expensive
              - recently_listed
            example: cheapest
        - name: sortDirection
          in: query
          required: false
          description: Sort direction
          schema:
            type: string
            enum:
              - asc
              - desc
            default: asc
        - name: onlyListing
          in: query
          required: false
          description: Show only items with active listings
          schema:
            type: boolean
        - name: onlyMinting
          in: query
          required: false
          description: Show only items available for minting
          schema:
            type: boolean
        - name: category
          in: query
          required: false
          description: Filter by NFT category
          schema:
            type: string
            enum:
              - wearable
              - emote
        - name: creator
          in: query
          required: false
          description: Filter by creator wallet address(es). Can be repeated.
          schema:
            type: array
            items:
              type: string
          style: form
          explode: true
        - name: isSoldOut
          in: query
          required: false
          description: Filter by sold out status
          schema:
            type: boolean
        - name: isOnSale
          in: query
          required: false
          description: Filter by whether item is currently on sale
          schema:
            type: boolean
        - name: search
          in: query
          required: false
          description: Text search across item names and descriptions
          schema:
            type: string
        - name: isWearableHead
          in: query
          required: false
          description: Filter for head wearables only
          schema:
            type: boolean
        - name: isWearableAccessory
          in: query
          required: false
          description: Filter for accessory wearables only
          schema:
            type: boolean
        - name: isWearableSmart
          in: query
          required: false
          description: Filter for smart wearables only
          schema:
            type: boolean
        - name: wearableCategory
          in: query
          required: false
          description: Filter by specific wearable category
          schema:
            type: string
            enum:
              - eyebrows
              - eyes
              - facial_hair
              - hair
              - body_shape
              - mouth
              - upper_body
              - lower_body
              - feet
              - earring
              - eyewear
              - hat
              - helmet
              - mask
              - tiara
              - top_head
              - skin
              - hands_wear
        - name: rarity
          in: query
          required: false
          description: Filter by rarity. Can be repeated for multiple rarities.
          schema:
            type: array
            items:
              type: string
              enum:
                - unique
                - mythic
                - exotic
                - legendary
                - epic
                - rare
                - uncommon
                - common
          style: form
          explode: true
        - name: wearableGender
          in: query
          required: false
          description: Filter by wearable gender compatibility. Can be repeated.
          schema:
            type: array
            items:
              type: string
              enum:
                - male
                - female
                - unisex
          style: form
          explode: true
        - name: emoteCategory
          in: query
          required: false
          description: Filter by emote category
          schema:
            type: string
            enum:
              - dance
              - stunt
              - greetings
              - fun
              - poses
              - reactions
              - horror
              - miscellaneous
        - name: emoteGender
          in: query
          required: false
          description: Filter by emote gender compatibility. Can be repeated.
          schema:
            type: array
            items:
              type: string
              enum:
                - male
                - female
                - unisex
          style: form
          explode: true
        - name: emotePlayMode
          in: query
          required: false
          description: Filter by emote play mode. Can be repeated.
          schema:
            type: array
            items:
              type: string
              enum:
                - simple
                - loop
          style: form
          explode: true
        - name: emoteHasGeometry
          in: query
          required: false
          description: Filter for emotes with geometry/props
          schema:
            type: boolean
        - name: emoteHasSound
          in: query
          required: false
          description: Filter for emotes with sound
          schema:
            type: boolean
        - name: contractAddress
          in: query
          required: false
          description: Filter by collection contract address(es). Can be repeated.
          schema:
            type: array
            items:
              type: string
          style: form
          explode: true
        - name: itemId
          in: query
          required: false
          description: Filter by specific item ID within a collection
          schema:
            type: string
        - name: network
          in: query
          required: false
          description: Filter by blockchain network
          schema:
            type: string
            enum:
              - ETHEREUM
              - MATIC
        - name: minPrice
          in: query
          required: false
          description: Minimum price filter in ETH/MATIC
          schema:
            type: string
        - name: maxPrice
          in: query
          required: false
          description: Maximum price filter in ETH/MATIC
          schema:
            type: string
        - name: urn
          in: query
          required: false
          description: Filter by item URN(s). Can be repeated.
          schema:
            type: array
            items:
              type: string
          style: form
          explode: true
        - name: id
          in: query
          required: false
          description: Filter by item ID(s). Can be repeated.
          schema:
            type: array
            items:
              type: string
          style: form
          explode: true
      responses:
        '200':
          description: Marketplace catalog
          content:
            application/json:
              schema:
                type: object
                properties: &ref_2
                  items:
                    type: array
                    items:
                      type: object
                      properties: &ref_12
                        id:
                          type: string
                          description: Item ID
                        name:
                          type: string
                          description: Item name
                        description:
                          type: string
                          description: Item description
                        image:
                          type: string
                          description: Item image URL
                        category:
                          type: string
                          description: Item category
                        rarity:
                          type: string
                          description: Item rarity
                        price:
                          type: number
                          description: Item price
                      additionalProperties: true
                      required: &ref_13
                        - id
                        - name
                        - category
                    description: List of catalog items
                  total:
                    type: number
                    description: Total number of items
                required: &ref_3
                  - items
                  - total
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                type: object
                properties: *ref_0
                required: *ref_1
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
                properties: *ref_0
                required: *ref_1
  /v2/catalog:
    get:
      tags:
        - Catalog
      summary: Get marketplace catalog (v2 - Recommended)
      description: |
        Retrieves the marketplace catalog with enhanced filtering and sorting capabilities.

        **Supports comprehensive filtering by:**
        - Categories (wearables, emotes)
        - Price ranges and sorting
        - Rarities and creator addresses
        - Wearable-specific filters (gender, category, accessories, smart wearables)
        - Emote-specific filters (category, play mode, sound, geometry)
        - Text search across item names and descriptions

        **Pagination:** Uses `first` and `skip` parameters.

        Authentication is optional but may provide personalized results and user-specific data.

        This endpoint accepts all the same parameters as /v1/catalog.
      operationId: getCatalogV2
      security:
        - SignedFetch: []
        - {}
      parameters:
        - name: first
          in: query
          required: false
          description: 'Maximum number of items to return (default: 20)'
          schema:
            type: number
            default: 20
            example: 10
        - name: skip
          in: query
          required: false
          description: 'Number of items to skip for pagination (default: 0)'
          schema:
            type: number
            default: 0
            example: 0
        - name: sortBy
          in: query
          required: false
          description: Sort results by specified criteria
          schema:
            type: string
            enum:
              - newest
              - recently_sold
              - cheapest
              - most_expensive
              - recently_listed
            example: cheapest
        - name: sortDirection
          in: query
          required: false
          description: Sort direction
          schema:
            type: string
            enum:
              - asc
              - desc
            default: asc
        - name: onlyListing
          in: query
          required: false
          description: Show only items with active listings
          schema:
            type: boolean
        - name: onlyMinting
          in: query
          required: false
          description: Show only items available for minting
          schema:
            type: boolean
        - name: category
          in: query
          required: false
          description: Filter by NFT category
          schema:
            type: string
            enum:
              - wearable
              - emote
        - name: creator
          in: query
          required: false
          description: Filter by creator wallet address(es). Can be repeated.
          schema:
            type: array
            items:
              type: string
          style: form
          explode: true
        - name: isSoldOut
          in: query
          required: false
          description: Filter by sold out status
          schema:
            type: boolean
        - name: isOnSale
          in: query
          required: false
          description: Filter by whether item is currently on sale
          schema:
            type: boolean
        - name: search
          in: query
          required: false
          description: Text search across item names and descriptions
          schema:
            type: string
        - name: isWearableHead
          in: query
          required: false
          description: Filter for head wearables only
          schema:
            type: boolean
        - name: isWearableAccessory
          in: query
          required: false
          description: Filter for accessory wearables only
          schema:
            type: boolean
        - name: isWearableSmart
          in: query
          required: false
          description: Filter for smart wearables only
          schema:
            type: boolean
        - name: wearableCategory
          in: query
          required: false
          description: Filter by specific wearable category
          schema:
            type: string
            enum:
              - eyebrows
              - eyes
              - facial_hair
              - hair
              - body_shape
              - mouth
              - upper_body
              - lower_body
              - feet
              - earring
              - eyewear
              - hat
              - helmet
              - mask
              - tiara
              - top_head
              - skin
              - hands_wear
        - name: rarity
          in: query
          required: false
          description: Filter by rarity. Can be repeated for multiple rarities.
          schema:
            type: array
            items:
              type: string
              enum:
                - unique
                - mythic
                - exotic
                - legendary
                - epic
                - rare
                - uncommon
                - common
          style: form
          explode: true
        - name: wearableGender
          in: query
          required: false
          description: Filter by wearable gender compatibility. Can be repeated.
          schema:
            type: array
            items:
              type: string
              enum:
                - male
                - female
                - unisex
          style: form
          explode: true
        - name: emoteCategory
          in: query
          required: false
          description: Filter by emote category
          schema:
            type: string
            enum:
              - dance
              - stunt
              - greetings
              - fun
              - poses
              - reactions
              - horror
              - miscellaneous
        - name: emoteGender
          in: query
          required: false
          description: Filter by emote gender compatibility. Can be repeated.
          schema:
            type: array
            items:
              type: string
              enum:
                - male
                - female
                - unisex
          style: form
          explode: true
        - name: emotePlayMode
          in: query
          required: false
          description: Filter by emote play mode. Can be repeated.
          schema:
            type: array
            items:
              type: string
              enum:
                - simple
                - loop
          style: form
          explode: true
        - name: emoteHasGeometry
          in: query
          required: false
          description: Filter for emotes with geometry/props
          schema:
            type: boolean
        - name: emoteHasSound
          in: query
          required: false
          description: Filter for emotes with sound
          schema:
            type: boolean
        - name: contractAddress
          in: query
          required: false
          description: Filter by collection contract address(es). Can be repeated.
          schema:
            type: array
            items:
              type: string
          style: form
          explode: true
        - name: itemId
          in: query
          required: false
          description: Filter by specific item ID within a collection
          schema:
            type: string
        - name: network
          in: query
          required: false
          description: Filter by blockchain network
          schema:
            type: string
            enum:
              - ETHEREUM
              - MATIC
        - name: minPrice
          in: query
          required: false
          description: Minimum price filter in ETH/MATIC
          schema:
            type: string
        - name: maxPrice
          in: query
          required: false
          description: Maximum price filter in ETH/MATIC
          schema:
            type: string
        - name: urn
          in: query
          required: false
          description: Filter by item URN(s). Can be repeated.
          schema:
            type: array
            items:
              type: string
          style: form
          explode: true
        - name: id
          in: query
          required: false
          description: Filter by item ID(s). Can be repeated.
          schema:
            type: array
            items:
              type: string
          style: form
          explode: true
      responses:
        '200':
          description: Marketplace catalog v2
          content:
            application/json:
              schema:
                type: object
                properties: *ref_2
                required: *ref_3
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                type: object
                properties: *ref_0
                required: *ref_1
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
                properties: *ref_0
                required: *ref_1
  /v1/wert/sign:
    post:
      tags:
        - Payments
      summary: Sign Wert payment transaction
      description: |
        Signs a transaction for Wert payment gateway integration.
        Wert is a fiat-to-crypto payment solution that allows users to purchase NFTs with credit/debit cards.
        This endpoint validates and signs the transaction data before forwarding to Wert's infrastructure.

        Authentication is optional but recommended for tracking user transactions.
      operationId: signWertTransaction
      security:
        - SignedFetch: []
        - {}
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties: &ref_14
                transaction:
                  type: object
                  additionalProperties: true
                  description: |
                    Transaction data (TODO: align with precise source types)
                signature:
                  type: string
                  description: Transaction signature
              required: &ref_15
                - transaction
      responses:
        '200':
          description: Signed transaction
          content:
            application/json:
              schema:
                type: object
                properties: &ref_16
                  signedTransaction:
                    type: string
                    description: Signed transaction
                  success:
                    type: boolean
                    description: Signing success status
                required: &ref_17
                  - signedTransaction
                  - success
  /v1/transak/orders/{id}:
    get:
      tags:
        - Payments
      summary: Get Transak order details
      description: |
        Retrieves detailed information about a Transak payment order.
        Transak is a fiat-to-crypto payment gateway that enables credit/debit card purchases.

        Use this endpoint to check order status, amount, currency, and completion details.
        Authentication is optional but may provide access to user-specific order information.
      operationId: getTransakOrder
      security:
        - SignedFetch: []
        - {}
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: Unique Transak order identifier
      responses:
        '200':
          description: Transak order
          content:
            application/json:
              schema:
                type: object
                properties: &ref_18
                  id:
                    type: string
                    description: Order ID
                  status:
                    type: string
                    description: Order status
                  amount:
                    type: number
                    description: Order amount
                  currency:
                    type: string
                    description: Order currency
                  createdAt:
                    type: string
                    format: date-time
                    description: Order creation timestamp
                required: &ref_19
                  - id
                  - status
                  - amount
                  - currency
        '404':
          description: Order not found
          content:
            application/json:
              schema:
                type: object
                properties: *ref_0
                required: *ref_1
  /v1/ens/generate:
    get:
      tags:
        - ENS
      summary: Generate ENS name image
      description: |
        Generates a visual representation (image) for an ENS (Ethereum Name Service) name.
        This is typically used to create profile images or avatar representations for ENS domains
        in the Decentraland marketplace.

        The generated image can be used as a preview or thumbnail for ENS-based NFTs.
      operationId: generateENSImage
      security: []
      responses:
        '200':
          description: Generated ENS image
          content:
            application/json:
              schema:
                type: object
                properties: &ref_20
                  imageUrl:
                    type: string
                    description: Generated ENS image URL
                  success:
                    type: boolean
                    description: Generation success status
                required: &ref_21
                  - imageUrl
                  - success
  /v1/trades:
    get:
      tags:
        - Trades
      summary: List marketplace trades
      description: |
        Retrieves a list of trades in the marketplace.
        Trades represent peer-to-peer exchanges between users, including offers and accepted deals.

        Results are ordered by creation date (most recent first).

        **Note:** This endpoint currently returns all trades without pagination support.
      operationId: getTrades
      security: []
      responses:
        '200':
          description: List of trades
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties: &ref_4
                    id:
                      type: string
                      description: Trade ID
                    buyer:
                      type: string
                      description: Buyer address
                    seller:
                      type: string
                      description: Seller address
                    item:
                      type: object
                      properties: &ref_6
                        id:
                          type: string
                          description: Item ID
                        name:
                          type: string
                          description: Item name
                        description:
                          type: string
                          description: Item description
                        image:
                          type: string
                          description: Item image URL
                        category:
                          type: string
                          description: Item category
                        rarity:
                          type: string
                          description: Item rarity
                        price:
                          type: number
                          description: Item price
                        owner:
                          type: string
                          description: Item owner
                      required: &ref_7
                        - id
                        - name
                        - category
                    price:
                      type: number
                      description: Trade price
                    status:
                      type: string
                      enum:
                        - pending
                        - completed
                        - cancelled
                      description: Trade status
                    createdAt:
                      type: string
                      format: date-time
                      description: Trade creation timestamp
                  required: &ref_5
                    - id
                    - buyer
                    - seller
                    - price
                    - status
    post:
      tags:
        - Trades
      summary: Create a new trade
      description: |
        Creates a new trade offer in the marketplace.

        **Authentication Required**: This endpoint requires Decentraland authentication with signed metadata.
        The authentication validates:
        - User identity via signed message (ADR-44l)
        - Authorized origins (dcl:marketplace or dcl:builder)
        - Metadata intent (dcl:create-trade)

        The trade will be validated against blockchain data and marketplace rules before creation.
      operationId: createTrade
      security:
        - SignedFetch: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties: &ref_22
                itemId:
                  type: string
                  description: Item ID
                price:
                  type: number
                  description: Trade price
                seller:
                  type: string
                  description: Seller address
              required: &ref_23
                - itemId
                - price
                - seller
      responses:
        '201':
          description: Trade created successfully
          content:
            application/json:
              schema:
                type: object
                properties: *ref_4
                required: *ref_5
        '401':
          description: Unauthorized - invalid signed fetch
          content:
            application/json:
              schema:
                type: object
                properties: *ref_0
                required: *ref_1
        '403':
          description: Forbidden - invalid metadata
          content:
            application/json:
              schema:
                type: object
                properties: *ref_0
                required: *ref_1
  /v1/trades/{id}:
    get:
      tags:
        - Trades
      summary: Get trade by ID
      description: |
        Retrieves detailed information about a specific trade including:
        - Trade participants (buyer and seller)
        - Item details and metadata
        - Trade price and currency
        - Current status (pending, completed, or cancelled)
        - Timestamps (creation, updates, completion)
      operationId: getTrade
      security: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: Unique trade identifier
      responses:
        '200':
          description: Trade details
          content:
            application/json:
              schema:
                type: object
                properties: *ref_4
                required: *ref_5
        '404':
          description: Trade not found
          content:
            application/json:
              schema:
                type: object
                properties: *ref_0
                required: *ref_1
  /v1/trades/{hashedSignature}/accept:
    get:
      tags:
        - Trades
      summary: Get trade acceptance event
      description: |
        Retrieves information about a trade acceptance event using the hashed signature.
        This endpoint is used to verify and track when a trade offer was accepted on-chain.

        The hashed signature serves as a unique identifier linking the off-chain trade
        to its blockchain transaction acceptance event.
      operationId: getTradeAcceptedEvent
      security: []
      parameters:
        - name: hashedSignature
          in: path
          required: true
          schema:
            type: string
          description: Keccak-256 hashed signature of the trade acceptance transaction
      responses:
        '200':
          description: Trade accepted event
          content:
            application/json:
              schema:
                type: object
                properties: &ref_24
                  tradeId:
                    type: string
                    description: Trade ID
                  hashedSignature:
                    type: string
                    description: Hashed signature
                  timestamp:
                    type: string
                    format: date-time
                    description: Event timestamp
                required: &ref_25
                  - tradeId
                  - hashedSignature
        '404':
          description: Event not found
          content:
            application/json:
              schema:
                type: object
                properties: *ref_0
                required: *ref_1
  /v1/bids:
    get:
      tags:
        - Bids
      summary: List marketplace bids
      description: |
        Retrieves a paginated list of bids placed on marketplace items.
        Bids represent offers made by potential buyers on NFTs and items.

        **Filter options:**
        - Bidder and seller addresses
        - Contract address, token ID, and item ID
        - Bid status (open, sold, cancelled)
        - Network (Ethereum, Polygon)

        **Sorting options:**
        - recently_offered (default)
        - recently_updated
        - most_expensive

        **Pagination:** Uses `limit` and `offset` parameters.

        Results include bid amounts, timestamps, and current status.
      operationId: getBids
      security: []
      parameters:
        - name: limit
          in: query
          required: false
          description: 'Maximum number of bids to return per request (default: 100, max: 100)'
          schema:
            type: number
            default: 100
            maximum: 100
            example: 10
        - name: offset
          in: query
          required: false
          description: 'Number of bids to skip for pagination (default: 0)'
          schema:
            type: number
            default: 0
            example: 0
        - name: sortBy
          in: query
          required: false
          description: Sort results by specified criteria
          schema:
            type: string
            enum:
              - recently_offered
              - recently_updated
              - most_expensive
            example: recently_offered
        - name: bidder
          in: query
          required: false
          description: Filter by bidder wallet address
          schema:
            type: string
            example: '0x1234567890abcdef1234567890abcdef12345678'
        - name: seller
          in: query
          required: false
          description: Filter by seller wallet address
          schema:
            type: string
        - name: contractAddress
          in: query
          required: false
          description: Filter by NFT contract address
          schema:
            type: string
            example: '0x1234567890abcdef1234567890abcdef12345678'
        - name: tokenId
          in: query
          required: false
          description: Filter by specific token ID
          schema:
            type: string
        - name: itemId
          in: query
          required: false
          description: Filter by item ID
          schema:
            type: string
        - name: network
          in: query
          required: false
          description: Filter by blockchain network
          schema:
            type: string
            enum:
              - ETHEREUM
              - MATIC
            example: MATIC
        - name: status
          in: query
          required: false
          description: Filter by bid/listing status
          schema:
            type: string
            enum:
              - open
              - sold
              - cancelled
            example: open
      responses:
        '200':
          description: Paginated list of bids
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                    example: true
                  data:
                    type: object
                    properties:
                      results:
                        type: array
                        items:
                          type: object
                          description: A bid placed on an NFT or item in the marketplace
                          properties: &ref_26
                            id:
                              type: string
                              description: Unique bid identifier
                            bidder:
                              type: string
                              description: Bidder wallet address
                              example: '0x1234567890abcdef1234567890abcdef12345678'
                            seller:
                              type: string
                              description: Seller wallet address
                              example: '0x1234567890abcdef1234567890abcdef12345678'
                            price:
                              type: string
                              description: Bid price in Wei
                              example: '1000000000000000000'
                            fingerprint:
                              type: string
                              description: Bid fingerprint for verification
                            status:
                              type: string
                              enum:
                                - open
                                - sold
                                - cancelled
                              description: Current bid status
                            blockchainId:
                              type: string
                              description: Blockchain transaction ID
                            blockNumber:
                              type: string
                              description: Block number when bid was created
                            expiresAt:
                              type: number
                              description: Expiration timestamp (Unix epoch in milliseconds)
                            createdAt:
                              type: number
                              description: Creation timestamp (Unix epoch in milliseconds)
                            updatedAt:
                              type: number
                              description: Last update timestamp (Unix epoch in milliseconds)
                            contractAddress:
                              type: string
                              description: NFT contract address
                            tokenId:
                              type: string
                              description: Token ID being bid on
                            network:
                              type: string
                              enum:
                                - ETHEREUM
                                - MATIC
                              description: Blockchain network
                            chainId:
                              type: number
                              description: Chain ID
                          required: &ref_27
                            - id
                            - bidder
                            - price
                            - status
                      total:
                        type: number
                        description: Total number of bids matching the filters
                      page:
                        type: number
                        description: Current page number (0-indexed)
                      pages:
                        type: number
                        description: Total number of pages
                      limit:
                        type: number
                        description: Number of items per page
                    required:
                      - results
                      - total
                      - page
                      - pages
                      - limit
                required:
                  - ok
                  - data
        '400':
          description: Bad request - invalid parameters
          content:
            application/json:
              schema:
                type: object
                properties: *ref_0
                required: *ref_1
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
                properties: *ref_0
                required: *ref_1
  /v1/nfts:
    get:
      tags:
        - NFTs
      summary: List and search NFTs
      description: |
        Retrieves NFTs from the Decentraland marketplace with comprehensive filtering capabilities.

        **Supports multiple NFT types:**
        - Wearables (clothing, accessories)
        - LAND parcels and Estates
        - ENS names
        - Emotes

        **Advanced filtering options:**
        - Ownership and sale/rental status
        - Categories and search text
        - Price ranges (min/max)
        - LAND-specific: distance to plaza, adjacent to roads, estate size
        - Rental status and rental days for LAND parcels
        - Wearable filters: category, gender, head/accessory/smart types
        - Emote filters: category, play mode, sound, geometry
        - Network selection (Ethereum mainnet, Polygon)
        - Sort by: name, newest, recently listed/sold, cheapest, rental metrics

        **Pagination:** Uses `first` and `skip` parameters (NOT `limit`/`offset`).

        Authentication is optional but provides access to user-specific data like favorites.
      operationId: getNFTs
      security:
        - SignedFetch: []
        - {}
      parameters:
        - name: first
          in: query
          required: false
          description: 'Maximum number of NFTs to return (default: 100)'
          schema:
            type: number
            default: 100
            example: 10
        - name: skip
          in: query
          required: false
          description: 'Number of NFTs to skip for pagination (default: 0)'
          schema:
            type: number
            default: 0
            example: 0
        - name: sortBy
          in: query
          required: false
          description: Sort results by specified criteria
          schema:
            type: string
            enum:
              - name
              - newest
              - recently_listed
              - recently_sold
              - cheapest
              - rental_listing_date
              - rented_date
              - max_rental_price
              - min_rental_price
            example: newest
        - name: category
          in: query
          required: false
          description: Filter by NFT category
          schema:
            type: string
            enum:
              - parcel
              - estate
              - wearable
              - ens
              - emote
            example: wearable
        - name: owner
          in: query
          required: false
          description: Filter by owner wallet address
          schema:
            type: string
            example: '0x1234567890abcdef1234567890abcdef12345678'
        - name: isOnSale
          in: query
          required: false
          description: Filter by whether NFT is currently on sale
          schema:
            type: boolean
            example: true
        - name: isOnRent
          in: query
          required: false
          description: Filter by whether NFT (LAND) is available for rent
          schema:
            type: boolean
        - name: search
          in: query
          required: false
          description: Text search across NFT names and descriptions
          schema:
            type: string
            example: genesis
        - name: isLand
          in: query
          required: false
          description: Filter for LAND parcels and estates only
          schema:
            type: boolean
        - name: isWearableHead
          in: query
          required: false
          description: Filter for head wearables only
          schema:
            type: boolean
        - name: isWearableAccessory
          in: query
          required: false
          description: Filter for accessory wearables only
          schema:
            type: boolean
        - name: isWearableSmart
          in: query
          required: false
          description: Filter for smart wearables only
          schema:
            type: boolean
        - name: wearableCategory
          in: query
          required: false
          description: Filter by specific wearable category
          schema:
            type: string
            enum:
              - eyebrows
              - eyes
              - facial_hair
              - hair
              - body_shape
              - mouth
              - upper_body
              - lower_body
              - feet
              - earring
              - eyewear
              - hat
              - helmet
              - mask
              - tiara
              - top_head
              - skin
              - hands_wear
            example: upper_body
        - name: wearableGender
          in: query
          required: false
          description: Filter by wearable gender compatibility. Can be repeated.
          schema:
            type: array
            items:
              type: string
              enum:
                - male
                - female
                - unisex
          style: form
          explode: true
        - name: emoteCategory
          in: query
          required: false
          description: Filter by emote category
          schema:
            type: string
            enum:
              - dance
              - stunt
              - greetings
              - fun
              - poses
              - reactions
              - horror
              - miscellaneous
            example: dance
        - name: emoteGender
          in: query
          required: false
          description: Filter by emote gender compatibility. Can be repeated.
          schema:
            type: array
            items:
              type: string
              enum:
                - male
                - female
                - unisex
          style: form
          explode: true
        - name: emotePlayMode
          in: query
          required: false
          description: Filter by emote play mode. Can be repeated.
          schema:
            type: array
            items:
              type: string
              enum:
                - simple
                - loop
          style: form
          explode: true
        - name: emoteHasGeometry
          in: query
          required: false
          description: Filter for emotes with geometry/props
          schema:
            type: boolean
        - name: emoteHasSound
          in: query
          required: false
          description: Filter for emotes with sound
          schema:
            type: boolean
        - name: contractAddress
          in: query
          required: false
          description: Filter by collection contract address(es). Can be repeated.
          schema:
            type: array
            items:
              type: string
          style: form
          explode: true
        - name: creator
          in: query
          required: false
          description: Filter by creator wallet address(es). Can be repeated.
          schema:
            type: array
            items:
              type: string
          style: form
          explode: true
        - name: tokenId
          in: query
          required: false
          description: Filter by specific token ID
          schema:
            type: string
        - name: itemRarity
          in: query
          required: false
          description: Filter by item rarity. Can be repeated.
          schema:
            type: array
            items:
              type: string
              enum:
                - unique
                - mythic
                - exotic
                - legendary
                - epic
                - rare
                - uncommon
                - common
          style: form
          explode: true
        - name: itemId
          in: query
          required: false
          description: Filter by specific item ID within a collection
          schema:
            type: string
        - name: network
          in: query
          required: false
          description: Filter by blockchain network
          schema:
            type: string
            enum:
              - ETHEREUM
              - MATIC
            example: MATIC
        - name: rentalStatus
          in: query
          required: false
          description: Filter by rental status (for LAND). Can be repeated.
          schema:
            type: array
            items:
              type: string
              enum:
                - open
                - cancelled
                - executed
                - claimed
          style: form
          explode: true
        - name: adjacentToRoad
          in: query
          required: false
          description: Filter for LAND parcels adjacent to roads
          schema:
            type: boolean
        - name: minDistanceToPlaza
          in: query
          required: false
          description: Minimum distance to plaza (for LAND filtering)
          schema:
            type: number
        - name: maxDistanceToPlaza
          in: query
          required: false
          description: Maximum distance to plaza (for LAND filtering)
          schema:
            type: number
        - name: tenant
          in: query
          required: false
          description: Filter by tenant wallet address (for rented LAND)
          schema:
            type: string
        - name: minPrice
          in: query
          required: false
          description: Minimum price filter in ETH/MATIC (e.g., "0.1")
          schema:
            type: string
            example: '0.1'
        - name: maxPrice
          in: query
          required: false
          description: Maximum price filter in ETH/MATIC (e.g., "100")
          schema:
            type: string
            example: '100'
        - name: minEstateSize
          in: query
          required: false
          description: Minimum estate size (number of parcels)
          schema:
            type: number
        - name: maxEstateSize
          in: query
          required: false
          description: Maximum estate size (number of parcels)
          schema:
            type: number
        - name: rentalDays
          in: query
          required: false
          description: Filter by rental period in days. Can be repeated.
          schema:
            type: array
            items:
              type: number
          style: form
          explode: true
      responses:
        '200':
          description: List of NFTs with total count
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      properties: &ref_28
                        id:
                          type: string
                          description: NFT ID
                        tokenId:
                          type: string
                          description: Token ID
                        contract:
                          type: string
                          description: Contract address
                        owner:
                          type: string
                          description: Owner address
                        metadata:
                          type: object
                          description: NFT metadata
                        price:
                          type: number
                          description: NFT price
                      required: &ref_29
                        - id
                        - tokenId
                        - contract
                        - owner
                  total:
                    type: number
                    description: Total number of NFTs matching the filters
                required:
                  - data
                  - total
        '400':
          description: Bad request - invalid parameters
          content:
            application/json:
              schema:
                type: object
                properties: *ref_0
                required: *ref_1
  /v1/orders:
    get:
      tags:
        - Orders
      summary: List marketplace orders
      description: |
        Retrieves marketplace orders (listings) for NFTs and items.
        Orders represent sell listings created by item owners.

        **Filter options:**
        - Contract address, token ID, and item ID
        - Order status (open, sold, cancelled)
        - Owner (seller) or buyer addresses
        - Marketplace address
        - NFT name search
        - Network (Ethereum, Polygon)

        **Sorting options:**
        - recently_listed, recently_updated, cheapest
        - issued_id_asc, issued_id_desc, oldest

        **Pagination:** Uses `first` and `skip` parameters (NOT `limit`/`offset`).

        Use this endpoint to find available items for purchase and their pricing.
      operationId: getOrders
      security: []
      parameters:
        - name: first
          in: query
          required: false
          description: 'Maximum number of orders to return (default: 100)'
          schema:
            type: number
            default: 100
            example: 10
        - name: skip
          in: query
          required: false
          description: 'Number of orders to skip for pagination (default: 0)'
          schema:
            type: number
            default: 0
            example: 0
        - name: sortBy
          in: query
          required: false
          description: Sort results by specified criteria
          schema:
            type: string
            enum:
              - recently_listed
              - recently_updated
              - cheapest
              - issued_id_asc
              - issued_id_desc
              - oldest
            example: recently_listed
        - name: marketplaceAddress
          in: query
          required: false
          description: Filter by marketplace contract address
          schema:
            type: string
        - name: owner
          in: query
          required: false
          description: Filter by owner (seller) wallet address
          schema:
            type: string
            example: '0x1234567890abcdef1234567890abcdef12345678'
        - name: buyer
          in: query
          required: false
          description: Filter by buyer wallet address
          schema:
            type: string
        - name: contractAddress
          in: query
          required: false
          description: Filter by NFT contract address
          schema:
            type: string
            example: '0x1234567890abcdef1234567890abcdef12345678'
        - name: tokenId
          in: query
          required: false
          description: Filter by specific token ID
          schema:
            type: string
        - name: status
          in: query
          required: false
          description: Filter by order status
          schema:
            type: string
            enum:
              - open
              - sold
              - cancelled
            example: open
        - name: network
          in: query
          required: false
          description: Filter by blockchain network
          schema:
            type: string
            enum:
              - ETHEREUM
              - MATIC
            example: MATIC
        - name: itemId
          in: query
          required: false
          description: Filter by item ID
          schema:
            type: string
        - name: nftName
          in: query
          required: false
          description: Filter by NFT name
          schema:
            type: string
      responses:
        '200':
          description: List of orders with total count
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      properties: &ref_30
                        id:
                          type: string
                          description: Order ID
                        maker:
                          type: string
                          description: Maker address
                        taker:
                          type: string
                          description: Taker address
                        item:
                          type: object
                          properties: *ref_6
                          required: *ref_7
                        price:
                          type: number
                          description: Order price
                        status:
                          type: string
                          enum:
                            - open
                            - filled
                            - cancelled
                          description: Order status
                        createdAt:
                          type: string
                          format: date-time
                          description: Order creation timestamp
                      required: &ref_31
                        - id
                        - maker
                        - price
                        - status
                  total:
                    type: number
                    description: Total number of orders matching the filters
                required:
                  - data
                  - total
        '400':
          description: Bad request - invalid parameters
          content:
            application/json:
              schema:
                type: object
                properties: *ref_0
                required: *ref_1
  /v1/contracts:
    get:
      tags:
        - Contracts
      summary: List smart contracts and collections
      description: |
        Retrieves smart contract addresses and collection information available in the marketplace.

        This endpoint returns both marketplace contracts (LAND, Estates, Names, etc.) 
        and collection contracts (primarily wearables) from the database.

        **Contract Types:**
        - **Marketplace Contracts**: Core Decentraland contracts including LAND parcels, Estates, ENS Names, and legacy wearable collections
        - **Collection Contracts**: Third-party and creator collections, primarily wearables on Polygon network

        **Filter Options:**
        - Category filtering (parcel, estate, ens, wearable, emote)
        - Network filtering
        - Pagination (first/skip)

        **Pagination:**
        - Use `first` and `skip` parameters for pagination
        - `first=0` returns all results (no limit)
        - `skip` allows you to skip the first N results
        - Pagination is applied after category and network filters

        **Use Cases:**
        - Retrieve contract addresses for specific NFT categories
        - List all available collections in the marketplace
        - Filter contracts by network
        - Paginate through large result sets

        **Response Structure:**
        Each contract includes:
        - Contract address
        - Contract name
        - NFT category (parcel, estate, ens, wearable, emote)
        - Network
        - Chain ID

        **Performance Notes:**
        - Collection contracts are cached for 1 hour to improve performance
        - Use category and network filters to reduce response size
        - Pagination is applied in-memory after fetching all matching contracts
      operationId: getContracts
      security: []
      parameters:
        - name: category
          in: query
          required: false
          description: Filter by NFT category
          schema:
            type: string
            enum:
              - parcel
              - estate
              - ens
              - wearable
              - emote
            example: wearable
        - name: network
          in: query
          required: false
          description: Filter by network
          schema:
            type: string
            enum:
              - ETHEREUM
              - MATIC
            example: MATIC
        - name: first
          in: query
          required: false
          description: 'Maximum number of contracts to return. Use 0 to return all results (default: 0)'
          schema:
            type: number
            default: 0
            minimum: 0
            example: 10
        - name: skip
          in: query
          required: false
          description: 'Number of contracts to skip for pagination (default: 0)'
          schema:
            type: number
            default: 0
            minimum: 0
            example: 0
      responses:
        '200':
          description: List of contracts with total count
          content:
            application/json:
              schema:
                type: object
                properties: &ref_66
                  data:
                    type: array
                    items:
                      type: object
                      properties: &ref_68
                        name:
                          type: string
                          description: Human-readable name of the contract or collection
                          example: Decentraland Wearables
                        address:
                          type: string
                          pattern: ^0x[a-fA-F0-9]{40}$
                          description: Contract address
                          example: '0x123456789abcdef123456789abcdef0123456789'
                        category:
                          type: string
                          enum:
                            - parcel
                            - estate
                            - ens
                            - wearable
                            - emote
                          description: |
                            NFT category type:
                            - parcel: LAND parcels
                            - estate: Estate (group of LAND parcels)
                            - ens: Ethereum Name Service names
                            - wearable: Avatar wearables
                            - emote: Avatar emotes/animations
                          example: wearable
                        network:
                          type: string
                          enum:
                            - ETHEREUM
                            - MATIC
                          description: |
                            Blockchain network:
                            - ETHEREUM: Ethereum mainnet
                            - MATIC: Polygon network
                          example: MATIC
                        chainId:
                          type: number
                          enum:
                            - 1
                            - 137
                          description: |
                            Blockchain chain ID:
                            - 1: Ethereum mainnet
                            - 137: Polygon mainnet
                          example: 137
                      required: &ref_69
                        - name
                        - address
                        - category
                        - network
                        - chainId
                    description: List of contracts
                  total:
                    type: number
                    description: Total number of contracts matching the query
                required: &ref_67
                  - data
                  - total
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
                properties: *ref_0
                required: *ref_1
  /v1/items:
    get:
      tags:
        - Items
      summary: List marketplace items
      description: |
        Retrieves items from marketplace collections.
        Items are templates/blueprints for NFTs in collections (e.g., wearable designs, emote templates).

        **Filter capabilities:**
        - Specific contract address and item ID
        - Category (wearable, emote)
        - Creator addresses (multiple allowed)
        - Sale and sold-out status
        - Text search by name or description
        - Price range filtering
        - Wearable filters: category, gender, head/accessory/smart types
        - Emote filters: category, play mode, sound, geometry
        - Network selection (Ethereum, Polygon)
        - URN and ID filtering

        **Pagination:** Uses `first` and `skip` parameters (NOT `limit`/`offset`).

        Authentication is optional but may provide personalized results including pick statistics.
      operationId: getItems
      security:
        - SignedFetch: []
        - {}
      parameters:
        - name: first
          in: query
          required: false
          description: 'Maximum number of items to return (default: 100)'
          schema:
            type: number
            default: 100
            example: 10
        - name: skip
          in: query
          required: false
          description: 'Number of items to skip for pagination (default: 0)'
          schema:
            type: number
            default: 0
            example: 0
        - name: category
          in: query
          required: false
          description: Filter by NFT category
          schema:
            type: string
            enum:
              - wearable
              - emote
            example: wearable
        - name: creator
          in: query
          required: false
          description: Filter by creator wallet address(es). Can be repeated for multiple creators.
          schema:
            type: array
            items:
              type: string
          style: form
          explode: true
          example:
            - '0x1234567890abcdef1234567890abcdef12345678'
        - name: isSoldOut
          in: query
          required: false
          description: Filter by sold out status
          schema:
            type: boolean
            example: false
        - name: isOnSale
          in: query
          required: false
          description: Filter by whether item is currently on sale
          schema:
            type: boolean
            example: true
        - name: search
          in: query
          required: false
          description: Text search across item names and descriptions
          schema:
            type: string
            example: cyberpunk
        - name: isWearableHead
          in: query
          required: false
          description: Filter for head wearables only
          schema:
            type: boolean
        - name: isWearableAccessory
          in: query
          required: false
          description: Filter for accessory wearables only
          schema:
            type: boolean
        - name: isWearableSmart
          in: query
          required: false
          description: Filter for smart wearables only
          schema:
            type: boolean
        - name: wearableCategory
          in: query
          required: false
          description: Filter by specific wearable category
          schema:
            type: string
            enum:
              - eyebrows
              - eyes
              - facial_hair
              - hair
              - body_shape
              - mouth
              - upper_body
              - lower_body
              - feet
              - earring
              - eyewear
              - hat
              - helmet
              - mask
              - tiara
              - top_head
              - skin
              - hands_wear
            example: upper_body
        - name: rarity
          in: query
          required: false
          description: Filter by rarity. Can be repeated for multiple rarities.
          schema:
            type: array
            items:
              type: string
              enum:
                - unique
                - mythic
                - exotic
                - legendary
                - epic
                - rare
                - uncommon
                - common
          style: form
          explode: true
          example:
            - legendary
        - name: wearableGender
          in: query
          required: false
          description: Filter by wearable gender compatibility. Can be repeated.
          schema:
            type: array
            items:
              type: string
              enum:
                - male
                - female
                - unisex
          style: form
          explode: true
          example:
            - unisex
        - name: emoteCategory
          in: query
          required: false
          description: Filter by emote category
          schema:
            type: string
            enum:
              - dance
              - stunt
              - greetings
              - fun
              - poses
              - reactions
              - horror
              - miscellaneous
            example: dance
        - name: emoteGender
          in: query
          required: false
          description: Filter by emote gender compatibility. Can be repeated.
          schema:
            type: array
            items:
              type: string
              enum:
                - male
                - female
                - unisex
          style: form
          explode: true
        - name: emotePlayMode
          in: query
          required: false
          description: Filter by emote play mode. Can be repeated.
          schema:
            type: array
            items:
              type: string
              enum:
                - simple
                - loop
          style: form
          explode: true
          example:
            - loop
        - name: emoteHasGeometry
          in: query
          required: false
          description: Filter for emotes with geometry/props
          schema:
            type: boolean
        - name: emoteHasSound
          in: query
          required: false
          description: Filter for emotes with sound
          schema:
            type: boolean
        - name: contractAddress
          in: query
          required: false
          description: Filter by collection contract address(es). Can be repeated.
          schema:
            type: array
            items:
              type: string
          style: form
          explode: true
          example:
            - '0x1234567890abcdef1234567890abcdef12345678'
        - name: itemId
          in: query
          required: false
          description: Filter by specific item ID within a collection
          schema:
            type: string
            example: '0'
        - name: network
          in: query
          required: false
          description: Filter by blockchain network
          schema:
            type: string
            enum:
              - ETHEREUM
              - MATIC
            example: MATIC
        - name: minPrice
          in: query
          required: false
          description: Minimum price filter in ETH/MATIC (e.g., "0.1")
          schema:
            type: string
            example: '0.1'
        - name: maxPrice
          in: query
          required: false
          description: Maximum price filter in ETH/MATIC (e.g., "100")
          schema:
            type: string
            example: '100'
        - name: urn
          in: query
          required: false
          description: Filter by item URN(s). Can be repeated.
          schema:
            type: array
            items:
              type: string
          style: form
          explode: true
        - name: id
          in: query
          required: false
          description: Filter by item ID(s). Can be repeated.
          schema:
            type: array
            items:
              type: string
          style: form
          explode: true
      responses:
        '200':
          description: List of items with total count
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      properties: *ref_6
                      required: *ref_7
                  total:
                    type: number
                    description: Total number of items matching the filters
                required:
                  - data
                  - total
        '400':
          description: Bad request - invalid parameters
          content:
            application/json:
              schema:
                type: object
                properties: *ref_0
                required: *ref_1
  /v1/sales:
    get:
      tags:
        - Sales
      summary: List completed sales
      description: |
        Retrieves historical sales transactions from the marketplace.
        Sales represent completed purchases of NFTs and items.

        **Use this endpoint to:**
        - Track sales history and market activity
        - Analyze price trends
        - View transaction details (buyer, seller, price, timestamp)

        **Filter options:**
        - Sale type (order, bid, mint)
        - Categories (wearable, emote, parcel, estate, ens)
        - Seller and buyer addresses
        - Contract address, token ID, and item ID
        - Time range filtering (from/to timestamps)
        - Price range (min/max)
        - Network (Ethereum, Polygon)

        **Sorting options:**
        - recently_sold (default)
        - most_expensive

        **Pagination:** Uses `first` and `skip` parameters (NOT `limit`/`offset`).
      operationId: getSales
      security: []
      parameters:
        - name: first
          in: query
          required: false
          description: 'Maximum number of sales to return (default: 100)'
          schema:
            type: number
            default: 100
            example: 10
        - name: skip
          in: query
          required: false
          description: 'Number of sales to skip for pagination (default: 0)'
          schema:
            type: number
            default: 0
            example: 0
        - name: sortBy
          in: query
          required: false
          description: Sort results by specified criteria
          schema:
            type: string
            enum:
              - recently_sold
              - most_expensive
            example: recently_sold
        - name: type
          in: query
          required: false
          description: Filter by sale type
          schema:
            type: string
            enum:
              - order
              - bid
              - mint
            example: order
        - name: category
          in: query
          required: false
          description: Filter by NFT category. Can be repeated for multiple categories.
          schema:
            type: array
            items:
              type: string
              enum:
                - parcel
                - estate
                - wearable
                - ens
                - emote
          style: form
          explode: true
          example:
            - wearable
        - name: seller
          in: query
          required: false
          description: Filter by seller wallet address
          schema:
            type: string
            example: '0x1234567890abcdef1234567890abcdef12345678'
        - name: buyer
          in: query
          required: false
          description: Filter by buyer wallet address
          schema:
            type: string
        - name: contractAddress
          in: query
          required: false
          description: Filter by NFT contract address
          schema:
            type: string
            example: '0x1234567890abcdef1234567890abcdef12345678'
        - name: tokenId
          in: query
          required: false
          description: Filter by specific token ID
          schema:
            type: string
        - name: itemId
          in: query
          required: false
          description: Filter by item ID
          schema:
            type: string
        - name: from
          in: query
          required: false
          description: Filter sales from this Unix timestamp (in seconds)
          schema:
            type: number
            example: 1640000000
        - name: to
          in: query
          required: false
          description: Filter sales up to this Unix timestamp (in seconds)
          schema:
            type: number
            example: 1650000000
        - name: minPrice
          in: query
          required: false
          description: Minimum sale price filter
          schema:
            type: string
            example: '0.1'
        - name: maxPrice
          in: query
          required: false
          description: Maximum sale price filter
          schema:
            type: string
            example: '100'
        - name: network
          in: query
          required: false
          description: Filter by blockchain network
          schema:
            type: string
            enum:
              - ETHEREUM
              - MATIC
            example: MATIC
      responses:
        '200':
          description: List of sales with total count
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      properties: &ref_32
                        id:
                          type: string
                          description: Sale ID
                        buyer:
                          type: string
                          description: Buyer address
                        seller:
                          type: string
                          description: Seller address
                        item:
                          type: object
                          properties: *ref_6
                          required: *ref_7
                        price:
                          type: number
                          description: Sale price
                        timestamp:
                          type: string
                          format: date-time
                          description: Sale timestamp
                      required: &ref_33
                        - id
                        - buyer
                        - seller
                        - price
                  total:
                    type: number
                    description: Total number of sales matching the filters
                required:
                  - data
                  - total
        '400':
          description: Bad request - invalid parameters
          content:
            application/json:
              schema:
                type: object
                properties: *ref_0
                required: *ref_1
  /v1/prices:
    get:
      tags:
        - Prices
      summary: Get current market prices
      description: |
        Retrieves current cryptocurrency and token price information used in the marketplace.

        Returns price data for:
        - MANA (Decentraland's native token)
        - ETH (Ethereum)
        - Other supported currencies

        Prices are typically provided in USD and updated regularly.
        Use this endpoint to display current conversion rates and calculate fiat equivalents.
      operationId: getPrices
      security: []
      responses:
        '200':
          description: Price information
          content:
            application/json:
              schema:
                type: object
                properties: &ref_34
                  prices:
                    type: object
                    description: Price data by category
                  timestamp:
                    type: string
                    format: date-time
                    description: Price timestamp
                required: &ref_35
                  - prices
  /v1/trendings:
    get:
      tags:
        - Trending
      summary: Get trending marketplace items
      description: |
        Retrieves currently trending items in the marketplace based on various metrics.

        Trending scores are calculated from:
        - Recent sales volume
        - Number of views and interactions
        - Price movements
        - Time-weighted activity

        Use this endpoint to display popular items and identify market trends.
        Results are updated periodically and represent the most active items in the marketplace.
      operationId: getTrendings
      security: []
      responses:
        '200':
          description: Trending items
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties: &ref_36
                    item:
                      type: object
                      properties: *ref_6
                      required: *ref_7
                    trendScore:
                      type: number
                      description: Trend score
                    volume:
                      type: number
                      description: Trading volume
                  required: &ref_37
                    - item
                    - trendScore
  /v1/stats/{category}/{stat}:
    get:
      tags:
        - Statistics
      summary: Get marketplace statistics
      description: |
        Retrieves specific statistical data for marketplace categories.

        Common categories:
        - wearable: Statistics for wearable items
        - emote: Statistics for emotes
        - land: Statistics for LAND parcels
        - ens: Statistics for ENS names

        Common stat types:
        - sales_volume: Total sales volume in specified timeframe
        - average_price: Average sale price
        - unique_buyers: Number of unique buyers
        - unique_sellers: Number of unique sellers

        Use this endpoint for analytics dashboards and market insights.
      operationId: getStats
      security: []
      parameters:
        - name: category
          in: path
          required: true
          schema:
            type: string
            enum:
              - wearable
              - emote
              - land
              - ens
              - all
          description: Item category for statistics (e.g., wearable, emote, land)
        - name: stat
          in: path
          required: true
          schema:
            type: string
          description: Type of statistic to retrieve (e.g., sales_volume, average_price)
      responses:
        '200':
          description: Statistics data
          content:
            application/json:
              schema:
                type: object
                properties: &ref_38
                  category:
                    type: string
                    description: Statistics category
                  stat:
                    type: string
                    description: Statistics type
                  value:
                    type: number
                    description: Statistics value
                  timestamp:
                    type: string
                    format: date-time
                    description: Statistics timestamp
                required: &ref_39
                  - category
                  - stat
                  - value
  /v1/rankings/{entity}/{timeframe}:
    get:
      tags:
        - Rankings
      summary: Get marketplace rankings
      description: |
        Retrieves ranked lists of marketplace entities based on various metrics and timeframes.

        Entity types:
        - collections: Top-performing collections
        - creators: Most active or highest-earning creators
        - items: Best-selling items
        - sellers: Top sellers by volume

        Timeframes:
        - day: Last 24 hours
        - week: Last 7 days
        - month: Last 30 days
        - all: All-time rankings

        Rankings are calculated based on sales volume, transaction count, and other relevant metrics.
      operationId: getRankings
      security: []
      parameters:
        - name: entity
          in: path
          required: true
          schema:
            type: string
            enum:
              - collections
              - creators
              - items
              - sellers
          description: Type of entity to rank (collections, creators, items, sellers)
        - name: timeframe
          in: path
          required: true
          schema:
            type: string
            enum:
              - day
              - week
              - month
              - all
          description: Time period for rankings (day, week, month, all)
      responses:
        '200':
          description: Rankings data
          content:
            application/json:
              schema:
                type: object
                properties: &ref_40
                  entity:
                    type: string
                    description: Entity type
                  timeframe:
                    type: string
                    description: Timeframe
                  rankings:
                    type: array
                    items:
                      type: object
                    description: Rankings data
                required: &ref_41
                  - entity
                  - timeframe
                  - rankings
  /v1/volume/{timeframe}:
    get:
      tags:
        - Volume
      summary: Get trading volume data
      description: |
        Retrieves total trading volume for the marketplace within a specified timeframe.

        Volume metrics include:
        - Total sales amount (in MANA and USD)
        - Number of transactions
        - Unique traders (buyers and sellers)

        Available timeframes:
        - day: Last 24 hours
        - week: Last 7 days
        - month: Last 30 days
        - all: All-time volume

        Use this data for market health monitoring and trend analysis.
      operationId: getVolume
      security: []
      parameters:
        - name: timeframe
          in: path
          required: true
          schema:
            type: string
            enum:
              - day
              - week
              - month
              - all
          description: Time period for volume calculation (day, week, month, all)
      responses:
        '200':
          description: Volume data
          content:
            application/json:
              schema:
                type: object
                properties: &ref_42
                  timeframe:
                    type: string
                    description: Timeframe
                  volume:
                    type: number
                    description: Volume value
                  timestamp:
                    type: string
                    format: date-time
                    description: Volume timestamp
                required: &ref_43
                  - timeframe
                  - volume
  /v1/lists/{id}/picks:
    get:
      tags:
        - Lists
        - Picks
      summary: Get picks from a favorites list
      description: |
        Retrieves all items (picks) that have been added to a specific favorites list.
        Lists are user-curated collections of marketplace items.

        Authentication is optional but recommended to access private lists or user-specific data.
      operationId: getListPicks
      security:
        - SignedFetch: []
        - {}
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: Unique identifier of the favorites list
      responses:
        '200':
          description: List picks
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties: &ref_8
                    id:
                      type: string
                      description: Pick ID
                    itemId:
                      type: string
                      description: Item ID
                    listId:
                      type: string
                      description: List ID
                    user:
                      type: string
                      description: User address
                    createdAt:
                      type: string
                      format: date-time
                      description: Pick creation timestamp
                  required: &ref_9
                    - id
                    - itemId
                    - listId
                    - user
    post:
      tags:
        - Lists
        - Picks
      summary: Add item to favorites list
      description: |
        Adds an item (pick) to a user's favorites list.

        **Authentication Required**: User must be authenticated and authorized to modify the list.
        Only list owners and users with granted access can add items.
      operationId: addPickToList
      security:
        - SignedFetch: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: Unique identifier of the favorites list
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties: &ref_44
                itemId:
                  type: string
                  description: Item ID
              required: &ref_45
                - itemId
      responses:
        '201':
          description: Pick added successfully
          content:
            application/json:
              schema:
                type: object
                properties: *ref_8
                required: *ref_9
        '401':
          description: Unauthorized - invalid signed fetch
          content:
            application/json:
              schema:
                type: object
                properties: *ref_0
                required: *ref_1
        '403':
          description: Forbidden - invalid metadata
          content:
            application/json:
              schema:
                type: object
                properties: *ref_0
                required: *ref_1
  /v1/lists/{id}/picks/{itemId}:
    delete:
      tags:
        - Lists
        - Picks
      summary: Remove item from favorites list
      description: |
        Removes a specific item (pick) from a favorites list.

        **Authentication Required**: User must be authenticated and authorized to modify the list.
        Only list owners and users with granted access can remove items.
      operationId: removePickFromList
      security:
        - SignedFetch: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: Unique identifier of the favorites list
        - name: itemId
          in: path
          required: true
          schema:
            type: string
          description: Unique identifier of the item to remove
      responses:
        '200':
          description: Pick removed successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
        '401':
          description: Unauthorized - invalid signed fetch
          content:
            application/json:
              schema:
                type: object
                properties: *ref_0
                required: *ref_1
        '403':
          description: Forbidden - invalid metadata
          content:
            application/json:
              schema:
                type: object
                properties: *ref_0
                required: *ref_1
  /v1/picks/{itemId}/stats:
    get:
      tags:
        - Picks
      summary: Get statistics for a specific item
      description: |
        Retrieves pick statistics for a specific marketplace item.

        Returns:
        - Total number of times the item has been picked (added to lists)
        - Number of different lists containing this item
        - Popularity metrics

        Authentication is optional but may provide additional user-specific data.
      operationId: getPickStats
      security:
        - SignedFetch: []
        - {}
      parameters:
        - name: itemId
          in: path
          required: true
          schema:
            type: string
          description: Unique identifier of the marketplace item
      responses:
        '200':
          description: Pick statistics
          content:
            application/json:
              schema:
                type: object
                properties: &ref_46
                  itemId:
                    type: string
                    description: Item ID
                  pickCount:
                    type: number
                    description: Number of picks
                  listsCount:
                    type: number
                    description: Number of lists containing this item
                required: &ref_47
                  - itemId
                  - pickCount
                  - listsCount
  /v1/picks/stats:
    get:
      tags:
        - Picks
      summary: Get global pick statistics
      description: |
        Retrieves aggregated statistics across all picks in the marketplace.

        Returns:
        - Total number of picks across all lists
        - Total number of unique items that have been picked
        - Total number of active lists

        Use this endpoint for global marketplace analytics and engagement metrics.
      operationId: getAllPicksStats
      security: []
      responses:
        '200':
          description: All picks statistics
          content:
            application/json:
              schema:
                type: object
                properties: &ref_48
                  totalPicks:
                    type: number
                    description: Total number of picks
                  totalItems:
                    type: number
                    description: Total number of items picked
                  totalLists:
                    type: number
                    description: Total number of lists
                required: &ref_49
                  - totalPicks
                  - totalItems
                  - totalLists
  /v1/picks/{itemId}:
    get:
      tags:
        - Picks
      summary: Get all picks for a specific item
      description: |
        Retrieves all pick instances for a specific marketplace item.
        Shows which lists contain this item and associated pick metadata.

        Authentication is optional but may provide access to private lists if the user has permissions.
      operationId: getPicksForItem
      security:
        - SignedFetch: []
        - {}
      parameters:
        - name: itemId
          in: path
          required: true
          schema:
            type: string
          description: Unique identifier of the marketplace item
      responses:
        '200':
          description: Item picks
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties: *ref_8
                  required: *ref_9
    post:
      tags:
        - Picks
      summary: Bulk pick/unpick operation
      description: |
        Adds or removes an item from multiple favorites lists in a single operation.

        **Authentication Required**: User must be authenticated and authorized.

        Use cases:
        - Add an item to multiple lists at once
        - Remove an item from multiple lists at once

        This is more efficient than making individual pick/unpick requests when managing multiple lists.
      operationId: bulkPickUnpick
      security:
        - SignedFetch: []
      parameters:
        - name: itemId
          in: path
          required: true
          schema:
            type: string
          description: Unique identifier of the marketplace item to pick/unpick
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties: &ref_50
                action:
                  type: string
                  enum:
                    - pick
                    - unpick
                  description: Action to perform
                listIds:
                  type: array
                  items:
                    type: string
                  description: List of list IDs
              required: &ref_51
                - action
                - listIds
      responses:
        '200':
          description: Bulk operation completed
          content:
            application/json:
              schema:
                type: object
                properties: &ref_52
                  success:
                    type: boolean
                    description: Operation success status
                  processed:
                    type: number
                    description: Number of items processed
                required: &ref_53
                  - success
                  - processed
        '401':
          description: Unauthorized - invalid signed fetch
          content:
            application/json:
              schema:
                type: object
                properties: *ref_0
                required: *ref_1
        '403':
          description: Forbidden - invalid metadata
          content:
            application/json:
              schema:
                type: object
                properties: *ref_0
                required: *ref_1
  /v1/lists/{id}:
    get:
      tags:
        - Lists
      summary: Get favorites list details
      description: |
        Retrieves detailed information about a specific favorites list.

        Returns:
        - List name and description
        - Owner information
        - Privacy settings (public/private)
        - Item count
        - Creation and update timestamps

        Authentication may be required for private lists depending on access permissions.
      operationId: getListDetails
      security:
        - SignedFetch: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: Unique identifier of the favorites list
      responses:
        '200':
          description: List details
          content:
            application/json:
              schema:
                type: object
                properties: &ref_10
                  id:
                    type: string
                    description: List ID
                  name:
                    type: string
                    description: List name
                  description:
                    type: string
                    description: List description
                  owner:
                    type: string
                    description: List owner
                  isPublic:
                    type: boolean
                    description: Whether list is public
                  itemCount:
                    type: number
                    description: Number of items in list
                  createdAt:
                    type: string
                    format: date-time
                    description: List creation timestamp
                required: &ref_11
                  - id
                  - name
                  - owner
                  - isPublic
                  - itemCount
        '404':
          description: List not found
          content:
            application/json:
              schema:
                type: object
                properties: *ref_0
                required: *ref_1
    put:
      tags:
        - Lists
      summary: Update favorites list
      description: |
        Updates an existing favorites list's properties.

        **Authentication Required**: Only the list owner can update list details.

        Updatable fields:
        - List name
        - Description
        - Privacy settings (public/private)
      operationId: updateList
      security:
        - SignedFetch: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: Unique identifier of the favorites list to update
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties: &ref_56
                name:
                  type: string
                  description: List name
                description:
                  type: string
                  description: List description
                isPublic:
                  type: boolean
                  description: Whether list should be public
              required: &ref_57
                - name
                - isPublic
      responses:
        '200':
          description: List updated successfully
          content:
            application/json:
              schema:
                type: object
                properties: *ref_10
                required: *ref_11
        '401':
          description: Unauthorized - invalid signed fetch
          content:
            application/json:
              schema:
                type: object
                properties: *ref_0
                required: *ref_1
        '403':
          description: Forbidden - invalid metadata
          content:
            application/json:
              schema:
                type: object
                properties: *ref_0
                required: *ref_1
        '404':
          description: List not found
          content:
            application/json:
              schema:
                type: object
                properties: *ref_0
                required: *ref_1
    delete:
      tags:
        - Lists
      summary: Delete favorites list
      description: |
        Permanently deletes a favorites list and all its picks.

        **Authentication Required**: Only the list owner can delete the list.

        **Warning**: This action is irreversible. All items in the list will be removed.
      operationId: deleteList
      security:
        - SignedFetch: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: Unique identifier of the favorites list to delete
      responses:
        '200':
          description: List deleted successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
        '401':
          description: Unauthorized - invalid signed fetch
          content:
            application/json:
              schema:
                type: object
                properties: *ref_0
                required: *ref_1
        '403':
          description: Forbidden - invalid metadata
          content:
            application/json:
              schema:
                type: object
                properties: *ref_0
                required: *ref_1
        '404':
          description: List not found
          content:
            application/json:
              schema:
                type: object
                properties: *ref_0
                required: *ref_1
  /v1/lists:
    get:
      tags:
        - Lists
      summary: Get user's favorites lists
      description: |
        Retrieves all favorites lists owned by the authenticated user.

        **Authentication Required**: User must be authenticated to view their lists.

        Returns both public and private lists owned by the user, including:
        - List metadata (name, description, privacy settings)
        - Item counts
        - Creation and update timestamps
      operationId: getUserLists
      security:
        - SignedFetch: []
      responses:
        '200':
          description: User lists
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties: *ref_10
                  required: *ref_11
        '401':
          description: Unauthorized - invalid signed fetch
          content:
            application/json:
              schema:
                type: object
                properties: *ref_0
                required: *ref_1
        '403':
          description: Forbidden - invalid metadata
          content:
            application/json:
              schema:
                type: object
                properties: *ref_0
                required: *ref_1
    post:
      tags:
        - Lists
      summary: Create new favorites list
      description: |
        Creates a new favorites list for the authenticated user.

        **Authentication Required**: User must be authenticated.

        When creating a list, specify:
        - List name (required)
        - Description (optional)
        - Privacy setting: public or private (required)

        Public lists can be viewed by anyone, while private lists are only accessible to the owner
        and users who have been granted explicit access.
      operationId: createList
      security:
        - SignedFetch: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties: &ref_54
                name:
                  type: string
                  description: List name
                description:
                  type: string
                  description: List description
                isPublic:
                  type: boolean
                  description: Whether list should be public
              required: &ref_55
                - name
                - isPublic
      responses:
        '201':
          description: List created successfully
          content:
            application/json:
              schema:
                type: object
                properties: *ref_10
                required: *ref_11
        '401':
          description: Unauthorized - invalid signed fetch
          content:
            application/json:
              schema:
                type: object
                properties: *ref_0
                required: *ref_1
        '403':
          description: Forbidden - invalid metadata
          content:
            application/json:
              schema:
                type: object
                properties: *ref_0
                required: *ref_1
  /v1/accounts:
    get:
      tags:
        - Accounts
      summary: Query account statistics and activity
      description: |
        Retrieves accounts with their marketplace activity statistics including sales, purchases, 
        earnings, spending, royalties, and collection counts.

        Supports filtering and sorting by various metrics:
        - Most sales, purchases, collections created
        - Highest earnings, spending, or royalties earned
        - Specific accounts by address or ID
        - Network filtering (Ethereum, Polygon)

        Use this endpoint to:
        - Display marketplace leaderboards
        - Track user trading statistics
        - Analyze account activity and performance
        - Identify top sellers, buyers, and creators

        Results are paginated and can be sorted by different ranking criteria.
      operationId: getAccounts
      security: []
      parameters:
        - name: first
          in: query
          required: false
          description: 'Maximum number of accounts to return (default: 100, max: 1000)'
          schema:
            type: number
            example: 100
        - name: skip
          in: query
          required: false
          description: 'Number of accounts to skip for pagination (default: 0)'
          schema:
            type: number
            example: 0
        - name: sortBy
          in: query
          required: false
          description: |
            Sort accounts by specific metrics:
            - most_sales: Accounts with most items sold
            - most_purchases: Accounts with most items purchased
            - most_royalties: Accounts earning most royalties
            - most_collections: Accounts with most collections created
            - most_earned: Accounts with highest total earnings
            - most_spent: Accounts with highest total spending
          schema:
            type: string
            enum:
              - most_sales
              - most_purchases
              - most_royalties
              - most_collections
              - most_earned
              - most_spent
            example: most_sales
        - name: id
          in: query
          required: false
          description: Filter by specific account ID
          schema:
            type: string
        - name: address
          in: query
          required: false
          description: Filter by one or more account addresses (can be repeated or comma-separated)
          schema:
            type: array
            items:
              type: string
          style: form
          explode: true
        - name: network
          in: query
          required: false
          description: Filter by network
          schema:
            type: string
            enum:
              - ETHEREUM
              - MATIC
            example: ETHEREUM
      responses:
        '200':
          description: Account statistics
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      properties: &ref_62
                        id:
                          type: string
                          description: Account identifier
                          example: '0x1234567890abcdef1234567890abcdef12345678'
                        address:
                          type: string
                          description: Wallet address of the account
                          example: '0x1234567890abcdef1234567890abcdef12345678'
                        sales:
                          type: number
                          description: Total number of items sold
                          example: 43
                        purchases:
                          type: number
                          description: Total number of items purchased
                          example: 15
                        spent:
                          type: string
                          description: Total amount spent in Wei (as string to handle large numbers)
                          example: '5000000000000000000'
                        earned:
                          type: string
                          description: Total amount earned from sales in Wei
                          example: '10000000000000000000'
                        royalties:
                          type: string
                          description: Total royalties earned in Wei
                          example: '500000000000000000'
                        collections:
                          type: number
                          description: Number of collections created
                          example: 3
                      required: &ref_63
                        - id
                        - address
                        - sales
                        - purchases
                        - spent
                        - earned
                        - royalties
                        - collections
                  total:
                    type: number
                    description: Total number of accounts matching the filters
                required:
                  - data
                  - total
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                    example: false
                  message:
                    type: string
                    example: Could not fetch accounts
  /v1/collections:
    get:
      tags:
        - Collections
      summary: List and search marketplace collections
      description: |
        Retrieves marketplace collections with their metadata and statistics.

        Supports comprehensive filtering:
        - Search by collection name or text
        - Filter by creator address
        - Filter by contract address or URN
        - Show only collections with items on sale
        - Network filtering

        Sorting options:
        - Newest collections
        - Recently reviewed
        - Alphabetical by name
        - By collection size (item count)
        - Recently listed

        Use this endpoint to:
        - Browse marketplace collections
        - Search for specific creator's collections
        - Display collection catalogs
        - Track new collection launches

        Results include collection metadata, item counts, and listing status.
      operationId: getCollections
      security: []
      parameters:
        - name: first
          in: query
          required: false
          description: 'Maximum number of collections to return (default: 100, max: 1000)'
          schema:
            type: number
            example: 100
        - name: skip
          in: query
          required: false
          description: 'Number of collections to skip for pagination (default: 0)'
          schema:
            type: number
            example: 0
        - name: sortBy
          in: query
          required: false
          description: |
            Sort collections by:
            - newest: Most recently created
            - recently_reviewed: Most recently reviewed
            - name: Alphabetical order
            - size: Number of items in collection
            - recently_listed: Most recently listed for sale
          schema:
            type: string
            enum:
              - newest
              - recently_reviewed
              - name
              - size
              - recently_listed
            example: newest
        - name: name
          in: query
          required: false
          description: Filter by exact collection name
          schema:
            type: string
        - name: search
          in: query
          required: false
          description: Search collections by name or description (text search)
          schema:
            type: string
        - name: creator
          in: query
          required: false
          description: Filter by creator wallet address
          schema:
            type: string
            example: '0x1234567890abcdef1234567890abcdef12345678'
        - name: urn
          in: query
          required: false
          description: Filter by collection URN (Uniform Resource Name)
          schema:
            type: string
        - name: contractAddress
          in: query
          required: false
          description: Filter by collection contract address
          schema:
            type: string
            example: '0x1234567890abcdef1234567890abcdef12345678'
        - name: isOnSale
          in: query
          required: false
          description: Filter collections that have items currently on sale
          schema:
            type: boolean
            example: true
        - name: network
          in: query
          required: false
          description: Filter by blockchain network (ETHEREUM or MATIC)
          schema:
            type: string
            enum:
              - ETHEREUM
              - MATIC
            example: ETHEREUM
      responses:
        '200':
          description: List of collections
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      properties: &ref_64
                        urn:
                          type: string
                          description: Collection URN (Uniform Resource Name)
                          example: urn:decentraland:matic:collections-v2:0xabcd1234...
                        creator:
                          type: string
                          description: Creator wallet address
                          example: '0x1234567890abcdef1234567890abcdef12345678'
                        name:
                          type: string
                          description: Collection name
                          example: My Awesome Wearables
                        contractAddress:
                          type: string
                          description: Smart contract address of the collection
                          example: '0x1234567890abcdef1234567890abcdef12345678'
                        createdAt:
                          type: number
                          description: Creation timestamp (Unix epoch in milliseconds)
                          example: 1640000000000
                        updatedAt:
                          type: number
                          description: Last update timestamp (Unix epoch in milliseconds)
                          example: 1640100000000
                        reviewedAt:
                          type: number
                          description: Review timestamp (Unix epoch in milliseconds)
                          example: 1640050000000
                        isOnSale:
                          type: boolean
                          description: Whether the collection has items currently on sale
                          example: true
                        size:
                          type: number
                          description: Number of items in the collection
                          example: 25
                        network:
                          type: string
                          enum:
                            - ETHEREUM
                            - MATIC
                          description: Blockchain network where the collection is deployed
                          example: MATIC
                        chainId:
                          type: number
                          description: Chain ID of the blockchain network
                          example: 137
                        firstListedAt:
                          oneOf:
                            - type: number
                            - type: 'null'
                          description: Timestamp when first item was listed (Unix epoch in milliseconds, null if never listed)
                          example: 1640020000000
                      required: &ref_65
                        - urn
                        - creator
                        - name
                        - contractAddress
                        - createdAt
                        - updatedAt
                        - reviewedAt
                        - isOnSale
                        - size
                        - network
                        - chainId
                        - firstListedAt
                  total:
                    type: number
                    description: Total number of collections matching the filters
                required:
                  - data
                  - total
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                    example: false
                  message:
                    type: string
                    example: Could not fetch collections
  /v1/lists/{id}/access:
    post:
      tags:
        - Lists
      summary: Grant access to private list
      description: |
        Grants a user access to a private favorites list.

        **Authentication Required**: Only the list owner can grant access.

        Use this endpoint to share private lists with specific users by providing their
        wallet address and desired permissions. This allows collaborative list management
        without making the list public.
      operationId: grantListAccess
      security:
        - SignedFetch: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: Unique identifier of the favorites list
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties: &ref_58
                userAddress:
                  type: string
                  description: User address to grant access to
                permissions:
                  type: array
                  items:
                    type: string
                  description: List of permissions
              required: &ref_59
                - userAddress
                - permissions
      responses:
        '200':
          description: Access granted successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
        '401':
          description: Unauthorized - invalid signed fetch
          content:
            application/json:
              schema:
                type: object
                properties: *ref_0
                required: *ref_1
        '403':
          description: Forbidden - invalid metadata
          content:
            application/json:
              schema:
                type: object
                properties: *ref_0
                required: *ref_1
        '404':
          description: List not found
          content:
            application/json:
              schema:
                type: object
                properties: *ref_0
                required: *ref_1
    delete:
      tags:
        - Lists
      summary: Revoke access from private list
      description: |
        Revokes a user's access to a private favorites list.

        **Authentication Required**: Only the list owner can revoke access.

        After revocation, the specified user will no longer be able to view or modify
        the private list. Use this endpoint to manage access control for collaborative lists.
      operationId: revokeListAccess
      security:
        - SignedFetch: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: Unique identifier of the favorites list
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties: &ref_60
                userAddress:
                  type: string
                  description: User address to revoke access from
              required: &ref_61
                - userAddress
      responses:
        '200':
          description: Access revoked successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
        '401':
          description: Unauthorized - invalid signed fetch
          content:
            application/json:
              schema:
                type: object
                properties: *ref_0
                required: *ref_1
        '403':
          description: Forbidden - invalid metadata
          content:
            application/json:
              schema:
                type: object
                properties: *ref_0
                required: *ref_1
        '404':
          description: List not found
          content:
            application/json:
              schema:
                type: object
                properties: *ref_0
                required: *ref_1
components:
  securitySchemes:
    SignedFetch:
      type: http
      scheme: bearer
      description: |
        Signed fetch authentication using decentraland-crypto-middleware with metadata validation (ADR-44l). 
        Requires auth chain headers (x-identity, x-signature, x-timestamp) for signature validation. 
        See http://adr.decentraland.org/adr/ADR-44l for details.
  schemas:
    CatalogResponse:
      type: object
      properties: *ref_2
      required: *ref_3
    CatalogItem:
      type: object
      properties: *ref_12
      additionalProperties: true
      required: *ref_13
    WertSignRequest:
      type: object
      properties: *ref_14
      required: *ref_15
    WertSignResponse:
      type: object
      properties: *ref_16
      required: *ref_17
    TransakOrder:
      type: object
      properties: *ref_18
      required: *ref_19
    ENSImageResponse:
      type: object
      properties: *ref_20
      required: *ref_21
    Trade:
      type: object
      properties: *ref_4
      required: *ref_5
    CreateTradeRequest:
      type: object
      properties: *ref_22
      required: *ref_23
    TradeAcceptedEvent:
      type: object
      properties: *ref_24
      required: *ref_25
    Bid:
      type: object
      description: A bid placed on an NFT or item in the marketplace
      properties: *ref_26
      required: *ref_27
    NFT:
      type: object
      properties: *ref_28
      required: *ref_29
    Order:
      type: object
      properties: *ref_30
      required: *ref_31
    Item:
      type: object
      properties: *ref_6
      required: *ref_7
    Sale:
      type: object
      properties: *ref_32
      required: *ref_33
    PricesResponse:
      type: object
      properties: *ref_34
      required: *ref_35
    TrendingItem:
      type: object
      properties: *ref_36
      required: *ref_37
    StatsResponse:
      type: object
      properties: *ref_38
      required: *ref_39
    RankingsResponse:
      type: object
      properties: *ref_40
      required: *ref_41
    VolumeResponse:
      type: object
      properties: *ref_42
      required: *ref_43
    Pick:
      type: object
      properties: *ref_8
      required: *ref_9
    AddPickRequest:
      type: object
      properties: *ref_44
      required: *ref_45
    PickStats:
      type: object
      properties: *ref_46
      required: *ref_47
    AllPicksStats:
      type: object
      properties: *ref_48
      required: *ref_49
    BulkPickRequest:
      type: object
      properties: *ref_50
      required: *ref_51
    BulkPickResponse:
      type: object
      properties: *ref_52
      required: *ref_53
    List:
      type: object
      properties: *ref_10
      required: *ref_11
    CreateListRequest:
      type: object
      properties: *ref_54
      required: *ref_55
    UpdateListRequest:
      type: object
      properties: *ref_56
      required: *ref_57
    GrantAccessRequest:
      type: object
      properties: *ref_58
      required: *ref_59
    RevokeAccessRequest:
      type: object
      properties: *ref_60
      required: *ref_61
    Account:
      type: object
      properties: *ref_62
      required: *ref_63
    Collection:
      type: object
      properties: *ref_64
      required: *ref_65
    Error:
      type: object
      properties: *ref_0
      required: *ref_1
    ContractsResponse:
      type: object
      properties: *ref_66
      required: *ref_67
    Contract:
      type: object
      properties: *ref_68
      required: *ref_69
