Coinbase Historical Downloader (`dccd.histo_dl.coinbase`)¶

Objects to download historical data from Coinbase exchange.

class FromCoinbase(path, crypto, span, fiat='USD', form='xlsx', tz='local')[source]¶

Bases: ImportDataCryptoCurrencies

Class to import crypto-currencies data from the Coinbase exchange.

Parameters:

pathstr: Root directory for data files.
cryptostr: Crypto-currency symbol, e.g. 'BTC'.
spanint or str: Candle interval in seconds (minimum 60) or a label such as 'hourly' or '1h'.
fiatstr, optional: Quote currency. Default is 'USD'. The pair is formatted with a hyphen separator (e.g. 'BTC' + 'USD' → 'BTC-USD').
formstr, optional: Legacy parameter — ignored. Storage is always Parquet via DataStore.
tzstr, optional: Timezone for date parsing: 'local' (default), 'UTC', or any IANA timezone name.

Attributes:

pairstr: Pair symbol, crypto-fiat (e.g. ‘BTC-USD’).
start, endint: Timestamp to starting and ending download data.
spanint: Number of seconds between observations.
full_pathstr: Directory managed by DataStore — {path}/coinbase/ohlc/{pair}/{span}/.

Methods

`import_data`([start, end])	Download data from Coinbase for specific time interval.
`save`([form, by_period])	Save `df` to disk via `DataStore`.
`get_data`([format])	Return the downloaded data.
`import_trades`([start, end])	Fetch individual trades for a time window.
`save_trades`([form, by_period])	Save `trades_df` via `DataStore`.
`import_orderbook`([depth])	Fetch the current order book snapshot at a given depth.
`save_orderbook`([form])	Save `orderbook_df` via `DataStore`.

See also

FromBinance, FromKraken, FromBybit, FromOKX

Notes

See Coinbase Exchange API documentation [1] for more details on parameters. This class uses the public market data endpoint which does not require authentication.

References

[1]

https://docs.cdp.coinbase.com/exchange/reference/exchangerestapi_getproductcandles

get_data(format='polars')¶

Return the downloaded data.

Parameters:

format{‘polars’, ‘pandas’}, optional: Output format. Default is ‘polars’.

Returns:

pl.DataFrame: Current data in the requested format.

import_data(start='last', end='now')[source]¶

Download data from Coinbase for specific time interval.

Parameters:

startint or str: Timestamp of the first observation of you want as int or date format ‘yyyy-mm-dd hh:mm:ss’ as string.
endint or str: Timestamp of the last observation of you want as int or date format ‘yyyy-mm-dd hh:mm:ss’ as string.

Returns:

datapl.DataFrame: Data sorted and cleaned in a data frame.

import_orderbook(depth=50)¶

Fetch the current order book snapshot at a given depth.

Downloads the bid/ask ladder from the exchange REST API, validates each level, and stores the result in orderbook_df. Use save_orderbook to persist to disk.

Parameters:

depthint, optional: Number of price levels to fetch per side (bids + asks), default 50. Maximum varies by exchange.

Returns:

ImportDataCryptoCurrencies: Returns self for method chaining.

Notes

Order book REST endpoints return a current snapshot only. Historical order book data is not available via public APIs.

import_trades(start=0, end='now')¶

Fetch individual trades for a time window.

Downloads executed trades from the exchange REST API, validates each record, and stores the result in trades_df. Use save_trades to persist to disk.

Parameters:

startint or str, optional: Start of the time window. Accepts a Unix timestamp (int), a date string 'yyyy-mm-dd hh:mm:ss', or 0 (default, meaning “as far back as the API allows”).
endint or str, optional: End of the time window. 'now' (default) resolves to the current UTC time. Accepts a Unix timestamp or date string.

Returns:

ImportDataCryptoCurrencies: Returns self for method chaining.

Notes

Exchanges vary in how much history they expose:

Binance and Kraken provide full paginated history.
OKX exposes several months of history via cursor pagination.
Bybit returns the ~1 000 most recent trades regardless of start/end.
Coinbase returns up to 100 recent trades (cursor-based, no deep history).

save(form='parquet', by_period='Y')¶

Save df to disk via DataStore.

Data is always written as Parquet, grouped annually. The form and by_period parameters are accepted for backward compatibility but ignored — storage format and period granularity are managed by DataStore.

Parameters:

formstr, optional: Ignored. Kept for backward-compatibility.
by_periodstr, optional: Ignored. Kept for backward-compatibility.

save_orderbook(form='parquet')¶

Save orderbook_df via DataStore.

The snapshot is timestamped with the current UTC time and written into the daily orderbook file. The form parameter is accepted for backward compatibility but ignored.

Parameters:

formstr, optional: Ignored. Kept for backward-compatibility.

Returns:

ImportDataCryptoCurrencies: Returns self to allow method chaining.

save_trades(form='parquet', by_period='D')¶

Save trades_df via DataStore.

Trades are grouped by calendar day and written as Parquet. The form and by_period parameters are accepted for backward compatibility but ignored.

Parameters:

formstr, optional: Ignored. Kept for backward-compatibility.
by_periodstr, optional: Ignored. Kept for backward-compatibility.

Returns:

ImportDataCryptoCurrencies: Returns self to allow method chaining.

FromCoinbase downloads OHLCV candles, recent trades, and order book snapshots from the Coinbase Exchange public REST API. No authentication is required.

Exchange specifics¶

Pair format	Hyphen separator: `'BTC'` + `'USD'` → `'BTC-USD'`.
Candles per request	300 (endpoint: `GET /products/{pair}/candles`).
Minimum span	60 seconds (1 minute).
Trade history	Recent trades only — up to the last 100 trades. The Coinbase public API does not support deep historical pagination.
Order book depth	Level 2 snapshot (aggregated by price level, no per-order count).
Authentication	Not required for public data.

Quick example¶

from dccd.histo_dl import FromCoinbase

obj = FromCoinbase('/data/crypto/', 'BTC', span=3600, fiat='USD')

# Full OHLCV history (pagination supported)
obj.import_data(start='2024-01-01 00:00:00', end='2024-12-31 00:00:00')
obj.save(form='parquet')

# Only recent trades are available (≤ 100)
obj.import_trades(start='last', end='now')
obj.save_trades(form='parquet')

Coinbase Historical Downloader (dccd.histo_dl.coinbase)¶

Exchange specifics¶

Quick example¶

Coinbase Historical Downloader (`dccd.histo_dl.coinbase`)¶