> ## 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

> 
    Retrieves a list of tokens with filtering options (trending, new, popular, top_posts).
    Supports optional hashtag filtering and pagination.

    Returns token data including:
    - Holder counts
    - Media counts
    - Vote aggregates (upvotes/downvotes with weights)
    - Livestream status
    - Associated hashtags
    - Creator information

    Authentication is optional - unauthenticated requests receive public data without user-specific vote information.
  



## OpenAPI

````yaml post /get-tokens
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:
    post:
      tags:
        - Tokens
      summary: Get tokens list
      description: |2-

            Retrieves a list of tokens with filtering options (trending, new, popular, top_posts).
            Supports optional hashtag filtering and pagination.

            Returns token data including:
            - Holder counts
            - Media counts
            - Vote aggregates (upvotes/downvotes with weights)
            - Livestream status
            - Associated hashtags
            - Creator information

            Authentication is optional - unauthenticated requests receive public data without user-specific vote information.
          
      operationId: getTokens
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GetTokensRequest'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetTokensResponse'
        '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:
    GetTokensRequest:
      type: object
      properties:
        hashtag_name:
          type: string
          description: Filter tokens by hashtag name
          example: defi
        filter:
          type: string
          enum:
            - trending
            - new
            - popular
            - top_posts
          description: Sorting/filtering strategy for tokens
          example: trending
        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
      required:
        - filter
    GetTokensResponse:
      type: object
      properties:
        success:
          type: boolean
          enum:
            - true
        tokens:
          type: array
          items:
            $ref: '#/components/schemas/Token'
        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
    Token:
      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
        token_layer_id:
          type: string
          nullable: true
        created_at:
          type: string
          format: date-time
        launch_post_id:
          type: string
          nullable: true
          format: uuid
        total_posts_count:
          type: integer
          minimum: 0
        total_media_count:
          type: integer
          minimum: 0
        groups_count:
          type: integer
          minimum: 0
        holders_count:
          type: integer
          minimum: 0
        market_cap:
          type: number
        upvotes:
          type: integer
          minimum: 0
        downvotes:
          type: integer
          minimum: 0
        weighted_upvotes:
          type: number
          minimum: 0
        weighted_downvotes:
          type: number
          minimum: 0
        user_vote:
          type: string
          nullable: true
          enum:
            - upvote
            - downvote
        is_live:
          type: boolean
        hashtags:
          type: array
          items:
            type: string
        creator:
          $ref: '#/components/schemas/User'
        token_addresses:
          type: array
          items:
            $ref: '#/components/schemas/TokenAddress'
        launch_post:
          type: object
          nullable: true
          properties:
            id:
              type: string
              format: uuid
            upvotes:
              type: integer
              minimum: 0
            downvotes:
              type: integer
              minimum: 0
            weighted_upvotes:
              type: number
              minimum: 0
            weighted_downvotes:
              type: number
              minimum: 0
            user_vote:
              type: string
              nullable: true
              enum:
                - upvote
                - downvote
          required:
            - id
            - upvotes
            - downvotes
            - weighted_upvotes
            - weighted_downvotes
            - user_vote
      required:
        - id
        - name
        - symbol
        - slug
        - logo
        - banner_url
        - video_url
        - description
        - token_layer_id
        - created_at
        - launch_post_id
        - total_posts_count
        - total_media_count
        - groups_count
        - holders_count
        - upvotes
        - downvotes
        - weighted_upvotes
        - weighted_downvotes
        - user_vote
        - is_live
        - hashtags
        - creator
      description: Token with full metadata
    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
    User:
      type: object
      nullable: true
      properties:
        id:
          type: string
          format: uuid
        username:
          type: string
        profile_picture:
          type: string
          nullable: true
          format: uri
      required:
        - id
        - username
        - profile_picture
      description: User profile 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
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: JWT token or API key

````