Crocodile

<p align="center"><img src="assets/logo.svg" width="84" alt="鳄鱼"></p> <h1 align="center">鳄鱼</h1> <p align="center"> <b>用于加密货币和美国股票市场的确定性市场数据引擎。</b><br> 从 109 个加密货币交易平台和 9 个股票市场来源中，收集订单簿、交易、资金、期权链、文件和链上 DEX 事件到一个 Parquet 湖中，然后重放任意时间窗口，得到相同的字节。<br> </p> <p align="center"> <a href="LICENSE"><img alt="Apache-2.0" src="https://img.shields.io/badge/license-Apache--2.0-2ea043"></a> <img alt="Python 3.12+" src="https://img.shields.io/badge/python-3.12%2B-3572A5"> <img alt="3,941 tests" src="https://img.shields.io/badge/tests-3%2C941-2ea043"> <img alt="62 CLI commands" src="https://img.shields.io/badge/CLI-62%20commands-a3620a"> <img alt="API keys mostly optional" src="https://img.shields.io/badge/API%20keys-mostly%20optional-f0a92e"> </p>  每个市场数据工具都可以获取价格。三个特点使这个工具值得关注。 **所有数据共用一个模式。** 手写的 Deribit 连接器、ccxt Kraken 交易平台、Base 上的 Uniswap V3 池和 SEC EDGAR 表格 4 都发出相同的记录类型 - 30 种记录类型，只需定义一次。“显示我所有来源的所有交易” 只需一个 SQL 语句，而不是四个代码库。 **单一功能，涵盖两个市场。** 鳄鱼是两个引擎的合并 - Crypcodile 用于加密货币，Stockodile 用于股票 - 并且这两个历史记录都存在于此存储库的 `git log` 中。结果是一个包含 **49 种功能** 的单一注册表，其中 42 种功能适用于两种资产类别，名称和参数模式相同。 不适用的七种功能各自都有书面解释，说明为什么无法找到股票类似物。 CLI、REST API 和 MCP 服务器是该注册表的 *投影*，因此它们都不能偏离注册表。 **湖泊属于你，它记录了每个数字的来源。** 存储在磁盘上的数据是规范化、验证和可重放的。 每个记录还包含它如何存在：一个溯源级别、它所依赖的方法，以及通过注册公式计算的置信度，而不是手动选择。 建模的答案在读取一行之前会说明这一点。 ## 比较 市场数据业务大多是租用的。 你支付月费，查询 API，当你停止支付时，你被合同要求删除你拉取的数据。 Massive 的市场数据条款 §8 明确表示： > 您同意停止使用市场数据并删除您拥有的所有市场数据。 鳄鱼将 Parquet 文件写入您选择的目录。 没有什么能阻止您停止支付。  三个诚实的备注，因为无法核实的比较是毫无价值的： - **鳄鱼不是许可存档。** Kaiko 和 Databento 出售具有 SLA 保障、审计级历史的存档，基于交易平台协议。 鳄鱼摄取公共端点返回的数据。 如果您有合规性要求，这些不是可互换的。 - **确定性重放并非独有。** Tardis.dev 提供了四个记录的重放端点，NautilusTrader 具有纳秒级 L3 到条形事件重放。 两者都很好。 这里的独特之处在于 *组合* - 两个资产类别、任意窗口、您拥有的存储，费用为零。 - **MCP 也不是独有的。** CoinAPI、Massive 和 CryptoQuant 都提供了 MCP 服务器。 独特之处在于，鳄鱼的 MCP 工具、REST 路由和 CLI 命令都是从一个声明中生成的，因此代理、 `curl` 和 shell 不能不同意某个功能的作用。 _{截至 2026-07-29，已针对各供应商的定价、文档和条款页面进行验证。 Kaiko 已收购 Amberdata；计为一次。 Polygon.io 于 2025-10-30 更名为 Massive.com。 NautilusTrader 通过付费 Databento 订阅（每月 199 美元起）或 Interactive Brokers 账户访问美国股票市场。} ## 安装 **不在 PyPI 上。** 该名称属于一个无关项目，因此请从存储库安装： ```bash uv pip install "crocodile[full] @ git+https://github.com/nazmiefearmutcu/Crocodile.git" ``` 删除 `[full]`，您仍然可以获得整个流媒体核心：每个原生连接器、Parquet 湖、重放和 62 命令的 CLI。 较重的表面是按需选择的，因此您永远不会为不使用的依赖树付费： | 额外 | 添加 | |---|---| | `[market]` | 通过通用 ccxt 连接器连接 100+ 个交易所 | | `[ml]` | 资金预测、Black-Scholes、3D 波动率曲面（xgboost、scipy、matplotlib） | | `[web]` | FastAPI 服务器 + Streamlit 示例 | | `[onchain]` | Base L2 / GMX / Superchain 连接器（web3） | | `[full]` | 以上所有 | 没有桌面额外功能。 此存储库中没有任何内容需要显示服务器。 ## 五分钟 ```bash # 将 Deribit BTC-perp 交易 + 账本变化流式写入本地湖 crocodile collect --asset-class crypto --sources deribit --symbols BTC-PERPETUAL \ --channels trade --channels book_delta --data-dir data # 湖只是分区 Parquet - 每个通道一个 DuckDB 视图 crocodile query --asset-class crypto "SELECT count(*) AS n FROM trade" # 稍后重放该窗口 - 相同的字节，每次运行 crocodile replay --asset-class crypto --channels trade --symbols BTC-PERPETUAL \ --start-ns 0 --end-ns 9223372036854775807 ``` 其中三项是承载负载且容易出错的： - **`--sources`，而不是 `--exchange`/`--provider`。** 合并将两个分支的分区合并为一个 `source=`，并且标志也随之而来。 在旧的 `exchange=` 前缀下编写的湖泊需要先进行 `crocodile migrate-lake`。 - **当符号未命名其市场时，使用 `--asset-class`。** 裸 `BTC-PERPETUAL` 可能属于任一分支。 猜测是请求如何落在错误市场的实现中并返回具有可信数字的结果，因此拒绝而不是猜测。 - **没有 `records` 表。** 湖泊注册每个找到的 `channel=` 目录的视图 - `trade`、`book_snapshot`、`ohlcv` - 因此通道是视图名称而不是列。 `crocodile catalog-channels` 列出给定湖泊实际拥有的内容。 `replay` 和 `query` 读取您指向的湖泊，而不读取其他任何内容。 没有捆绑的样本和离线回退，因此在您克隆后，两个答案在空白克隆上都为空。 还有一个交互式 shell - `crocodile shell` - 具有历史记录和选项卡补全，并且每个命令都在其中运行。 ## 触及整个市场  在加密货币方面，鳄鱼支持 **109 个交易平台**：10 个原生连接器，手工编写以确保忠实度，加上整个 [ccxt](https://github.com/ccxt/ccxt) 家庭在通用连接器后面。 六个名称存在于两者中 - binance、bybit、coinbase、deribit、derive、okx - 并且原生连接器优先，因此总数是并集而不是总和： 10 ∪ 105 = 109。 该数字 105 不是固定数字。 依赖项是 `ccxt>=4.5`，而 105 是此版本解析的数字。 `crocodile markets --asset-class crypto` 打印出您安装的实际计数。 | | 交易平台 | |---|---| | **原生** | Binance · Bybit · Coinbase · Deribit · OKX · Base 链上（Uniswap V3，Aerodrome）· GMX/Synthetix · Derive · Superchain · CoinGecko | | **通用** | 每个 ccxt 交易所 ID - Kraken，KuCoin，MEXC，Gate，HTX，Bitget，… | 在股票方面，有 **9 个来源**，每个来源可以请求的内容由来源本身决定，而不是来自共享菜单 - 因此为提供该内容的提供商提供通道，而其他地方则不提供： | 来源 | 编写 | 密钥 | |---|---|---| | `alpaca` | `trade` `quote` `ohlcv` | 是 | | `yahoo` | `options_chain` `ohlcv` `corp_action` `insider` | 否 | | `sec_edgar` | `insider` `holding_13f` `filing` `fundamental` | 否（联系字符串） | | `treasury` | `macro_series` | 否 | | `tiingo` | `ohlcv` `corp_action` | 是（免费层） | | `stooq` | `ohlcv` `index_value` | 否 | | `msn_money` | `ohlcv` `corp_action` | 否 | | `google_finance` | `trade` `index_value` `fundamental` | 否 | | `finnhub` | `trade` | 是 | `openfigi` 故意不是一个来源：它丰富了一个工具宇宙并且不写入任何通道。 您不需要命名符号。 命名市场的某个 *切片*，鳄鱼会从实时宇宙中解析出具体的列表： ```bash # 币安上 200 个最具流动性的现货交易对，通过单个 WebSocket 流式传输 crocodile collect-market --asset-class crypto --sources binance --top 200 \ --kinds spot --use-ws --channels trade --channels book_ticker # 跨三个交易平台的每一种 USDT 永续合约，包括订单簿 crocodile collect-market --asset-class crypto --sources bybit,okx,mexc \ --all-symbols --quote USDT --kinds perpetual --channels book_snapshot \ --max-symbols 400 # 整个币圈 - 17k+ 币，包括长尾 CEX 未列出的部分 crocodile collect --asset-class crypto --sources coingecko --symbols _ \ --channels ohlcv ``` 两个设计选择使该规模诚实。 ccxt 路径是 **先使用 REST 拉取**，适用于所有交易平台，但会在交易所支持的情况下升级到 **单个多符号 WebSocket** - 交易所不支持的差异是三个符号的一个套接字和整个交易所的一个套接字。 并且 `universe` 按实时 24 小时交易量对市场的交易平台进行排名，因此 `--top N` 涵盖了流动性的核心，而不是一万个死交易对。 ### 整个市场，一屏显示 `crocodile census` 实时测量市场并打印一个 JSON 文档 - 连接器覆盖范围、交易平台市场数量、币圈、市场资本化、主导地位和总锁定价值。 每个数字都来自无密钥公共提要。 2026-07-28 运行于十二个主要交易平台： > **109** 个可达交易平台 · **34,208** 个市场跨主要交易平台 · **17,863** 个活跃币 · **2.28T** 市值 · **75.4B** DeFi TVL ```bash crocodile census --asset-class crypto \ --venues binance,bybit,okx,coinbase,kraken,kucoin,mexc,gate,htx,bitget,bingx,cryptocom ``` 显式命名交易平台。 裸 `crocodile census` 报告为零 - 空元组默认将参数作为字符串字面值到达，并且零交易平台与运行并找到零的普查无法区分。 同一个错误使得 `--kinds` 在 `collect-market` 上是强制性的。 ## 一个声明，三个投影  三个数字描述了同一个 CLI，而您需要哪一个取决于问题。 **62** 是 `--help` 列出的内容。 **54** 消除了 8 个已弃用的拼写，这些拼写保留给已经连接的调用者。 **49** 是功能注册表 - 除了五个启动器之外的每个命令都是一个声明的投影，而 REST 路由和 MCP 工具也是一个声明的投影。 | 集群 | 命令 | |---|---| | **湖泊** | `collect` · `collect-market` · `backfill` · `replay` · `query` · `export` · `resample` | | **发现** | `census` · `markets` · `universe` · `search` · `resolve-symbols` · `data-coverage` · `list-exchanges` · `catalog` · `catalog-channels` · `catalog-dates` · `catalog-exchanges` · `catalog-inventory` · `catalog-scan` · `catalog-stats` · `catalog-summary` · `catalog-symbols` | | **期权和资金** | `iv-surface` · `term-structure` · `vol-skew` · `risk-reversal` · `funding-apr` · `funding-predict` · `basis` · `perp-basis` · `spot-future-basis` · `open-interest` | | **微观结构** | `ofi` · `slippage` · `whale-alerts` · `liquidity-depth` · `depth` · `indicators` | | **链上 / L2 风险** | `sequencer-latency` · `peg-deviation` · `chaos-score` · `lending-stress` · `gas-vol` · `smart-money` · `label-transfers` · `mev-sandwich` · `onchain-price` · `base-market-data` | | **服务器** | `mcp` · `api` | | **操作** | `shell` · `update` · `migrate-lake` | | **已弃用拼写** | `inventory_snapshot` · `list_data_channels` · `list_dates` · `list_exchanges_on_disk` · `list_symbols` · `query_market_data` · `search_symbols` · `simulate-price-impact` | 最后一行是一个分类帐，只有减少。 每个条目都曾在一个或两个分支下使用，并且解析为单个声明，因此永远不会有第二个实现位于第二个名称后面。 摄取在序列间隙和死信队列（[`src/crocodile/core/ingest/`](src/crocodile/core/ingest/))的桥接下生存；无论存储在磁盘上的内容都规范化为 [30 记录模式](src/crocodile/core/schema/records.py)，并且可重放。 ## 每个数字的来源  每条记录都附带四个字段。 `prov` 表示值的类别 - 当交易平台报告时为 `native`，从原生记录计算时为 `derived`，从另一个数据类建模时为 `synthetic`，当它是一个类型化的空值而不是零时为 `unavailable`。 `prov_basis` 命名注册的方法。 `prov_inputs` 列出该方法消耗的内容。 `prov_confidence` 由基础的自身纯粹、文档化的公式填充 - 没有支持的手动输入置信度的方法。 在连接时，`worst_provenance()` 获胜，因此建模的输入不能将其自身伪装成原生外观的答案。 ## 分析 湖泊为期权 + 微观结构库提供支持，该库可以通过三种方式访问 - CLI、MCP 工具或通过 `Catalog` 使用纯 Python。 [`examples/`](examples/) 中的九个可运行脚本： ```python from crocodile.crypto.analytics.funding import funding_apr from crocodile.crypto.analytics.volsurface import iv_surface from crocodile.core.store.catalog import Catalog catalog = Catalog(data_dir="data") apr = funding_apr(catalog, "BTCUSDT", from_ns, to_ns) # Polars DataFrame surface = iv_surface(catalog, "BTC", at_ns, rate=0.0) # strike × expiry × IV ``` 此处的符号是交易平台自己的拼写，如存储的符号。 CLI 读取的规范 `source:RAW` 形式以确定您要查找的市场不是湖的 `symbol` 列中存储的内容，因此传入 `binance:BTCUSDT` 到读取器会匹配内容并返回空帧，而不是引发异常。 完整的集合范围包括 OFI、滑移、鲸鱼警报、期限结构、波动率偏差、风险逆转、现货-永续/现货-期货基差、开放兴趣和 L2/DeFi 风险家族（排序延迟、锚定偏差、贷款压力、MEV 三明治检测）。 每个读取相同的规范化记录 - 原生交易平台还是 ccxt，都无法区分。 ## 适用于代理（MCP） ```bash crocodile mcp --data-dir data # 基于 stdio 的模型上下文协议服务器 ``` 每个工具都是只读和确定性的 - 答案来自湖泊和链条，而非模型的想象。 工具列表由与 CLI 相同的注册表生成，因此代理无法调用 shell 没有的功能，并且每个输入模式都源自功能的参数类型而非二次编写。 与 Claude、Cursor 或任何支持 MCP 的工具配合使用。 ## REST API `crocodile 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，您可以覆盖它。 ## 性能  离线路径的网络免费、综合数据基准测试（规范化 → 存储 → 查询 → 重采样 → 重放），固定种子，每个数字由运行本身写入： [`benchmarks/RESULTS.md`](benchmarks/RESULTS.md). 使用 `uv run python benchmarks/bench.py` 重现。 这里没有 GUI，因此没有可引用的帧率。 ## 测试 ```bash uv sync --all-extras pytest tests/ ``` 240 个文件中的 2,682 个测试函数，**3,941 个用例** 在参数化扩展后。 在此标题下：本地模拟 RPC 服务器用于降级网络的端到端运行（`tests/e2e/`），对抗有效载荷套件，真实交易所 API 异常生成的回归文件，以及 `tests/conformance/`，它断言此代码库运行的参数而非其行为。 CI 友好 - Matplotlib 以无头模式运行，BLAS 线程上限在 Apple Silicon 上保留导入速度。 其中之一值得命名。 `tests/replay/test_byte_identity.py` 在两个不同的 `PYTHONHASHSEED` 值下，在两个子进程中重放相同的窗口，并比较原始输出，因为顶部的声明是关于字节的，而同一个进程的重复不会注意到静默依赖于 `set` 迭代顺序的依赖关系。 它是英雄图像下的门。 `mypy --strict` 和 Ruff 都没有覆盖整个 `src/`，而是说这描述了一个不存在的门。 实际上存在： - **零 Ruff 发现** 在 `core`、`contrib`、`capabilities`、`surfaces` 和两个弃用 shim 中 - 合并写入的每一行。 - **一个棘轮，目前为 202**，在 `crypto` 和 `equity` 上，这两个继承树。 它只会减少；`tests/conformance/test_phase1_exit.py` 在它上升时失败，而第三个测试在任何文件落在两个门之外时失败。 删除桌面层使其从 222 减少到 202，仅凭这一点 - 一个门在代码减少时收紧需要有人记住收紧它。 - **`mypy --strict` 在 229 个文件上完全干净**，在 `pyproject.toml` 中豁免了 `crocodile.crypto.*` 和 `crocodile.equity.*` ，直到它们被迁移。 还有一个一致性门，当源代码中的句子声明代码不再持有的数字时会失败。 这就是为什么本页上的数字值得信赖：它们不是手动维护的。 ## 不是什么 - **不是交易机器人。** 按照设计，没有订单执行路径。 - **不是托管服务。** 所有内容都在您的机器上运行，对抗您的湖泊。 - **不是许可的数据存档。** 它摄取公共端点返回的内容。 - **不是图表。** 鳄鱼没有 GUI。 [FlowMap](https://github.com/nazmiefearmutcu/flowmap) 是一个单独的市场流动性可视化工具，它读取类似的湖泊。 - **不是魔术。** 期权分析需要期权数据 - 将 `iv-surface` 指向一个包含 Deribit 快照的湖泊，而不是空目录。 ## 贡献 PRs 欢迎。 在 [`CHANGELOG.md`](CHANGELOG.md) 中找到方向，将上述 `mypy --strict` 和 Ruff 网关保持绿色 - 新代码进入零发现的半部分，继承部分的计数器永远不会上升 - 并确保端到端和对抗性套件在打开 PR 之前通过。 Apache-2.0 - 请参阅 [LICENSE](LICENSE)。