> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tokenlayer.network/llms.txt
> Use this file to discover all available pages before exploring further.

# Get tokens list with trading metrics (v2)

> 
    Retrieves a list of tokens with comprehensive trading metrics.

    Key improvements over v1:
    - All calculations done in database for better performance
    - Volume metrics for multiple time periods (1m, 5m, 1h, 24h)
    - Transaction count (trx) and holder counts
    - Price change percentage over 24h
    - Keyword search across name, symbol, and description
    - Multi-hashtag filtering with AND logic
    - Flexible ordering by any metric

    Authentication is optional.
  



## OpenAPI

````yaml post /get-tokens-v2
openapi: 3.0.3
info:
  title: Token Layer API
  version: 1.0.0
  description: |2-

          Token Layer is an omnichain token trading platform where users can create and trade tokens across multiple chains.

          This API provides comprehensive access to token operations, trading, earnings,
          blockchain transactions, and portfolio management.

          ## Base URL
          All endpoints are accessed via: `https://api.tokenlayer.network/{endpoint}`

          ## Authentication
          Most endpoints require authentication using an JWT token or API key passed as a Bearer token in the Authorization header.

          ## Rate Limiting
          API calls are rate limited per user. Please implement appropriate backoff strategies.
        
  contact:
    name: Token Layer API Support
    url: https://app.tokenlayer.network
servers:
  - url: https://api.tokenlayer.network/functions/v1
    description: Production server
  - url: https://api.tokenlayer.network/functions/v1
    description: Staging server
security: []
tags:
  - name: Tokens
    description: Token creation, browsing, search, trading, and price operations
  - name: Transactions
    description: Blockchain transactions (send, tip, ownership checks)
paths:
  /get-tokens-v2:
    post:
      tags:
        - Tokens
      summary: Get tokens list with trading metrics (v2)
      description: |2-

            Retrieves a list of tokens with comprehensive trading metrics.

            Key improvements over v1:
            - All calculations done in database for better performance
            - Volume metrics for multiple time periods (1m, 5m, 1h, 24h)
            - Transaction count (trx) and holder counts
            - Price change percentage over 24h
            - Keyword search across name, symbol, and description
            - Multi-hashtag filtering with AND logic
            - Flexible ordering by any metric

            Authentication is optional.
          
      operationId: getTokensV2
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GetTokensV2Request'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetTokensV2Response'
        '400':
          description: Bad request - Invalid parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
        - BearerAuth: []
        - {}
