When developers and analysts first start using CoinAPI, one of the most common questions is:

"Should I use the Market Data API or the Flat Files API to get historical cryptocurrency data?"

Both give you access to cryptocurrency market data, but in very different ways.

This tutorial helps you make the right choice for your use case, whether you're building a trading app or training a machine learning model.

Rule of Thumb

Choosing between CoinAPI’s Market Data API and Flat Files is like choosing between:

• Market Data API = Live TV
• Flat Files API = Recorded Archives

→ Read the full comparison article: Flat Files vs Market Data API: Which One Should You Use A detailed breakdown of delivery models, performance, credit costs, and real-world use cases.

Key Differences at a Glance

When to Use the Market Data API

Use when:

• You need real-time quotes, trades, or order books
• You're building trading bots, arbitrage engines, or smart order routers
• You want to fetch specific historical data (symbol + time window)

When to Use the Flat Files API

Use when:

• You need large volumes of historical data
• You want to train ML models or test strategies across years
• You’re ingesting data into a warehouse or S3 bucket

Access & Delivery

Market Data API:

• ✅ REST – for on-demand queries
• ✅ WebSocket/FIX – for real-time streaming

Flat Files API:

• ✅ S3-compatible HTTP download
• Delivered daily by 06:00 UTC

How to retrieve data using Flat Files API: Tools You Can Use

You can retrieve flat files using several tools. The most beginner-friendly options are:

1. AWS CLI (Command Line Tool for All Platforms)

2. S3 Browser (Easy-to-use interface for Windows)

Let’s walk through both options step-by-step.

Option 1: Using AWS CLI (Command Line)

🔧 Step 1: Install AWS CLI

Run the following command in your terminal (Linux/macOS) or command prompt (Windows):

1pip install awscli

Make sure Python is installed on your system.

Step 2: Configure AWS CLI

Open a terminal or command prompt and run:

1aws configure

You’ll be asked to enter:

• AWS Access Key ID: 73034021-THIS-IS-SAMPLE-KEY
• AWS Secret Access Key: coinapi
• Default region name: us-east-1
• Default output format: (Just press Enter to skip)

Step 3: List Available Files (Buckets)

To see what files (buckets) are available, run:

1aws --endpoint-url <http://s3.flatfiles.coinapi.io> s3 ls s3://coinapi

Step 4: Download a File

Let’s say you want to download a historical trade file. Use:

1aws --endpoint-url <http://s3.flatfiles.coinapi.io> s3 cp s3://coinapi/T-LIMITBOOK_FULL/D-20220904/E-COINBASE/IDDI-27576+SC-COINBASE_SPOT_BTC_USD+S-BTC__002DUSD.csv.gz /local/path/
2

Replace /local/path/ with the folder on your computer where you want the file to be saved.

Tips for AWS CLI Users

• Make sure you're using the latest AWS CLI version.
• Large files are split into chunks (multipart). You can change the size limit in AWS CLI settings.
• Refer to AWS CLI docs for more configuration options.

Option 2: Using S3 Browser (Windows Only)

🪟 Step-by-Step Guide

1. Download and install S3 Browser from: 👉 https://s3browser.com
2. Open the app and go to: File → Add New Account
3. Enter your account info:
   • Account Name: CoinAPI Flat Files
   • Access Key ID: 73034021-THIS-IS-SAMPLE-KEY
   • Secret Access Key: coinapi
   • REST Endpoint: http://s3.flatfiles.coinapi.io
   • Connection: Choose HTTP or HTTPS
4. Click "Test Connection" to make sure it works.
5. Save and start browsing files on the left sidebar!

Best Practices for Retrieving Data

• Use Prefix Filters: Only request the specific data you need.
• Use HTTPS in production: Secure your data transfers.
• Download selectively: Use date ranges and symbols to minimize file size.
• Cache files locally: Avoid re-downloading the same data repeatedly.
• Monitor usage: Stay within your API limits.

Bonus: Use Python for Downloads

You can also use Python to download and load files:

Step 1: Download a file

1import boto3
2import os
3
4client = boto3.client('s3',
5                      region_name='us-east-1',
6                      endpoint_url='<https://s3.flatfiles.coinapi.io>',
7                      aws_access_key_id='YOUR_API_KEY',
8                      aws_secret_access_key='coinapi')
9
10file_key = 'T-TRADES/D-20250901/E-BINANCE/IDDI-138123+SC-BINANCE_SPOT_BTC_USDT+S-BTCUSDT.csv.gz'
11os.makedirs('downloads', exist_ok=True)
12client.download_file('bucket', file_key, f"downloads/{os.path.basename(file_key)}")
13
14

📊 Step 2: Load into Pandas

import pandas as pd

1df = pd.read_csv("downloads/IDDI-138123+SC-BINANCE_SPOT_BTC_USDT+S-BTCUSDT.csv.gz", compression='gzip')
2print(df.head())
3

Summary

Using CoinAPI’s Flat Files S3 API, you can easily get historical data for analysis, backtesting, or ML training. Start simple, and scale as you grow!