Getting Started with CoinAPI's S3-Compatible File System

Downloading large amounts of historical crypto market data through a traditional REST API is not always practical. If you need months or years of trades, quotes, OHLCV, or full order book data, bulk files are usually a better fit.

CoinAPI’s Flat Files S3 API provides S3-compatible access to historical cryptocurrency market data stored as compressed CSV files.

You can browse available datasets, select the exchanges and dates you need, and download the files using familiar tools such as AWS CLI, Python, AWS SDKs, or other S3-compatible clients.

This guide explains what data is available, how files are organized, how authentication works, and how to start downloading CoinAPI Flat Files.

What Is CoinAPI Flat Files S3 API?

CoinAPI Flat Files S3 API is designed for bulk access to historical cryptocurrency market data.

Instead of requesting individual records or small time ranges through REST endpoints, you work directly with pre-generated historical data files.

The API follows an Amazon S3-compatible structure and is focused on retrieval workflows:

• browse available historical files
• inspect available objects
• download the files you need
• automate large historical data jobs

It is not a general-purpose cloud storage service. Customers use it to access CoinAPI historical market data rather than upload, modify, or delete their own objects.

This approach is particularly useful when working with large datasets for backtesting, quantitative research, machine learning, market surveillance, and data warehousing.

What Data Is Available?

CoinAPI Flat Files include several different cryptocurrency market datasets.

Trades

Trades contain individual transaction events reported by cryptocurrency exchanges.

Records can include information such as:

• exchange timestamp
• CoinAPI timestamp
• symbol
• trade ID
• price
• size
• taker side

Trade data is useful for transaction-level research, execution analysis, volume analysis, backtesting, and quantitative modeling.

The corresponding S3 path prefix is:

T-TRADES

Quotes

Quotes represent top-of-book market information, including the best available bid and ask.

They can be used to analyze:

• bid and ask prices
• bid and ask sizes
• spreads
• top-of-book liquidity
• changes in quoting conditions

The corresponding S3 path prefix is:

T-QUOTES

Limit Book Full

Full Limit Order Book data captures updates to the order book from the source.

Depending on what information the underlying exchange exposes, the dataset can contain Level 2 or Level 3 information.

Level 2 represents liquidity aggregated by price level.

Level 3 provides individual order-level information where the source exchange exposes market-by-order data and order identifiers.

This dataset is particularly useful for:

• full order book reconstruction
• historical market replay
• market microstructure research
• execution simulations
• liquidity analysis
• slippage modeling
• market-making research

The corresponding path prefix is:

T-LIMITBOOK_FULL

Limit Book Snapshot 50

limitbook_snapshot_50 provides snapshots of up to the top 50 bid and ask levels of the order book.

Unlike Full Limit Order Book data, which is intended for detailed reconstruction using book updates, snapshots provide the state of the market at particular points in time.

This makes them useful when you need significant market depth without processing every individual order book update.

Limit Book Depth Bands

limitbook_depth_bands provides a different view of liquidity.

Instead of representing individual price levels, it describes cumulative liquidity around the midpoint using predefined basis-point bands.

This can be useful for studying:

• liquidity concentration
• market depth
• potential price impact
• execution capacity
• changes in liquidity around the midpoint

OHLCV Active Consolidated

OHLCV data aggregates transactions into standard market-data candles containing:

• Open
• High
• Low
• Close
• Volume

CoinAPI provides multiple aggregation periods, including commonly used intervals such as:

1SEC

1MIN

1HRS

1DAY

Available periods can range from one second to one month.

OHLCV records are generated for periods where trading activity occurred, making the dataset useful for charting, historical analysis, strategy research, and backtesting that does not require individual tick-level events.

The corresponding S3 path family uses:

T-OHLCV_ACTIVE_CONSOLIDATED

CoinAPI Flat File Format

CoinAPI Flat Files are delivered as CSV files compressed with gzip:

.csv.gz

This combination is useful for large historical datasets because CSV is widely supported while gzip significantly reduces the amount of data that needs to be transferred and stored.

Files can be processed using common data tools and programming environments, including:

• Python
• Pandas
• Spark
• AWS CLI
• Boto3
• AWS SDKs
• S3-compatible clients
• data warehouses and ETL pipelines

You can either decompress files before processing or use software capable of reading gzip-compressed CSV directly.

For example, Pandas can read .csv.gz files without manually extracting them first.

Endpoint and Authentication

The CoinAPI Flat Files S3 endpoint is:

https://s3.flatfiles.coinapi.io

To connect, you need a CoinAPI account, a Flat Files API key, and sufficient Usage Credits.

