内容
<p align="center"><img src="assets/logo.svg" width="84" alt="鳄鱼"></p>
<h1 align="center">鳄鱼</h1>
<p align="center"><b>整个加密市场的确定性引擎。</b><br>
从 100 多个交易场所拉取订单簿、交易、资金和链上 DEX 事件到一个 Parquet 湖中，然后按字节逐一重放。</p>
<p align="center"><sub>Python 3.12+ · Apache-2.0 · 公共市场数据无需 API 密钥</sub></p>
---
每个市场数据工具都可以获取价格。两个特点使这个工具与众不同。
**所有数据共用一个模式。** 手工编写的 Deribit 连接器、ccxt Kraken 交易场所和 Base 上的 Uniswap V3 池都发出相同的记录类型。因此，像“显示我来自所有来源的每笔 BTC 交易”这样的问题只需要一个 SQL 语句，而不是三个代码库。
**数据湖是确定性的。** 落盘的数据是规范化、验证和可重放的 - 今天或明年重放同一个窗口，得到的是相同的字节。没有隐藏的时钟，没有重新获取，没有漂移。
在此基础上，构建了一个期权和微观结构分析库、**FlowMap**（GPU 订单流可视化器）和一个 **MCP 服务器**，让 LLM 代理读取真实价格，而不是编造价格。
## 安装
```bash
uv pip install crypcodile # 或：pip install crypcodile
```
基本安装是整个流媒体核心：每个原生连接器、Parquet 湖、重放和 47 命令的 CLI。更重的部分是可选的额外功能，因此您永远不会为未使用的依赖树付费：
```bash
uv pip install 'crypcodile[market]' # +100 交易所通过通用 ccxt 连接器
uv pip install 'crypcodile[gui]' # FlowMap 可视化器 + Gas 跟踪器（PyQt6）
uv pip install 'crypcodile[ml]' # 资金预测 + Black-Scholes（xgboost/scipy）
uv pip install 'crypcodile[web]' # FastAPI 服务器 + Streamlit 示例
uv pip install 'crypcodile[onchain]' # Base L2 / GMX / Superchain 连接器（web3）
uv pip install 'crypcodile[full]' # 所有功能
```
更喜欢一键安装？[`install.sh`](install.sh)（macOS/Linux）和 [`install.ps1`](install.ps1)（Windows）安装 `crypcodile[full]`。
## 五分钟
```bash
# 将 Deribit BTC 永续合约交易和订单簿变化流式传输到本地湖中
crypcodile collect --exchange deribit --symbols BTC-PERPETUAL \
--channels trade --channels book_delta --data-dir data
# 湖只是分区 Parquet — 用 DuckDB SQL 查询它
crypcodile query "SELECT count(*) FROM records WHERE channel = 'trade'"
# 稍后重放该窗口 — 相同的字节，每次运行
crypcodile replay --channels trade --symbols deribit:BTC-PERPETUAL
# 在实时 Binance 数据上打开订单流可视化器（[gui] 额外功能）
crypcodile flowmap --symbol binance-spot:BTCUSDT --historical-hours 2.0
```
还没有湖吗？`replay` 和 `query` 回退到 [`test_data/`](test_data/) 中的捆绑样本，因此全新克隆可以离线工作。还有一个交互式 Shell — `crypcodile shell` — 具有历史记录和选项卡补全，每个命令都在其中运行。
## 覆盖整个市场
鳄鱼支持 **108 个交易场所**：10 个原生连接器，手工编写以确保忠实度，加上整个 [ccxt](https://github.com/ccxt/ccxt) 家族（104 个交易所）在一个通用连接器后面。当一个名称同时存在于两者时，原生连接器优先。
| | 交易场所 |
|---|---|
| **原生** | Binance · Bybit · Coinbase · Deribit · OKX · Base 链上（Uniswap V3，Aerodrome）· GMX/Synthetix · Derive · Superchain · CoinGecko |
| **通用** | ccxt 的所有 104 个交易所 — Kraken，KuCoin，MEXC，Gate，HTX，Bitget，… |
您不必指定交易对。命名市场的某个 **切片**，鳄鱼会从实时宇宙中解析具体的列表：
```bash
# Binance 上最具流动性的 200 个交易对，通过单个 WebSocket 流式传输
crypcodile collect-market --exchange binance --top 200 --use-ws \
--channels trade --channels book_ticker
# 跨三个交易场所的每种 USDT 永续合约，包含订单簿
crypcodile collect-market --exchange bybit,okx,mexc --all \
--quote USDT --kind perpetual --channels book_snapshot --limit 400
# 整个货币宇宙 — 17k+ 货币，包括长尾 CEX 未列出的货币
crypcodile collect --exchange coingecko --symbols _ --channels ohlcv
```
两个设计选择使这种规模诚实。ccxt 路径是 **REST-先轮询**（适用于每个交易场所），但在交易场所支持的情况下升级到 **单个多符号 WebSocket**（`watchTradesForSymbols` / `watchTickers`）— 一个套接字用于三个符号和一个套接字用于整个交易所的书籍之间的区别。并且 `universe` 按交易场所的市场排名，交易量排名靠前，因此 `--top N` 涵盖了流动性核心，而不是一万个死交易对。
### 整个市场在一个屏幕上
`crypcodile census` 实时测量市场，并写入一个自包含的 HTML 仪表盘 — 交易场所市场计数（ccxt），货币宇宙 + 市值 + 优势（CoinGecko），以及总价值锁定（DeFiLlama）。每个数字都来自无密钥公共提要；最近的运行：
> **108** 可达交易场所 · **34,171** 市场跨主要交易场所 ·
> **17,657** 活跃货币 · **$2.29T** 市值 · **$75.8B** DeFi TVL
```bash
crypcodile census # → census.html + 终端摘要
```
## 47 个命令
| 群集 | 命令 |
|---|---|
| **湖** | `collect` · `collect-market` · `backfill` · `replay` · `query` · `export` |
| **发现** | `census` · `markets` · `universe` · `search` · `resolve-symbols` · `data-coverage` · `catalog*` (7) · `list-exchanges` |
| **期权和资金** | `iv-surface` · `term-structure` · `vol-skew` · `risk-reversal` · `funding-apr` · `funding-predict` · `basis` · `open-interest` |
| **微观结构** | `ofi` · `slippage` · `whale-alerts` · `liquidity-depth` · `indicators` |
| **链上 / L2 风险** | `sequencer-latency` · `peg-deviation` · `chaos-score` · `lending-stress` · `gas-vol` · `smart-money` · `label-transfers` · `mev-sandwich` |
| **桌面** | `flowmap` · `gas-tracker` |
| **服务器** | `mcp` · `api` |
| **Shell** | `shell` · `update` |
摄取在出现断开连接时通过序列间隙桥接和死信队列存活下来（[`src/crypcodile/ingest/`](src/crypcodile/ingest/)）；所有到达磁盘的数据都针对 [16 记录模式](src/crypcodile/schema/records.py) 进行规范化，并可重放。
## FlowMap
FlowMap 将静止的订单簿深度随时间绘制为流动性热图，并在其上层叠交易记录：攻击者着色的交易气泡、VWAP 和 BBO 标签、COB/CVP/SVP 交易量配置文件、累积增量条、DOM 梯度和冰山 / 大宗交易跟踪器。用实时数据、湖重放或内置的综合市场对其进行馈送，以离线测试 UI。
```bash
crypcodile flowmap --symbol binance-spot:BTCUSDT --historical-hours 2.0
```
它在 `QOpenGLWidget` 上渲染，带有纯 NumPy 密度引擎（通过 `FLOWMAP_RENDERER=opengl|cpu` 固定后端）。无上限的离屏基准测试在 Apple Silicon 上以 1920×1080 清除 100 FPS；窗口本身位于 vsync。
## 分析
湖泊提供了一个期权 + 微观结构库，可以通过三种方式访问 — CLI、MCP 工具或通过 `Catalog` 的纯 Python。 [`examples/`](examples/) 中有两个可运行的示例：
```python
from crypcodile.analytics.funding import funding_apr
from crypcodile.analytics.volsurface import iv_surface
from crypcodile.store.catalog import Catalog
catalog = Catalog(data_dir="data")
apr = funding_apr(catalog, "binance:BTCUSDT", from_ns, to_ns) # Polars DataFrame
surface = iv_surface(catalog, "BTC", at_ns, rate=0.0) # strike × expiry × IV
```
完整的集合包括 OFI、滑移、鲸鱼警报、期限结构、波动率偏度、风险逆转、现货-永续 / 现货-期货基差、开放兴趣和 L2/DeFi 风险家族（排序延迟、锚定偏差、贷款压力、MEV 三明治检测）。每个都读取相同的规范化记录 — 原生交易场所或 ccxt，它无法区分。
## 适用于代理（MCP）
```bash
crypcodile mcp --data-dir data # 模型上下文协议服务器通过 stdio
```
每个工具都是只读和确定性的 — 答案来自湖泊和链条，而不是模型的想象力。工具涵盖市场数据读取（有界 DuckDB SQL、链上价格）、目录发现（`search_symbols`、`list_all_exchanges`、覆盖范围、库存）和分析库。适用于 Claude、Cursor 或任何支持 MCP 的工具。
## REST API
`crypcodile api` 通过 FastAPI 在 `/api/v1/*` 上提供相同的湖泊 — 操作和目录发现、有界只读 `POST /query`、衍生品和微观结构分析，以及基于 x402 协议的付费演示路由。
## Base L2
`BaseOnchainConnector` 从 Base RPC 日志中读取 Uniswap V3 和 Aerodrome 交换/储备事件，并发出与 CEX 连接器相同的记录类型，因此跨交易场所的查询是一个 SQL 语句，而不是两个代码库。以 [docs/base_quickstart.md](docs/base_quickstart.md) 开头；有一个 Streamlit 仪表盘和一个 Farcaster 帧服务器位于 [`examples/`](examples/) 下。公共数据无需密钥；链上读取使用默认 Base RPC，您可以覆盖它。
## 测试
```bash
uv sync --all-extras
pytest tests/
```
141 个文件中有 1760 个测试函数：一个用于降级网络 E2E 运行的本地模拟 RPC 服务器（`tests/e2e/`）、对抗性有效载荷套件和一个由真实交易所 API 异常种子生成的回归文件。`mypy --strict` 和 Ruff 控制 `src/`。CI 友好 — Qt 和 Matplotlib 以无头模式运行，BLAS 线程上限使 Apple Silicon 上的导入速度保持快速。
## 它不是什么
- **不是交易机器人。** 按照设计，没有订单执行路径。
- **不是托管服务。** 所有操作都在您的机器上运行，对应您的湖泊。
- **不是魔法。** 期权分析需要期权数据 — 将 `iv-surface` 指向一个包含 Deribit 快照的湖泊，而不是一个空目录。
- FlowMap 是一个桌面应用程序；它需要一个显示屏。数据管道不是。
## 贡献
欢迎 PR。浏览 [`CHANGELOG.md`](CHANGELOG.md) 获取方向，保持 `mypy --strict` 和 Ruff 网关绿色，确保 E2E 和对抗性套件在打开 PR 之前通过。
Apache-2.0 — 见 [LICENSE](LICENSE)。
