cryptofeed

Cryptocurrency Exchange Feed Handler

Handles multiple cryptocurrency exchange data feeds and returns normalized and standardized results to client registered callbacks for events like trades, book updates, ticker updates, etc. Utilizes websockets when possible, but can also poll data via REST endpoints if a websocket is not provided.

Supported exchanges

• Bitfinex
• bitFlyer
• Bithumb
• Bitstamp
• Bybit
• Binance
• Binance Delivery
• Binance Futures
• Binance US
• Bitget
• Coinbase
• Crypto.com
• Deribit
• Gate
• Gate Futures
• dYdX v4
• Gemini
• Hyperliquid
• HTX (formerly Huobi)
• HTX Swap (Coin-M and USDT-M)
• Independent Reserve
• Kraken
• MEXC (spot)
• Kraken Futures
• KuCoin
• OKX
• Phemex
• Poloniex
• Upbit

Basic Usage

Create a FeedHandler object and add subscriptions. For the various data channels that an exchange supports, you can supply callbacks for data events, or use provided backends (described below) to handle the data for you. Start the feed handler and you’re done!

from cryptofeed import FeedHandler
# not all imports shown for clarity

fh = FeedHandler()

# ticker, trade and book are user defined coroutine functions, each taking the
# normalized object and the timestamp cryptofeed received the message at:
#
#     async def trade(t, receipt_timestamp):
#         print(f'{t.exchange} {t.symbol} {t.side} {t.amount} @ {t.price}')
#
# a callback must be async - wrap a synchronous one in cryptofeed.callback.ExecutorCallback
ticker_cb = {TICKER: ticker}
trade_cb = {TRADES: trade}
gemini_cb = {TRADES: trade, L2_BOOK: book}


fh.add_feed(Coinbase(symbols=['BTC-USD'], channels=[TICKER], callbacks=ticker_cb))
fh.add_feed(Bitfinex(symbols=['BTC-USD'], channels=[TICKER], callbacks=ticker_cb))
fh.add_feed(Poloniex(symbols=['BTC-USDT'], channels=[TRADES], callbacks=trade_cb))
fh.add_feed(Gemini(symbols=['BTC-USD', 'ETH-USD'], channels=[TRADES, L2_BOOK], callbacks=gemini_cb))

fh.run()

National Best Bid/Offer (NBBO)

Cryptofeed also provides a synthetic NBBO (National Best Bid/Offer) feed that aggregates the best bids and asks from the user specified feeds.

from cryptofeed import FeedHandler
from cryptofeed.exchanges import Coinbase, Gemini, Kraken


async def nbbo_update(symbol, bid, bid_size, ask, ask_size, bid_feed, ask_feed):
    print(f'Pair: {symbol} Bid Price: {bid:.2f} Bid Size: {bid_size:.6f} Bid Feed: {bid_feed} Ask Price: {ask:.2f} Ask Size: {ask_size:.6f} Ask Feed: {ask_feed}')


def main():
    f = FeedHandler()
    f.add_nbbo([Coinbase, Kraken, Gemini], ['BTC-USD'], nbbo_update)
    f.run()

Supported Channels

Cryptofeed supports the following public data channels from exchanges

• L1_BOOK - Top of book
• L2_BOOK - Price aggregated sizes. Some exchanges provide the entire depth, some provide a subset.
• L3_BOOK - Price aggregated orders. Like the L2 book, some exchanges may only provide partial depth.
• TRADES - Note this reports the taker’s side, even for exchanges that report the maker side.
• TICKER
• FUNDING
• OPEN_INTEREST - Open interest data.
• LIQUIDATIONS
• INDEX
• CANDLES - Candlestick / K-Line data.

Normalized data

Every callback receives two arguments: a normalized object and receipt_timestamp, the time (float epoch seconds) cryptofeed received the message that produced the callback. The objects are defined in cryptofeed/types.pyx (Trade, Ticker, OrderBook, L1Book, Candle, Funding, OpenInterest, Liquidation, Index) and share these rules:

