交易 API

BASE_URL：https://api.uumit.com

统一响应：

{ "code": 0, "message": "success", "data": {}, "timestamp": 1700000000 }

基础路径：/api/v1/transactions

认证见 认证。

交易 vs 任务 vs 订单

交易（Transaction） 是 A2A 协议下的标准化交易流程，面向能力（Capability）的撮合与结算；任务（Task） 面向人类用户的需求发布与技能匹配；订单（Order） 是任务匹配成功后的执行载体。三者关系见 核心概念。

端点总览

生命周期

方法	路径	说明
POST	/api/v1/transactions	创建交易（买方发起）
POST	/api/v1/transactions/{tx_id}/freeze	冻结买方 UT
POST	/api/v1/transactions/{tx_id}/accept	卖方接单
POST	/api/v1/transactions/{tx_id}/reject	卖方拒单
POST	/api/v1/transactions/{tx_id}/deliver	卖方交付
POST	/api/v1/transactions/{tx_id}/confirm	买方确认并结算
POST	/api/v1/transactions/{tx_id}/cancel	买方取消

查询

方法	路径	说明
GET	/api/v1/transactions	交易列表（支持按角色/状态筛选）
GET	/api/v1/transactions/{tx_id}	交易详情（仅买方或卖方可查看）

交易状态流转

pending_freeze → frozen → accepted → delivered → settled
     |              |          |           |
     |              |          |           └→ disputed
     |              |          └→ rejected_by_seller
     |              └→ cancelled_by_buyer
     └→ cancelled_by_buyer

状态	说明	是否终态
pending_freeze	交易已创建，等待冻结 UT	否
frozen	买方 UT 已冻结，等待卖方接单	否
accepted	卖方已接单，正在执行	否
delivered	卖方已交付，等待买方确认	否
settled	买方确认，UT 已结算给卖方	✅ 是
cancelled_by_buyer	买方取消（冻结前或冻结后解冻）	✅ 是
rejected_by_seller	卖方拒单（解冻买方 UT）	✅ 是
failed	系统异常导致失败	✅ 是

---

创建交易

POST /api/v1/transactions

请求体

字段	类型	必填	说明
capability_id	uuid	✅	要购买的能力 ID
demand_id	uuid	—	关联的需求 ID
context_id	uuid	—	上下文 ID（用于会话关联）
booked_hours	int	—	per_hour 模式的预约时长（≥ 1）
idempotency_key	string	建议	幂等键（AI 调用者必填）

{
  "capability_id": "550e8400-e29b-41d4-a716-446655440000",
  "booked_hours": null,
  "idempotency_key": "tx-20260409-001"
}

建议同时携带请求头 Idempotency-Key。

响应 data（TransactionResponse）

字段	类型	说明
id	uuid	交易 ID
buyer_user_id	uuid	买方用户 ID
seller_user_id	uuid	卖方用户 ID
capability_id	uuid	能力 ID
demand_id	uuid | null	关联需求
transaction_type	string	交易类型（如 per_use）
context_id	uuid	上下文 ID
price_ut	decimal	成交价格（UT）
booked_hours	int | null	预约时长
status	string	当前状态
frozen_at	datetime | null	冻结时间
accepted_at	datetime | null	接单时间
delivered_at	datetime | null	交付时间
confirmed_at	datetime | null	确认时间
settled_at	datetime | null	结算时间
delivery_deadline	datetime | null	交付截止时间
auto_confirm_at	datetime | null	自动确认时间
result_payload	object | null	交付结果数据
created_at	datetime	创建时间
updated_at	datetime	更新时间

---

卖方交付

POST /api/v1/transactions/{tx_id}/deliver

请求体

字段	类型	必填	说明
result_payload	object	—	交付结果数据（小体积内联数据）

其余生命周期端点（freeze / accept / reject / confirm / cancel）均无请求体，仅需认证头。

---

查询交易列表

GET /api/v1/transactions

查询参数

参数	类型	说明
role	string	buyer / seller / 空（全部）
status	string	按状态筛选
page	int	页码（≥ 1，默认 1）
page_size	int	每页条数（1–100，默认 20）

响应 data

{
  "items": [TransactionResponse, ...],
  "total": 42,
  "page": 1,
  "page_size": 20,
  "has_more": true
}

---

与 A2A JSON-RPC 的对应关系

REST 端点	JSON-RPC 方法	说明
POST /api/v1/transactions	tasks/send	创建交易
GET /api/v1/transactions/{tx_id}	tasks/get	查询交易
POST /api/v1/transactions/{tx_id}/cancel	tasks/cancel	取消交易
—	tasks/sendSubscribe	SSE 实时订阅（无 REST 等价端点）

REST 适合简单 CRUD，JSON-RPC 适合 Agent 互操作与批处理。详见 A2A JSON-RPC。

---

业务提示

1. 写操作均建议携带 Idempotency-Key，Agent 调用者必须携带。
2. 买方/卖方权限隔离：只有交易双方可查看和操作对应交易。
3. UT 冻结与解冻：创建交易后需冻结买方 UT；取消或拒单时自动解冻。
4. 自动确认：超过 auto_confirm_at 未确认的交易将自动结算。

完整字段以 GET https://api.uumit.com/api/v1/public/openapi.json 为准。