Data Encyclopedia
HomeCharts
  • Welcome & Product Overview
  • Getting Started
  • Tutorials and Examples
    • Tutorials
      • Python API Client Walkthrough
      • Getting Started With Market Data
      • Getting Started With Futures Data
      • Aggregating Options Data
      • Examining Orderbook Depth
      • Aggregating Orderbook Depth to Create Liquidity Metrics
      • Comparing Stablecoin Prices Using Different Pricing Methods
      • Comparing Volumes of Exchanges and Assets
      • Creating Custom Network Data Metrics Using ATLAS
      • Applying Different Types of Marketcap Metrics
      • Comparing the Dominance of Mining Pools Using ATLAS
      • Using Staking Metrics to Get Yield and Staked Supply
      • Granular Insights On Chain Using Hourly Network Data Metrics
      • Exploring Options, Open Interest, and Volatility Data
      • Calculating Total Value Locked in Liquidity Pools using DEX Data
      • Calculating DEX Liquidity Pool Fees and Volumes
      • Analyzing DeFi Protocol Balance Sheets
    • How To Guides
      • How To Export Data
      • How To Migrate From Catalog to Catalog V2 and Reference Data
      • How To Use the Coin Metrics API Efficiently
    • Dashboard Examples
  • Packages
    • CM Labs
    • Coin Metrics Community Data
  • Access Our Data
    • API Reference
    • API Conventions
      • Catalog V1 to Catalog V2 Migration
    • Python API Client
    • R API Client
    • Coverage
    • Status Page
  • Data Visualization
    • Charting Tool
      • Formula Builder
      • Correlation Tool
      • Embedded Charts
      • Troubleshooting
    • Dashboard
      • Troubleshooting
    • CMTV Charts (Labs)
      • Troubleshooting
    • Atlas Explorer
  • Network Data
    • Network Data Pro Overview
      • Availability
        • Asset Completion Time
      • Addresses
        • Active Addresses
        • Address Balances
        • New Addresses
      • Economics
        • Mining
        • Valuation
      • Exchange
        • Deposits
        • Exchange Supply
        • Net Flows
        • Transaction Count
        • Withdrawals
      • Fees and Revenue
        • Fees
        • Revenue
      • Market
        • Market Capitalization
        • Price
        • Profitability
        • Returns
        • Volatility
      • Key Risk Indicator (KRI) Feed
        • Blocks
        • Block Attributes
        • Block Size
        • Block Times
        • Empty Blocks
        • Fees
        • Outputs
        • Rewards
        • Feerates
        • Hashrate
        • Transaction Feerates
        • Transaction Fees
        • Transaction Sizes
        • Transactions
      • Mining
        • Balances
        • Difficulty
        • Exchange Flows
        • Flows
        • Hardware Hash Rate
        • Hash Rate
      • Network Usage
        • Blocks
        • Contracts
        • Profitability
        • UTXOs
        • Blobs
      • Staking
        • Consensus Health
        • Flows
        • Penalty Metrics
        • Slashing Metrics
        • Validator Supply
        • Stakers
        • Yield
      • Supply
        • Active Supply
        • Addresses with Balance
        • Burnt Supply
        • Current Supply
        • Free Float Supply
        • Future Expected Supply
        • Miner Revenue
        • Profitability
        • Revived Supply
        • Shielded Supply
        • Supply Issuance
        • Staking Supply
      • Transactions
        • Blobs
        • Contracts
        • Token Transactions
        • Transactions
        • Transfer Value
        • Transfers
        • Velocity
      • Wallets
        • Active Wallets
        • Wallet Balances
    • Atlas Overview
      • Accounts
      • Account Balance
      • Blocks
        • Full Block
      • Transactions
        • Full Transaction
          • Full Transaction Info for Block
      • Balance Updates
    • Methodologies
      • Normalizing Block Times
    • DeFi Overview
      • Decentralized Exchange Data
      • DeFi Balance Sheets
      • DeFi FAQs
    • Tagging Meta Data
    • Transaction Tracker
    • CM Labs
      • Mining Pool Monitor Overview
        • Mining Pool Monitor API Fields
      • Reorg & Fork Tracker Overview
        • Reorg & Fork Tracker Tracker API Fields
    • Deprecated
      • Mempool Monitor
      • WatchTower Alerts Overview - DEPRECATED
        • WatchTower Alerts - DEPRECATED
          • Ethereum Proof-of-Stake Alerts - DEPRECATED
            • Missed Slot Alert - DEPRECATED
            • Fast Increase in Transaction Count Alert - DEPRECATED
            • Fast Decrease in Transaction Count Alert - DEPRECATED
            • Fast Decrease in Base Fees - DEPRECATED
            • Fast Increase in Base Fees - DEPRECATED
            • Fast Decrease in Priority Fees (Tips) Alert - DEPRECATED
            • Fast Increase in Priority Fees (Tips) Alert - DEPRECATED
            • Decrease in Active Addresses Alert - DEPRECATED
            • Increase in Active Addresses Alert - DEPRECATED
            • Decrease in Total Block Fees Alert - DEPRECATED
            • Increase in Total Block Fees Alert - DEPRECATED
          • DeFi Alerts - DEPRECATED
            • Smart Contract Admin Change Alert - DEPRECATED
            • Admin Change with Issuance Event Alert - DEPRECATED
            • Admin Change with Large Issuance Event Alert - DEPRECATED
          • Mining Alerts - DEPRECATED
            • Unknown Miner Predominance Alert - DEPRECATED
            • Mining Pool Conflict Alert - DEPRECATED
            • Persistent Mining Pool Conflict Alert - DEPRECATED
            • Hashrate Decrease Alert - DEPRECATED
            • 1-Block Difficulty Decrease - DEPRECATED
          • Blockchain Alerts - DEPRECATED
            • 1 Block Reorg Alert - DEPRECATED
            • 2 Block Reorg Alert - DEPRECATED
            • 3 Block Reorg Alert - DEPRECATED
            • Satoshi Coins Spent - DEPRECATED
            • Vintage Coins Spent - DEPRECATED
            • Slow Block Alert - DEPRECATED
            • 1 Consecutive Empty Block Alert - DEPRECATED
            • 2 Consecutive Empty Blocks Alert - DEPRECATED
            • 3 Consecutive Empty Blocks Alert - DEPRECATED
            • 6 Consecutive Empty Blocks Alert - DEPRECATED
          • Mempool Alerts - DEPRECATED
            • Mempool Disruption Alert - DEPRECATED
            • Mempool Size 90% Alert - DEPRECATED
            • Mempool Size 95% Alert - DEPRECATED
            • Mempool Size 99% Alert - DEPRECATED
            • Mempool Size 100% Alert - DEPRECATED
            • Mempool Congestion Alert - DEPRECATED
        • WatchTower API Fields - DEPRECATED
    • Network Data Glossary
    • Network Data FAQs
  • Market Data
    • Market Data Overview
      • Basis
      • Candles
      • Contract Prices
      • Funding Rates
        • Funding Rates
        • Predicted Funding Rates
        • Aggregated Futures Funding Rate
        • Cumulative Futures Funding Rate
      • Greeks
      • Institution Metrics
        • Grayscale
          • Shares Outstanding
          • Market Price
          • Net Asset Value
          • Coin Per Share
          • Total Assets
      • Liquidations
        • Market Level Liquidations
        • Liquidation Metrics
      • Liquidity
        • Bid-Ask Spread Percent
        • Order Book Depth
        • Slippage
      • Market Metadata
      • Open Interest
        • Market Level Open Interest
        • Reported Open Interest
      • Orderbooks
      • Quotes
      • Trades
      • Volatility
        • Market Implied Volatility
        • Implied Volatility
        • Realized Volatility
      • Volume
        • Trusted Volume
        • Reported Volume
    • CM Prices
      • Reference Rate
      • Principal Market Price (USD)
      • Principal Market (USD)
    • Methodologies
      • Coin Metrics Prices Policies
      • Coin Metrics Prices Methodology
      • Trusted Exchange Framework
    • Market Data FAQs
      • CM Prices FAQs
      • Trusted Exchange Framework FAQs
  • Index Data
    • Index Overview
      • Index Timeseries
        • Index Levels
        • Index Candles
        • Index Constituents
    • Policies & Charters
      • CMBI Index Policies
      • Governance Committees
    • Methodologies
      • Fork Legitimacy Framework
      • Adjusted Free Float Supply Methodology
      • Candidate Market Guidelines
    • Fact Sheets
      • CMBI Single Asset Series Fact Sheet
      • CMBI Multi Asset Series Fact Sheet
      • CMBI Total Market Series Fact Sheet
      • CMBI Mining Series Fact Sheet
    • Indexes Glossary
    • Index FAQs
  • Reference Data
    • datonomy Overview
      • Taxonomy for Assets
      • Taxonomy Metadata for Assets
      • datonomy FAQs
    • Profiles Overview
      • Asset Profiles
      • Network Profiles
    • Security Master Overview
      • Assets
      • Markets
    • Methodologies
      • Guiding Principles and Methodology for datonomy
  • BITTENSOR
    • Precog Methodology
      • Point Forecast Ranking
      • Interval Forecast Ranking
      • Interval Score Examples
      • Miner Weight from Rank
