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

# Get Coins

> Get comprehensive data about all cryptocurrencies

<Note>**2** credits per request</Note><hr />

<AccordionGroup>
  <Accordion title="You will get">
    * Price, market cap, and volume
    * Price changes (1h, 24h, 7d, 1m)
    * Supply information
    * Trading metrics
    * Social links and metadata
  </Accordion>

  <Accordion title="Optional">
    * currency: Display currency (defaults to USD).
    * limit & skip: Control pagination.
    * includeRiskScore: When `true`, response includes the risk score field.
    * categories: Comma-separated category filters.
    * blockchains: Comma-separated blockchain filters.
    * sortBy / sortDir: Sort the result set.
  </Accordion>
</AccordionGroup>


## OpenAPI

````yaml /api-reference/openapi.json get /v1/coins
openapi: 3.0.0
info:
  title: CoinStats Public API
  description: >-
    CoinStats Public API — programmatic access to market data, news, NFTs,
    wallets, exchange connections, and user portfolios. Authenticate every
    request with the `X-API-KEY` header (or an OAuth Bearer token in the
    `Authorization` header). Generate keys at https://openapi.coinstats.app.
  version: '1.0'
  contact: {}
servers:
  - url: https://openapiv1.coinstats.app
security: []
tags:
  - name: CoinStats
    description: ''
  - name: Market Data
    description: >-
      The Market Data section of the API provides endpoints to access a wide
      range of market-related information, including cryptocurrency coins,
      ticker data, and fiat currency rates. This category offers comprehensive
      data to help users monitor and analyze the cryptocurrency market, track
      prices, and gain insights into market trends
  - name: News
    description: >-
      The News section of the API allows you to access news articles and updates
      related to cryptocurrencies and the blockchain industry. It provides
      valuable information from various sources to keep you informed about the
      latest developments
  - name: NFTs
    description: >-
      The NFT section of the API provides endpoints to interact with
      Non-Fungible Tokens (NFTs), which are unique digital assets stored on a
      blockchain. These endpoints allow you to retrieve information about NFTs,
      including collections, assets, trending NFTs, and specific assets
      associated with wallet addresses.
  - name: Wallet Data
    description: >-
      The Wallet section of the API provides a comprehensive set of endpoints to
      manage and interact with wallets. It enables users to retrieve wallet
      balances, monitor syncing status, fetch transaction data, and synchronize
      wallet information with the blockchain. By integrating these endpoints
      into your application, you can offer robust wallet functionality to your
      users.
  - name: Exchange Connection
    description: >-
      The Exchange Connection section of the API provides a comprehensive set of
      endpoints to manage and interact with exchanges. It enables users to
      retrieve exchange balances, monitor syncing status, fetch transaction
      data. By integrating these endpoints into your application, you can offer
      robust exchange portfolio tracking functionality to your users.
  - name: User Portfolio
    description: >-
      The Portfolio section of the API provides a comprehensive set of endpoints
      to manage and interact with Share Portfolios. It enables users to retrieve
      current Portfolio Coins and Transactions.
  - name: Usage
    description: The Usage section provides account-level API usage data.
  - name: Status
    description: The Status section provides API availability checks.
