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

# 💼 Top Gainers & Losers

> This endpoint allows you to **query the top 30 coins with largest price gain and loss by a specific time duration**

<Note>
  ### Note

  * The endpoint response only includes coins with a 24-hour trading volume of at least \$50,000.
  * CoinGecko equivalent page: [https://www.coingecko.com/en/crypto-gainers-losers](https://www.coingecko.com/en/crypto-gainers-losers).
  * Cache / Update Frequency: Every 5 minutes.
  * Exclusive for Paid Plan Subscribers (Analyst, Lite, Pro and Enterprise).
</Note>


## OpenAPI

````yaml api-reference/coingecko-pro.json get /coins/top_gainers_losers
openapi: 3.0.0
info:
  title: CoinGecko Pro API
  version: 3.0.0
servers:
  - url: https://pro-api.coingecko.com/api/v3
security:
  - apiKeyAuth: []
  - apiKeyQueryParam: []
paths:
  /coins/top_gainers_losers:
    get:
      tags:
        - Coins
      summary: 💼 Top Gainers & Losers
      description: >-
        This endpoint allows you to **query the top 30 coins with largest price
        gain and loss by a specific time duration**
      operationId: coins-top-gainers-losers
      parameters:
        - name: vs_currency
          in: query
          description: |-
            target currency of coins 
             *refers to [`/simple/supported_vs_currencies`](/reference/simple-supported-currencies).
          required: true
          schema:
            type: string
            example: usd
            default: usd
        - name: duration
          in: query
          description: |-
            filter result by time range 
             Default value: `24h`
          required: false
          schema:
            type: string
            enum:
              - 1h
              - 24h
              - 7d
              - 14d
              - 30d
              - 60d
              - 1y
        - name: price_change_percentage
          in: query
          description: >-
            include price change percentage timeframe, comma-separated if query
            more than 1 price change percentage timeframe 
             Valid values: 1h, 24h, 7d, 14d, 30d, 200d, 1y
          required: false
          schema:
            type: string
          examples:
            one value:
              value: 1h
            multiple values:
              value: 1h,24h,7d
        - name: top_coins
          in: query
          description: >-
            filter result by market cap ranking (top 300 to 1000) or all coins
            (including coins that do not have market cap) 
             Default value: `1000`
          required: false
          schema:
            type: string
            enum:
              - '300'
              - '500'
              - '1000'
              - all
      responses:
        '200':
          description: List top 30 gainers and losers
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TopGainersLosers'
components:
  schemas:
    TopGainersLosers:
      type: object
      properties:
        top_gainers:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
                description: coin ID
              symbol:
                type: string
                description: coin symbol
              name:
                type: string
                description: coin name
              image:
                type: string
                description: coin image url
              market_cap_rank:
                type: number
                description: coin rank by market cap
              usd:
                type: number
                description: coin price in USD
              usd_24h_vol:
                type: number
                description: coin 24hr volume in USD
              usd_24h_change:
                type: number
                nullable: true
                description: coin 24hr change percentage in USD
              usd_1h_change:
                type: number
                nullable: true
                description: coin 1hr change percentage in USD
              usd_7d_change:
                type: number
                nullable: true
                description: coin 7 day change percentage in USD
              usd_14d_change:
                type: number
                nullable: true
                description: coin 14 day change percentage in USD
              usd_30d_change:
                type: number
                nullable: true
                description: coin 30 day change percentage in USD
              usd_200d_change:
                type: number
                nullable: true
                description: coin 200 day change percentage in USD
              usd_1y_change:
                type: number
                nullable: true
                description: coin 1 year change percentage in USD
        top_losers:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
                description: coin ID
              symbol:
                type: string
                description: coin symbol
              name:
                type: string
                description: coin name
              image:
                type: string
                description: coin image url
              market_cap_rank:
                type: number
                description: coin rank by market cap
              usd:
                type: number
                description: coin price in USD
              usd_24h_vol:
                type: number
                description: coin 24hr volume in USD
              usd_24h_change:
                type: number
                nullable: true
                description: coin 24hr change percentage in USD
              usd_1h_change:
                type: number
                nullable: true
                description: coin 1hr change percentage in USD
              usd_7d_change:
                type: number
                nullable: true
                description: coin 7 day change percentage in USD
              usd_14d_change:
                type: number
                nullable: true
                description: coin 14 day change percentage in USD
              usd_30d_change:
                type: number
                nullable: true
                description: coin 30 day change percentage in USD
              usd_200d_change:
                type: number
                nullable: true
                description: coin 200 day change percentage in USD
              usd_1y_change:
                type: number
                nullable: true
                description: coin 1 year change percentage in USD
      example:
        top_gainers:
          - id: hemi
            symbol: hemi
            name: Hemi
            image: >-
              https://coin-images.coingecko.com/coins/images/68469/original/hemi.png?1755838145
            market_cap_rank: 504
            usd: 0.11185590814980959
            usd_24h_vol: 37605963.6544256
            usd_24h_change: 97.50734564945273
            usd_1h_change: -0.17390830639913413
            usd_7d_change: 109.51907994608104
            usd_14d_change: 174.05573448108248
            usd_30d_change: null
            usd_200d_change: null
            usd_1y_change: null
          - id: pumpbtc-2
            symbol: pump
            name: PumpBTC
            image: >-
              https://coin-images.coingecko.com/coins/images/55057/original/pumpbtc.jpg?1743518852
            market_cap_rank: 884
            usd: 0.16754354002402758
            usd_24h_vol: 140450837.37342194
            usd_24h_change: 79.0420542402058
            usd_1h_change: 8.40284698009908
            usd_7d_change: 28.741928455454058
            usd_14d_change: 313.0525092121525
            usd_30d_change: 324.6502118828966
            usd_200d_change: null
            usd_1y_change: null
          - id: thena
            symbol: the
            name: Thena
            image: >-
              https://coin-images.coingecko.com/coins/images/28864/original/Symbol-Color200x200.png?1706810126
            market_cap_rank: 642
            usd: 0.6638151932043868
            usd_24h_vol: 487895427.62352824
            usd_24h_change: 61.81094922342915
            usd_1h_change: 0.9390562783319398
            usd_7d_change: 86.44786589199917
            usd_14d_change: 97.8025192992777
            usd_30d_change: 73.66796131254053
            usd_200d_change: 55.59406002775006
            usd_1y_change: 331.98491608746525
        top_losers:
          - id: alchemist-ai
            symbol: alch
            name: Alchemist AI
            image: >-
              https://coin-images.coingecko.com/coins/images/52302/original/small-logo.png?1733053544
            market_cap_rank: 756
            usd: 0.07041470135934932
            usd_24h_vol: 27971580.84457393
            usd_24h_change: -17.226320551694926
            usd_1h_change: -2.2542371779000514
            usd_7d_change: -23.040652631290545
            usd_14d_change: -19.470542701647435
            usd_30d_change: -46.09430540829394
            usd_200d_change: 45.86147201477917
            usd_1y_change: null
          - id: openvpp
            symbol: ovpp
            name: OpenVPP
            image: >-
              https://coin-images.coingecko.com/coins/images/68508/original/IMG_9538.jpeg?1756034149
            market_cap_rank: 656
            usd: 0.0928916427310922
            usd_24h_vol: 2056051.9687436165
            usd_24h_change: -16.433799392732045
            usd_1h_change: 6.52588781595783
            usd_7d_change: -30.059713680473045
            usd_14d_change: 26.47704349007484
            usd_30d_change: null
            usd_200d_change: null
            usd_1y_change: null
          - id: tutorial
            symbol: tut
            name: Tutorial
            image: >-
              https://coin-images.coingecko.com/coins/images/54299/original/image_2025-02-08_18-56-13.png?1739165439
            market_cap_rank: 709
            usd: 0.07931969147215992
            usd_24h_vol: 100448249.77316675
            usd_24h_change: -14.152000966660887
            usd_1h_change: 1.2261498633124626
            usd_7d_change: 15.617617995365999
            usd_14d_change: 16.107294253488487
            usd_30d_change: 32.794999688255686
            usd_200d_change: 5109.0575785263345
            usd_1y_change: null
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: x-cg-pro-api-key
    apiKeyQueryParam:
      type: apiKey
      in: query
      name: x_cg_pro_api_key

````