Powered by GitBook
On this page
  • HTTP API
  • Python API Client
  • Page Size
  • Data Formats
  • Wildcards
  • Parallelization

Was this helpful?

  1. Tutorials and Examples
  2. How To Guides

How To Use the Coin Metrics API Efficiently

HTTP API

Please follow these rules to use API most efficiently and get the best API performance.

The rules are sorted in the priority order. The first ones make the biggest impact.

  • Ensure that your HTTP client sends the proper request headers to enable HTTP compression. Your HTTP request should have an "Accept-Encoding: gzip" header.

  • Use the line-delimited JSON format (format=json_stream) if it's supported by an API endpoint (check API docs) instead of the default format=json. That format allows you to avoid paging so you can quickly request all data using only one HTTP request without facing page_size limitations (10k elements per page) and related difficulties.

  • If you have to use the format=json (default value), strive to use the paging_from=start query parameter instead of paging_from=end (default value). It always produces faster responses.

  • Instead of sending individual requests for different entities, combine them in a single request using commas. For example, assets=btc,eth&metrics=ReferenceRateUSD,ReferenceRateEUR.

  • Strive to use limit_per_<entity> query parameters if you want to fetch recent metric values for multiple entities (for example, assets, markets, indexes) at the same time. For example, if you want to request recent reference rates for a set of assets, use the following request: https://api.coinmetrics.io/v4/timeseries/asset-metrics?assets=btc,eth&frequency=1m&metrics=ReferenceRates&limit_per_asset=1&page_size=2&api_key=<key>. Note that page_size must be greater or equal to the number of requested entities (assets) multiplied by limit_per_<entity> value.

  • Specify start_time and end_time query parameters instead of relying on their default values to narrow your results and improve API performance.

  • Avoid the sort=time query parameter since it provides worse performance than default sorting.

  • Avoid setting the granularity query parameter to any value other than "raw" (default). That parameter enables API-level downsampling of the raw data which is slow by design and, in some cases, can lead to a 524 timeout from Cloudflare.

  • Avoid the pretty=true query parameter in production code because it's always slower than pretty=false (default value).