paths:
  /v1/coins:
    get:
      tags:
        - Market Data
      summary: Get comprehensive data about all cryptocurrencies
      operationId: get-coins
      parameters:
        - name: page
          required: false
          in: query
          description: Page number to retrieve (1-based indexing)
          schema:
            example: 1
            type: number
        - name: limit
          required: false
          in: query
          description: Number of items to return per page
          schema:
            example: 20
            type: number
        - name: coinIds
          required: false
          in: query
          description: >-
            Filter coins by specific coin IDs. Use comma-separated values to
            specify multiple coins. Each coin ID should be the unique identifier
            for the cryptocurrency.
          schema:
            example: bitcoin,ethereum,solana
            type: string
        - name: currency
          required: false
          in: query
          description: The currency to display coin prices and market data in.
          schema:
            example: USD
            type: string
        - name: name
          required: false
          in: query
          description: >-
            Search for coins by their name. Supports partial matching - you can
            search for "bit" to find "Bitcoin" and other coins containing that
            substring.
          schema:
            example: bitcoin
            type: string
        - name: symbol
          required: false
          in: query
          description: >-
            Filter coins by their ticker symbol. Use the standard trading symbol
            for the cryptocurrency (e.g., BTC for Bitcoin, ETH for Ethereum).
          schema:
            example: BTC
            type: string
        - name: contractAddresses
          required: false
          in: query
          description: >-
            Filter coins by smart contract addresses. Use comma-separated values
            to specify multiple addresses. Matching is case-insensitive.
          schema:
            example: >-
              0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48,0xdac17f958d2ee523a2206206994597c13d831ec7
            type: string
        - name: blockchains
          required: false
          in: query
          description: >-
            Filter coins by blockchain networks. Use comma-separated values to
            specify multiple blockchains. Common values include ethereum,
            solana, binance-smart-chain, polygon, avalanche.
          schema:
            example: ethereum,solana,binance-smart-chain
            type: string
        - name: includeRiskScore
          required: false
          in: query
          description: >-
            Include risk score data in the response. Set to "true" to include
            risk assessment metrics, or "false" to exclude them.
          schema:
            example: 'true'
            type: string
        - name: categories
          required: false
          in: query
          description: >-
            Filter coins by categories. Use comma-separated values to specify
            multiple categories. Common categories include defi, memecoins,
            gaming, nft, metaverse, layer-1, layer-2.
          schema:
            example: defi,memecoins,gaming
            type: string
        - name: sortBy
          required: false
          in: query
          description: Field to sort results by.
          schema:
            example: marketCap
            type: string
            enum:
              - rank
              - marketCap
              - price
              - volume
              - priceChange1h
              - priceChange1d
              - priceChange7d
              - priceChange1m
              - name
              - symbol
        - name: sortDir
          required: false
          in: query
          description: >-
            Sort direction for the results. Use "asc" for ascending order or
            "desc" for descending order.
          schema:
            example: desc
            type: string
            enum:
              - asc
              - desc
        - name: marketCap~greaterThan
          required: false
          in: query
          description: >-
            Filter coins with market capitalization greater than the specified
            value (in USD). Example: 1000000000 for coins with market cap above
            $1 billion.
          schema:
            example: '1000000000'
            type: number
        - name: marketCap~equals
          required: false
          in: query
          description: >-
            Filter coins with market capitalization equal to the specified value
            (in USD). Exact matches are rare due to constant price fluctuations.
          schema:
            example: '500000000'
            type: number
        - name: marketCap~lessThan
          required: false
          in: query
          description: >-
            Filter coins with market capitalization less than the specified
            value (in USD). Example: 100000000 for coins with market cap below
            $100 million.
          schema:
            example: '100000000'
            type: number
        - name: fullyDilutedValuation~greaterThan
          required: false
          in: query
          description: >-
            Filter coins with fully diluted valuation greater than the specified
            value (in USD). FDV represents the theoretical market cap if all
            tokens were in circulation.
          schema:
            example: '2000000000'
            type: number
        - name: fullyDilutedValuation~equals
          required: false
          in: query
          description: >-
            Filter coins with fully diluted valuation equal to the specified
            value (in USD). FDV = total supply × current price.
          schema:
            example: '1500000000'
            type: number
        - name: fullyDilutedValuation~lessThan
          required: false
          in: query
          description: >-
            Filter coins with fully diluted valuation less than the specified
            value (in USD). Useful for finding smaller cap projects with growth
            potential.
          schema:
            example: '500000000'
            type: number
        - name: volume~greaterThan
          required: false
          in: query
          description: >-
            Filter coins with 24-hour trading volume greater than the specified
            value (in USD). Higher volume indicates more liquidity and trading
            activity.
          schema:
            example: '10000000'
            type: number
        - name: volume~equals
          required: false
          in: query
          description: >-
            Filter coins with 24-hour trading volume equal to the specified
            value (in USD). Exact matches are uncommon due to constant trading
            activity.
          schema:
            example: '5000000'
            type: number
        - name: volume~lessThan
          required: false
          in: query
          description: >-
            Filter coins with 24-hour trading volume less than the specified
            value (in USD). Useful for finding less traded or emerging coins.
          schema:
            example: '1000000'
            type: number
        - name: priceChange1h~greaterThan
          required: false
          in: query
          description: >-
            Filter coins with 1-hour price change greater than the specified
            percentage. Example: 5 for coins with more than 5% gain in the last
            hour.
          schema:
            example: '5'
            type: number
        - name: priceChange1h~equals
          required: false
          in: query
          description: >-
            Filter coins with 1-hour price change equal to the specified
            percentage. Useful for finding stable coins in short timeframes.
          schema:
            example: '0'
            type: number
        - name: priceChange1h~lessThan
          required: false
          in: query
          description: >-
            Filter coins with 1-hour price change less than the specified
            percentage. Example: -2 for coins declining more than 2% in the last
            hour.
          schema:
            example: '-2'
            type: number
        - name: priceChange1d~greaterThan
          required: false
          in: query
          description: >-
            Filter coins with 24-hour price change greater than the specified
            percentage. Example: 10 for coins with more than 10% daily gain.
          schema:
            example: '10'
            type: number
        - name: priceChange1d~equals
          required: false
          in: query
          description: >-
            Filter coins with 24-hour price change equal to the specified
            percentage. Useful for finding stable coins over a day.
          schema:
            example: '0'
            type: number
        - name: priceChange1d~lessThan
          required: false
          in: query
          description: >-
            Filter coins with 24-hour price change less than the specified
            percentage. Example: -5 for coins declining more than 5% today.
          schema:
            example: '-5'
            type: number
        - name: priceChange7d~greaterThan
          required: false
          in: query
          description: >-
            Filter coins with 7-day price change greater than the specified
            percentage. Example: 20 for coins with more than 20% weekly gain.
          schema:
            example: '20'
            type: number
        - name: priceChange7d~equals
          required: false
          in: query
          description: >-
            Filter coins with 7-day price change equal to the specified
            percentage. Useful for finding coins with stable weekly performance.
          schema:
            example: '0'
            type: number
        - name: priceChange7d~lessThan
          required: false
          in: query
          description: >-
            Filter coins with 7-day price change less than the specified
            percentage. Example: -10 for coins declining more than 10% this
            week.
          schema:
            example: '-10'
            type: number
        - name: priceChange1m~greaterThan
          required: false
          in: query
          description: >-
            Filter coins with 1-month price change greater than the specified
            percentage. Example: 30 for coins with more than 30% monthly gain.
          schema:
            example: '30'
            type: number
        - name: priceChange1m~equals
          required: false
          in: query
          description: >-
            Filter coins with 1-month price change equal to the specified
            percentage. Useful for finding coins with stable monthly
            performance.
          schema:
            example: '0'
            type: number
        - name: priceChange1m~lessThan
          required: false
          in: query
          description: >-
            Filter coins with 1-month price change less than the specified
            percentage. Example: -20 for coins declining more than 20% this
            month.
          schema:
            example: '-20'
            type: number
        - name: availableSupply~greaterThan
          required: false
          in: query
          description: >-
            Filter coins with circulating supply greater than the specified
            amount. This represents tokens currently available for trading in
            the market.
          schema:
            example: '1000000'
            type: number
        - name: availableSupply~equals
          required: false
          in: query
          description: >-
            Filter coins with circulating supply equal to the specified amount.
            Example: 21000000 for Bitcoin's maximum supply.
          schema:
            example: '21000000'
            type: number
        - name: availableSupply~lessThan
          required: false
          in: query
          description: >-
            Filter coins with circulating supply less than the specified amount.
            Useful for finding scarce or limited supply tokens.
          schema:
            example: '100000'
            type: number
        - name: totalSupply~greaterThan
          required: false
          in: query
          description: >-
            Filter coins with total supply greater than the specified amount.
            Total supply includes all minted tokens, including locked and vested
            ones.
          schema:
            example: '10000000'
            type: number
        - name: totalSupply~equals
          required: false
          in: query
          description: >-
            Filter coins with total supply equal to the specified amount. Useful
            for finding tokens with specific supply characteristics.
          schema:
            example: '1000000000'
            type: number
        - name: totalSupply~lessThan
          required: false
          in: query
          description: >-
            Filter coins with total supply less than the specified amount. Great
            for finding ultra-scarce tokens with limited total supply.
          schema:
            example: '500000'
            type: number
        - name: rank~greaterThan
          required: false
          in: query
          description: >-
            Filter coins with market cap rank greater than the specified number.
            Example: 100 to exclude top 100 coins and find smaller cap projects.
          schema:
            example: '100'
            type: number
        - name: rank~equals
          required: false
          in: query
          description: >-
            Filter coins with market cap rank equal to the specified number.
            Example: 10 to find the 10th largest cryptocurrency by market cap.
          schema:
            example: '10'
            type: number
        - name: rank~lessThan
          required: false
          in: query
          description: >-
            Filter coins with market cap rank less than the specified number.
            Example: 50 to show only top 50 cryptocurrencies.
          schema:
            example: '50'
            type: number
        - name: price~greaterThan
          required: false
          in: query
          description: >-
            Filter coins with current price greater than the specified value (in
            the selected currency). Example: 100 for coins priced above $100.
          schema:
            example: '100'
            type: number
        - name: price~equals
          required: false
          in: query
          description: >-
            Filter coins with current price equal to the specified value. Useful
            for finding stablecoins or coins at specific price points.
          schema:
            example: '1'
            type: number
        - name: price~lessThan
          required: false
          in: query
          description: >-
            Filter coins with current price less than the specified value.
            Example: 0.01 for coins under 1 cent, often called "penny coins".
          schema:
            example: '0.01'
            type: number
        - name: riskScore~greaterThan
          required: false
          in: query
          description: >-
            Filter coins with risk score greater than the specified value (0-100
            scale). Higher scores indicate higher risk. Only available when
            **includeRiskScore=true**.
          schema:
            minimum: 0
            maximum: 100
            example: '70'
            type: number
        - name: riskScore~equals
          required: false
          in: query
          description: >-
            Filter coins with risk score equal to the specified value (0-100
            scale). Useful for finding coins with specific risk profiles. Only
            available when **includeRiskScore=true**.
          schema:
            minimum: 0
            maximum: 100
            example: '50'
            type: number
        - name: riskScore~lessThan
          required: false
          in: query
          description: >-
            Filter coins with risk score less than the specified value (0-100
            scale). Lower scores indicate lower risk investments. Only available
            when **includeRiskScore=true**.
          schema:
            minimum: 0
            maximum: 100
            example: '30'
            type: number
      responses:
        '200':
          description: Get coins list
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CoinListResponseDto'
        '400':
          description: Bad Request
          content:
            application/json:
              example:
                statusCode: 400
                message: Bad Request
                requestId: 11111111-2222-3333-4444-555555555555
                path: <requested-endpoint>
        '401':
          description: Unauthorized
          content:
            application/json:
              example:
                statusCode: 401
                message: Unauthorized
                requestId: 11111111-2222-3333-4444-555555555555
                path: <requested-endpoint>
        '403':
          description: Forbidden
          content:
            application/json:
              example:
                statusCode: 403
                message: Forbidden
                requestId: 11111111-2222-3333-4444-555555555555
                path: <requested-endpoint>
        '404':
          description: Not Found
          content:
            application/json:
              example:
                statusCode: 404
                message: Not Found
                requestId: 11111111-2222-3333-4444-555555555555
                path: <requested-endpoint>
        '409':
          description: Conflict (for some endpoints)
          content:
            application/json:
              example:
                statusCode: 409
                message: Transactions not synced
                requestId: 11111111-2222-3333-4444-555555555555
                path: <requested-endpoint>
        '429':
          description: Too Many Requests
          content:
            application/json:
              example:
                statusCode: 429
                message: Rate limit exceeded
                requestId: 11111111-2222-3333-4444-555555555555
                path: <requested-endpoint>
        '503':
          description: Service Unavailable
          content:
            application/json:
              example:
                statusCode: 503
                message: Service Unavailable. Please Contact Support
      security:
        - X-API-KEY: []
