CryptoService

一个高性能的Python加密货币数据处理包，专注于币安市场数据的获取、存储和分析。

✨ 核心功能

🚀 高性能异步：全面支持async/await，高效处理大量数据
📊 全面数据覆盖：现货、永续合约、历史K线、实时WebSocket
💾 智能存储：SQLite数据库 + 文件导出，支持增量更新
🔧 开箱即用：完整的类型提示、错误处理和重试机制
📈 数据处理：内置数据转换、验证和分析工具

📦 安装

pip install cryptoservice

🚀 快速开始

1. 环境配置

# .env 文件
BINANCE_API_KEY=your_api_key
BINANCE_API_SECRET=your_api_secret

2. 基本使用

import asyncio
import os
from cryptoservice import MarketDataService
from cryptoservice.models import Freq

async def main():
    api_key = os.getenv("BINANCE_API_KEY")
    api_secret = os.getenv("BINANCE_API_SECRET")
    if not api_key or not api_secret:
        raise RuntimeError("BINANCE_API_KEY / BINANCE_API_SECRET are required")

    async with await MarketDataService.create(api_key=api_key, api_secret=api_secret) as service:
        # 获取实时行情
        ticker = await service.get_symbol_ticker("BTCUSDT")
        print(f"BTC价格: {ticker.price}")

        # 获取历史K线（示例区间）
        klines = await service.get_historical_klines(
            symbol="BTCUSDT",
            start_time="2024-01-01",
            end_time="2024-01-31",
            interval=Freq.d1,
        )
        print(f"K线数量: {len(klines)}")

asyncio.run(main())

📋 完整工作流程演示

demo/ 目录提供 v2 的端到端工作流程，基于不可变 universe.json：

# 步骤1: 定义 universe.json（symbols + start/end）
python demo/define_universe.py

# 步骤2: 严格按 daily_snapshots 下载到数据库
python demo/download_data.py

# 步骤3: 严格按 daily_snapshots 导出并生成 report.json
python demo/export_data.py

# 额外: WebSocket实时数据流
python demo/websocket.py

✅ CLI Shell 脚本（最终交付用法）

bash scripts/universe_define.sh \
  --symbols BTCUSDT,ETHUSDT,SOLUSDT \
  --start-date 2024-10-01 \
  --end-date 2024-10-31 \
  --output ./data/universe.json \
  --api-key "${BINANCE_API_KEY}" \
  --api-secret "${BINANCE_API_SECRET}"

bash scripts/universe_download.sh \
  --universe-file ./data/universe.json \
  --db-path ./data/database/market.db \
  --api-key "${BINANCE_API_KEY}" \
  --api-secret "${BINANCE_API_SECRET}" \
  --interval 5m \
  --download-market-metrics

# 可选：仅下载小时间窗用于验证/可视化
bash scripts/universe_download.sh \
  --universe-file ./data/universe.json \
  --db-path ./data/database/market.db \
  --start-date 2024-10-10 \
  --end-date 2024-10-12 \
  --interval 5m

bash scripts/universe_export.sh \
  --universe-file ./data/universe.json \
  --db-path ./data/database/market.db \
  --export-base-path ./data/exports \
  --source-freq 5m \
  --export-freq 5m

# 可选：仅导出小时间窗
bash scripts/universe_export.sh \
  --universe-file ./data/universe.json \
  --db-path ./data/database/market.db \
  --export-base-path ./data/exports \
  --source-freq 5m \
  --export-freq 5m \
  --start-date 2024-10-10 \
  --end-date 2024-10-12

Scripts are pass-through wrappers; consumer must provide all paths and options. Credentials can be passed via --api-key/--api-secret, or via env (BINANCE_API_KEY, BINANCE_API_SECRET). Dotenv option: uv run --env-file .env cryptoservice universe define ....

define 也支持从 txt 导入 symbols，例如：

bash scripts/universe_define.sh \
  --symbols BTCUSDT,@./symbols.txt,ETHUSDT \
  --start-date 2024-10-01 \
  --end-date 2024-10-31 \
  --output ./data/universe.json \
  --api-key "${BINANCE_API_KEY}" \
  --api-secret "${BINANCE_API_SECRET}"

演示脚本说明

define_universe.py: 生成 v2 universe.json（每日 active_symbols / missing_symbols）
download_data.py: 仅读取 universe.json 执行严格日级下载计划
export_data.py: 仅读取 universe.json 导出并生成缺失覆盖报告
websocket.py: WebSocket客户端示例，展示实时数据流处理

详细使用说明请参考 demo/README.md

🛠️ 开发环境

# 克隆项目
git clone https://github.com/ppmina/xdata.git
cd xdata