• exchange is the venue id and symbol the normalized name: BASE-QUOTE for spot, BASE-QUOTE-PERP for perpetuals, BASE-QUOTE-<expiry> for dated futures with the expiry as a two-digit year, a futures month code and a zero-padded day (BTC-USD-26H05), and BASE-QUOTE-<strike>-<expiry>-CALL|PUT for options.
• Prices, sizes, rates and volumes are Decimal. numeric_type on a backend or to_dict() converts them.
• timestamp is the venue’s event time in float epoch seconds. timestamp is None when the venue does not provide a timestamp and backends then store the receipt time in its place.
• Trade.side is the taker’s side. Trade.id is the venue’s id or None.
• OrderBook.book holds the full local book (.bids, .asks). delta is None for a snapshot and otherwise lists the levels that changed as (price, size) with size 0 for a removed level. sequence_number and checksum are set when the venue provides them.
• Candle.closed is True once the bar is final, by default only closed candles are delivered. (candle_closed_only=False also delivers each update of the open bar).
• trade_history, candle_history and liquidation_history control whether the batch of recent trades, candles or liquidations some venues send on subscribe is delivered, by default it is False.

Backends

Cryptofeed supports backend callbacks that will write directly to storage or other interfaces.

Supported Backends:

• Redis (Sorted Sets, Streams and Keys)
• ZeroMQ
• UDP Sockets
• TCP Sockets
• Unix Domain Sockets
• InfluxDB v2
• MongoDB
• Kafka
• PostgreSQL
• QuestDB
• ClickHouse

Data Capture and Replay

Cryptofeed can record data from data feeds to standard pcap files for later replay

from cryptofeed import FeedHandler

# `record` is a pcap file path or a directory
fh = FeedHandler(record='sample_data/')
fh.add_feed('COINBASE', symbols=['BTC-USD'], channels=[TRADES, L2_BOOK], callbacks=...)
fh.run()

examples/record.py wraps this into a small recording tool. The pcaps are zstandaard compressed by default. Wireshark and tshark open these files natively and playback decompresses transparently. Metadata is stored in .meta.json.

Installation

Note: cryptofeed requires Python 3.13+

Cryptofeed can be installed from PyPi. (It’s recommended that you install in a virtual environment of your choosing).

pip install cryptofeed

Cryptofeed has optional dependencies, depending on the backends used. You can install them individually, or all at once. To install Cryptofeed along with all its optional dependencies in one bundle:

pip install cryptofeed[all]

If you wish to clone the repository and work on it (development uses uv), run this from the root of the cloned repository:

uv sync

Alternatively, you can install from source in editable mode with pip:

pip install -e .

Performance

Measured on Python 3.14.6 based on throughput over real recorded exchange traffic.

Operation	Result
Trade construct / to_dict / from_dict	102 ns / 214 ns / 277 ns
Ticker / Candle / Funding construct	70 ns / 118 ns / 141 ns
Book single level update / delete / top-of-book read	89 ns / 124 ns / 140 ns
Book to_dict, 10 / 100 levels per side	2.4 µs / 22.2 µs
Checksum, Kraken / OKX format (200 levels)	2.0 µs / 6.1 µs
JSON decode with Decimal (msgspec / stdlib fallback)	1.39M / 0.60M msg/s
JSON encode to str / bytes	4.65M / 5.25M msg/s
Message handler, Kraken / Bybit / KuCoin / Kraken Futures	161k / 134k / 122k / ~100k frames/s

Future Work

There are a lot of planned features, new exchanges, etc planned! If you’d like to discuss ongoing development, please join the discord or open a thread in the discussions in GitHub.

Contributing

Issues and PRs are welcomed!

Cryptofeed wouldn’t be possible without the help of many contributors! I owe them and all other contributors my thanks!

Donations / Support

Support and donations are appreciated but not required. You can donate via GitHub Sponsors, or via the addresses below:

• Bitcoin: bc1qm0kxz8hqacaglku5fjhfe9a5hjnuyfwk02lsyr
• Ethereum: 0x690709FEe13eEce9E7852089BB2D53Ae5D073154