components:
  schemas:
    CoinListResponseDto:
      type: object
      properties:
        meta:
          description: Pagination metadata including page info and totals
          example:
            page: 1
            limit: 20
            itemCount: 150
            pageCount: 8
            hasPreviousPage: false
            hasNextPage: true
          allOf:
            - $ref: '#/components/schemas/PageMetaDto'
        result:
          description: Array of coin data items for the current page
          example:
            - id: ethereum
              icon: https://static.coinstats.app/coins/ethereum_32.png
              name: Ethereum
              symbol: ETH
              rank: 2
              price: 2680.45
              priceBtc: 0.062
              volume: 8520000000
              marketCap: 322100000000
              availableSupply: 120280000
              totalSupply: 120280000
              fullyDilutedValuation: 322100000000
              priceChange1h: -0.25
              priceChange1d: 1.85
              priceChange1w: 3.42
              priceChange1m: 7.21
              websiteUrl: https://ethereum.org
              redditUrl: https://reddit.com/r/ethereum
              twitterUrl: https://twitter.com/ethereum
              contractAddress: null
              contractAddresses: []
              decimals: 18
              explorers:
                - https://etherscan.io
              liquidityScore: 88.7
              volatilityScore: 38.9
              marketCapScore: 92.1
              riskScore: 18.5
              avgChange: 2.14
          type: array
          items:
            $ref: '#/components/schemas/CoinListResponseItemDto'
      required:
        - meta
        - result
    PageMetaDto:
      type: object
      properties:
        page:
          type: number
          description: Current page number (1-based)
          example: 2
          minimum: 1
        limit:
          type: number
          description: Number of items per page
          example: 20
          minimum: 1
          maximum: 1000
        itemCount:
          type: number
          description: Total number of items across all pages
          example: 150
          minimum: 0
        pageCount:
          type: number
          description: Total number of pages available
          example: 8
          minimum: 0
        hasPreviousPage:
          type: boolean
          description: Whether there is a previous page available
          example: true
        hasNextPage:
          type: boolean
          description: Whether there is a next page available
          example: true
      required:
        - page
        - limit
        - itemCount
        - pageCount
        - hasPreviousPage
        - hasNextPage
    CoinListResponseItemDto:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier for the cryptocurrency
          example: bitcoin
        icon:
          type: string
          description: URL to the cryptocurrency icon/logo
          example: https://static.coinstats.app/coins/1650455588819.png
        name:
          type: string
          description: Full name of the cryptocurrency
          example: Bitcoin
        symbol:
          type: string
          description: Trading symbol/ticker of the cryptocurrency
          example: BTC
        rank:
          type: number
          description: Market capitalization rank of the cryptocurrency
          example: 1
        price:
          type: number
          description: Current price of the cryptocurrency in USD
          example: 43250.75
        priceBtc:
          type: number
          description: Current price of the cryptocurrency in BTC
          example: 1
        volume:
          type: number
          description: 24-hour trading volume in USD
          example: 15420000000
        marketCap:
          type: number
          description: Market capitalization in USD
          example: 847350000000
        availableSupply:
          type: number
          description: Number of coins currently in circulation
          example: 19600000
        totalSupply:
          type: number
          description: Total supply of the cryptocurrency
          example: 21000000
        fullyDilutedValuation:
          type: number
          description: Fully diluted market valuation
          example: 907500000000
        priceChange1h:
          type: number
          description: Percentage price change in the last 1 hour
          example: 0.75
        priceChange1d:
          type: number
          description: Percentage price change in the last 24 hours
          example: 2.15
        priceChange1w:
          type: number
          description: Percentage price change in the last 7 days
          example: -1.42
        priceChange1m:
          type: number
          description: Percentage price change in the last 1 month
          example: 4.25
        websiteUrl:
          type: string
          description: Official website URL of the cryptocurrency project
          example: https://bitcoin.org
        redditUrl:
          type: string
          description: Reddit community URL for the cryptocurrency
          example: https://reddit.com/r/bitcoin
        twitterUrl:
          type: string
          description: Official Twitter account URL
          example: https://twitter.com/bitcoin
        contractAddress:
          type: string
          description: Smart contract address for the token
          example: '0xa0b86a33e6776e2e09e384b0c92fceaade8fa82f'
        contractAddresses:
          description: Array of contract addresses across different blockchains
          type: array
          items:
            $ref: '#/components/schemas/ContractAddressDto'
        decimals:
          type: number
          description: Number of decimal places for the token
          example: 18
        explorers:
          description: Array of blockchain explorer URLs
          example:
            - https://blockstream.info
          type: array
          items:
            type: string
        liquidityScore:
          type: number
          description: Liquidity score of the cryptocurrency (0-100)
          example: 85.5
        volatilityScore:
          type: number
          description: Volatility score of the cryptocurrency (0-100)
          example: 42.3
        marketCapScore:
          type: number
          description: Market capitalization score (0-100)
          example: 95.8
        riskScore:
          type: number
          description: Overall risk score of the cryptocurrency (0-100)
          example: 25.7
        avgChange:
          type: number
          description: Average price change percentage
          example: 1.25
        isStable:
          type: boolean
          description: >-
            Indicates if the cryptocurrency is a stablecoin. Only present for
            stablecoins.
          example: true
        color:
          type: string
          description: >-
            Brand color of the cryptocurrency in hex format (without #). Only
            present for coins that have it defined.
          example: FF9500
        slug:
          type: string
          description: URL-friendly identifier for the cryptocurrency
          example: bitcoin
        allTimeHigh:
          type: number
          description: >-
            All-time high price in the requested currency. Only present for
            coins that have it defined.
          example: 126080
        allTimeLow:
          type: number
          description: >-
            All-time low price in the requested currency. Only present for coins
            that have it defined.
          example: 67.81
      required:
        - id
        - icon
        - name
        - symbol
        - rank
        - price
        - priceBtc
        - volume
        - marketCap
        - availableSupply
        - totalSupply
        - fullyDilutedValuation
        - priceChange1h
        - priceChange1d
        - priceChange1w
        - priceChange1m
        - websiteUrl
        - redditUrl
        - twitterUrl
        - explorers
        - slug
    ContractAddressDto:
      type: object
      properties:
        blockchain:
          type: string
          description: The blockchain network where the contract is deployed
          example: ethereum
        contractAddress:
          type: string
          description: The smart contract address on the blockchain
          example: '0xa0b86a33e6776e2e09e384b0c92fceaade8fa82f'
      required:
        - blockchain
        - contractAddress
  securitySchemes:
    X-API-KEY:
      type: apiKey
      in: header
      name: X-API-KEY
      description: >-
        API key required to access the endpoints. Generate one from your
        dashboard at https://openapi.coinstats.app and pass it in the
        `X-API-KEY` request header. Never expose your key in client-side code.

````