Trades

Overview

The Trades data type provides information about individual transactions that have occurred on an exchange for a specific trading pair. This data is crucial for understanding market activity, price movements, and trading volumes.

File Organization

Trade data is organized in the S3 buckets using the structure below. Paths are identical in coinapi and coinapi-daily-tail; the bucket and partition date determine which dataset you are reading.

T-TRADES/
└── D-{YYYYMMDD | YYYYMMDDHH}/
    └── E-[EXCHANGE]/
        └── IDDI-[IDENTIFIER]+SC-[COINAPI_SYMBOL_ID]+S-[EXCHANGE_SYMBOL].csv.gz

Examples:

T-TRADES/D-20230701/E-BINANCE/IDDI-1234+SC-BINANCE_SPOT_ETH_USDT+S-ETH-USDT.csv.gz

T-TRADES/D-2026011722/E-COINBASE/IDDI-6002426+SC-COINBASE_SPOT_AVAX_USD+S-AVAX__002DUSD.csv.gz

Where:

• T-TRADES: Indicates the data type (Trades)
• D-{YYYYMMDD | YYYYMMDDHH} defines the time partition:
  • YYYYMMDD in coinapi → legacy daily partitions published before 2026-06-09
  • YYYYMMDD in coinapi-daily-tail → previous day only, retained 24 hours
  • YYYYMMDDHH in coinapi → hourly partitions for data published on or after 2026-06-09
• E-[EXCHANGE]: Exchange name
• IDDI-[IDENTIFIER]: CoinAPI's internal identifier
• SC-[COINAPI_SYMBOL_ID]: CoinAPI's symbol identifier
• S-[EXCHANGE_SYMBOL]: The symbol as identified by the exchange

File Format

Files are in CSV format, compressed with gzip. Each row represents a single trade.

Data Fields

Example Data

time_exchange;time_coinapi;guid;price;base_amount;taker_side;id_exch_guid;id_exch_int_inc;order_id_maker;order_id_taker
2025-02-14T13:30:03.5851480;2025-02-14T13:30:48.4535346;723787cc-c2c2-42e0-9c17-47533847600f;0.00000732;180.35;BUY;;;;
2025-02-14T12:50:00.6090960;2025-02-14T13:30:48.4535346;c6f313f5-cef6-4974-8397-f9a472b3a169;0.00000723;1410.59;SELL;;;;
2025-02-14T12:35:53.4036209;2025-02-14T13:30:48.4535346;9c68a7ee-7b5a-4c81-82bb-dbb8976b917a;0.00000722;462.49;SELL;;;;
2025-02-14T12:09:06.7816889;2025-02-14T13:30:48.4535346;0cf1ad21-9a43-459d-bede-d6fd9b7a4a14;0.00000728;963.14;BUY;;;;
2025-02-14T12:02:12.9110560;2025-02-14T13:30:48.4535346;a568765e-2f67-4b38-9b70-d0a677653f52;0.00000729;676.59;SELL;;;;

Data Collection Process

1. We maintain real-time connections to supported exchanges.
2. As trades occur, we capture the trade information provided by the exchange.
3. The data is processed, normalized, and stored in our system.
4. Data is uploaded to the coinapi bucket as hourly partitions for data published on or after 2026-06-09. Legacy daily partitions published before that date remain in coinapi. The coinapi-daily-tail bucket receives daily files for the previous day only and retains them for 24 hours.

Taker Side Explanation

• BUY: The exchange reported that the trade aggressor was buying.
• SELL: The exchange reported that the trade aggressor was selling.
• BUY_ESTIMATED: The exchange didn't report the aggressor; we estimated it was more likely a buy.
• SELL_ESTIMATED: The exchange didn't report the aggressor; we estimated it was more likely a sell.
• UNKNOWN: The exchange didn't report the aggressor, and we couldn't confidently estimate it.

Corner Cases and Special Considerations

1. Time Discrepancies: There might be slight differences between time_exchange and time_coinapi due to network latency or exchange API delays.
2. Estimated Taker Side: When the exchange doesn't provide the taker side, we use our algorithms to estimate it. These estimations are based on order book data and may not always be 100% accurate.
3. Trade Reversals: In rare cases, exchanges might reverse or cancel trades. These are typically not reflected in our data, so be aware that very recent trade data might be subject to change on the exchange itself.

Usage Tips

1. Use the guid field to uniquely identify trades and avoid double-counting when processing multiple files.
2. The base_amount field represents the amount in the base currency of the trading pair (e.g., BTC in BTC/USDT).
3. To calculate the total value of a trade in the quote currency, multiply price by base_amount.
4. When analyzing trade direction, consider using only BUY and SELL categories for the most accurate data, or include estimated values if you need more comprehensive data.

For any questions or issues with the Trades data, please contact our support team.