crobat

Cryptocurrency Order Book Analysis Tool
Explore the docs » · Report Bug · Request Feature

Table of Contents

• About
• Getting Started
• Usage
• Output Format
• Roadmap
• Contributing
• License
• Contact
• References

About

crobat is a Python library for recording live Level 2 order book data from the Coinbase Advanced Trade WebSocket feed. It captures limit order insertions (LO), cancellations (CO), and market orders (MO) in real time and saves them as structured time series files.

The project grew out of research on CUSUM statistics applied to Bitcoin transactions, and the output formats are designed to be compatible with conventions from the market microstructure literature (see References).

Getting Started

Prerequisites

• Python 3.10+
• A Coinbase Advanced Trade account with API credentials (cdp_api_key.json)

Installation

git clone https://github.com/orderbooktools/crobat.git
cd crobat
pip install -r requirements.txt   # or: pip install -e .

Place your cdp_api_key.json in the project root. Configure defaults in config.ini:

[recording]
currency_pair      = XRP-USD
position_range     = 5
recording_duration = 10
sides              = bid,ask,signed
filetype           = csv

Note: On busy pairs like BTC-USD, consider recording outside NYSE and LSE trading hours to reduce message volume. XRP-USD is a good starting point.

Usage

CLI

# Use defaults from config.ini
python CLI/crobat_cli.py

# Override parameters
python CLI/crobat_cli.py --pair BTC-USD --duration 30 --filetype pkl

# Interactive mode — prompts for each parameter
python CLI/crobat_cli.py --interactive

Python API

from crobat.recorder import L2Recorder
from crobat.config import recording_defaults

class Settings:
    d = recording_defaults()
    currency_pair      = d['currency_pair']
    position_range     = d['position_range']
    recording_duration = d['recording_duration']
    sides              = d['sides']
    filetype           = d['filetype']
    output_dir         = 'runs'

recorder = L2Recorder(Settings())
recorder.start()

# Access session history after recording
recorder.book.bid_events       # bid-side event log
recorder.book.ask_events       # ask-side event log
recorder.book.signed_events    # signed event log
recorder.book.latest_snapshot(side='signed')

Output Format

Each session produces up to 9 files in the output directory (default: runs/), named with a UTC timestamp suffix.

File	Side	Description
L2_orderbook_volm_bid<ts>	bid	Volume snapshots, bid side
L2_orderbook_volm_ask<ts>	ask	Volume snapshots, ask side
L2_orderbook_volm_signed<ts>	both	Volume snapshots, signed order book
L2_orderbook_prices_bid<ts>	bid	Price snapshots, bid side
L2_orderbook_prices_ask<ts>	ask	Price snapshots, ask side
L2_orderbook_prices_signed<ts>	both	Price snapshots, signed order book
L2_orderbook_events_bid<ts>	bid	Event time series, bid side
L2_orderbook_events_ask<ts>	ask	Event time series, ask side
L2_orderbook_events_signed<ts>	both	Event time series, signed

Snapshot format (single side)

Timestamp	1	2	3	...	position_range
YYYY-MM-DD HH:MM:SS.ffffff	vol @ pos 1	vol @ pos 2	...		vol @ pos n

An associated price snapshot is generated in the same format.

Signed order book snapshot

Follows the convention from Cont, Kukanov and Stoikov (2011). Bid positions are negative, ask positions are positive. Position 0 is skipped.

Timestamp	-5	-4	-3	-2	-1	1	2	3	4	5
YYYY-MM-DD HH:MM:SS.ffffff	← bid vol (negative) →	← ask vol →

Event recordings

Timestamp	order_type	price_level	event_size	position	mid_price	spread
YYYY-MM-DD HH:MM:SS.ffffff	LO/CO/MO	quote ccy	base ccy	ordinal	(ask+bid)/2	ask-bid

Signed events add a side column and sign the event size by order flow convention: positive for buy-side activity, negative for sell-side.

See Demo/ for example output files.

Roadmap

• Live L2 order book recording via Coinbase Advanced Trade WebSocket
• Bid, ask, and signed order book snapshots
• LO, CO, MO event time series
• CSV, pkl, and xlsx output formats
• CLI with config.ini defaults and interactive mode
• Snapshot timeout detection with retry logic
• Fixed tick order book snapshots
• Configurable output file naming

Contributing

Contributions are welcome. Please fork the repo, create a feature branch, and open a pull request.

1. Fork the project
2. Create your feature branch (git checkout -b feature/my-feature)
3. Commit your changes (git commit -m 'Add my feature')
4. Push to the branch (git push origin feature/my-feature)
5. Open a pull request

License

Distributed under the GNU GPLv3 License. See LICENSE for more information.

Contact

Ivan E. Perez — @IvanEPerez — perez.ivan.e@gmail.com

Project Link: https://github.com/orderbooktools/crobat

References

1. Huang W., Lehalle C.A. and Rosenbaum M. — Simulating and analyzing order book data: The queue-reactive model
2. Cont R., Stoikov S. and Talreja R. — A stochastic model for order book dynamics
3. Cont R., Kukanov A. and Stoikov S. — The price impact of order book events
4. Cartea A., Jaimungal S. and Wang Y. — Spoofing and Price Manipulation in Order Driven Markets
5. Silyantev E. — Order flow analysis of cryptocurrency markets
6. Perez I.E. — A Study of CUSUM Statistics on Bitcoin Transactions