For S3-compatible clients, use the following configuration:

Your CoinAPI API key acts as the S3 Access Key ID.

The value:

coinapi

is used as the Secret Access Key.

Use HTTPS for production connections so credentials and downloaded data are transmitted securely.

How CoinAPI Flat Files Are Organized

Files are organized using predictable S3-style paths.

The structure makes it possible to narrow a request by characteristics such as:

• dataset
• date
• exchange
• symbol
• OHLCV period

For example, trade data can follow a structure such as:

1s3://coinapi/T-TRADES/D-YYYYMMDD/E-BINANCE/

Quotes:

1s3://coinapi/T-QUOTES/D-YYYYMMDD/E-BINANCE/

And OHLCV:

1s3://coinapi/T-OHLCV_ACTIVE_CONSOLIDATED/D-YYYYMMDD/E-BINANCE/

Inside an OHLCV exchange/date location, different aggregation periods can be represented separately:

1T-OHLCV_ACTIVE_CONSOLIDATED/
2└── D-YYYYMMDD/
3    └── E-BINANCE/
4        ├── TP-1SEC.csv.gz
5        ├── TP-1MIN.csv.gz
6        ├── TP-1HRS.csv.gz
7        └── TP-1DAY.csv.gz

This hierarchy is important when working with large datasets.

Instead of downloading everything and filtering it afterward, you can identify the specific dataset, exchange, date, and period you need before downloading.

Daily and Hourly Historical Partitions

Depending on the dataset and when it was published, you may encounter both daily and hourly historical partitions.

Legacy data can use daily date partitions such as:

D-YYYYMMDD

For new Trades, Quotes, and Full Limit Order Book data published from June 9, 2026, CoinAPI uses hourly partitions:

D-YYYYMMDDHH

For example:

D-2026083114

represents the hour beginning at 14:00 UTC on August 31, 2026.

The hourly structure makes it easier to retrieve smaller portions of high-volume datasets without downloading an entire UTC day.

Older historical files remain accessible using their existing daily structure.

Supported S3 Operations

CoinAPI Flat Files S3 API implements the parts of the Amazon S3 interface required for historical data retrieval.

The main workflow is:

List → Inspect → Download

Supported retrieval operations include listing available files, downloading objects with GET, and checking object metadata with HEAD where supported.

The service is not intended to be a complete replacement for Amazon S3.

You do not use CoinAPI Flat Files to upload your own data or manage a general-purpose storage bucket.

Its purpose is to make CoinAPI historical datasets accessible through familiar S3-compatible tooling.

Using CoinAPI Flat Files With AWS CLI

One of the easiest ways to browse Flat Files is with AWS CLI.

After installing AWS CLI, configure your credentials using:

• Access Key ID: your CoinAPI Flat Files API key
• Secret Access Key: coinapi
• Region: us-east-1

Because CoinAPI uses its own S3-compatible endpoint, include the endpoint URL in your commands.

For example, to list Binance Trades for January 1, 2024:

1aws --endpoint-url https://s3.flatfiles.coinapi.io \
2  s3 ls s3://coinapi/T-TRADES/D-20240101/E-BINANCE/

The response will show the objects available under that path.

Once you know the object you need, you can download it using the standard AWS CLI S3 commands while continuing to specify the CoinAPI endpoint.

This makes AWS CLI particularly useful for quickly exploring the Flat Files structure before building an automated download pipeline.

Using CoinAPI Flat Files With Python and Boto3

For automated workflows, you can use Boto3, the AWS SDK for Python.

First create an S3 client configured for CoinAPI:

1import boto3
2
3s3 = boto3.client(
4    "s3",
5    endpoint_url="https://s3.flatfiles.coinapi.io",
6    aws_access_key_id="YOUR_COINAPI_KEY",
7    aws_secret_access_key="coinapi",
8    region_name="us-east-1"
9)

You can then list available files under a specific prefix:

1response = s3.list_objects_v2(
2    Bucket="coinapi",
3    Prefix="T-TRADES/D-20240101/E-BINANCE/"
4)
5
6for item in response.get("Contents", []):
7    print(item["Key"])

The same client can then be used to download the objects you need.

This approach is useful for larger workflows where you want to automate retrieval across multiple:

• dates
• exchanges
• symbols
• datasets

For example, a research pipeline could iterate through a historical date range, retrieve the required Binance files, process each .csv.gz file, and write the resulting data into a local database or analytical environment.

Other Compatible Tools

You are not limited to AWS CLI or Python.

Because the service uses an S3-compatible interface, it can work with a range of tools that allow you to configure a custom S3 endpoint.

Examples include:

