openapi: 3.1.0
info:
  title: LooksRare Public Collections Seaport 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: Seaport
  description: Endpoints specific to the LooksRare Seaport integration, enabling Seaport-compatible orders and events while earning LooksRare rewards.
paths:
  /v2/orders/seaport:
    get:
      operationId: getSeaportOrders
      summary: Get LooksRare Seaport orders
      description: Retrieve maker orders placed through the LooksRare Seaport integration. These orders earn LooksRare rewards and gems while using the Seaport protocol.
      tags:
      - Seaport
      parameters:
      - name: collection
        in: query
        description: Filter by collection contract address.
        schema:
          $ref: '#/components/schemas/EthereumAddress'
      - name: signer
        in: query
        description: Filter by the Ethereum address of the order signer.
        schema:
          $ref: '#/components/schemas/EthereumAddress'
      - 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 orders.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderListResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
        '500':
          $ref: '#/components/responses/InternalServerError'
    post:
      operationId: createSeaportOrder
      summary: Create a LooksRare Seaport order
      description: Submit a signed Seaport order into the LooksRare order book. Allows listing and bidding through the Seaport protocol while still earning LooksRare rewards and gems.
      tags:
      - Seaport
      security:
      - ApiKeyHeader: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              description: Signed Seaport order payload.
      responses:
        '201':
          description: Seaport order successfully created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderCreateResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '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:
      - Seaport
      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'
  /v2/collections/seaport:
    get:
      operationId: checkCollectionSeaportEligibility
      summary: Check Seaport eligibility for a collection
      description: Check whether a specific NFT collection is eligible for trading via the LooksRare Seaport integration.
      tags:
      - Seaport
      parameters:
      - name: collection
        in: query
        required: true
        description: Collection contract address to check.
        schema:
          $ref: '#/components/schemas/EthereumAddress'
      responses:
        '200':
          description: Seaport eligibility status for the collection.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CollectionSeaportResponse'
        '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
    CollectionSeaportResponse:
      type: object
      properties:
        success:
          type: boolean
        message:
          type: string
          nullable: true
        data:
          type: object
          properties:
            eligible:
              type: boolean
              description: Whether this collection is eligible for trading via LooksRare Seaport.
    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.
    OrderStatus:
      type: string
      enum:
      - VALID
      - CANCELLED
      - EXECUTED
      - EXPIRED
      description: Status of an order in the LooksRare order book.
    OrderListResponse:
      type: object
      properties:
        success:
          type: boolean
        message:
          type: string
          nullable: true
        data:
          type: array
          items:
            $ref: '#/components/schemas/MakerOrder'
    EventListResponse:
      type: object
      properties:
        success:
          type: boolean
        message:
          type: string
          nullable: true
        data:
          type: array
          items:
            $ref: '#/components/schemas/Event'
    OrderCreateResponse:
      type: object
      properties:
        success:
          type: boolean
        message:
          type: string
          nullable: true
        data:
          $ref: '#/components/schemas/MakerOrder'
    MakerOrder:
      type: object
      description: A maker order (ask or bid) stored in the LooksRare V2 off-chain order book.
      properties:
        id:
          type: string
          description: Unique order identifier.
        hash:
          type: string
          description: Order hash (keccak256).
        quoteType:
          $ref: '#/components/schemas/QuoteType'
        globalNonce:
          type: string
          description: User's global bid or ask nonce at time of order creation.
        subsetNonce:
          type: string
          description: Subset nonce for grouping arbitrary orders.
        orderNonce:
          type: string
          description: Specific nonce for this order.
        strategyId:
          $ref: '#/components/schemas/StrategyId'
        collectionType:
          $ref: '#/components/schemas/CollectionType'
        collection:
          $ref: '#/components/schemas/EthereumAddress'
        currency:
          $ref: '#/components/schemas/EthereumAddress'
        signer:
          $ref: '#/components/schemas/EthereumAddress'
        startTime:
          type: integer
          description: Order validity start timestamp (Unix seconds).
        endTime:
          type: integer
          description: Order validity end timestamp (Unix seconds).
        price:
          type: string
          description: Order price in wei.
        itemIds:
          type: array
          items:
            type: string
          description: List of token IDs included in the order.
        amounts:
          type: array
          items:
            type: string
          description: Amounts per item ID. ERC-721 always 1; ERC-1155 max 100.
        additionalParameters:
          type: string
          description: ABI-encoded additional parameters, or '0x' if unused.
        signature:
          type: string
          description: ECDSA signature (65 bytes, 0x-prefixed).
        status:
          $ref: '#/components/schemas/OrderStatus'
        createdAt:
          type: string
          format: date-time
          description: Timestamp when the order was created.
        merkleRoot:
          type: string
          nullable: true
          description: Merkle root for collection-wide orders.
        merkleProof:
          type: array
          nullable: true
          items:
            type: object
          description: Merkle proof nodes for collection-wide orders.
    StrategyId:
      type: integer
      enum:
      - 0
      - 1
      description: Maker strategy. 0 = Standard (specific token), 1 = Collection (any token in collection).
    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'
    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.
    CollectionType:
      type: integer
      enum:
      - 0
      - 1
      description: NFT collection standard. 0 = ERC-721, 1 = ERC-1155.
    QuoteType:
      type: integer
      enum:
      - 0
      - 1
      description: Order quote type. 0 = Bid (offer to buy), 1 = Ask (listing to sell).
  responses:
    BadRequest:
      description: Invalid request parameters.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    InternalServerError:
      description: Internal server error.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    RateLimitExceeded:
      description: Rate limit exceeded.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Unauthorized:
      description: Missing or invalid API key.
      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