openapi: 3.0.0
paths:
  /tokens/linea:
    get:
      description: Retrieve the details for the Linea token with vesting schedule
      operationId: TokensController_fetchLineaToken
      parameters: []
      responses:
        '200':
          description: Successfully retrieved the Linea token details with vesting schedule
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LineaTokenResponseDto'
      summary: Get Linea token details
      tags:
        - Tokens
  /tokens:
    get:
      description: Retrieve a list of tokens based on the provided query parameters
      operationId: TokensController_findTokens
      parameters:
        - name: page
          required: false
          in: query
          description: Page number
          schema:
            minimum: 1
            default: 1
            type: number
        - name: limit
          required: false
          in: query
          description: Number of items per page
          schema:
            minimum: 1
            maximum: 100
            default: 50
            type: number
        - name: isSecure
          required: false
          in: query
          description: Filter tokens secure tokens
          schema:
            type: boolean
        - name: addresses
          required: false
          in: query
          description: List of tokens addresses (comma-separated)
          schema:
            type: string
        - name: order
          required: false
          in: query
          description: Order by column
          schema:
            $ref: '#/components/schemas/OrderColumns'
        - name: sort
          required: false
          in: query
          description: Order sort (asc, desc)
          schema:
            type: string
            enum:
              - asc
              - desc
      responses:
        '200':
          description: Successfully retrieved tokens
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokenPageDto'
      summary: Get tokens
      tags:
        - Tokens
  /tokens/{contractAddress}:
    get:
      description: >-
        Retrieve detailed information about a specific token using its contract
        address
      operationId: TokensController_findOne
      parameters:
        - name: contractAddress
          required: true
          in: path
          description: The Ethereum contract address of the token
          schema:
            example: '0x1234567890123456789012345678901234567890'
            type: string
      responses:
        '200':
          description: Successfully retrieved token information
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokenResponseDto'
        '400':
          description: Invalid contract address format
        '404':
          description: Token not found
      summary: Get token by contract address
      tags:
        - Tokens
  /prices/{contractAddress}:
    get:
      description: Retrieve prices over the last 24 hours for a token
      operationId: PricesController_findOne
      parameters:
        - name: contractAddress
          required: true
          in: path
          schema:
            type: string
      responses:
        '200':
          description: Successfully retrieved prices
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/PriceResponseDto'
        '400':
          description: Invalid contract address format
        '404':
          description: Token not found
      summary: Get hourly prices for a token
      tags:
        - Prices
  /prices:
    get:
      description: Retrieve prices over the last 24 hours for multiple tokens
      operationId: PricesController_findMany
      parameters:
        - name: addresses
          required: true
          in: query
          description: List of tokens addresses (comma-separated)
          schema:
            type: string
      responses:
        '200':
          description: Successfully retrieved prices
      summary: Get hourly prices for multiple tokens
      tags:
        - Prices
info:
  title: Linea Token API
  description: >-
    API to access token information on Linea, including prices, traded tokens
    and top movers over 24h.
  version: 0.1.0
  contact: {}
