# Coinbase Exchange

{% hint style="info" %}
The market data is the property of Coinbase, Inc as applicable. All rights reserved, or otherwise licensed by Coinbase, Inc.

See [Coinbase market data license restrictions](https://docs.tardis.dev/legal/terms-of-service#id-23.-coinbase-market-data-license-restrictions) that apply.
{% endhint %}

Coinbase Exchange historical data for **all its currency pairs** is available since **2019-03-30**.

{% embed url="<https://api.tardis.dev/v1/exchanges/coinbase>" %}
See Coinbase Exchange historical data coverage: available symbols, channels, date ranges and incidents
{% endembed %}

### Downloadable **CSV** files

Historical CSV datasets for the first day of each month are **available to download without API key**. See [downloadable CSV files documentation](https://docs.tardis.dev/downloadable-csv-files/overview).

| data type             | symbol  | date       |                                                                                                          |
| --------------------- | ------- | ---------- | -------------------------------------------------------------------------------------------------------- |
| incremental\_book\_L2 | BTC-USD | 2019-07-01 | [Download sample](https://datasets.tardis.dev/v1/coinbase/incremental_book_L2/2019/07/01/BTC-USD.csv.gz) |
| trades                | BTC-USD | 2019-07-01 | [Download sample](https://datasets.tardis.dev/v1/coinbase/trades/2019/07/01/BTC-USD.csv.gz)              |
| quotes                | BTC-USD | 2019-07-01 | [Download sample](https://datasets.tardis.dev/v1/coinbase/quotes/2019/07/01/BTC-USD.csv.gz)              |

### API Access and data format

Historical data format is the same as provided by real-time Coinbase Exchange WebSocket API with addition of local timestamps. If you'd like to work with **normalized data format** instead (same format for each exchange) see [downloadable CSV files](https://docs.tardis.dev/downloadable-csv-files/overview) or official [client libs](https://docs.tardis.dev/api/quickstart) that perform data normalization client-side.

{% tabs %}
{% tab title="Python" %}

```python
# pip install tardis-dev
import asyncio
from tardis_dev import Channel, replay

async def main():
    async for local_timestamp, message in replay(
        exchange="coinbase",
        from_date="2024-01-01",
        to_date="2024-01-02",
        filters=[Channel(name="l2update", symbols=["BTC-USD"])],
        api_key="YOUR_API_KEY",
    ):
        # messages as provided by Coinbase Exchange real-time stream
        print(message)

asyncio.run(main())
```

See [Python client docs](https://docs.tardis.dev/python-client/quickstart).
{% endtab %}

{% tab title="Node.js" %}

```javascript
// npm install tardis-dev
import { replay } from 'tardis-dev';

const messages = replay({
  exchange: 'coinbase',
  from: '2024-01-01',
  to: '2024-01-02',
  filters: [{ channel: 'l2update', symbols: ['BTC-USD'] }],
  apiKey: 'YOUR_API_KEY'
});

// messages as provided by Coinbase Exchange real-time stream
for await (const { localTimestamp, message } of messages) {
  console.log(localTimestamp, message);
}
```

See [Node.js client docs](https://docs.tardis.dev/node-client/quickstart).
{% endtab %}

{% tab title="cURL & HTTP API" %}

```bash
curl --compressed -g 'https://api.tardis.dev/v1/data-feeds/coinbase?from=2024-01-01&filters=[{"channel":"l2update","symbols":["BTC-USD"]}]&offset=0'
```

{% embed url="<https://api.tardis.dev/v1/data-feeds/coinbase?from=2024-01-01&filters=[{%22channel%22:%22l2update%22,%22symbols%22:[%22BTC-USD%22]}]&offset=0>" %}
Example API response for Coinbase Exchange historical market data request
{% endembed %}

See [HTTP API docs](https://docs.tardis.dev/api/http-api-reference).
{% endtab %}

{% tab title="cURL & tardis-machine" %}

```bash
curl -g 'localhost:8000/replay?options={"exchange":"coinbase","filters":[{"channel":"l2update","symbols":["BTC-USD"]}],"from":"2024-01-01","to":"2024-01-02"}'
```

[Tardis-machine](https://docs.tardis.dev/tardis-machine/quickstart) is a locally runnable server that exposes API allowing efficiently requesting historical market data for whole time periods in contrast to [HTTP API](https://docs.tardis.dev/api/http-api-reference) that provides data only in minute by minute slices.

See [tardis-machine](https://docs.tardis.dev/tardis-machine/quickstart) docs.
{% endtab %}
{% endtabs %}

### Captured real-time channels

{% embed url="<https://docs.cdp.coinbase.com/exchange/websocket-feed/overview>" %}
See Coinbase Exchange WebSocket API docs providing documentation for each captured channel's format
{% endembed %}

{% hint style="info" %}
Click any channel below to see [HTTP API](https://docs.tardis.dev/api/http-api-reference#data-feeds-exchange) response with historical data recorded for it.
{% endhint %}

* [match](https://api.tardis.dev/v1/data-feeds/coinbase?from=2024-01-01\&filters=\[{%22channel%22:%22match%22}]) Trade match events from the matches channel
* [l2update](https://api.tardis.dev/v1/data-feeds/coinbase?from=2024-01-01\&filters=\[{%22channel%22:%22l2update%22}]) Level 2 order book updates
* [snapshot](https://api.tardis.dev/v1/data-feeds/coinbase?from=2024-01-01\&filters=\[{%22channel%22:%22snapshot%22}]) Level 2 order book snapshots
* [ticker](https://api.tardis.dev/v1/data-feeds/coinbase?from=2024-01-01\&filters=\[{%22channel%22:%22ticker%22}]) Ticker updates with last trade and best bid and ask
* [subscriptions](https://api.tardis.dev/v1/data-feeds/coinbase?from=2024-01-01\&filters=\[{%22channel%22:%22subscriptions%22}]) Subscription acknowledgements stream
* [received](https://api.tardis.dev/v1/data-feeds/coinbase?from=2024-01-01\&filters=\[{%22channel%22:%22received%22}]) Order received events from the full channel
* [open](https://api.tardis.dev/v1/data-feeds/coinbase?from=2024-01-01\&filters=\[{%22channel%22:%22open%22}]) Order open events from the full channel
* [done](https://api.tardis.dev/v1/data-feeds/coinbase?from=2024-01-01\&filters=\[{%22channel%22:%22done%22}]) Order done and cancel events from the full channel
* [change](https://api.tardis.dev/v1/data-feeds/coinbase?from=2024-01-01\&filters=\[{%22channel%22:%22change%22}]) Order change events from the full channel
* [last\_match](https://api.tardis.dev/v1/data-feeds/coinbase?from=2024-01-01\&filters=\[{%22channel%22:%22last_match%22}]) Most recent trade included with ticker updates
* [full\_snapshot](https://api.tardis.dev/v1/data-feeds/coinbase?from=2024-01-01\&filters=\[{%22channel%22:%22full_snapshot%22,%22symbols%22:\[%22BTC-USD%22]}]) — generated channel Generated full order book L3 snapshots stream. Coinbase full channel does not provide initial snapshots, so snapshots are fetched from REST API and emitted as `"type":"full_snapshot"` with `"generated":true`. This enables historical full (L3) order book reconstruction and sequence-overlap validation against websocket full updates (enabled since 2020-06-11).
* [rfq\_matches](https://api.tardis.dev/v1/data-feeds/coinbase?from=2024-01-01\&filters=\[{%22channel%22:%22rfq_matches%22}]) RFQ match events stream

### Market data collection details

[Market data collection infrastructure](https://docs.tardis.dev/faq/general#what-is-your-infrastructure-setup) for Coinbase Exchange is located in GCP europe-west2 region (London, UK).

Real-time market data is captured via **multiple WebSocket connections** to `wss://ws-direct.exchange.coinbase.com`.

{% hint style="info" %}
Coinbase Exchange servers are located in AWS us-east-1 region (N. Virginia, USA).
{% endhint %}