openapi: 3.0.0
paths:
  /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
            maximum: 1000
            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:
            maxItems: 100
            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
  /tokens/{contractAddress}/supply/total:
    get:
      description: >-
        Returns the LINEA total supply (post-burn). Defaults to a plain-text
        number; pass ?format=json for a structured object.
      operationId: LineaSupplyController_getTotalSupply
      parameters:
        - name: contractAddress
          required: true
          in: path
          description: The LINEA token contract address
          schema:
            example: '0x1789e0043623282D5DCc7F213d703C6D8BAfBB04'
            type: string
        - name: format
          required: false
          in: query
          description: >-
            Response format. "raw" returns a single number as plain text; "json"
            returns a structured object.
          schema:
            enum:
              - raw
              - json
            type: string
      responses:
        '200':
          description: >-
            Total supply — plain-text number by default, or a structured object
            with ?format=json
          content:
            text/plain:
              schema:
                type: string
                example: '71593816498.833170312930582115'
            application/json:
              schema:
                $ref: '#/components/schemas/TotalSupplyResponseDto'
        '404':
          description: Supply data is only available for the LINEA token
        '503':
          description: Supply data is not available yet
      summary: Get LINEA total supply
      tags:
        - Tokens
  /tokens/{contractAddress}/supply/circulating:
    get:
      description: >-
        Returns the LINEA circulating supply. Defaults to a plain-text number;
        pass ?format=json for a structured object including the excluded-wallet
        breakdown.
      operationId: LineaSupplyController_getCirculatingSupply
      parameters:
        - name: contractAddress
          required: true
          in: path
          description: The LINEA token contract address
          schema:
            example: '0x1789e0043623282D5DCc7F213d703C6D8BAfBB04'
            type: string
        - name: format
          required: false
          in: query
          description: >-
            Response format. "raw" returns a single number as plain text; "json"
            returns a structured object.
          schema:
            enum:
              - raw
              - json
            type: string
      responses:
        '200':
          description: >-
            Circulating supply — plain-text number by default, or a structured
            object with ?format=json
          content:
            text/plain:
              schema:
                type: string
                example: '24169536844.304868484915986684'
            application/json:
              schema:
                $ref: '#/components/schemas/CirculatingSupplyResponseDto'
        '404':
          description: Supply data is only available for the LINEA token
        '503':
          description: Supply data is not available yet
      summary: Get LINEA circulating supply
      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:
            maxItems: 100
            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:
    OrderColumns:
      type: string
      enum:
        - name
        - symbol
        - decimals
        - contractAddress
        - currentPrice
        - priceUpdatedAt
        - createdAt
        - updatedAt
        - last24hVariation
        - last24hVariationAbsolute
        - sells
        - buys
        - swaps
        - isPossibleSpam
        - totalSupply
        - fdv
    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
    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-06-18T07:50:44.215Z
          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
    TotalSupplyResponseDto:
      type: object
      properties:
        totalSupply:
          type: string
          example: '71593816498.833170312930582115'
          description: >-
            Total supply (post-burn) in LINEA, decimal-adjusted to the token
            decimals (18)
        lastUpdated:
          format: date-time
          type: string
          description: Time the cached figure was last refreshed
      required:
        - totalSupply
        - lastUpdated
    ExcludedWalletResponseDto:
      type: object
      properties:
        address:
          type: string
          example: '0x8156b28cA956C3a8BAb86e1D38D8648d58CD23ec'
          description: Wallet address on Linea L2
        label:
          type: string
          example: Consensys Treasury
          description: Human-readable wallet label
        status:
          type: string
          example: Locked
          description: Wallet status
        balance:
          type: string
          example: '10801498500'
          description: Wallet balance in LINEA, decimal-adjusted to the token decimals (18)
      required:
        - address
        - label
        - status
        - balance
    CirculatingSupplyResponseDto:
      type: object
      properties:
        circulatingSupply:
          type: string
          example: '24169536844.304868484915986684'
          description: >-
            Circulating supply in LINEA, decimal-adjusted to the token decimals
            (18)
        totalSupply:
          type: string
          example: '71593816498.833170312930582115'
          description: >-
            Total supply (post-burn) in LINEA, decimal-adjusted to the token
            decimals (18)
        lastUpdated:
          format: date-time
          type: string
          description: Time the cached figure was last refreshed
        excludedWallets:
          description: Wallets excluded from circulating supply
          type: array
          items:
            $ref: '#/components/schemas/ExcludedWalletResponseDto'
      required:
        - circulatingSupply
        - totalSupply
        - lastUpdated
        - excludedWallets
    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-06-18T07:50:44.307Z
          description: Date and time when the price was fetched
      required:
        - price
        - timestamp