# HTTP API 设计

HTTP 接口定义于 `specs/openapi.draft.json`。这是协议合约，不是在线端点。已发布接口列于[实现状态](https://proof21.xyz/zh-hans/docs/start/status/)。

| 拟议操作 | 用途 |
| --- | --- |
| `POST /v0/evaluations` | 提交受支持的证据评估 |
| `POST /v0/verifications` | 验证所提供报告及预期上下文 |
| `GET /v0/jobs/{jobId}` | 查询异步任务 |
| `GET /health` | 运行健康状况，不代表证明正确性 |

## 请求原则

要求配置／版本、操作标识符、明确预期上下文和有界证据引用。不得执行任意用户代码或策略。金融数值采用整数字符串，并明确网络及精确资产身份。URL 属于受获取策略约束的非可信输入。

幂等键绑定调用方和请求摘要。使用不同输入复用同一键会失败。每个已发布端点都明确其身份认证、支付和权限要求。

## 响应

处理状态、产物有效性、评估和本地接受保持为独立字段。以 FAIL 完成的评估不是服务器错误。缺失证据产生 INDETERMINATE。结构化错误码包含说明和机器可读要求。

异步时间戳及未来来源选择应作为任务处理。同步端点不得在比特币确认不存在时承诺已确认的证据。

## OpenAPI 局限

草案模式描述接口结构，不证明密码学有效性。它不认证最终性、签名算法、退款行为或生产授权。宣称实现兼容之前，需要测试错误目录及签名／规范化配置。

<!-- p21-source-payment-v08 -->

## 支付证据与仅一次记账

发票绑定调用者、请求摘要、幂等键、准确的网络和资产身份、商户收款方、原子单位整数金额、服务额度权益、期限和结算策略。适配器检查已执行转账事件的目的地、金额、部署身份、主链区块、确认数、索引覆盖及支持的规则版本。交易 ID、内存池观测、铭文创建或钱包余额截图并不等于支付结算。

使用网络、资产部署、交易和操作或铭文身份保证事件唯一性。通过发票契约将发票所有权绑定调用者，而非接受任意提交的交易哈希。结算入账、任务预留、消耗和释放使用原子账本事务与唯一约束。网络重试或 webhook 重放不得重复记账或扣费。缺失证据、索引延迟或冲突、重组应保持待定或进入复核。为深度重组定义补偿账目和运营方损失策略，不得悄悄扣取另一笔客户付款。


## 商业启用与实现状态

NAT 和 USDC 都必须通过初次商业发布验收。公开文档、源代码和策略测试样例不是实时支付端点。静态支付策略将必备方式列为 `enabled: false`，不提供收款方或实时端点，直到各通道通过端到端结算、记账、失败与重组、安全及所有者批准关卡。不能把仅支持 USDC 的版本称为完整首发支付范围。

此版本未发行代币、未公布数据源元素，也未执行主网铭文、客户扣款、资金兑换或钱包授权。生产服务可用性与网站发布分开。此处不暗示 Trac 合作关系、托管 SLA 或独立密码学审计。


[1] https://digital-matter-theory.gitbook.io/digital-matter-theory/introduction/digital-elements/.element-registry

[2] https://github.com/Trac-Systems/ord-tap/blob/b8f6ea35cf6b9d405d4db7c58555e3c8ab33e8cd/src/index/updater/inscription_updater/tap/ops/dmt_element.rs

[3] https://digital-matter-theory.gitbook.io/digital-matter-theory/introduction/nat-use-cases/usdnat-method-1-live

[4] https://digital-matter-theory.gitbook.io/digital-matter-theory/introduction/non-arbitrary-tokens-nats/nat-token-transfer

[5] https://docs.x402.org/core-concepts/network-and-token-support

[6] https://github.com/Trac-Systems/ord-tap/blob/b8f6ea35cf6b9d405d4db7c58555e3c8ab33e8cd/README.md

[7] https://arxiv.org/abs/1605.04559

<!-- p21-enforcement-v10 -->

## Authorization schema 不是在线端点

仓库发布 `p21.authorization.v1`、`p21.consumer-decision.v1` 和 `p21.equivocation-evidence.v1` 的 JSON Schema 草案，用于互操作和一致性测试。当前 OpenAPI 不暴露生产 authorization/signing/decision/dispute 路由，客户端不能从 schema 的存在推断任何执行权限。