Python API Client

The Python API Client can be optimized in many ways to speed up your queries.

Page Size

Queries can be made much faster by increasing the page_size parameter. The higher the page_size, the faster the query, with a maximum of page_size=10000

Data Formats

When a user calls the API using a CoinMetricsClientobject, it returns a DataCollection. A DataCollection is an object that stores information about your client request.

from coinmetrics.api_client import CoinMetricsClient

client = CoinMetricsClient()
data_collection = client.get_asset_metrics(assets='btc', metrics='PriceUSD', limit_per_asset=5)

Responses can be returned in the following formats, in order of how fast they're returned:

  • A Python Generator (DataCollection)

  • A CSV/JSON file (DataCollection.export_to_csv(), DataCollection.export_to_json())

  • A list (DataCollection.to_list())

  • A dataframe (DataCollection.to_dataframe())

Wildcards

Wildcards (*) allow you to query several entities, such as assets, exchanges, and markets, as one parameter. For example:

# Get prices for all assets
asset_metrics = client.get_asset_metrics(assets='*', metrics='PriceUSD', limit_per_asset=1)

# Get btc-usd candles for all exchanges
market_candles_btc_usd = client.get_market_candles(markets=['*-btc-usd-spot'], limit_per_market=10)

# Get all spot exchanges and pairs
exchanges_reference = client.reference_data_exchanges().to_list()

market_candles_spot = client.get_market_candles(markets=[f'{exchange}-*-spot' for exchange['exchange'] in exchanges_reference], limit_per_market=10)

Parallelization

API requests can be parallelized by calling .parallel() on a DataCollection object. Requests can be partitioned in the following ways:

By Column

# Parallelize on 'assets' column
data = client.get_asset_metrics(
    assets=['btc', 'eth'],
    metrics=['PriceUSD', 'FeeMeanNtv'],
    limit_per_asset=5
).parallel('assets').to_list()

# Parallelize on 'assets' and 'metrics' columns
data = client.get_asset_metrics(
    assets=['btc', 'eth'],
    metrics=['PriceUSD', 'FeeMeanNtv'],
    limit_per_asset=5
).parallel(['assets', 'metrics']).to_list()

By Time or (Block) Height Increment

# Parallelize by time increment

from datetime import timedelta
from dateutil.relative_delta import relativedelta

# Parallelize request in 1 month chunks
data = client.get_asset_metrics(
    assets=['btc', 'eth'],
    metrics=['ReferenceRateUSD'],
    start_time='2024-01-01',
    end_time='2024-08-01',
    frequency='1h'
).parallel(time_increment=relativedelta(months=1)).to_list()

# Parallelize request in 1 day chunks
data = client.get_asset_metrics(
    assets=['btc', 'eth'],
    metrics=['ReferenceRateUSD'],
    start_time='2024-01-01',
    end_time='2024-08-01',
    frequency='1h'
).parallel(time_increment=timedelta(days=1))

# Parallelize by 1000 blocks
data = client.get_asset_metrics(
    assets=['btc', 'eth'],
    metrics=['FeeMeanNtv'],
    start_height=0,
    end_height=100_000,
    frequency='1b'
).parallel(height_increment=1000)

Persisting Large Data Requests

Given that parallelization allows you to request large amounts of data, the methods for non-parallelized data may run slower. The export_to_json_files() and export_to_csv_files() allow you to save parallelized data in an organized way in your local directory.

### save data in local directory

data = client.get_asset_metrics(
    assets=['btc', 'eth'],
    metrics=['FeeMeanNtv'],
    start_height=0,
    end_height=100_000,
    frequency='1b'
).parallel(height_increment=1000).export_to_json_files()
PreviousHow To Migrate From Catalog to Catalog V2 and Reference DataNextDashboard Examples

Last updated 6 months ago

Was this helpful?

For more information, see: the .

Python API Client documentation