# 安装uv（推荐）
./scripts/setup_uv.sh  # macOS/Linux
# 或 .\scripts\setup_uv.ps1  # Windows

# 安装依赖
uv pip install -e ".[dev-all]"

# 激活环境
source .venv/bin/activate

常用命令

pytest                    # 运行测试
ruff format              # 格式化代码
ruff check --fix         # 检查并修复
mypy src/cryptoservice   # 类型检查
mkdocs serve            # 本地文档

🚢 发布流程（main release）

个人维护时推荐手动准备版本，并由 GitHub Actions 负责最终构建/发布：

确保工作区干净并切到 main 分支。
运行 python3 scripts/prepare_release.py 1.12.0 --auto --push（替换为目标版本），脚本会从 main 检出新分支 release/v1.12.0，同步更新版本号，生成最新的 CHANGELOG.md 段落，执行 pytest，提交 chore: release v1.12.0、创建 v1.12.0 标签，并将分支和标签推送到远端。若只想本地检查，可省略 --push；如无需运行测试可加 --skip-tests；也可通过 --base / --release-branch 定制分支名称。
Release 工作流会在标签推送后自动运行测试、构建以及（若配置了 PYPI_API_TOKEN）上传到 PyPI；也可以在 GitHub Actions 中手动触发该工作流只做验证。

若只想更新版本号，可使用 --skip-changelog 跳过自动生成的变更记录；(#123) 的提交引用会自动转为 GitHub PR 链接。

📚 文档

完整文档：https://ppmina.github.io/Xdata/

🤝 贡献

Fork项目并创建分支：git checkout -b feature/your-feature
遵循Conventional Commits规范
提交Pull Request

📄 许可证

MIT License

📞 联系

Issues: GitHub Issues
Email: minzzzai.s@gmail.com

License
- OSI Approved :: MIT License
Operating System
- OS Independent
Programming Language
- Python :: 3

Metadata

License
- OSI Approved :: MIT License
Operating System
- OS Independent
Programming Language
- Python :: 3

Release files for cryptoservice 2.0.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for cryptoservice 2.0.0
File	Size	Uploaded
cryptoservice-2.0.0.tar.gz	121.2 kB	Feb 22, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for cryptoservice 2.0.0
File	Interpreter	ABI	Platform	Reset
cryptoservice-2.0.0-py3-none-any.whl 157.2 kB Feb 22, 2026	Python 3	none	any	Details

Total release size: 278.5 kB

Release files / cryptoservice-2.0.0.tar.gz

Download URL	cryptoservice-2.0.0.tar.gz
Size	121.2 kB
Tags	Source
SHA-256 checksum How to use checksums	`3ac2dffa707277f4db336bb8b055769d2786f75c5fa59081469cd912339718e1`
BLAKE2b-256 checksum How to use checksums	`08797c6fc31c7e410c4ef2f3940cccf969b8861bb6d8e707a603e0ec76056991`
Upload date	Feb 22, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/6.1.0 CPython/3.13.7`

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/ppmina/Xdata
Publishing commit: github.com/ppmina/Xdata/tree/d73f3daa64c9188b7ff1868a587e7719a32d9772

Workflow

Publishing configuration: github.com/ppmina/Xdata/blob/d73f3daa64c9188b7ff1868a587e7719a32d9772/.github/workflows/release.yml
Publishing logs: github.com/ppmina/Xdata/actions/runs/22274225454/attempts/1

Artifact

Subject: cryptoservice-2.0.0.tar.gz
SHA-256 checksum: 3ac2dffa707277f4db336bb8b055769d2786f75c5fa59081469cd912339718e1 Verifying attestations

Release files / cryptoservice-2.0.0-py3-none-any.whl

Download URL	cryptoservice-2.0.0-py3-none-any.whl
Size	157.2 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`99780266167ea513076deecaf399892209b45c34e03a2a87499f1b07aaed6662`
BLAKE2b-256 checksum How to use checksums	`cb2a586ea7b1a6b2f1bd9443b69367665e05c3952da09543fc7f95a176cb02be`
Upload date	Feb 22, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/6.1.0 CPython/3.13.7`

Provenance

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/ppmina/Xdata
Publishing commit: github.com/ppmina/Xdata/tree/d73f3daa64c9188b7ff1868a587e7719a32d9772

Workflow

Publishing configuration: github.com/ppmina/Xdata/blob/d73f3daa64c9188b7ff1868a587e7719a32d9772/.github/workflows/release.yml
Publishing logs: github.com/ppmina/Xdata/actions/runs/22274225454/attempts/1

Artifact

Subject: cryptoservice-2.0.0-py3-none-any.whl
SHA-256 checksum: 99780266167ea513076deecaf399892209b45c34e03a2a87499f1b07aaed6662 Verifying attestations