• AWS SDKs
• Boto3
• S3 Browser
• S3-compatible command-line clients
• custom ETL applications
• data engineering tools with configurable S3 connections

The key requirement is the ability to specify the CoinAPI endpoint and credentials rather than connecting directly to Amazon's standard S3 endpoint.

Usage Credits and Billing

Accessing CoinAPI Flat Files requires Usage Credits (UC).

Users need:

1. a CoinAPI account;
2. a Flat Files API key;
3. sufficient Usage Credits in the Customer Portal.

Flat Files pricing depends on the dataset and the amount of data accessed.

Different datasets have different usage rates. For example, Full Limit Order Book data, Trades, Quotes, and OHLCV are priced independently because their typical file sizes and data volumes differ significantly.

Pricing can also use volume tiers, so the effective rate may decrease as more data is accessed within the applicable tier.

This means that before downloading a very large dataset, it is useful to determine:

• which dataset you need;
• the exchange or exchanges;
• the required symbols;
• the historical period;
• the estimated data size.

This helps estimate Usage Credit consumption before starting a large bulk download.

Error Handling

CoinAPI uses S3-compatible responses where possible.

In general, treat non-2xx responses as unsuccessful unless the specific operation documents otherwise.

Error responses can include an S3-compatible XML body describing the issue.

Typical causes can include:

• malformed requests
• incorrect credentials
• insufficient access or Usage Credits
• incorrect object paths
• objects that do not exist

For example, a 403 response can indicate an authentication, authorization, or account-related problem, while a 404 generally means that the requested object could not be found.

When troubleshooting, first verify your API key, endpoint, bucket, object prefix, and available Usage Credits.

Best Practices for Working With Large Historical Datasets

Flat Files can contain substantial amounts of market data, particularly when working with Trades or Full Limit Order Book datasets across long historical periods.

A few practices can make the process much more efficient.

1. Download only what you need

Avoid downloading an entire dataset if your research requires only one exchange, instrument, or time range.

Use the S3 path hierarchy to narrow the dataset before downloading.

2. Choose the right dataset

If your strategy needs one-minute candles, downloading Full Limit Order Book data creates unnecessary cost and processing overhead.

Likewise, OHLCV data will not be sufficient if you need to reconstruct historical market depth.

Match the dataset to the research question.

3. Keep files compressed where possible

.csv.gz files reduce transfer and storage requirements.

Many analytical tools can read gzip-compressed CSV files directly, so decompression is not always necessary.

4. Automate large jobs

AWS CLI is convenient for exploration and smaller downloads.

For hundreds or thousands of files, use an SDK such as Boto3 to automate listing, downloading, retries, and processing.

5. Use HTTPS

Use:

https://s3.flatfiles.coinapi.io

for production access.

Do not expose API credentials through unsecured connections or hard-code them into publicly accessible scripts and repositories.

6. Estimate usage before very large downloads

Full-depth order book datasets can become extremely large.

Check the required scope and expected file size before downloading months or years of high-frequency data.

This helps avoid downloading unnecessary data and makes Usage Credit requirements easier to predict.

REST API or Flat Files?

Both provide access to historical cryptocurrency market data, but they solve different problems.

Use REST API when you need relatively targeted queries, application-level access, current information, or smaller historical requests.

Use Flat Files S3 API when you need to download and process historical data in bulk.

For example:

The larger and more granular the historical dataset becomes, the more useful bulk Flat Files access becomes.

Start Using CoinAPI Flat Files

CoinAPI Flat Files S3 API provides a practical way to work with large-scale historical cryptocurrency market data without retrieving millions of individual records through a traditional API.

You get compressed .csv.gz datasets, predictable S3-style paths, and compatibility with familiar tools such as AWS CLI, Boto3, and other S3 clients.

The basic workflow is straightforward:

Choose your dataset

→ identify the date, exchange, and market you need

→ list the available objects

→ download the required files

→ process them in your own infrastructure.

For small queries, REST may still be the easiest choice.

For large historical datasets, full order book reconstruction, quantitative research, backtesting, or machine learning, Flat Files provide an infrastructure designed for bulk data access.

Explore the CoinAPI Flat Files documentation or access the Customer Portal to configure your API key, Usage Credits, and historical data workflow.

Related Topics

• DEX vs CEX Data Quality: What Institutions Need to Know
• Options Market Structure: How Crypto Options Data Powers Forecasting and Prediction Systems
• Best Crypto Data Platforms in 2026
• 10 Best Crypto Exchange APIs for Developers and Traders in 2025
• CoinAPI MCP API Upgrade
• Building Reinforcement Learning-based (RL) crypto trading bot with CoinAPI