# v0.58 币安历史流水首期

“我的资产 → 交易所历史流水”复用当前个人保存的Binance全球站只读连接。任务只查询数据，不发单、不划转、不提现、不更新余额、成本或净值。保存任务、刷新列表和查看结果不访问交易所；只有点击“采集下一段”才请求一页。没有新增定时任务或自动同步。

## 已开放范围

| 单任务通道 | API来源 | 范围和边界 |
| --- | --- | --- |
| trades | GET /api/v3/myTrades | 一个明确的完整现货交易对，含收付腿和手续费；每个交易对另建任务 |
| deposits | GET /sapi/v1/capital/deposit/hisrec | status=1的成功充值，识别Spot/Funding钱包；不包含未完成及其他状态 |
| withdrawals | GET /sapi/v1/capital/withdraw/history | status=6的完成提现，保留API amount及transactionFee，扣款口径需人工核对 |
| MAIN_FUNDING | GET /sapi/v1/asset/transfer | 现货到资金账户；CONFIRMED记录生成双腿，PENDING/FAILED仅留在原始证据 |
| FUNDING_MAIN | GET /sapi/v1/asset/transfer | 资金到现货账户，其他划转路径不接入 |

本期没有OKX历史适配，也不涵盖理财、返佣、Convert、P2P、合约、保证金、子账户、其他划转方向或自动发现全部交易对。原有OKX余额同步保持可用。指定交易对仍须可通过公开元数据接口识别；下架或元数据变化时停止，使用交易所原CSV补齐。

## 操作

1. 在个人连接区保存仅读取权限的HMAC密钥，选择自己的币安全球站连接。
2. 选择一个通道，成交填写完整交易对，如BTCUSDT、ETHUSDT或用户自行指定的其他交易对。
3. 输入UTC起止时间和说明，边界均包含。单任务最多31天，终点至少早于现在10分钟；最早从2017-08-01起。划转仅开放最近180天的保守查询范围，交易所实际保留边界仍以返回为准。
4. 保存任务后点击“采集下一段”。每次读取一个最长24小时的分片；任务持久保存断点，可关闭页面后回来继续。任务不会自动运行。
5. 若返回数量达到100条或划转total大于已返回条数，当前片只保存证据，继续拆成互不重叠的两个区间，不把截断结果写为完成。单一毫秒仍饱和则留下缺口。后续任务可缩小范围，但不能靠跳过时间消除密集区间。
6. 查看接受、待查、冲突和缺口。任务可暂停、恢复手动采集或取消剩余；恢复数据库后的任务须新建，不直接继续旧租约。
7. 下载JSON留存原始API返回、毫秒时间、请求范围和哈希链。派生CSV须另外确认时间语义和重叠范围；提现还须核对每笔amount是否含手续费。不一致的提现应使用JSON逐笔核对，不能强行选统一口径。

CSV使用UTC秒精度，原始毫秒保留在JSON；按接口记录时间输出，不能视为实际记账时间。充值使用insertTime，提现将无时区的applyTime按UTC解析（须与交易所记录核对），成交使用time，划转使用timestamp。成功/完成过滤也不证明该时间就是资产扣收时间。账户标识一致仅核对保存状态，不重新访问交易所。CSV不自动导入，需要核对后在“原始交易流水”中选择派生CSV上传，文件名明确标为API-derived。

API-derived与原有交易所CSV的同一交易可能标签或备注不同，当前连续账本不会自动识别这类跨来源重复。优先按不重叠期间导入，先交叉核对再拼接。同一API来源ID在多次API任务中保持稳定，派生CSV保留ID备注；不同任务中的相同记录可成为现有账本的相同内容候选。

## 完整性和去重

“所选查询分片已返回”只描述所选通道和交易对在观察时的接口结果，不是全账户历史完成。空页也不能证明未发生任何资产变动。延迟到账、随后更正、接口保留期、未查询币种与未支持业务仍可能有缺口；需要重查相同期间时显式新建任务。

去重键绑定当前个人、币安全球站、已核验交易所UID、通道、交易对和来源ID。大整数ID从原始JSON保留为字符串，数量使用18位精确小数，不转为浮点。相同ID且规范化数量相同只保存一份来源事件，各次查询仍保存证据。相同ID的数量不同则把整片保留为冲突缺口，不覆盖原事实，也不插入该片的其他记录。本期不提供自动冲突裁决。

