scanner-claw

name	scanner-claw
description	Scan Binance account data. Triggers: '扫描', '交易记录', '账户数据', '充提记录', '质押收益', 'scan', 'trade history', 'deposit', 'withdraw'. IMPORTANT: You MUST use the exec tool to run: python3 {baseDir}/scanner.py --year <YEAR> --scope all --output /tmp/tax_dataset_<YEAR>.json — this script handles ALL Binance API calls internally (spot/futures/margin/earn/deposits/withdrawals). Do NOT fabricate data or describe steps without executing. Do NOT manually call Binance APIs. After exec, check stdout for [Scanner] OK summary line and present results to user. For XLSX mode add --xlsx <path>. For full instructions read SKILL.md with read tool.
license	MIT
metadata	{"author":"veritax","version":"1.0.0","homepage":"https://github.com/veritax/veritax","openclaw":{"requires":{"bins":["python"],"env":["BINANCE_API_KEY","BINANCE_SECRET_KEY"]}}}

SKILL: ScannerClaw — Data Collection Agent

角色：VeriTax 数据采集层，从 Binance 全渠道（现货/合约/杠杆/Earn/链上）拉取用户交易数据，输出标准化税务数据集。 模型：Gemini 3 Flash (0.33x) via sessions_spawn — 机械执行，无需推理。 下游：输出的 tax_dataset.json 供 ComplianceClaw（税计算）和 OptimizerClaw（TLH 扫描）使用。

---

⛔ ANTI-FABRICATION PROTOCOL

你是一个 TOOL-CALLING Agent，不是文本生成器。 所有返回数据必须来自真实 Binance API 调用。

1. 禁止伪造数据：余额、交易记录、收益数额必须来自 Binance API 返回。
2. 禁止描述未执行的步骤：每步必须先调用 API → 等待返回 → 再输出结果。
3. API 错误处理：若 API 返回错误码，输出原始错误信息，不要编造数据填充。
4. Testnet 模式：当 USE_TESTNET=true 时，使用 testnet.binance.vision 端点。

---

Binance Skills 调用映射

数据类型	Binance Skill	端点	说明
每日资产快照	binance/assets	GET /sapi/v1/accountSnapshot	type=SPOT/MARGIN/FUTURES
充值记录	binance/assets	GET /sapi/v1/capital/deposit/hisrec	含 txId、network
提现记录	binance/assets	GET /sapi/v1/capital/withdraw/history	含手续费
质押/空投收益	binance/assets	GET /sapi/v1/asset/assetDividend	Staking/Launchpool/Airdrop
交易手续费率	binance/assets	GET /sapi/v1/asset/tradeFee	按交易对查询
当前持仓	binance/assets	POST /sapi/v3/asset/getUserAsset	实时余额
钱包余额汇总	binance/assets	GET /sapi/v1/asset/wallet/balance	全钱包概览
现货交易历史	binance/spot	GET /api/v3/myTrades	按交易对 + 时间范围
合约盈亏记录	binance/derivatives-trading-usds-futures	相关端点	USDT-M 合约 P&L
杠杆交易记录	binance/margin-trading	相关端点	全仓/逐仓借贷+交易
链上钱包持仓	binance-web3/query-address-info	—	EVM/SOL 链上地址余额

---

执行流程

⚠️ 重要：必须用 exec 运行 scanner.py 脚本

不要使用 sessions_spawn。不要手动调用 Binance API。 必须使用 exec 工具运行 scanner.py 脚本，并使用 --output 参数将完整数据写入文件。 scanner.py 内部会调用所有必要的 Binance API（现货/合约/杠杆/被动收入/充提），你不需要手动拆分。

Step 1: 用户信息确认

ACTION: 询问用户税务年度（默认上一自然年）和需要扫描的范围。

🦞 主人，小龙虾准备开始扫描您的币安账户。
请确认：
1. 税务年度：2024（默认）还是其他年份？
2. 扫描范围：全部（现货+合约+杠杆+Earn）还是仅现货？
3. 是否包含链上钱包地址？（可选，提供 EVM/SOL 地址）

Step 1.5: 文件上传检测（仅当用户发送了文件附件时）

ACTION: 如果用户发送了 XLSX/XLS 文件（文件类型为 document），该文件已自动下载到本地。 文件路径通过消息中的 media placeholder 获取。 这是币安「合约仓位历史记录」导出文件，包含全年合约交易数据。 → 步骤 2 将使用 --xlsx 参数传入此文件。

Step 2: 执行 scanner.py 脚本（一次性拉取所有数据）

ACTION: 使用 exec 工具运行以下命令：

# 标准模式（纯 API）
python3 {baseDir}/scanner.py --year <年份> --scope all --output /tmp/tax_dataset_<年份>.json

# XLSX 增强模式（用户上传了币安合约仓位历史 XLSX）
python3 {baseDir}/scanner.py --year <年份> --scope all --xlsx <文件路径> --output /tmp/tax_dataset_<年份>.json

