VCP Explorer API v1.1

概述

VCP Explorer API为VeritasChain Protocol (VCP)提供事件搜索、Merkle证明检索和事件证书生成。完全符合VCP规范v1.0,使外部方(监管机构、经纪商、自营交易公司、审计员)能够独立验证记录的事件。

密码学验证

符合RFC 6962的Merkle证明支持无需信任API的外部验证。实践"验证,不信任"原则。

高级搜索

通过TraceID追踪完整交易生命周期。按符号、时间范围、事件类型和算法ID过滤。

监管证书

生成包含事件数据、Merkle证明和密码签名的合规审计证书。

VCP模块结构

通过VCP-TRADE、VCP-RISK和VCP-GOV模块清晰分离关注点来组织事件数据。

纳秒精度

基于字符串的时间戳避免JavaScript 2^53限制,支持真正的纳秒级精度。

区块链锚定(计划中)

未来版本的VCP Explorer将支持将审计根锚定到以太坊以提供额外的不可变性保证。

基础URL

https://explorer.veritaschain.org/api/v1

注意: Explorer API部署正在进行中。在实时端点可用之前,本文档作为实现参考。开发者不应在部署公告前尝试调用这些端点。

认证

所有API请求需要在请求头中使用API密钥进行认证:

HTTP头

X-VCP-API-Key: <your_api_key>

安全: 不要在客户端代码中暴露API密钥。始终使用服务器端请求并妥善管理密钥。

API端点

GET /v1/events

通过符号、事件类型、trace_id、时间戳等搜索和过滤VCP事件。

查询参数

参数	类型	必填	说明	示例
`symbol`	String	否	交易符号	XAUUSD, EURUSD
`event_type`	String	否	事件类型名称	ORD, EXE, REJ
`trace_id`	UUID v7	否	交易跟踪ID	01934e3a-6a1b...
`start_time`	ISO8601	否	时间范围开始	2025-11-24T00:00:00Z
`end_time`	ISO8601	否	时间范围结束	2025-11-24T23:59:59Z
`limit`	Integer	否	最大结果数(1-500)	20 (默认)

请求示例

GET https://explorer.veritaschain.org/api/v1/events?symbol=XAUUSD&limit=20

curl -H "X-VCP-API-Key: your_api_key" \\
  "https://explorer.veritaschain.org/api/v1/events?symbol=XAUUSD&limit=20"

GET /v1/events/{event_id}

通过ID检索完整事件详情,包括头部、载荷(VCP-TRADE, VCP-RISK, VCP-GOV)和安全元数据。

GET /v1/events/{event_id}/proof

返回VCP Merkle包含证明(RFC 6962样式),支持无需信任API的外部验证。

"验证,不信任": 此端点通过密码学证明支持事件真实性的独立验证。

GET /v1/events/{event_id}/certificate

生成包含事件数据、Merkle证明、签名元数据和验证结果的监管级证书。

使用场景

监管审计: 提供算法交易事件的可验证证据
支付争议: 证明执行的真实性和时间
合规报告: 为金融监管机构生成审计跟踪
第三方验证: 支持外部方的独立验证

事件类型参考

VCP规范v1.0定义了固定的事件类型代码以确保实现间的一致性:

代码	类型	说明	类别
1	`SIG`	信号/决策生成	交易
2	`ORD`	订单发送	交易
3	`ACK`	订单确认	交易
4	`EXE`	完全执行	交易
5	`PRT`	部分成交	交易
6	`REJ`	订单拒绝	交易
7	`CXL`	订单取消	交易
20	`ALG`	算法更新	治理
21	`RSK`	风险参数更改	风险
98	`HBT`	心跳	系统
99	`ERR`	错误	系统

Merkle证明验证指南

VCP Explorer API遵循RFC 6962证书透明度标准进行Merkle树证明。这使任何人都能独立验证事件真实性而无需信任API。

验证步骤

1. 获取事件

使用GET /v1/events/:id检索完整事件详情。从安全部分提取event_hash。

2. 获取证明

使用GET /v1/events/:id/proof获取Merkle证明。包含审计路径和根哈希。

3. 计算根

在二叉Merkle树结构中使用SHA-256组合event_hash和audit_path。

4. 验证根

比较计算的根与返回的merkle_root。如果匹配,事件已验证。

重要性: 此验证过程确保事件在记录后无法被篡改。区块链锚定提供额外的不可变性层,因为Merkle根永久记录在以太坊主网上。

HTTP状态码

状态	含义	说明
200	OK	请求成功
400	Bad Request	无效的请求参数或格式错误的JSON
401	Unauthorized	无效或缺少API密钥
404	Not Found	未找到事件ID
429	Too Many Requests	超过速率限制
500	Server Error	内部服务器错误

概述