openapi: 3.1.0
info:
  title: LooksRare Public Collections Events API
  description: LooksRare is a community-first NFT marketplace built on Ethereum. The public REST API exposes read and write access to orders, events (listings, sales, offers, cancellations), token metadata, and collection data across Ethereum Mainnet (https://api.looksrare.org) and the Sepolia testnet (https://api-sepolia.looksrare.org). A mainnet API key is required for write operations such as order creation.
  version: 2.0.0
  contact:
    url: https://looksrare.dev
  license:
    name: Attribution Required
    url: https://looksrare.dev
  x-logo:
    url: https://looksrare.org/favicon.ico
servers:
- url: https://api.looksrare.org/api
  description: Ethereum Mainnet
- url: https://api-sepolia.looksrare.org/api
  description: Sepolia Testnet
security: []
tags:
- name: Events
  description: Retrieve token and order activity events from the LooksRare marketplace, including listings, sales, offers, and cancellations.
paths:
  /v2/events:
    get:
      operationId: getEvents
      summary: Get V2 marketplace events
      description: Retrieve token and order activity events from the LooksRare V2 marketplace including LIST, SALE, OFFER, CANCEL_LIST, and CANCEL_OFFER event types. Results are ordered by creation timestamp. For V1 events, mints, and transfers use the /v1/events endpoint.
      tags:
      - Events
      parameters:
      - name: collection
        in: query
        description: Filter events by collection contract address.
        schema:
          $ref: '#/components/schemas/EthereumAddress'
      - name: itemId
        in: query
        description: Filter by specific token ID. Requires the collection parameter.
        schema:
          type: string
      - name: from
        in: query
        description: Filter by sender (from) Ethereum address.
        schema:
          $ref: '#/components/schemas/EthereumAddress'
      - name: to
        in: query
        description: Filter by receiver (to) Ethereum address.
        schema:
          $ref: '#/components/schemas/EthereumAddress'
      - name: type
        in: query
        description: Filter by event type.
        schema:
          $ref: '#/components/schemas/EventType'
      - name: pagination[first]
        in: query
        description: Number of results per page (default 20, max 150).
        schema:
          type: integer
          minimum: 1
          maximum: 150
          default: 20
      - name: pagination[cursor]
        in: query
        description: Cursor for pagination; use the ID of the last event from the previous page.
        schema:
          type: string
      responses:
        '200':
          description: List of marketplace events matching the filters.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EventListResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /v1/events:
    get:
      operationId: getV1Events
      summary: Get V1 marketplace events
      description: Retrieve historical V1 protocol events including mints, transfers, and legacy order events. Use /v2/events for current marketplace activity.
      tags:
      - Events
      parameters:
      - name: collection
        in: query
        description: Filter events by collection contract address.
        schema:
          $ref: '#/components/schemas/EthereumAddress'
      - name: itemId
        in: query
        description: Filter by specific token ID.
        schema:
          type: string
      - name: from
        in: query
        description: Filter by sender Ethereum address.
        schema:
          $ref: '#/components/schemas/EthereumAddress'
      - name: to
        in: query
        description: Filter by receiver Ethereum address.
        schema:
          $ref: '#/components/schemas/EthereumAddress'
      - name: type
        in: query
        description: Filter by event type.
        schema:
          type: string
          enum:
          - LIST
          - SALE
          - OFFER
          - CANCEL_LIST
          - CANCEL_OFFER
          - MINT
          - TRANSFER
      - name: pagination[first]
        in: query
        description: Number of results per page (default 20, max 150).
        schema:
          type: integer
          minimum: 1
          maximum: 150
          default: 20
      - name: pagination[cursor]
        in: query
        description: Cursor for pagination.
        schema:
          type: string
      responses:
        '200':
          description: List of V1 marketplace events.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EventListResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /v2/events/seaport:
    get:
      operationId: getSeaportEvents
      summary: Get LooksRare Seaport events
      description: Retrieve marketplace events for orders executed through the LooksRare Seaport integration.
      tags:
      - Events
      parameters:
      - name: collection
        in: query
        description: Filter events by collection contract address.
        schema:
          $ref: '#/components/schemas/EthereumAddress'
      - name: itemId
        in: query
        description: Filter by specific token ID.
        schema:
          type: string
      - name: pagination[first]
        in: query
        description: Number of results per page (default 20, max 150).
        schema:
          type: integer
          minimum: 1
          maximum: 150
          default: 20
      - name: pagination[cursor]
        in: query
        description: Cursor for pagination.
        schema:
          type: string
      responses:
        '200':
          description: List of Seaport marketplace events.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EventListResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
        '500':
          $ref: '#/components/responses/InternalServerError'
components:
  schemas:
    Token:
      type: object
      description: NFT token metadata as indexed by LooksRare.
      properties:
        id:
          type: string
          description: Token ID within the collection.
        collection:
          $ref: '#/components/schemas/Collection'
        name:
          type: string
          description: Token name.
          nullable: true
        description:
          type: string
          description: Token description.
          nullable: true
        image:
          type: string
          format: uri
          description: Token image URI.
          nullable: true
        animationURI:
          type: string
          format: uri
          description: Token animation or video URI.
          nullable: true
        attributes:
          type: array
          description: On-chain attribute traits for this token.
          items:
            type: object
            properties:
              traitType:
                type: string
              value:
                type: string
              displayType:
                type: string
                nullable: true
    ErrorResponse:
      type: object
      properties:
        success:
          type: boolean
          example: false
        message:
          type: string
          description: Human-readable error message.
    EventType:
      type: string
      enum:
      - LIST
      - SALE
      - OFFER
      - CANCEL_LIST
      - CANCEL_OFFER
      description: Type of marketplace event.
    Event:
      type: object
      description: A marketplace activity event on LooksRare.
      properties:
        id:
          type: string
          description: Unique event identifier.
        type:
          $ref: '#/components/schemas/EventType'
        collection:
          $ref: '#/components/schemas/Collection'
        token:
          $ref: '#/components/schemas/Token'
        from:
          $ref: '#/components/schemas/EthereumAddress'
        to:
          $ref: '#/components/schemas/EthereumAddress'
          nullable: true
        price:
          type: string
          description: Sale or offer price in wei.
          nullable: true
        createdAt:
          type: string
          format: date-time
          description: Timestamp when the event was recorded.
        hash:
          type: string
          description: On-chain transaction hash for settled events.
          nullable: true
    Collection:
      type: object
      description: NFT collection metadata as indexed by LooksRare.
      properties:
        address:
          $ref: '#/components/schemas/EthereumAddress'
        name:
          type: string
          description: Collection name.
        description:
          type: string
          description: Collection description.
          nullable: true
        symbol:
          type: string
          description: Collection token symbol.
          nullable: true
        type:
          $ref: '#/components/schemas/CollectionType'
        logoURI:
          type: string
          format: uri
          description: URI for the collection logo image.
          nullable: true
        bannerURI:
          type: string
          format: uri
          description: URI for the collection banner image.
          nullable: true
        totalSupply:
          type: integer
          description: Total token supply in the collection.
          nullable: true
        verified:
          type: boolean
          description: Whether the collection is verified by LooksRare.
    EventListResponse:
      type: object
      properties:
        success:
          type: boolean
        message:
          type: string
          nullable: true
        data:
          type: array
          items:
            $ref: '#/components/schemas/Event'
    CollectionType:
      type: integer
      enum:
      - 0
      - 1
      description: NFT collection standard. 0 = ERC-721, 1 = ERC-1155.
    EthereumAddress:
      type: string
      pattern: ^0x[a-fA-F0-9]{40}$
      description: A valid Ethereum contract or wallet address (42 characters including 0x prefix).
      example: '0x60e4d786628fea6478f785a6d7e704777c86a7c6'
  responses:
    InternalServerError:
      description: Internal server error.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    BadRequest:
      description: Invalid request parameters.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    RateLimitExceeded:
      description: Rate limit exceeded.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  securitySchemes:
    ApiKeyHeader:
      type: apiKey
      in: header
      name: X-Looks-Api-Key
      description: API key required for mainnet write operations (order creation). Not needed for read endpoints or testnet.
externalDocs:
  description: LooksRare Developer Documentation
  url: https://looksrare.dev