components:
  schemas:
    GetTokensV2Request:
      type: object
      properties:
        hashtags:
          type: array
          items:
            type: string
          description: >-
            Filter tokens by hashtags (must match ALL hashtags provided - AND
            logic)
          example:
            - defi
            - ethereum
        keyword:
          type: string
          description: >-
            Search keyword to filter by token name, symbol, or description
            (case-insensitive)
          example: bitcoin
        chains:
          type: array
          items:
            $ref: '#/components/schemas/ChainSlug'
          description: >-
            Filter tokens by chain slugs (returns tokens available on any of the
            specified chains)
          example:
            - base
            - solana
            - ethereum
        builder_code:
          type: string
          pattern: ^0x[a-fA-F0-9]{40}$
          description: >-
            Filter tokens by builder address (case-insensitive). Returns only
            tokens deployed by this builder.
          example: '0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb'
        stage:
          allOf:
            - $ref: '#/components/schemas/TokenLaunchStage'
            - description: >-
                Filter tokens by launch stage. Defaults to stage-specific
                ordering when provided without an explicit order_by.
        order_by:
          type: string
          enum:
            - volume_1m
            - volume_5m
            - volume_1h
            - volume_24h
            - market_cap
            - price_change_24h
            - trx
            - holders
            - created_at
          default: created_at
          description: Field to order results by
          example: volume_24h
        order_direction:
          type: string
          enum:
            - ASC
            - DESC
          default: DESC
          description: Sort direction
          example: DESC
        limit:
          type: integer
          minimum: 1
          maximum: 100
          default: 20
          description: Maximum number of tokens to return
          example: 20
        offset:
          type: integer
          minimum: 0
          default: 0
          description: Number of tokens to skip for pagination
          example: 0
        verified_only:
          type: boolean
          default: false
          description: Only return tokens with token_layer_id (verified)
          example: false
    GetTokensV2Response:
      type: object
      properties:
        success:
          type: boolean
          enum:
            - true
        tokens:
          type: array
          items:
            $ref: '#/components/schemas/TokenV2'
        pagination:
          $ref: '#/components/schemas/Pagination'
      required:
        - success
        - tokens
        - pagination
    Error:
      type: object
      properties:
        success:
          type: boolean
          enum:
            - false
        error:
          type: string
      required:
        - success
        - error
      description: Error response
    ChainSlug:
      type: string
      enum:
        - solana
        - solana-devnet
        - arbitrum
        - base
        - base-sepolia
        - avalanche
        - op-bnb
        - bnb
        - bnb-testnet
        - ethereum
        - monad
        - unichain
        - unichain-testnet
        - abstract
        - polygon
        - zksync
        - zksync-testnet
      description: >-
        Blockchain identifier. Supported chains: solana, solana-devnet,
        arbitrum, base, base-sepolia, avalanche, op-bnb, bnb, bnb-testnet,
        ethereum, monad, unichain, unichain-testnet, abstract, polygon, zksync,
        zksync-testnet
      example: base-sepolia
    TokenLaunchStage:
      type: string
      nullable: true
      enum:
        - new
        - graduating
        - graduated
      description: Token launch stage derived from indexer launch and graduation events
      example: graduating
    TokenV2:
      type: object
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        symbol:
          type: string
        slug:
          type: string
        logo:
          type: string
          nullable: true
          format: uri
        banner_url:
          type: string
          nullable: true
          format: uri
        video_url:
          type: string
          nullable: true
          format: uri
        description:
          type: string
          nullable: true
        token_layer_id:
          type: string
          nullable: true
        created_at:
          type: string
          format: date-time
        holders_count:
          type: integer
          nullable: true
          minimum: 0
        market_cap:
          type: number
          nullable: true
        price:
          type: number
          nullable: true
        volume_1m:
          type: number
          nullable: true
        volume_5m:
          type: number
          nullable: true
        volume_1h:
          type: number
          nullable: true
        volume_24h:
          type: number
          nullable: true
        price_change_24h:
          type: number
          nullable: true
        price_change_24h_percent:
          type: number
          nullable: true
        launchpad_supply:
          type: number
          nullable: true
        launchpad_tokens_left:
          type: number
          nullable: true
        launchpad_progress_pct:
          type: number
          nullable: true
        trx:
          type: integer
          nullable: true
          minimum: 0
        token_addresses:
          type: array
          items:
            $ref: '#/components/schemas/TokenAddress'
        stage:
          $ref: '#/components/schemas/TokenLaunchStage'
        token_uri:
          type: string
          nullable: true
        hashtags:
          type: array
          items:
            type: string
        indexer_metadata:
          $ref: '#/components/schemas/TokenV2IndexerMetadata'
      required:
        - id
        - name
        - symbol
        - slug
        - logo
        - banner_url
        - video_url
        - description
        - token_layer_id
        - created_at
        - holders_count
        - market_cap
        - price
        - volume_1m
        - volume_5m
        - volume_1h
        - volume_24h
        - price_change_24h
        - price_change_24h_percent
        - launchpad_supply
        - launchpad_tokens_left
        - launchpad_progress_pct
        - trx
        - token_addresses
        - stage
        - token_uri
        - hashtags
        - indexer_metadata
      description: Token with volume and trading metrics
    Pagination:
      type: object
      properties:
        limit:
          type: integer
          minimum: 0
          exclusiveMinimum: true
        offset:
          type: integer
          minimum: 0
        total_returned:
          type: integer
          minimum: 0
        has_more:
          type: boolean
      required:
        - limit
        - offset
        - total_returned
        - has_more
      description: Pagination information
    TokenAddress:
      type: object
      properties:
        id:
          type: string
          format: uuid
        token_id:
          type: string
          format: uuid
        address:
          type: string
        address_display:
          type: string
          nullable: true
        address_type:
          type: string
          enum:
            - evm
            - sol
        chain:
          type: string
        platform_name:
          type: string
        is_registered:
          type: boolean
        dex_name:
          type: string
          nullable: true
        dex_address:
          type: string
          nullable: true
        created_at:
          type: string
          format: date-time
      required:
        - id
        - token_id
        - address
        - address_display
        - address_type
        - chain
        - platform_name
        - is_registered
        - dex_name
        - dex_address
        - created_at
      description: Token address on a specific blockchain
    TokenV2IndexerMetadata:
      type: object
      nullable: true
      properties:
        token_uri:
          type: string
        resolved_metadata_url:
          type: string
          nullable: true
        image_url:
          type: string
          nullable: true
        image_storage_path:
          type: string
          nullable: true
        image_storage_url:
          type: string
          nullable: true
        banner_url:
          type: string
          nullable: true
        name:
          type: string
          nullable: true
        symbol:
          type: string
          nullable: true
        description:
          type: string
          nullable: true
        created_on:
          type: string
          nullable: true
        addresses:
          nullable: true
        token_layer_id:
          type: string
          nullable: true
        hashtags:
          type: array
          items:
            type: string
        token:
          type: string
          nullable: true
        website:
          type: string
          nullable: true
        twitter_url:
          type: string
          nullable: true
        discord_url:
          type: string
          nullable: true
        telegram_url:
          type: string
          nullable: true
        farcaster_url:
          type: string
          nullable: true
        github_url:
          type: string
          nullable: true
        socials:
          nullable: true
        attributes:
          nullable: true
        raw_json:
          nullable: true
        fetched_at:
          type: string
          format: date-time
        immutable:
          type: boolean
      required:
        - token_uri
        - resolved_metadata_url
        - image_url
        - image_storage_path
        - image_storage_url
        - banner_url
        - name
        - symbol
        - description
        - created_on
        - token_layer_id
        - hashtags
        - token
        - website
        - twitter_url
        - discord_url
        - telegram_url
        - farcaster_url
        - github_url
        - fetched_at
        - immutable
      description: Parsed token metadata sourced from indexer.token_metadata
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: JWT token or API key

````