# Bitfinex Derivatives

Bitfinex exchange historical data for **all its derivative instruments** is available since **2019-09-14.**

{% embed url="<https://api.tardis.dev/v1/exchanges/bitfinex-derivatives>" %}
See Bitfinex Derivatives 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 | BTCF0-USTF0 | 2019-12-01 | [Download sample](https://datasets.tardis.dev/v1/bitfinex-derivatives/incremental_book_L2/2019/12/01/BTCF0-USTF0.csv.gz) |
| trades                | BTCF0-USTF0 | 2019-12-01 | [Download sample](https://datasets.tardis.dev/v1/bitfinex-derivatives/trades/2019/12/01/BTCF0-USTF0.csv.gz)              |
| derivative\_ticker    | BTCF0-USTF0 | 2019-12-01 | [Download sample](https://datasets.tardis.dev/v1/bitfinex-derivatives/derivative_ticker/2019/12/01/BTCF0-USTF0.csv.gz)   |

### API Access and data format

Historical data format is the same as provided by real-time Bitfinex WebSocket **v2** API with addition of local timestamps and **since 2020-05-27 also with addition of channel and symbol at the end of each message** which allows us providing filtering for the data server-side. 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="bitfinex-derivatives",
        from_date="2023-03-01",
        to_date="2023-03-02",
        filters=[Channel(name="book", symbols=["BTCF0:USTF0"])],
        api_key="YOUR_API_KEY",
    ):
        # messages as provided by Bitfinex 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: 'bitfinex-derivatives',
  from: '2023-03-01',
  to: '2023-03-02',
  filters: [{ channel: 'book', symbols: ['BTCF0:USTF0'] }],
  apiKey: 'YOUR_API_KEY'
});

// messages as provided by Bitfinex 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/bitfinex-derivatives?from=2023-03-01&filters=[{"channel":"book","symbols":["BTCF0:USTF0"]}]&offset=0'
```

{% embed url="<https://api.tardis.dev/v1/data-feeds/bitfinex-derivatives?from=2023-03-01&filters=[{%22channel%22:%22book%22,%22symbols%22:[%22BTCF0:USTF0%22]}]&offset=0>" %}
Example API response for Bitfinex Derivatives 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":"bitfinex-derivatives","filters":[{"channel":"book","symbols":["BTCF0:USTF0"]}],"from":"2023-03-01","to":"2023-03-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.bitfinex.com/v2/docs/ws-general>" %}
See Bitfinex 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 %}

* [trades](https://api.tardis.dev/v1/data-feeds/bitfinex-derivatives?from=2024-01-01\&filters=\[{%22channel%22:%22trades%22}]) Public trade executions stream
* [book](https://api.tardis.dev/v1/data-feeds/bitfinex-derivatives?from=2024-01-01\&filters=\[{%22channel%22:%22book%22}]) Order book snapshots and deltas (prec=P0, freq=F0, len=100) During data collection integrity of order book incremental updates is being **validated** using [sequence numbers](https://docs.bitfinex.com/v2/docs/ws-general#section-available-options) (SEQ\_ALL option) provided by real-time feed - in case of detecting missed message WebSocket connection is being restarted.
* [ticker](https://api.tardis.dev/v1/data-feeds/bitfinex-derivatives?from=2024-01-01\&filters=\[{%22channel%22:%22ticker%22}]) Derivative ticker updates with mark and funding related fields
* [liquidations](https://api.tardis.dev/v1/data-feeds/bitfinex-derivatives?from=2024-01-01\&filters=\[{%22channel%22:%22liquidations%22}]) Forced liquidation events stream
* [status](https://api.tardis.dev/v1/data-feeds/bitfinex-derivatives?from=2024-01-01\&filters=\[{%22channel%22:%22status%22}]) Instrument status and derivative market state updates
* [raw\_book](https://api.tardis.dev/v1/data-feeds/bitfinex-derivatives?from=2024-01-01\&filters=\[{%22channel%22:%22raw_book%22}]) Raw order book snapshots and deltas (prec=R0, freq=F0, len=100)

All data collection is performed with `TIMESTAMP` and `SEQ_ALL` config flags set.

{% hint style="info" %}
Since 2020-05-27 each collected Bitfinex real-time data message has appended channel and symbol at the end of array - this allows us providing data filtering via API. Before that date if filters are provided with API request, always all recorded, unfiltered data feed is being returned.
{% endhint %}

### Market data collection details

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

Real-time market data is captured via **multiple WebSocket connections** to `wss://api-pub.bitfinex.com/ws/2`.

{% hint style="info" %}
Bitfinex servers are located in Market Synergy DC (Switzerland). All its public APIs are proxied through Cloudflare.
{% endhint %}