提现不自动生成扣款腿。导出时，用户核对amount为含费总额则生成principal=amount-fee和独立手续费，合计扣amount；若amount为另扣费的金额则生成principal=amount和手续费，合计扣amount+fee。该选择只作用于派生导出，不改原始API证据。

## 权限、容量与失败

每次采集先检查公共时间、只读权限和现货账户UID，成交再读交易对元数据，然后只访问固定域名的GET白名单。拒绝交易、提现、划转及未知权限。重定向不转发凭证，失败只保留阶段、路径、HTTP和有界错误码，不保留上游错误消息。

历史与余额同步共用账户租约；每次网络调用前以及返回后复查个人权限、任务修订、连接修订及租约。最终事务再次核对来源、冲突与容量。暂停、撤权、断开和换钥会阻断在途写入。密钥轮换不能更换交易所账户。

每次尝试至少间隔5秒；同个人历史POST共用每分钟8次预算，历史上游另有全站每分钟12次预算。429/418遵守有界Retry-After及保守退避，全站共享历史冷却。此全站历史预算不替代其他产品请求的交易所IP级总预算。

每人最多20任务、1500个去重来源事件、1000分片及合计3 MiB分片和事件内容；每任务最多256分片，单次API原文192 KiB、单片保存证据256 KiB。超限停止并保留断点，不截断、不自动删除。当前控制台备份仍有全产品8 MiB及每表5000行上限，超限须使用既有管理员数据库备份流程，不能把控制台备份当作无限容量归档。

## 浏览器控制台API

全部接口只归当前登录个人，同源会话认证；不接受团队工作区选择头，也不开放独立Bearer或自动任务入口。请求沿用个人资产128 KiB限制，不允许提交响应原文或自定义URL。

| 方法 | 路径 | 输入 |
| --- | --- | --- |
| GET | /api/console/wealth/history | 无查询参数，返回自己的任务元数据 |
| POST | /api/console/wealth/history/create | id、accountId、lane、symbol或null、from、to、note |
| POST | /api/console/wealth/history/run | id、revision；只推进一个分片 |
| POST | /api/console/wealth/history/control | id、revision、action=pause/resume/cancel |
| POST | /api/console/wealth/history/report | id；带哈希的完整历史证据 |
| POST | /api/console/wealth/history/csv | id、acknowledgeTime=true、acknowledgeOverlap=true、acknowledgePartial、withdrawalBasis或null |

模型为personal-exchange-history-v1 / binance-history-0.58.0。新增3表1迁移，共72业务表、37迁移、50恢复文件；当前清单release-v058.json。v0.57的49个恢复文件逐字节冻结于v057目录。MCP原始文件列表只增加任务数量和能力标识，不返回个人历史记录。

## 复算与恢复

JSON证据是私人财务资料，含交易所UID及原始充提响应中的地址等字段；不要公开。请求签名和密钥不会写入证据。

```sh
node --experimental-strip-types scripts/reproduce-exchange-history.mts --file exported-history.json --out replay-result.json
```

使用Node24及源码，输出路径必须不存在。CLI检查封装、分片链、时间划分和逐笔数量。内部哈希不能认证交易所来源真实性，也不能证明当前服务器或实际持仓状态。

恢复逐片复算来源事件并核对账户、任务和审计。恢复后标为requires_review，停止待采任务，清除交易所凭证与全部租约；旧证据保留，用户重连只读密钥并新建任务重新采集。旧v0.57结构或模型不足，兼容检查阻止直接回退。

自动化检查使用隔离合成响应；真实币安连通性、密钥/IP许可、历史保留与覆盖、真实浏览器点击须单独验收。本轮开发不会调用用户的真实密钥或创建真实采集任务。

## 官方协议来源（2026-10-18核对）

- Binance官方Spot REST文档：https://github.com/binance/binance-spot-api-docs/blob/master/rest-api.md#account-trade-list-user_data
- 充提历史：https://developers.binance.com/en/docs/catalog/core-trading-wallet/api/rest-api/capital
- 通用划转查询：https://developers.binance.com/en/docs/catalog/core-trading-wallet/api/rest-api/asset