openapi: 3.1.0
info:
  title: LooksRare Public Collections Tokens 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: Tokens
  description: Retrieve NFT token metadata including collection information and on-chain attribute traits.
paths:
  /v1/tokens:
    get:
      operationId: getToken
      summary: Get NFT token metadata
      description: Retrieve NFT token metadata including token details, parent collection information, and on-chain attribute traits for any token indexed by LooksRare. Both collection and tokenId are required.
      tags:
      - Tokens
      parameters:
      - name: collection
        in: query
        required: true
        description: Collection contract address (Ethereum address).
        schema:
          $ref: '#/components/schemas/EthereumAddress'
      - name: tokenId
        in: query
        required: true
        description: Token ID within the collection.
        schema:
          type: string
      responses:
        '200':
          description: Token metadata including collection and attributes.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokenResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
        '500':
          $ref: '#/components/responses/InternalServerError'
components:
  schemas:
    TokenResponse:
      type: object
      properties:
        success:
          type: boolean
        message:
          type: string
          nullable: true
        data:
          $ref: '#/components/schemas/Token'
    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.
    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.
    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