Examples¶
This section contains example scripts found in the examples directory. The examples in this repository are meant to be simple template scripts, mainly showing how to export large amounts of structured data from the API, and focus on getting to specific outcomes using specific functionality of the API Client. Although they are not meant to be for data exploration, they can be configured to other use-cases. For example, metrics_exporter_json.py by default exports two metrics for btc, but if your desired export had other assets like ada, eth, or algo and
wanted to query ReferenceRateUSD as well, it would be as simple as changing the values for ASSETS_TO_EXPORT and
METRICS.
If this is your first time using the API Client, we recommend you follow this walkthrough. To explore the data for broader, data-specific use-case, see our Tutorials. To learn more about the data itself, see the Product Documentation for general knowledge about Coin Metrics data.
Example Types¶
The types of examples below are divided into two groups:
"Current" examples represent the most up-to-date, recommended ways of using the Python API Client.
"Legacy" examples represent older usage patterns of the Python API Client, which generally work but may be suboptimal. They were created before major optimization updates (Parallelization, DataFrames, etc.) to the Python API Client. Use them at your own risk.
Current Examples
- Notebooks - These examples are Python Jupyter notebooks that provide runnable examples showing how to use the Python API examples for data analysis/ data exploration. See Tutorials for a more complete set of cases.
- Streaming data - These examples show how to CoinMetrics websocket endpoints
- Parallel Exports - These examples export data using parallelization. We strongly recommend using these over the legacy data export scripts below.
Legacy Examples
- Jsonl exporter - These examples export data to one or multiple json line files. This is a useful format for storing and working with arbitrarily large amounts of data compared to standard JSON. In order to parse normal JSON files you need to load the entire file into memory, which may be unfeasible if the file is a GB+ in size, but json line files can be read, appended to, or processed line by line and scale as long as your machine has memory.
- CSV exporter - These examples export data to csv. CSV files are not as useful for large files or nested data structures, but can be easier to work with for data analysis tasks and for use by non-programmers. with the API client. Websockets are useful for getting real time data as quick and performant as possible, but can require additional overhead to use compared to HTTP endpoints
- Flat files exporter - These examples leverage our flat files server, which is best used to download large amounts of historical data for backfilling or data analysis purposes.
Example Directory (Current)¶
| Route | Description | Example Type |
|---|---|---|
| general api usage #2 | Notebook that shows some of the more advanced features offered by the API, and features a case study of the BTC mining crackdown in China | notebook |
| community api usage | Notebook that gives an overview of the features offered for free as part of the Community API | notebook |
| /timeseries/market-quotes | Notebook that shows how to use Python Pandas to process data related to btc options offered by deribit | notebook |
| /timeseries-stream/asset-metrics | Example script showing how to interact with streaming websockets endpoint for btc and eth ReferenceRates | streaming data |
| /timeseries-stream/market-candles | Example script showing how to interact with streaming market candles from a coinbase btc-usd market | streaming data |
| /timeseries-stream/market-orderbooks | Example script showing how to interact with streaming market orderbooks for a binance btc-usdt pair | streaming data |
| /timeseries-stream/market-quotes | Example script showing how to interact with streaming market quotes for all markets | streaming data |
| /timeseries-stream/market-trades | Example script showing how to interact with streaming market trades for a coinbase btc-usd spot market | streaming data |
| /timeseries/asset-metrics | Example script showing how to export metrics in parallel at high frequency | parallel exports |
| /timeseries/market-candles | Example script showing how to export candles using parallelization | parallel exports |
| /timeseries/market-candles | Example script showing how parallelization works, using the candles CSV export as a case-study. | parallel exports |
| /timeseries/market-orderbooks | Example script showing how to export market orderbook data, which is usually data intensive. | parallel exports |
| /timeseries/market-orderbooks | Example script showing how to export market orderbook data, aggregated by day. | parallel exports |
| /timeseries/market-trades | Example script showing how to export market trades data. | parallel exports |
Example Directory (Legacy)¶
| Route | Description | Example Type |
|---|---|---|
| /timeseries/asset-metrics | Function to export all metrics for a given asset, in this case 'btc' | jsonl exporter |
| /timeseries/asset-metrics | Function to export end of day metrics for a given asset, in this case 'btc' | csv exporter |
| /timeseries/asset-metrics | Function to export reference rates for assets above a provided market cap | jsonl exporter |
| /timeseries/asset-metrics | Generic asset exporter for 'btc', easily adjustable to add other assets or metrics | jsonl exporter |
| /timeseries/asset-metrics | Generic reference rates exporter, can add other metrics or assets as needed | jsonl exporter |
| /timeseries/asset-pair-metrics | Exports several asset-pair metrics for eth, btc, and ada to usd pairs, extensible to all asset pair metrics | jsonl exporter |
| /timeseries/institution-metrics | Exports 1d metrics for grayscale | jsonl exporter |
| /timeseries/exchange-metrics | Exports all 1d exchange metrics for all exchanges, can be reduced in scope | jsonl exporter |
| /timeseries/market-contract-prices | Exports market contract prices data for first 100 ETH based options contracts, can be increased in scope to export much more | jsonl exporter |
| /timeseries/market-greeks | Exports market greeks data for first 100 ETH based options contracts, can be increased in scope to export much more | jsonl exporter |
| /timeseries/market-liquidations | Exports market liquidations for ETH based contracts on FTX, can be increased in scope to export much more | jsonl exporter |
| /timeseries/market-openinterest | Exports market open interest for BTC based futures contracts, can be increased in scope to export much more | jsonl exporter |
| /timeseries/exchange-asset-metrics | Generic exchange asset metrics exporter, exports basis_annualized_90d_exp for binance-btc in this case | jsonl exporter |
| /timeseries/market-orderbooks | Exports market orderbooks for btc/usd pairs on Binance, can be used for any other purpose | jsonl exporter |
| /timeseries/market-candles | Generic script to export market candles for btc/usd pairs, extensible to all | jsonl exporter |
| /timeseries/market-funding-rates | Script to export market funding rates for btc/usd pairs, extensible to all | jsonl exporter |
| /timeseries/index-levels | Script to export index levels for CMBIBTC and CMBIETH, works for whole CM index universe | jsonl exporter |
| /timeseries/market-implied-volatility | Script that exports all market implied volatility measures available, can be reduced in scope | jsonl exporter |
| /timeseries/market-orderbooks | Script to export all market orderbooks, can be reduced in scope | csv exporter |
| /timeseries/market-quotes | Script to export all market quotes for options, can be reduced in scope or made to include futures and spot quotes as well | jsonl exporter |
| /timeseries/market-trades | Script to export futures trades over a subset of exchanges and future markets, easily modified | csv exporter |
| /timeseries/market-trades | Script to export market trades for btc/usd market for futures and spot trades across all exchanges | jsonl exporter |
| /timeseries/market-metrics | Script to export market metrics for all binance btc pairs at a frequency 1d | jsonl exporter |
| /timeseries/pair-candles | Script to export asset pair candles for all BTC spot and future markets at a 1h frequency | jsonl exporter |
| /market-candles-spot | Script that shows how to bulk downlaod market candles flat files data | flat files exporter |
| /market-quotes-future | Script to show how to bulk download market quotes for futures markets for a full month | flat files exporter |
| /market-trades-spot | Script to show to bulk download market trades spot data for a full month | flat files exporter |
| /market-quotes-spot | Script to show to bulk download market quotes spot data for a full month | flat files exporter |
| general api usage | Notebook that gives a brief overview of the features offered by the CoinMetrics API/ API Client | notebook |