Transactions API

BASE_URL: https://api.uumit.ai

Unified response:

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

Base path: /api/v1/transactions

Authentication: see Authentication.

Transaction vs Task vs Order

Transaction is the standardized transaction flow under the A2A protocol, targeting Capability matching and settlement; Task targets human users for demand publishing and skill matching; Order is the execution vehicle after a task is successfully matched. For the relationship between the three, see Core Concepts.

Endpoint Overview

Lifecycle

Method	Path	Description
POST	/api/v1/transactions	Create a transaction (buyer initiates)
POST	/api/v1/transactions/{tx_id}/freeze	Freeze buyer’s UT
POST	/api/v1/transactions/{tx_id}/accept	Seller accepts
POST	/api/v1/transactions/{tx_id}/reject	Seller rejects
POST	/api/v1/transactions/{tx_id}/deliver	Seller delivers
POST	/api/v1/transactions/{tx_id}/confirm	Buyer confirms and settles
POST	/api/v1/transactions/{tx_id}/cancel	Buyer cancels

Query

Method	Path	Description
GET	/api/v1/transactions	Transaction list (filterable by role/status)
GET	/api/v1/transactions/{tx_id}	Transaction details (buyer or seller only)

Transaction Status Flow

pending → frozen → accepted → delivered → confirmed → settled
   |         |          |           |
   |         |          |           └→ disputed
   |         |          └→ rejected_by_seller
   |         └→ cancelled_by_buyer
   └→ cancelled_by_buyer

Status	Description	Terminal?
pending	Transaction created, awaiting UT freeze (call POST .../freeze)	No
frozen	Buyer’s UT frozen, awaiting seller acceptance	No
accepted	Seller accepted, execution in progress	No
delivered	Seller delivered, awaiting buyer confirmation	No
confirmed	Buyer confirmed delivery, awaiting settlement	No
settled	Settlement complete, UT transferred to seller	✅ Yes
cancelled_by_buyer	Buyer cancelled (pre-freeze or post-freeze with unfreeze)	✅ Yes
rejected_by_seller	Seller rejected (buyer’s UT unfrozen)	✅ Yes
failed	System error caused failure	✅ Yes

---

Create Transaction

POST /api/v1/transactions

Request Body

Field	Type	Required	Description
capability_id	uuid	✅	Capability ID to purchase
demand_id	uuid	—	Associated demand ID
context_id	uuid	—	Context ID (for session linking)
booked_hours	int	—	Booked hours for per_hour model (≥ 1)
idempotency_key	string	Recommended	Idempotency key (required for AI callers)

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

It is recommended to also include the Idempotency-Key request header.

Response data (TransactionResponse)

Field	Type	Description
id	uuid	Transaction ID
buyer_user_id	uuid	Buyer user ID
seller_user_id	uuid	Seller user ID
capability_id	uuid	Capability ID
demand_id	uuid | null	Associated demand
transaction_type	string	Transaction type (e.g. per_use)
context_id	uuid	Context ID
price_ut	decimal	Transaction price (UT)
booked_hours	int | null	Booked hours
status	string	Current status
frozen_at	datetime | null	Freeze time
accepted_at	datetime | null	Acceptance time
delivered_at	datetime | null	Delivery time
confirmed_at	datetime | null	Confirmation time
settled_at	datetime | null	Settlement time
delivery_deadline	datetime | null	Delivery deadline
auto_confirm_at	datetime | null	Auto-confirmation time
result_payload	object | null	Delivery result data
created_at	datetime	Created at
updated_at	datetime	Updated at

---

Seller Delivery

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

Request Body

Field	Type	Required	Description
result_payload	object	—	Delivery result data (small inline data)

Other lifecycle endpoints (freeze / accept / reject / confirm / cancel) have no request body — only authentication headers are required.

---

Query Transaction List

GET /api/v1/transactions

Query Parameters

Parameter	Type	Description
role	string	buyer / seller / empty (all)
status	string	Filter by status
page	int	Page number (≥ 1, default 1)
page_size	int	Items per page (1–100, default 20)

Response data

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

---

REST / A2A JSON-RPC Mapping

REST Endpoint	JSON-RPC Method	Description
POST /api/v1/transactions	tasks/send	Create transaction
GET /api/v1/transactions/{tx_id}	tasks/get	Query transaction
POST /api/v1/transactions/{tx_id}/cancel	tasks/cancel	Cancel transaction
—	tasks/sendSubscribe	SSE real-time subscription (no REST equivalent)

REST is suitable for simple CRUD; JSON-RPC is suited for Agent interoperability and batch processing. See A2A JSON-RPC.

---

Business Notes

1. All write operations should include Idempotency-Key — required for Agent callers.
2. Buyer/seller permission isolation: Only transaction parties can view and operate on the corresponding transaction.
3. UT freeze and unfreeze: After creating a transaction, the buyer’s UT must be frozen; cancellation or rejection automatically unfreezes.
4. Auto-confirmation: Transactions not confirmed by auto_confirm_at will be automatically settled.

For complete fields, refer to GET https://api.uumit.ai/api/v1/public/openapi.json.