tags: []
servers: []
components:
  schemas:
    TokenInfoResponseDto:
      type: object
      properties:
        sells:
          type: number
          example: 1000
          description: Number of sells
        buys:
          type: number
          example: 2000
          description: Number of buys
        swaps:
          type: number
          example: 3000
          description: Number of total swaps
        fdv:
          type: object
          example: 100000
          description: Fully diluted valuation (FDV)
        totalSupply:
          type: object
          example: '1000000'
          description: Total supply of the token
      required:
        - sells
        - buys
        - swaps
        - fdv
        - totalSupply
    LineaVestingScheduleDto:
      type: object
      properties:
        totalSupply:
          type: number
          example: 72009990000
          description: Total supply of tokens
        updatedAt:
          type: number
          example: 1758643127
          description: Timestamp when the data was last updated
        data:
          type: object
          description: Vesting data by timestamp
          additionalProperties: true
      required:
        - totalSupply
        - updatedAt
        - data
    LineaTokenResponseDto:
      type: object
      properties:
        name:
          type: string
          example: Token name
          description: Name of the token
        symbol:
          type: string
          example: Token symbol
          description: Symbol of the token
        decimals:
          type: number
          example: 18
          description: Number of decimals of the token
        logo:
          type: object
          example: https://example.com/logo.png
          description: URL of the token logo
        contractAddress:
          type: string
          example: '0x1111111111111111111111111111111111111111'
          description: Contract address of the token
        currentPrice:
          type: object
          example: 1000
          description: Current price of the token
        priceUpdatedAt:
          type: object
          example: 2026-04-07T17:04:05.547Z
          description: Date and time when the price was last updated
        last24hVariation:
          type: object
          example: 0
          description: Price variation in the last 24 hours
        info:
          description: Token information
          allOf:
            - $ref: '#/components/schemas/TokenInfoResponseDto'
        lineaVestingSchedule:
          description: Vesting schedule for the Linea token
          example:
            totalSupply: 72009990000
            updatedAt: 1758643127
            data:
              '1756677601':
                label: September 2025
                releases:
                  lineaConsortium:
                    ignitionLiquidityCexMm: 5760799200
                    ignition: 2880399600
                    longTermAlignment: 0
                  ecosystemFund: 8641198800
                totals:
                  monthly: 15842197800
                  cumulative: 15842197800
                  allocationReachedPct: 22
          allOf:
            - $ref: '#/components/schemas/LineaVestingScheduleDto'
      required:
        - name
        - symbol
        - decimals
        - logo
        - contractAddress
        - currentPrice
        - priceUpdatedAt
        - last24hVariation
        - info
        - lineaVestingSchedule
    OrderColumns:
      type: string
      enum:
        - name
        - symbol
        - decimals
        - contractAddress
        - currentPrice
        - priceUpdatedAt
        - createdAt
        - updatedAt
        - last24hVariation
        - last24hVariationAbsolute
        - sells
        - buys
        - swaps
        - isPossibleSpam
        - totalSupply
        - fdv
    TokenResponseDto:
      type: object
      properties:
        name:
          type: string
          example: Token name
          description: Name of the token
        symbol:
          type: string
          example: Token symbol
          description: Symbol of the token
        decimals:
          type: number
          example: 18
          description: Number of decimals of the token
        logo:
          type: object
          example: https://example.com/logo.png
          description: URL of the token logo
        contractAddress:
          type: string
          example: '0x1111111111111111111111111111111111111111'
          description: Contract address of the token
        currentPrice:
          type: object
          example: 1000
          description: Current price of the token
        priceUpdatedAt:
          type: object
          example: 2026-04-07T17:04:05.547Z
          description: Date and time when the price was last updated
        last24hVariation:
          type: object
          example: 0
          description: Price variation in the last 24 hours
        info:
          description: Token information
          allOf:
            - $ref: '#/components/schemas/TokenInfoResponseDto'
      required:
        - name
        - symbol
        - decimals
        - logo
        - contractAddress
        - currentPrice
        - priceUpdatedAt
        - last24hVariation
        - info
    PageMetaDto:
      type: object
      properties:
        page:
          type: number
          description: Current page number
        limit:
          type: number
          description: Number of items per page
        totalItemsCount:
          type: number
          description: Total number of items
        pagesCount:
          type: number
          description: Total number of pages
      required:
        - page
        - limit
        - totalItemsCount
        - pagesCount
    TokenPageDto:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/TokenResponseDto'
        meta:
          $ref: '#/components/schemas/PageMetaDto'
      required:
        - data
        - meta
    PriceResponseDto:
      type: object
      properties:
        price:
          type: number
          example: 1
          description: Price in USD at a given date and time
        timestamp:
          format: date-time
          type: string
          example: 2026-04-07T17:04:05.562Z
          description: Date and time when the price was fetched
      required:
        - price
        - timestamp