{
  "openapi": "3.0.0",
  "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": {}
  },
  "servers": [
    {
      "url": "https://token-api.linea.build",
      "description": "Linea Token API production server"
    }
  ],
  "tags": [
    {
      "name": "Tokens",
      "description": "ERC-20 token metadata and information"
    },
    {
      "name": "Prices",
      "description": "Token price history"
    }
  ],
  "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"
        ]
      }
    },
    "/prices/{contractAddress}": {
      "get": {
        "description": "Retrieve hourly prices over the last 24 hours for a single token",
        "operationId": "PricesController_findOne",
        "parameters": [
          {
            "name": "contractAddress",
            "required": true,
            "in": "path",
            "description": "The Ethereum contract address of the token",
            "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 hourly prices over the last 24 hours for multiple tokens",
        "operationId": "PricesController_findMany",
        "parameters": [
          {
            "name": "addresses",
            "required": true,
            "in": "query",
            "description": "List of token contract addresses (comma-separated, max 100)",
            "schema": {
              "maxItems": 100,
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successfully retrieved prices",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "description": "Map of contract address to price history array"
                }
              }
            }
          }
        },
        "summary": "Get hourly prices for multiple tokens",
        "tags": [
          "Prices"
        ]
      }
    }
  },
  "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": "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"
        ]
      },
      "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"
        ]
      },
      "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-05-19T13:38:03.784Z",
            "description": "Date and time when the price was fetched"
          }
        },
        "required": [
          "price",
          "timestamp"
        ]
      }
    }
  }
}