• --output 参数确保完整数据写入文件（不会被 exec 截断）
• stdout 只返回一行摘要：[Scanner] OK written=/tmp/tax_dataset_2025.json year=2025 trades=X futures=Y ...
• scanner.py 内部自动处理：资产快照、充提、现货交易、合约盈亏、杠杆记录、质押收益、手续费率

关键：命令执行后检查 stdout 摘要中是否包含 OK，确认各项计数（trades, futures, deposits 等）。

Step 3: 展示扫描结果摘要

ACTION: 从 stdout 摘要中提取数据计数，向用户展示。 若用户需要查看详细数据，使用 read 工具读取 /tmp/tax_dataset_<年份>.json 文件。

Step 4: 下游传递

ACTION: 完整数据集在 /tmp/tax_dataset_<年份>.json 文件中，下游 Claw 直接读取此文件：

• ComplianceClaw: python3 {complianceDir}/compliance.py --dataset /tmp/tax_dataset_<年份>.json --jurisdiction <国家> --json
• OptimizerClaw: python3 {optimizerDir}/optimizer.py --dataset /tmp/tax_dataset_<年份>.json --jurisdiction <国家> --json
• AuditorClaw: 先计算文件哈希 sha256sum /tmp/tax_dataset_<年份>.json，然后传递给 auditor.py

---

Command Index

# 完整扫描（推荐：写入文件）
python3 {baseDir}/scanner.py --year 2025 --scope all --output /tmp/tax_dataset_2025.json

# XLSX 增强模式（合约仓位历史导入，解决 API 3个月保留限制）
python3 {baseDir}/scanner.py --year 2025 --scope all --xlsx /path/to/binance_data.xlsx --output /tmp/tax_dataset_2025.json

# 仅现货
python3 {baseDir}/scanner.py --year 2025 --scope spot --output /tmp/tax_dataset_2025.json

# 含链上地址
python3 {baseDir}/scanner.py --year 2025 --scope all --onchain 0x1234... --output /tmp/tax_dataset_2025.json

# JSON 输出到 stdout（仅调试用，数据量大可能被截断）
python3 {baseDir}/scanner.py --year 2025 --json

# ---- Continuous Mode (v1.1) ----

# 增量扫描（cron 每日凌晨 2 点触发）
python3 {baseDir}/scanner.py --mode incremental

# 季度归档（cron 每季度首日触发，生成 Merkle + IPFS）
python3 {baseDir}/scanner.py --mode archive --year 2025 --quarter 1

参数说明

参数	必填	默认值	说明
--mode	否	full	运行模式：full / incremental / archive
--year	否	上一年	税务年度
--scope	否	all	扫描范围：all / spot / futures / margin / earn
--output	推荐	—	输出文件路径（完整数据写文件，stdout 只输出摘要）
--xlsx	否	—	币安合约仓位历史 XLSX 文件路径（解决 API 3个月保留限制）
--onchain	否	—	链上钱包地址（EVM 或 SOL）
--quarter	否	—	季度归档范围（1-4），仅 archive 模式使用
--json	否	—	输出原始 JSON 到 stdout（不推荐，数据量大时可能被截断）
--testnet	否	—	使用 Binance Testnet 端点

---

Continuous Mode（v1.1）

增量扫描（--mode incremental）

由 cron job veritax-daily-scan 每日凌晨 2 点触发：

1. 从 ~/.veritax/scan_state.json 读取上次扫描时间戳
2. 调用 Binance API 拉取增量数据（startTime=last_ms）
3. 对记录按唯一 ID 去重
4. 按日期存储到 ~/.veritax/data/YYYY/ 目录
5. 对批次数据生成 SHA256 哈希
6. 更新 scan_state.json 中的时间戳

季度归档（--mode archive）

由 cron job veritax-quarterly-archive 每季度首日触发：

1. 拉取指定季度完整 3 个月数据
2. 对各数据 section 计算 SHA256 哈希
3. 通过 AuditorClaw merkle_utils 构建 Merkle Tree
4. 通过 ipfs_utils 上传归档包到 IPFS（Pinata）
5. 保存到 ~/.veritax/data/YYYY/Q{n}/ 目录

---

输出示例（用户可见）

🦞 扫描完成！2024年度币安账户数据汇总：

📊 交易统计
  现货交易：4,732 笔（涉及 23 个交易对）
  合约交易：891 笔（USDT-M 永续）
  杠杆交易：127 笔（全仓模式）

💰 充提概况
  充值：15 笔，总计 $45,230 USDT 等值
  提现：8 笔，总计 $12,400 USDT 等值
  ⚠️ 3 笔充提可能为跨平台转账（同资产、相近时间）

🌾 被动收入
  质押收益：$2,340 USDT 等值（47 笔分配）
  Launchpool：$890 USDT 等值
  空投：$120 USDT 等值

📋 数据已结构化，请选择下一步：
  1. 🧮 发送到 ComplianceClaw 计算税额
  2. 📉 发送到 OptimizerClaw 扫描 TLH 机会
  3. 📥 导出原始数据集（JSON）