openapi: 3.0.0
info:
  title: Linea Token Prices Tokens API
  description: API to access token information on Linea, including prices, traded tokens and top movers over 24h.
  version: 0.1.0
  contact: {}
servers:
- url: https://token-api.linea.build
  description: Linea Token API production server
tags:
- name: Tokens
  description: ERC-20 token metadata and information
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 to secure tokens only
        schema:
          type: boolean
      - name: addresses
        required: false
        in: query
        description: List of token contract addresses (comma-separated, max 100)
        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: Sort direction (asc or 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
components:
  schemas:
    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: TKN
          description: Symbol of the token
        decimals:
          type: number
          example: 18
          description: Number of decimals of the token
        logo:
          type: string
          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: number
          example: 1000
          description: Current price of the token in USD
        priceUpdatedAt:
          type: string
          format: date-time
          example: '2026-05-19T13:38:03.744Z'
          description: Date and time when the price was last updated
        last24hVariation:
          type: number
          example: 0
          description: Price variation in the last 24 hours
        isPossibleSpam:
          type: boolean
          description: Whether the token is flagged as possible spam
        info:
          description: Token trading information
          allOf:
          - $ref: '#/components/schemas/TokenInfoResponseDto'
      required:
      - name
      - symbol
      - decimals
      - logo
      - contractAddress
      - currentPrice
      - priceUpdatedAt
      - last24hVariation
      - info
    TokenPageDto:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/TokenResponseDto'
        meta:
          $ref: '#/components/schemas/PageMetaDto'
      required:
      - data
      - meta
    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: number
          example: 100000
          description: Fully diluted valuation (FDV)
        totalSupply:
          type: string
          example: '1000000'
          description: Total supply of the token
      required:
      - sells
      - buys
      - swaps
      - fdv
      - totalSupply
    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