{ "openapi": "3.1.0", "info": { "title": "Tern HTTP API", "version": "1.16.0", "description": "资产查询、发行、交易、流动性与行情 HTTP 接口。JSON 响应直接返回对象；错误为 {code,message}。无需 API Key 或 Cookie。金额使用精确十进制字符串，最小单位数量使用整数字符串。行情时间为 UTC Unix 毫秒，交易与审核时间为 UTC Unix 秒。交易使用 TensorCash 原始交易格式；HTTP 200 不表示链上确认。" }, "servers": [ { "url": "/mainnet/v1" } ], "paths": { "/market": { "get": { "operationId": "getMarket", "summary": "查询行情目录", "parameters": [], "responses": { "200": { "description": "返回以下 JSON 对象；交易的最终结果以 state 和链上确认状态为准。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Market" } } } }, "400": { "description": "请求参数、资产策略或签名无效。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "未找到资产、池子或操作记录。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "审核过期、交易内容改变、价格不满足限制或分页游标失效。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "节点、签名服务、索引或上游暂不可用，按 Retry-After 秒数退避。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "建议等待的秒数。", "schema": { "type": "integer" } } } }, "429": { "description": "请求频率或容量达到上限，按 Retry-After 秒数退避。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "建议等待的秒数。", "schema": { "type": "integer" } } } } }, "tags": [ "Market" ], "description": "返回网络、索引状态、支持的 K 线周期、资产和池子目录；行情仅包含已确认且已索引的数据。" } }, "/pools/{id}/ticker": { "get": { "operationId": "getPoolTicker", "summary": "查询池子最新行情", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "description": "微池 Pool ID，64 位小写十六进制。" }, { "name": "quote", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "TSC" ], "default": "TSC" }, "description": "计价币种；当前只支持 TSC。" } ], "responses": { "200": { "description": "返回以下 JSON 对象；交易的最终结果以 state 和链上确认状态为准。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Ticker" } } } }, "400": { "description": "请求参数、资产策略或签名无效。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "未找到资产、池子或操作记录。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "审核过期、交易内容改变、价格不满足限制或分页游标失效。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "节点、签名服务、索引或上游暂不可用，按 Retry-After 秒数退避。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "建议等待的秒数。", "schema": { "type": "integer" } } } }, "429": { "description": "请求频率或容量达到上限，按 Retry-After 秒数退避。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "建议等待的秒数。", "schema": { "type": "integer" } } } } }, "tags": [ "Market" ], "description": "返回当前储备价、储备、最近成交、24 小时统计、仓位手续费和 APR；交易后储备价与整笔成交均价是不同字段。" } }, "/pools/{id}/candles": { "get": { "operationId": "getPoolCandles", "summary": "查询池子 K 线", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "description": "微池 Pool ID，64 位小写十六进制。" }, { "name": "quote", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "TSC" ], "default": "TSC" }, "description": "计价币种；当前只支持 TSC。" }, { "name": "interval", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "1m", "5m", "15m", "30m", "1h", "4h", "1d", "1w" ], "default": "1h" }, "description": "K 线周期：1m、5m、15m、30m、1h、4h、1d、1w。" }, { "name": "start_time", "in": "query", "required": false, "schema": { "type": "integer", "format": "int64", "minimum": 0 }, "description": "Inclusive UTC Unix milliseconds; candle open time for candles." }, { "name": "end_time", "in": "query", "required": false, "schema": { "type": "integer", "format": "int64", "minimum": 0 }, "description": "K 线查询结束时间，UTC Unix 毫秒；不传时查询最新区间。" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 300 }, "description": "本页最多返回的记录数量；默认和上限见约束。" }, { "name": "price_basis", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "execution", "spot" ], "default": "execution" }, "description": "spot 为交易后储备价；execution 为成交均价。" }, { "name": "gap_policy", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "omit", "carry_forward" ], "default": "omit" }, "description": "carry_forward 补齐无成交周期；不传则返回原有稀疏数据。" } ], "responses": { "200": { "description": "返回以下 JSON 对象；交易的最终结果以 state 和链上确认状态为准。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Candles" } } } }, "400": { "description": "请求参数、资产策略或签名无效。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "未找到资产、池子或操作记录。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "审核过期、交易内容改变、价格不满足限制或分页游标失效。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "节点、签名服务、索引或上游暂不可用，按 Retry-After 秒数退避。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "建议等待的秒数。", "schema": { "type": "integer" } } } }, "429": { "description": "请求频率或容量达到上限，按 Retry-After 秒数退避。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "建议等待的秒数。", "schema": { "type": "integer" } } } } }, "tags": [ "Market" ], "description": "按 interval 查询 OHLCV。时间为 UTC Unix 毫秒；price_basis 区分储备价和成交均价。gap_policy=carry_forward 时空周期沿用前收盘价、成交量为零；每页最多 1000 个周期，以 next_end_time 翻页。" } }, "/pools/{id}/trades": { "get": { "operationId": "getPoolTrades", "summary": "查询池子成交记录", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "description": "微池 Pool ID，64 位小写十六进制。" }, { "name": "quote", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "TSC" ], "default": "TSC" }, "description": "计价币种；当前只支持 TSC。" }, { "name": "start_time", "in": "query", "required": false, "schema": { "type": "integer", "format": "int64", "minimum": 0 }, "description": "Inclusive UTC Unix milliseconds; candle open time for candles." }, { "name": "end_time", "in": "query", "required": false, "schema": { "type": "integer", "format": "int64", "minimum": 0 }, "description": "K 线查询结束时间，UTC Unix 毫秒；不传时查询最新区间。" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 100 }, "description": "本页最多返回的记录数量；默认和上限见约束。" }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" }, "description": "分页游标，原样传入上次返回的 next_cursor。" } ], "responses": { "200": { "description": "返回以下 JSON 对象；交易的最终结果以 state 和链上确认状态为准。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Trades" } } } }, "400": { "description": "请求参数、资产策略或签名无效。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "未找到资产、池子或操作记录。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "审核过期、交易内容改变、价格不满足限制或分页游标失效。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "节点、签名服务、索引或上游暂不可用，按 Retry-After 秒数退避。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "建议等待的秒数。", "schema": { "type": "integer" } } } }, "429": { "description": "请求频率或容量达到上限，按 Retry-After 秒数退避。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "建议等待的秒数。", "schema": { "type": "integer" } } } } }, "tags": [ "Market" ], "description": "返回已确认成交，使用 next_cursor 翻页。重组或查询快照失效时重新读取，不能自行拼接不一致页面。" } }, "/prices/tsc": { "get": { "operationId": "getTscUsdReference", "summary": "查询 TSC 美元参考价", "description": "返回共享 SafeTrade TSC/USDT 缓存，只用于辅助美元展示。stale 或 unavailable 时 usd_price=null；不参与报价、滑点、TVL 的 TSC 计算。", "tags": [ "Market" ], "responses": { "200": { "description": "返回以下 JSON 对象；交易的最终结果以 state 和链上确认状态为准。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TscUsdReference" } } } }, "400": { "description": "请求参数、资产策略或签名无效。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "未找到资产、池子或操作记录。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "审核过期、交易内容改变、价格不满足限制或分页游标失效。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "请求体超过允许字节数。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "请求 Content-Type 不受支持。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "JSON 字段格式无效或包含未知字段。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "请求频率或容量达到上限，按 Retry-After 秒数退避。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "建议等待的秒数。", "schema": { "type": "integer" } } } }, "503": { "description": "节点、签名服务、索引或上游暂不可用，按 Retry-After 秒数退避。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "建议等待的秒数。", "schema": { "type": "integer" } } } } } } }, "/info": { "get": { "operationId": "getServiceInfo", "summary": "读取服务配置", "description": "返回网络身份、交易格式、费用和服务限制。交易签名前应核对固定的网络及签名公钥。", "tags": [ "Service" ], "responses": { "200": { "description": "返回以下 JSON 对象；交易的最终结果以 state 和链上确认状态为准。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServiceInfo" } } } }, "400": { "description": "请求参数、资产策略或签名无效。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "未找到资产、池子或操作记录。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "审核过期、交易内容改变、价格不满足限制或分页游标失效。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "请求体超过允许字节数。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "请求 Content-Type 不受支持。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "JSON 字段格式无效或包含未知字段。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "请求频率或容量达到上限，按 Retry-After 秒数退避。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "建议等待的秒数。", "schema": { "type": "integer" } } } }, "503": { "description": "节点、签名服务、索引或上游暂不可用，按 Retry-After 秒数退避。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "建议等待的秒数。", "schema": { "type": "integer" } } } } } } }, "/state": { "get": { "operationId": "getState", "summary": "查询余额与服务状态", "description": "返回池子目录、同步进度和交易服务状态。传 address 时查询该地址的余额及已提交操作。", "tags": [ "Service" ], "responses": { "200": { "description": "返回以下 JSON 对象；交易的最终结果以 state 和链上确认状态为准。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/State" } } } }, "400": { "description": "请求参数、资产策略或签名无效。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "未找到资产、池子或操作记录。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "审核过期、交易内容改变、价格不满足限制或分页游标失效。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "请求体超过允许字节数。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "请求 Content-Type 不受支持。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "JSON 字段格式无效或包含未知字段。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "请求频率或容量达到上限，按 Retry-After 秒数退避。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "建议等待的秒数。", "schema": { "type": "integer" } } } }, "503": { "description": "节点、签名服务、索引或上游暂不可用，按 Retry-After 秒数退避。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "建议等待的秒数。", "schema": { "type": "integer" } } } } }, "parameters": [ { "name": "address", "in": "query", "required": false, "schema": { "type": "string" }, "description": "当前网络的 P2WPKH 钱包地址；余额和个人操作按此地址查询。" }, { "name": "asset_id", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "description": "资产的链上 ID，64 位小写十六进制；只在对应网络有效。" } ] } }, "/assets": { "get": { "operationId": "listAssets", "summary": "查询精选与推荐资产", "description": "返回部署配置的精选资产和按已确认成交量、流动性排序的推荐资产。", "tags": [ "Assets" ], "responses": { "200": { "description": "返回以下 JSON 对象；交易的最终结果以 state 和链上确认状态为准。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssetRecommendations" } } } }, "400": { "description": "请求参数、资产策略或签名无效。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "未找到资产、池子或操作记录。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "审核过期、交易内容改变、价格不满足限制或分页游标失效。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "请求体超过允许字节数。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "请求 Content-Type 不受支持。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "JSON 字段格式无效或包含未知字段。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "请求频率或容量达到上限，按 Retry-After 秒数退避。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "建议等待的秒数。", "schema": { "type": "integer" } } } }, "503": { "description": "节点、签名服务、索引或上游暂不可用，按 Retry-After 秒数退避。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "建议等待的秒数。", "schema": { "type": "integer" } } } } } } }, "/assets/search": { "get": { "operationId": "searchAssets", "summary": "搜索资产", "description": "完整 Asset ID 直接查询详情；其他关键词按上游每页最多 100 个资产过滤链上符号或 ID 子串。page 从 1 开始，has_more 指上游还有下一页，不是匹配结果分页；当前不按元数据展示名称搜索。普通搜索行保留链上符号。", "tags": [ "Assets" ], "responses": { "200": { "description": "返回以下 JSON 对象；交易的最终结果以 state 和链上确认状态为准。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssetSearch" } } } }, "400": { "description": "请求参数、资产策略或签名无效。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "未找到资产、池子或操作记录。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "审核过期、交易内容改变、价格不满足限制或分页游标失效。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "请求体超过允许字节数。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "请求 Content-Type 不受支持。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "JSON 字段格式无效或包含未知字段。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "请求频率或容量达到上限，按 Retry-After 秒数退避。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "建议等待的秒数。", "schema": { "type": "integer" } } } }, "503": { "description": "节点、签名服务、索引或上游暂不可用，按 Retry-After 秒数退避。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "建议等待的秒数。", "schema": { "type": "integer" } } } } }, "parameters": [ { "name": "q", "in": "query", "required": false, "schema": { "type": "string" }, "description": "链上符号或 Asset ID 子串；完整 Asset ID 直接查询。当前不搜索元数据 display_name。" }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 1 }, "description": "页码，从 1 开始，默认 1。" } ] } }, "/assets/{id}": { "get": { "operationId": "getAsset", "summary": "查询资产信息", "description": "使用 Asset ID 查询符号、精度、收录状态、可用发行元数据、头像和当前 TSC 参考价格，并校验网络与资产策略。price 使用已确认储备最多的 TSC 池，不扫描成交历史、不额外查询链接口；无流动性或索引不新鲜时 value=null，不影响基础资产资料读取。美元参考换算另见 /prices/tsc。", "tags": [ "Assets" ], "responses": { "200": { "description": "返回以下 JSON 对象；交易的最终结果以 state 和链上确认状态为准。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssetLookup" } } } }, "400": { "description": "请求参数、资产策略或签名无效。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "未找到资产、池子或操作记录。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "审核过期、交易内容改变、价格不满足限制或分页游标失效。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "请求体超过允许字节数。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "请求 Content-Type 不受支持。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "JSON 字段格式无效或包含未知字段。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "请求频率或容量达到上限，按 Retry-After 秒数退避。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "建议等待的秒数。", "schema": { "type": "integer" } } } }, "503": { "description": "节点、签名服务、索引或上游暂不可用，按 Retry-After 秒数退避。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "建议等待的秒数。", "schema": { "type": "integer" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "description": "Asset ID，64 位小写十六进制。" } ] } }, "/assets/import": { "post": { "operationId": "importAsset", "summary": "导入资产到平台目录", "description": "校验并保存已有资产资料；不会发行资产、建池或转账。", "tags": [ "Assets" ], "responses": { "200": { "description": "返回以下 JSON 对象；交易的最终结果以 state 和链上确认状态为准。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssetLookup" } } } }, "400": { "description": "请求参数、资产策略或签名无效。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "未找到资产、池子或操作记录。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "审核过期、交易内容改变、价格不满足限制或分页游标失效。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "请求体超过允许字节数。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "请求 Content-Type 不受支持。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "JSON 字段格式无效或包含未知字段。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "请求频率或容量达到上限，按 Retry-After 秒数退避。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "建议等待的秒数。", "schema": { "type": "integer" } } } }, "503": { "description": "节点、签名服务、索引或上游暂不可用，按 Retry-After 秒数退避。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "建议等待的秒数。", "schema": { "type": "integer" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssetImport" } } } } } }, "/icons": { "post": { "operationId": "uploadAssetIcon", "summary": "上传资产头像", "description": "请求体直接发送 PNG/JPEG/WebP 原始字节，Content-Type 使用对应图片类型，最多 51200 字节、2048×2048 像素。不接受 JSON、Base64、SVG 或 multipart。服务端处理成最大 256×256 的 WebP 并固定到 IPFS，返回 URI 和图片信息。同一图片重复上传复用结果。创建资产也可直接传 icon_base64，不必先调用此接口。", "tags": [ "Creation" ], "responses": { "200": { "description": "返回以下 JSON 对象；交易的最终结果以 state 和链上确认状态为准。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UploadedIcon" } } } }, "400": { "description": "请求参数、资产策略或签名无效。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "未找到资产、池子或操作记录。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "审核过期、交易内容改变、价格不满足限制或分页游标失效。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "上传图片超过 51200 字节。" }, "415": { "description": "请求 Content-Type 不受支持。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "JSON 字段格式无效或包含未知字段。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "请求频率或容量达到上限，按 Retry-After 秒数退避。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "建议等待的秒数。", "schema": { "type": "integer" } } } }, "503": { "description": "节点、签名服务、索引或上游暂不可用，按 Retry-After 秒数退避。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "建议等待的秒数。", "schema": { "type": "integer" } } } } }, "requestBody": { "required": true, "content": { "image/png": { "schema": { "type": "string", "format": "binary" } }, "image/jpeg": { "schema": { "type": "string", "format": "binary" } }, "image/webp": { "schema": { "type": "string", "format": "binary" } } } } } }, "/icons/{name}": { "get": { "operationId": "getAssetIcon", "summary": "读取资产头像", "tags": [ "Creation" ], "parameters": [ { "name": "name", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^(?:[0-9a-f]{64}\\.(?:webp|png)|[A-Za-z0-9]{10,200}\\.webp)$" }, "description": "历史图片文件名：SHA-256 摘要加 .webp 或 .png。" } ], "responses": { "200": { "description": "返回图片二进制；长期不可变缓存，不返回 JSON。", "content": { "image/webp": { "schema": { "type": "string", "format": "binary" } }, "image/png": { "schema": { "type": "string", "format": "binary" } } } }, "404": { "description": "未找到资产、池子或操作记录。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "请求频率或容量达到上限，按 Retry-After 秒数退避。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "建议等待的秒数。", "schema": { "type": "integer" } } } }, "503": { "description": "节点、签名服务、索引或上游暂不可用，按 Retry-After 秒数退避。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "建议等待的秒数。", "schema": { "type": "integer" } } } } }, "description": "返回图片二进制。支持历史图片，以及本平台记录的 IPFS 图片；后者核对上传时的 CID、字节数与 SHA-256，支持不可变缓存。未知图片不会触发任意地址抓取。" } }, "/launches/config": { "get": { "operationId": "getCreationOptions", "summary": "查询发行能力与配置", "description": "先检查 availability.enabled。root 和 sponsored 是模式配置；当前部署发行未开放时 availability.enabled=false。media 描述图片上传能力。", "tags": [ "Creation" ], "responses": { "200": { "description": "返回以下 JSON 对象；交易的最终结果以 state 和链上确认状态为准。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreationConfig" } } } }, "400": { "description": "请求参数、资产策略或签名无效。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "未找到资产、池子或操作记录。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "审核过期、交易内容改变、价格不满足限制或分页游标失效。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "请求体超过允许字节数。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "请求 Content-Type 不受支持。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "JSON 字段格式无效或包含未知字段。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "请求频率或容量达到上限，按 Retry-After 秒数退避。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "建议等待的秒数。", "schema": { "type": "integer" } } } }, "503": { "description": "节点、签名服务、索引或上游暂不可用，按 Retry-After 秒数退避。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "建议等待的秒数。", "schema": { "type": "integer" } } } } } } }, "/launches": { "get": { "operationId": "listIssuerAssets", "summary": "查询地址发行的资产", "description": "只查询该地址通过平台发行的记录，包含待确认状态；不是钱包余额或全链发行者索引。最多 20 条，next_cursor 为 null 表示没有下一页。", "tags": [ "Creation" ], "responses": { "200": { "description": "返回以下 JSON 对象；交易的最终结果以 state 和链上确认状态为准。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IssuerAssets" } } } }, "400": { "description": "请求参数、资产策略或签名无效。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "未找到资产、池子或操作记录。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "审核过期、交易内容改变、价格不满足限制或分页游标失效。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "请求体超过允许字节数。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "请求 Content-Type 不受支持。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "JSON 字段格式无效或包含未知字段。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "请求频率或容量达到上限，按 Retry-After 秒数退避。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "建议等待的秒数。", "schema": { "type": "integer" } } } }, "503": { "description": "节点、签名服务、索引或上游暂不可用，按 Retry-After 秒数退避。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "建议等待的秒数。", "schema": { "type": "integer" } } } } }, "parameters": [ { "name": "actor", "in": "query", "required": true, "schema": { "type": "string" }, "description": "当前网络的发行者钱包地址；查询其通过平台发行的记录。" }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string" }, "description": "搜索关键词，可为名称、符号或完整 Asset ID。" }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "description": "分页游标，原样传入上次返回的 next_cursor。" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 20, "default": 20 }, "description": "本页最多返回的记录数量；默认和上限见约束。" } ] } }, "/launches/preview": { "post": { "operationId": "previewAssetCreation", "summary": "预览旧版发行资料", "description": "校验 draft 并生成链上描述文档，不签名、不广播。仅供已有 /launches 集成使用。", "tags": [ "Creation" ], "responses": { "200": { "description": "返回以下 JSON 对象；交易的最终结果以 state 和链上确认状态为准。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreationPreview" } } } }, "400": { "description": "请求参数、资产策略或签名无效。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "未找到资产、池子或操作记录。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "审核过期、交易内容改变、价格不满足限制或分页游标失效。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "请求体超过允许字节数。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "请求 Content-Type 不受支持。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "JSON 字段格式无效或包含未知字段。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "请求频率或容量达到上限，按 Retry-After 秒数退避。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "建议等待的秒数。", "schema": { "type": "integer" } } } }, "503": { "description": "节点、签名服务、索引或上游暂不可用，按 Retry-After 秒数退避。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "建议等待的秒数。", "schema": { "type": "integer" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreationDraft" } } } } } }, "/launches/prepare": { "post": { "operationId": "prepareAssetCreation", "summary": "准备旧版发行交易", "description": "step=register 注册，注册确认后用原 actor 和 draft 请求 step=mint。返回 300 秒有效的未签名审核，不广播。新集成使用 /issuances。", "tags": [ "Creation" ], "responses": { "200": { "description": "返回以下 JSON 对象；交易的最终结果以 state 和链上确认状态为准。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreationReview" } } } }, "400": { "description": "请求参数、资产策略或签名无效。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "未找到资产、池子或操作记录。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "审核过期、交易内容改变、价格不满足限制或分页游标失效。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "请求体超过允许字节数。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "请求 Content-Type 不受支持。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "JSON 字段格式无效或包含未知字段。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "请求频率或容量达到上限，按 Retry-After 秒数退避。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "建议等待的秒数。", "schema": { "type": "integer" } } } }, "503": { "description": "节点、签名服务、索引或上游暂不可用，按 Retry-After 秒数退避。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "建议等待的秒数。", "schema": { "type": "integer" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreationPrepare" } } } } } }, "/launches/submit": { "post": { "operationId": "submitAssetCreation", "summary": "提交旧版发行签名交易", "description": "提交原 review_id 与签名后的 hex，校验后持久保存并广播。HTTP 200 表示已提交，不表示确认；超时后查询原记录，重试同一签名请求。", "tags": [ "Creation" ], "responses": { "200": { "description": "返回以下 JSON 对象；交易的最终结果以 state 和链上确认状态为准。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreationSubmission" } } } }, "400": { "description": "请求参数、资产策略或签名无效。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "未找到资产、池子或操作记录。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "审核过期、交易内容改变、价格不满足限制或分页游标失效。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "请求体超过允许字节数。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "请求 Content-Type 不受支持。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "JSON 字段格式无效或包含未知字段。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "请求频率或容量达到上限，按 Retry-After 秒数退避。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "建议等待的秒数。", "schema": { "type": "integer" } } } }, "503": { "description": "节点、签名服务、索引或上游暂不可用，按 Retry-After 秒数退避。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "建议等待的秒数。", "schema": { "type": "integer" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreationSubmit" } } } } } }, "/launches/{id}": { "get": { "operationId": "getAssetCreation", "summary": "查询旧版发行状态", "description": "路径 id 是 Asset ID。返回注册与首次铸币的确认状态；重组可能回退确认，不能因此自动再铸币。", "tags": [ "Creation" ], "responses": { "200": { "description": "返回以下 JSON 对象；交易的最终结果以 state 和链上确认状态为准。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreationStatus" } } } }, "400": { "description": "请求参数、资产策略或签名无效。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "未找到资产、池子或操作记录。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "审核过期、交易内容改变、价格不满足限制或分页游标失效。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "请求体超过允许字节数。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "请求 Content-Type 不受支持。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "JSON 字段格式无效或包含未知字段。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "请求频率或容量达到上限，按 Retry-After 秒数退避。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "建议等待的秒数。", "schema": { "type": "integer" } } } }, "503": { "description": "节点、签名服务、索引或上游暂不可用，按 Retry-After 秒数退避。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "建议等待的秒数。", "schema": { "type": "integer" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "description": "Asset ID，64 位小写十六进制。" } ] } }, "/launches/{id}/retry": { "post": { "operationId": "retryAssetCreation", "summary": "重广播旧版已签名交易", "description": "只重广播服务器已经保存的原交易；不生成新交易，不请求新签名。", "tags": [ "Creation" ], "responses": { "200": { "description": "返回以下 JSON 对象；交易的最终结果以 state 和链上确认状态为准。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreationStatus" } } } }, "400": { "description": "请求参数、资产策略或签名无效。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "未找到资产、池子或操作记录。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "审核过期、交易内容改变、价格不满足限制或分页游标失效。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "请求体超过允许字节数。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "请求 Content-Type 不受支持。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "JSON 字段格式无效或包含未知字段。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "请求频率或容量达到上限，按 Retry-After 秒数退避。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "建议等待的秒数。", "schema": { "type": "integer" } } } }, "503": { "description": "节点、签名服务、索引或上游暂不可用，按 Retry-After 秒数退避。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "建议等待的秒数。", "schema": { "type": "integer" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "description": "Asset ID，64 位小写十六进制。" } ] } }, "/assets/{id}/metadata": { "get": { "operationId": "getCreatedAssetMetadata", "summary": "查询资产展示资料", "description": "当前只覆盖平台留有发行记录且注册已确认的资产；返回链上描述、图标地址和链接，不表示平台验证了项目或社交账户。", "tags": [ "Creation" ], "responses": { "200": { "description": "返回以下 JSON 对象；交易的最终结果以 state 和链上确认状态为准。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatedAssetMetadata" } } } }, "400": { "description": "请求参数、资产策略或签名无效。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "未找到资产、池子或操作记录。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "审核过期、交易内容改变、价格不满足限制或分页游标失效。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "请求体超过允许字节数。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "请求 Content-Type 不受支持。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "JSON 字段格式无效或包含未知字段。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "请求频率或容量达到上限，按 Retry-After 秒数退避。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "建议等待的秒数。", "schema": { "type": "integer" } } } }, "503": { "description": "节点、签名服务、索引或上游暂不可用，按 Retry-After 秒数退避。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "建议等待的秒数。", "schema": { "type": "integer" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "description": "Asset ID，64 位小写十六进制。" } ] } }, "/issuances": { "post": { "operationId": "prepareIssuance", "summary": "提交资产发行资料", "description": "一次提交资产资料；API 分配 Asset ID，处理可选图片并返回注册阶段的签名请求。不签名、不广播。request_id 是幂等键：相同 ID 和相同资料恢复原记录，资料不同返回 REQUEST_ID_CONFLICT。root 保证金 5 TSC，trc20 保证金 0.0001 TSC，载体与矿工费另计。注册和初始铸币是两笔依赖交易。", "tags": [ "Creation" ], "responses": { "200": { "description": "返回以下 JSON 对象；交易的最终结果以 state 和链上确认状态为准。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IssuanceResource" } } } }, "400": { "description": "请求参数、资产策略或签名无效。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "未找到资产、池子或操作记录。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "审核过期、交易内容改变、价格不满足限制或分页游标失效。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "请求体超过允许字节数。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "请求 Content-Type 不受支持。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "JSON 字段格式无效或包含未知字段。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "请求频率或容量达到上限，按 Retry-After 秒数退避。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "建议等待的秒数。", "schema": { "type": "integer" } } } }, "503": { "description": "节点、签名服务、索引或上游暂不可用，按 Retry-After 秒数退避。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "建议等待的秒数。", "schema": { "type": "integer" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IssuanceRequest" }, "examples": { "url": { "summary": "Use your own image URL", "value": { "request_id": "7c51d5ae-cb7d-4a26-891b-77193590d7ba", "chain_id": "tsc:2929292929292929292929292929292929292929292929292929292929292929:public", "actor": "", "mode": "root", "name": "Example Asset", "symbol": "EXAMPLE", "description": "An example native asset.", "decimals": 8, "supply": "1000000", "icon_url": "https://example.org/icon.webp" } }, "ipfs": { "summary": "Use an existing IPFS CID", "value": { "request_id": "7c51d5ae-cb7d-4a26-891b-77193590d7ba", "chain_id": "tsc:2929292929292929292929292929292929292929292929292929292929292929:public", "actor": "", "mode": "root", "name": "Example Asset", "symbol": "EXAMPLE", "description": "An example native asset.", "decimals": 8, "supply": "1000000", "icon_url": "ipfs://QmVeYLY5JCaUdS6vhuA2RANioHhw5ZYEU6eSUijut1d9am" } }, "upload": { "summary": "Submit image bytes in the same request", "value": { "request_id": "7c51d5ae-cb7d-4a26-891b-77193590d7ba", "chain_id": "tsc:2929292929292929292929292929292929292929292929292929292929292929:public", "actor": "", "mode": "root", "name": "Example Asset", "symbol": "EXAMPLE", "description": "An example native asset.", "decimals": 8, "supply": "1000000", "icon_base64": "iVBORw0KGgoAAAANSUhEUgAAACAAAAAgCAIAAAD8GO2jAAAAKklEQVR4nGMw9v1PU8QwasGoBaMWjFowasGoBaMWjFowasGoBaMWDBULALw6/EwgT7fRAAAAAElFTkSuQmCC" } }, "root": { "summary": "独立资产最小请求", "value": { "request_id": "7c51d5ae-cb7d-4a26-891b-77193590d7ba", "chain_id": "tsc:2929292929292929292929292929292929292929292929292929292929292929:public", "actor": "", "mode": "root", "name": "Example Asset", "symbol": "EXAMPLE", "description": "An example native asset.", "decimals": 8, "supply": "1000000" } }, "trc20": { "summary": "TRC20 子资产最小请求", "value": { "request_id": "7c51d5ae-cb7d-4a26-891b-77193590d7ba", "chain_id": "tsc:2929292929292929292929292929292929292929292929292929292929292929:public", "actor": "", "mode": "trc20", "name": "Example Asset", "symbol": "EXAMPLE", "description": "An example native asset.", "decimals": 8, "supply": "1000000" } } } } } } } }, "/issuances/{id}": { "get": { "operationId": "getIssuance", "summary": "查询发行进度", "description": "路径 id 为原 request_id，不是 Asset ID。只读查询，不构造、不签名、不广播；awaiting_confirmation 包含已补齐但尚未广播的交易。complete 表示两阶段均已确认。", "tags": [ "Creation" ], "responses": { "200": { "description": "返回以下 JSON 对象；交易的最终结果以 state 和链上确认状态为准。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IssuanceResource" } } } }, "400": { "description": "请求参数、资产策略或签名无效。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "未找到资产、池子或操作记录。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "审核过期、交易内容改变、价格不满足限制或分页游标失效。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "请求体超过允许字节数。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "请求 Content-Type 不受支持。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "JSON 字段格式无效或包含未知字段。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "请求频率或容量达到上限，按 Retry-After 秒数退避。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "建议等待的秒数。", "schema": { "type": "integer" } } } }, "503": { "description": "节点、签名服务、索引或上游暂不可用，按 Retry-After 秒数退避。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "建议等待的秒数。", "schema": { "type": "integer" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$" }, "description": "原始发行 request_id，小写 UUIDv4。" } ] } }, "/issuances/{id}/next": { "post": { "operationId": "nextIssuance", "summary": "获取当前或下一阶段签名请求", "description": "正文 {} 复用现有有效审核，或在注册确认后准备首次铸币。无需重传资产资料。refresh=true 显式请求新的未签名审核；有结果不明确的已签交易时先核对原交易，不能自动替换。", "tags": [ "Creation" ], "responses": { "200": { "description": "返回以下 JSON 对象；交易的最终结果以 state 和链上确认状态为准。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IssuanceResource" } } } }, "400": { "description": "请求参数、资产策略或签名无效。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "未找到资产、池子或操作记录。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "审核过期、交易内容改变、价格不满足限制或分页游标失效。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "请求体超过允许字节数。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "请求 Content-Type 不受支持。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "JSON 字段格式无效或包含未知字段。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "请求频率或容量达到上限，按 Retry-After 秒数退避。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "建议等待的秒数。", "schema": { "type": "integer" } } } }, "503": { "description": "节点、签名服务、索引或上游暂不可用，按 Retry-After 秒数退避。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "建议等待的秒数。", "schema": { "type": "integer" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IssuanceNext" }, "examples": { "continue": { "summary": "复用当前审核或获取下一阶段", "value": {} }, "refresh": { "summary": "显式刷新未签名审核", "value": { "refresh": true } } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$" }, "description": "原始发行 request_id，小写 UUIDv4。" } ] } }, "/issuances/{id}/finalize": { "post": { "operationId": "finalizeIssuance", "summary": "校验签名并返回完整交易", "description": "提交当前 review_id 和钱包签名结果 transaction。拒绝改动已审核的输入、输出和资产资料；TRC20 必要时补齐 Parent 签名。保存完整交易后返回 transaction 和 txid。不会广播，finalized 不表示链上确认。同一审核和原签名结果可安全重试。", "tags": [ "Creation" ], "responses": { "200": { "description": "返回以下 JSON 对象；交易的最终结果以 state 和链上确认状态为准。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IssuanceFinalized" } } } }, "400": { "description": "请求参数、资产策略或签名无效。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "未找到资产、池子或操作记录。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "审核过期、交易内容改变、价格不满足限制或分页游标失效。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "请求体超过允许字节数。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "请求 Content-Type 不受支持。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "JSON 字段格式无效或包含未知字段。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "请求频率或容量达到上限，按 Retry-After 秒数退避。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "建议等待的秒数。", "schema": { "type": "integer" } } } }, "503": { "description": "节点、签名服务、索引或上游暂不可用，按 Retry-After 秒数退避。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "建议等待的秒数。", "schema": { "type": "integer" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IssuanceFinalize" } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$" }, "description": "原始发行 request_id，小写 UUIDv4。" } ] } }, "/issuances/{id}/broadcast": { "post": { "operationId": "broadcastIssuance", "summary": "提交已补齐的原交易", "description": "在用户已批准提交这笔交易后，传入 finalize 返回的完整 transaction 和原 review_id。只通过当前网络 TSCScan 预检、广播；不构造、签名或替换交易。不需要额外钱包调用。accepted 包含此前已接受的交易；unknown 应保留原字节、查询状态并原样重试。链上确认以 GET /issuances/{id} 为准。", "tags": [ "Creation" ], "responses": { "200": { "description": "返回以下 JSON 对象；交易的最终结果以 state 和链上确认状态为准。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IssuanceBroadcastReceipt" } } } }, "400": { "description": "请求参数、资产策略或签名无效。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "未找到资产、池子或操作记录。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "审核过期、交易内容改变、价格不满足限制或分页游标失效。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "请求体超过允许字节数。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "请求 Content-Type 不受支持。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "JSON 字段格式无效或包含未知字段。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "请求频率或容量达到上限，按 Retry-After 秒数退避。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "建议等待的秒数。", "schema": { "type": "integer" } } } }, "503": { "description": "节点、签名服务、索引或上游暂不可用，按 Retry-After 秒数退避。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "建议等待的秒数。", "schema": { "type": "integer" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IssuanceBroadcast" } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$" }, "description": "原始发行 request_id，小写 UUIDv4。" } ] } }, "/estimate": { "post": { "operationId": "estimateSwap", "summary": "预估兑换数量", "description": "提供卖出币种、接收币种及卖出金额，至少一侧为 TSC。返回数量和路由；有效期 15 秒，不预留储备，不需要签名。", "tags": [ "Trading" ], "responses": { "200": { "description": "返回以下 JSON 对象；交易的最终结果以 state 和链上确认状态为准。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Estimate" } } } }, "400": { "description": "请求参数、资产策略或签名无效。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "未找到资产、池子或操作记录。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "审核过期、交易内容改变、价格不满足限制或分页游标失效。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "请求体超过允许字节数。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "请求 Content-Type 不受支持。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "JSON 字段格式无效或包含未知字段。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "请求频率或容量达到上限，按 Retry-After 秒数退避。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "建议等待的秒数。", "schema": { "type": "integer" } } } }, "503": { "description": "节点、签名服务、索引或上游暂不可用，按 Retry-After 秒数退避。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "建议等待的秒数。", "schema": { "type": "integer" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EstimateRequest" }, "examples": { "swap": { "value": { "input_asset_id": "TSC", "output_asset_id": "67c31777dbeb592406cd2758479c63b86b9ec5916178146b4e9a58f7897a1838", "amount": "1" } } } } } } } }, "/quote": { "post": { "operationId": "createQuote", "summary": "构造交易报价", "description": "根据 kind 构造创建、添加、追加、兑换或提款的未签名交易。有效期 300 秒，不锁定 UTXO；签名后输入输出金额固定。新池操作须先保存恢复资料。当前新 LP 功能门槛关闭时返回 RECOVERY_NOT_VALIDATED。", "tags": [ "Trading" ], "responses": { "200": { "description": "返回以下 JSON 对象；交易的最终结果以 state 和链上确认状态为准。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Quote" } } } }, "400": { "description": "请求参数、资产策略或签名无效。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "未找到资产、池子或操作记录。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "审核过期、交易内容改变、价格不满足限制或分页游标失效。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "请求体超过允许字节数。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "请求 Content-Type 不受支持。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "JSON 字段格式无效或包含未知字段。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "请求频率或容量达到上限，按 Retry-After 秒数退避。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "建议等待的秒数。", "schema": { "type": "integer" } } } }, "503": { "description": "节点、签名服务、索引或上游暂不可用，按 Retry-After 秒数退避。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "建议等待的秒数。", "schema": { "type": "integer" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuoteRequest" }, "examples": { "buy": { "summary": "TSC → Asset", "value": { "actor": "YOUR_P2WPKH_ADDRESS", "asset_id": "67c31777dbeb592406cd2758479c63b86b9ec5916178146b4e9a58f7897a1838", "kind": "swap", "tsc_in": true, "amount": "1", "min_output_units": "1" } }, "sell": { "summary": "Asset → TSC", "value": { "actor": "YOUR_P2WPKH_ADDRESS", "asset_id": "67c31777dbeb592406cd2758479c63b86b9ec5916178146b4e9a58f7897a1838", "kind": "swap", "tsc_in": false, "amount": "10", "min_output_units": "1" } }, "create": { "summary": "Create an independently owned pool", "value": { "actor": "YOUR_P2WPKH_ADDRESS", "asset_id": "67c31777dbeb592406cd2758479c63b86b9ec5916178146b4e9a58f7897a1838", "kind": "create_pool", "nonce": "1111111111111111111111111111111111111111111111111111111111111111", "owner_key": "3333333333333333333333333333333333333333333333333333333333333333", "tsc_amount": "5", "asset_amount": "500" } }, "add": { "summary": "Add an independently owned pool, no shared LP shares", "value": { "actor": "YOUR_P2WPKH_ADDRESS", "asset_id": "67c31777dbeb592406cd2758479c63b86b9ec5916178146b4e9a58f7897a1838", "kind": "add_liquidity", "nonce": "1111111111111111111111111111111111111111111111111111111111111111", "owner_key": "3333333333333333333333333333333333333333333333333333333333333333", "tsc_amount": "5", "asset_amount": "500" } }, "increase": { "summary": "Increase an existing owned position atomically", "value": { "actor": "YOUR_P2WPKH_ADDRESS", "asset_id": "67c31777dbeb592406cd2758479c63b86b9ec5916178146b4e9a58f7897a1838", "kind": "increase_liquidity", "pool_id": "4444444444444444444444444444444444444444444444444444444444444444", "nonce": "1111111111111111111111111111111111111111111111111111111111111111", "owner_key": "3333333333333333333333333333333333333333333333333333333333333333", "tsc_amount": "1", "asset_amount": "100" } }, "exit": { "summary": "Full owner exit", "value": { "actor": "YOUR_P2WPKH_ADDRESS", "asset_id": "67c31777dbeb592406cd2758479c63b86b9ec5916178146b4e9a58f7897a1838", "kind": "remove_liquidity", "pool_id": "4444444444444444444444444444444444444444444444444444444444444444", "withdraw_bps": 10000 } }, "partial": { "summary": "Partial exit into a replacement pool", "value": { "actor": "YOUR_P2WPKH_ADDRESS", "asset_id": "67c31777dbeb592406cd2758479c63b86b9ec5916178146b4e9a58f7897a1838", "kind": "remove_liquidity", "pool_id": "4444444444444444444444444444444444444444444444444444444444444444", "withdraw_bps": 5000, "nonce": "1111111111111111111111111111111111111111111111111111111111111111", "owner_key": "3333333333333333333333333333333333333333333333333333333333333333" } } } } } } } }, "/execute": { "post": { "operationId": "executeQuote", "summary": "提交已签名报价交易", "description": "提交 quote_id 和保持原模板的已签名 hex。quote.created 非 null 时需要 registration。相同 ID 和相同签名字节恢复同一操作；更改字节返回 TRANSACTION_CHANGED。HTTP 200 仍可能处于 submitting 或带 error，应继续查询原操作。", "tags": [ "Trading" ], "responses": { "200": { "description": "返回以下 JSON 对象；交易的最终结果以 state 和链上确认状态为准。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Execution" } } } }, "400": { "description": "请求参数、资产策略或签名无效。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "未找到资产、池子或操作记录。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "审核过期、交易内容改变、价格不满足限制或分页游标失效。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "请求体超过允许字节数。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "请求 Content-Type 不受支持。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "JSON 字段格式无效或包含未知字段。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "请求频率或容量达到上限，按 Retry-After 秒数退避。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "建议等待的秒数。", "schema": { "type": "integer" } } } }, "503": { "description": "节点、签名服务、索引或上游暂不可用，按 Retry-After 秒数退避。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "建议等待的秒数。", "schema": { "type": "integer" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExecuteRequest" } } } } } }, "/operations/{id}": { "get": { "operationId": "getOperation", "summary": "查询交易操作状态", "description": "路径 id 为 quote_id，不是链上 txid。只读，不重广播，约每 5 秒更新；已确认记录可能因重组变为 rechecking。不返回完整签名交易。", "tags": [ "Trading" ], "responses": { "200": { "description": "返回以下 JSON 对象；交易的最终结果以 state 和链上确认状态为准。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Operation" } } } }, "400": { "description": "请求参数、资产策略或签名无效。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "未找到资产、池子或操作记录。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "审核过期、交易内容改变、价格不满足限制或分页游标失效。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "请求体超过允许字节数。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "请求 Content-Type 不受支持。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "JSON 字段格式无效或包含未知字段。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "请求频率或容量达到上限，按 Retry-After 秒数退避。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "建议等待的秒数。", "schema": { "type": "integer" } } } }, "503": { "description": "节点、签名服务、索引或上游暂不可用，按 Retry-After 秒数退避。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "建议等待的秒数。", "schema": { "type": "integer" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "description": "报价 quote_id，64 位小写十六进制。" } ] } }, "/pools/{id}/backup": { "get": { "operationId": "getPoolBackup", "summary": "读取池子恢复资料", "description": "路径 id 为 Pool ID。返回公开恢复资料，不包含私钥；独立退出还需要原钱包及可用链查询和广播服务。", "tags": [ "Trading" ], "responses": { "200": { "description": "返回以下 JSON 对象；交易的最终结果以 state 和链上确认状态为准。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecoveryFile" } } } }, "400": { "description": "请求参数、资产策略或签名无效。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "未找到资产、池子或操作记录。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "审核过期、交易内容改变、价格不满足限制或分页游标失效。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "请求体超过允许字节数。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "请求 Content-Type 不受支持。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "JSON 字段格式无效或包含未知字段。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "请求频率或容量达到上限，按 Retry-After 秒数退避。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "建议等待的秒数。", "schema": { "type": "integer" } } } }, "503": { "description": "节点、签名服务、索引或上游暂不可用，按 Retry-After 秒数退避。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "建议等待的秒数。", "schema": { "type": "integer" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "description": "微池 Pool ID，64 位小写十六进制。" } ] } }, "/stream": { "get": { "operationId": "streamMarket", "tags": [ "Market" ], "summary": "订阅 WebSocket 行情", "description": "升级为 WebSocket，协议 tern.market.v1。使用 subscribe 订阅池子的 ticker、candles、trades；首次返回 snapshot，之后返回带序号的 update，重新连接从 snapshot 开始。", "responses": { "101": { "description": "WebSocket 协议升级成功。" }, "429": { "description": "请求频率或容量达到上限，按 Retry-After 秒数退避。" } }, "externalDocs": { "url": "../guide.md", "description": "WebSocket protocol and examples" } } } }, "components": { "schemas": { "IndexStatus": { "type": "object", "properties": { "indexed_height": { "type": [ "integer", "null" ], "description": "索引已处理到的区块高度。" }, "indexed_hash": { "type": [ "string", "null" ], "description": "索引已处理到的区块哈希。" }, "core_height": { "type": [ "integer", "null" ], "description": "节点已验证的区块高度。" }, "core_headers": { "type": [ "integer", "null" ], "description": "节点已知的最高区块头高度。" }, "node_ready": { "type": "boolean", "description": "节点是否已完成同步并可处理交易。" }, "caught_up": { "type": "boolean", "description": "行情索引是否已追上节点当前高度。" }, "last_checked_at": { "type": [ "integer", "null" ], "description": "最近一次索引检查时间，UTC Unix 毫秒。" }, "error": { "type": [ "string", "null" ], "description": "错误说明；无错误时为 null，交易状态仍以 state 为准。" }, "revision": { "type": "integer", "format": "int64", "minimum": 0, "description": "行情索引修订号；用于识别重建或状态变化。" } }, "required": [ "indexed_height", "indexed_hash", "core_height", "core_headers", "node_ready", "caught_up", "last_checked_at", "error", "revision" ] }, "Candle": { "type": "object", "properties": { "open_time": { "type": "integer", "format": "int64", "minimum": 0, "description": "K 线周期起始时间，UTC Unix 毫秒。" }, "close_time": { "type": "integer", "format": "int64", "minimum": 0, "description": "该 K 线周期的结束时间，UTC Unix 毫秒。" }, "trade_count": { "type": "integer", "format": "int64", "minimum": 0, "description": "该记录或区间的成交笔数。" }, "open": { "type": "string", "description": "本周期首个价格，单位 TSC/Asset，精确十进制字符串。" }, "high": { "type": "string", "description": "本周期最高价格，单位 TSC/Asset，精确十进制字符串。" }, "low": { "type": "string", "description": "本周期最低价格，单位 TSC/Asset，精确十进制字符串。" }, "close": { "type": "string", "description": "本周期最后价格，单位 TSC/Asset，精确十进制字符串。" }, "base_volume": { "type": "string", "description": "基础资产成交量，按资产单位表示的十进制字符串。" }, "quote_volume": { "type": "string", "description": "计价资产成交量，单位 TSC，十进制字符串。" }, "is_closed": { "type": "boolean", "description": "K 线周期是否已结束；未结束的蜡烛仍可能更新。" }, "is_filled": { "type": "boolean", "description": "是否为无成交周期的延续价格；true 时 OHLC 沿用前收盘、成交量和笔数为零。" }, "source_open_time": { "type": "integer", "minimum": 0, "description": "延续价格来源的真实 K 线起始时间，UTC Unix 毫秒；真实成交周期等于 open_time。" } }, "required": [ "open_time", "close_time", "trade_count", "open", "high", "low", "close", "base_volume", "quote_volume", "is_closed" ] }, "Trade": { "type": "object", "properties": { "id": { "type": "string", "description": "成交记录的稳定 ID，用于去重；同一交易可包含多个池成交。" }, "pool_id": { "type": "string", "description": "微池实例 ID，64 位小写十六进制；不是 Asset ID。" }, "txid": { "type": "string", "description": "链上交易 ID，64 位小写十六进制；不同于 quote_id 或 request_id。" }, "block_hash": { "type": "string", "description": "成交所在区块的哈希，64 位小写十六进制。" }, "native_base_units": { "type": "string", "description": "本次成交的基础资产最小单位数量。" }, "native_quote_units": { "type": "string", "description": "本次成交的计价资产最小单位数量。" }, "block_height": { "type": "integer", "format": "int64", "minimum": 0, "description": "成交所在区块高度。" }, "transaction_index": { "type": "integer", "format": "int64", "minimum": 0, "description": "交易在区块中的位置，从 0 开始。" }, "input_index": { "type": "integer", "format": "int64", "minimum": 0, "description": "池子输入在交易中的位置，从 0 开始。" }, "time": { "type": "integer", "format": "int64", "minimum": 0, "description": "成交所在区块时间，UTC Unix 毫秒。" }, "side": { "type": "string", "enum": [ "buy", "sell" ], "description": "相对于基础 Asset 的买入或卖出方向。" }, "price": { "type": [ "string", "null" ], "description": "本笔成交均价，单位 TSC/Asset；计价成交量除以基础资产成交量，不是交易后池价。" }, "base_volume": { "type": [ "string", "null" ], "description": "基础资产成交量，按资产单位表示的十进制字符串。" }, "quote_volume": { "type": [ "string", "null" ], "description": "计价资产成交量，单位 TSC，十进制字符串。" }, "quote_source": { "type": [ "object", "null" ], "description": "该成交的计价来源。" }, "pool_price_before": { "type": [ "string", "null" ], "description": "兑换前储备比价格，单位 TSC/Asset；缺少记录时为 null。" }, "reserves_before": { "type": [ "object", "null" ], "properties": { "tsc_units": { "type": "string", "description": "TSC 最小单位整数字符串；1 TSC = 100000000。" }, "asset_units": { "type": "string", "description": "非 TSC 资产数量，按该资产精度表示的最小单位整数字符串。" } }, "required": [ "tsc_units", "asset_units" ], "description": "兑换前实际储备的最小单位数量，不包含可退载体。" }, "pool_price_after": { "type": [ "string", "null" ], "description": "兑换后储备比价格，单位 TSC/Asset；缺少记录时为 null。" }, "reserves_after": { "type": [ "object", "null" ], "properties": { "tsc_units": { "type": "string", "description": "TSC 最小单位整数字符串；1 TSC = 100000000。" }, "asset_units": { "type": "string", "description": "非 TSC 资产数量，按该资产精度表示的最小单位整数字符串。" } }, "required": [ "tsc_units", "asset_units" ], "description": "兑换后实际储备的最小单位数量，不包含可退载体。" } }, "required": [ "id", "pool_id", "txid", "block_hash", "native_base_units", "native_quote_units", "block_height", "transaction_index", "input_index", "time", "side", "price", "base_volume", "quote_volume", "quote_source", "pool_price_before", "reserves_before", "pool_price_after", "reserves_after" ] }, "Error": { "type": "object", "properties": { "code": { "type": "string", "description": "稳定的错误码；使用该字段判断错误类型。" }, "message": { "type": "string", "description": "人类可读错误说明；程序判断错误使用 code。" } }, "required": [ "code", "message" ] }, "Market": { "type": "object", "properties": { "api_version": { "const": "1", "description": "接口版本。" }, "genesis": { "type": "string", "description": "当前网络的创世区块哈希，64 位小写十六进制。" }, "index": { "$ref": "#/components/schemas/IndexStatus", "description": "行情索引进度与同步状态；数据不完整时不要当作完整实时行情。" }, "time_unit": { "const": "unix_ms", "description": "时间戳单位，行情与参考价为 unix_ms。" }, "price_decimals": { "const": 72, "description": "行情内部计算的价格精度。" }, "timestamp_source": { "const": "block_time", "description": "行情时间来源；使用已确认区块时间。" }, "gap_policy": { "const": "omit", "description": "无成交周期的处理方式；carry_forward 沿用上一收盘价，成交量为零。" }, "confirmation_policy": { "const": "canonical_block_1_confirmation", "description": "成交纳入行情统计的确认规则。" }, "fee_basis": { "const": "pool_reserve_delta_including_lp_fee_excluding_network_fee", "description": "行情手续费统计口径。" }, "reference_asset_id": { "type": "null", "description": "历史参考资产 ID；当前统一使用 TSC，返回 null。" }, "intervals": { "type": "array", "items": { "type": "string" }, "description": "支持的 K 线周期列表。" }, "assets": { "type": "array", "items": { "type": "object", "properties": { "asset_id": { "type": "string", "description": "资产的链上 ID，64 位小写十六进制；只在对应网络有效。" }, "symbol": { "type": "string", "description": "资产展示符号；发行时填 3–11 位大写字母数字，首位字母，不加 TRC20. 前缀。" }, "precision": { "type": "integer", "format": "int64", "minimum": 0, "description": "资产小数位数；TSC 为 8，其他资产以链上登记值为准。" } }, "required": [ "asset_id", "symbol", "precision" ] }, "description": "当前查询范围内的资产列表。" }, "pools": { "type": "array", "items": { "type": "object", "properties": { "pool_id": { "type": "string", "description": "微池实例 ID，64 位小写十六进制；不是 Asset ID。" }, "asset_id": { "type": "string", "description": "资产的链上 ID，64 位小写十六进制；只在对应网络有效。" } }, "required": [ "pool_id", "asset_id" ] }, "description": "平台登记的池子列表。" } }, "required": [ "api_version", "genesis", "index", "time_unit", "price_decimals", "timestamp_source", "gap_policy", "confirmation_policy", "fee_basis", "reference_asset_id", "intervals", "assets", "pools" ] }, "Candles": { "type": "object", "properties": { "api_version": { "const": "1", "description": "接口版本。" }, "genesis": { "type": "string", "description": "当前网络的创世区块哈希，64 位小写十六进制。" }, "index": { "$ref": "#/components/schemas/IndexStatus", "description": "行情索引进度与同步状态；数据不完整时不要当作完整实时行情。" }, "time_unit": { "const": "unix_ms", "description": "时间戳单位，行情与参考价为 unix_ms。" }, "price_decimals": { "const": 72, "description": "行情内部计算的价格精度。" }, "timestamp_source": { "const": "block_time", "description": "行情时间来源；使用已确认区块时间。" }, "gap_policy": { "type": "string", "enum": [ "omit", "carry_forward" ], "description": "无成交周期的处理方式；carry_forward 沿用上一收盘价，成交量为零。" }, "confirmation_policy": { "const": "canonical_block_1_confirmation", "description": "成交纳入行情统计的确认规则。" }, "fee_basis": { "const": "pool_reserve_delta_including_lp_fee_excluding_network_fee", "description": "行情手续费统计口径。" }, "reference_asset_id": { "type": "null", "description": "历史参考资产 ID；当前统一使用 TSC，返回 null。" }, "pool_id": { "type": "string", "description": "微池实例 ID，64 位小写十六进制；不是 Asset ID。" }, "asset_id": { "type": "string", "description": "资产的链上 ID，64 位小写十六进制；只在对应网络有效。" }, "base_symbol": { "type": "string", "description": "被定价资产的展示符号。" }, "base_precision": { "type": "integer", "format": "int64", "minimum": 0, "description": "基础资产的小数位数。" }, "quote_symbol": { "enum": [ "TSC" ], "description": "计价符号；当前为 TSC。" }, "quote_asset_id": { "type": [ "string", "null" ], "description": "计价资产 ID；TSC 是原生币，没有非 TSC Asset ID。" }, "coverage": { "type": "object", "properties": { "total_trades": { "type": "integer", "format": "int64", "minimum": 0, "description": "该池已索引的总成交笔数。" }, "priced_trades": { "type": "integer", "format": "int64", "minimum": 0, "description": "具备所选计价币种价格的成交数量。" }, "unpriced_trades": { "type": "integer", "format": "int64", "minimum": 0, "description": "缺少计价信息的成交笔数；不等于没有成交。" } }, "required": [ "total_trades", "priced_trades", "unpriced_trades" ], "description": "本池行情记录的定价覆盖情况。" }, "interval": { "type": "string", "description": "K 线周期：1m、5m、15m、30m、1h、4h、1d、1w。" }, "has_more": { "type": "boolean", "description": "是否还有下一页；继续使用本响应的游标。" }, "next_end_time": { "type": [ "integer", "null" ], "description": "下一页 K 线查询的 end_time，UTC Unix 毫秒；无下一页为 null。" }, "candles": { "type": "array", "items": { "$ref": "#/components/schemas/Candle" }, "description": "当前页的 K 线列表，按时间排列。" }, "price_basis": { "type": "string", "enum": [ "execution", "spot" ], "description": "spot 使用交易后储备价；execution 使用成交均价。" }, "range_start": { "type": "integer", "minimum": 0, "description": "本页归一化时间范围的起点，含边界，UTC Unix 毫秒；补齐模式返回。" }, "range_end": { "type": "integer", "minimum": 0, "description": "本页归一化时间范围的终点，不含边界，UTC Unix 毫秒；补齐模式返回。" } }, "required": [ "api_version", "genesis", "index", "time_unit", "price_decimals", "timestamp_source", "gap_policy", "confirmation_policy", "fee_basis", "reference_asset_id", "pool_id", "asset_id", "base_symbol", "base_precision", "quote_symbol", "quote_asset_id", "coverage", "interval", "has_more", "next_end_time", "candles", "price_basis" ] }, "Trades": { "type": "object", "properties": { "api_version": { "const": "1", "description": "接口版本。" }, "genesis": { "type": "string", "description": "当前网络的创世区块哈希，64 位小写十六进制。" }, "index": { "$ref": "#/components/schemas/IndexStatus", "description": "行情索引进度与同步状态；数据不完整时不要当作完整实时行情。" }, "time_unit": { "const": "unix_ms", "description": "时间戳单位，行情与参考价为 unix_ms。" }, "price_decimals": { "const": 72, "description": "行情内部计算的价格精度。" }, "timestamp_source": { "const": "block_time", "description": "行情时间来源；使用已确认区块时间。" }, "gap_policy": { "const": "omit", "description": "无成交周期的处理方式；carry_forward 沿用上一收盘价，成交量为零。" }, "confirmation_policy": { "const": "canonical_block_1_confirmation", "description": "成交纳入行情统计的确认规则。" }, "fee_basis": { "const": "pool_reserve_delta_including_lp_fee_excluding_network_fee", "description": "行情手续费统计口径。" }, "reference_asset_id": { "type": "null", "description": "历史参考资产 ID；当前统一使用 TSC，返回 null。" }, "pool_id": { "type": "string", "description": "微池实例 ID，64 位小写十六进制；不是 Asset ID。" }, "asset_id": { "type": "string", "description": "资产的链上 ID，64 位小写十六进制；只在对应网络有效。" }, "base_symbol": { "type": "string", "description": "被定价资产的展示符号。" }, "base_precision": { "type": "integer", "format": "int64", "minimum": 0, "description": "基础资产的小数位数。" }, "quote_symbol": { "enum": [ "TSC" ], "description": "计价符号；当前为 TSC。" }, "quote_asset_id": { "type": [ "string", "null" ], "description": "计价资产 ID；TSC 是原生币，没有非 TSC Asset ID。" }, "coverage": { "type": "object", "properties": { "total_trades": { "type": "integer", "format": "int64", "minimum": 0, "description": "该池已索引的总成交笔数。" }, "priced_trades": { "type": "integer", "format": "int64", "minimum": 0, "description": "具备所选计价币种价格的成交数量。" }, "unpriced_trades": { "type": "integer", "format": "int64", "minimum": 0, "description": "缺少计价信息的成交笔数；不等于没有成交。" } }, "required": [ "total_trades", "priced_trades", "unpriced_trades" ], "description": "本池行情记录的定价覆盖情况。" }, "has_more": { "type": "boolean", "description": "是否还有下一页；继续使用本响应的游标。" }, "next_cursor": { "type": [ "string", "null" ], "description": "下一页游标；没有下一页时为 null，原样用于下一次请求。" }, "trades": { "type": "array", "items": { "$ref": "#/components/schemas/Trade" }, "description": "本页已确认成交列表。" } }, "required": [ "api_version", "genesis", "index", "time_unit", "price_decimals", "timestamp_source", "gap_policy", "confirmation_policy", "fee_basis", "reference_asset_id", "pool_id", "asset_id", "base_symbol", "base_precision", "quote_symbol", "quote_asset_id", "coverage", "has_more", "next_cursor", "trades" ] }, "Ticker": { "type": "object", "properties": { "api_version": { "const": "1", "description": "接口版本。" }, "genesis": { "type": "string", "description": "当前网络的创世区块哈希，64 位小写十六进制。" }, "index": { "$ref": "#/components/schemas/IndexStatus", "description": "行情索引进度与同步状态；数据不完整时不要当作完整实时行情。" }, "time_unit": { "const": "unix_ms", "description": "时间戳单位，行情与参考价为 unix_ms。" }, "price_decimals": { "const": 72, "description": "行情内部计算的价格精度。" }, "timestamp_source": { "const": "block_time", "description": "行情时间来源；使用已确认区块时间。" }, "gap_policy": { "const": "omit", "description": "无成交周期的处理方式；carry_forward 沿用上一收盘价，成交量为零。" }, "confirmation_policy": { "const": "canonical_block_1_confirmation", "description": "成交纳入行情统计的确认规则。" }, "fee_basis": { "const": "pool_reserve_delta_including_lp_fee_excluding_network_fee", "description": "行情手续费统计口径。" }, "reference_asset_id": { "type": "null", "description": "历史参考资产 ID；当前统一使用 TSC，返回 null。" }, "pool_id": { "type": "string", "description": "微池实例 ID，64 位小写十六进制；不是 Asset ID。" }, "asset_id": { "type": "string", "description": "资产的链上 ID，64 位小写十六进制；只在对应网络有效。" }, "base_symbol": { "type": "string", "description": "被定价资产的展示符号。" }, "base_precision": { "type": "integer", "format": "int64", "minimum": 0, "description": "基础资产的小数位数。" }, "quote_symbol": { "enum": [ "TSC" ], "description": "计价符号；当前为 TSC。" }, "quote_asset_id": { "type": [ "string", "null" ], "description": "计价资产 ID；TSC 是原生币，没有非 TSC Asset ID。" }, "coverage": { "type": "object", "properties": { "total_trades": { "type": "integer", "format": "int64", "minimum": 0, "description": "该池已索引的总成交笔数。" }, "priced_trades": { "type": "integer", "format": "int64", "minimum": 0, "description": "具备所选计价币种价格的成交数量。" }, "unpriced_trades": { "type": "integer", "format": "int64", "minimum": 0, "description": "缺少计价信息的成交笔数；不等于没有成交。" } }, "required": [ "total_trades", "priced_trades", "unpriced_trades" ], "description": "本池行情记录的定价覆盖情况。" }, "pool_price": { "type": [ "string", "null" ], "description": "当前已确认储备比价格，单位 TSC/Asset；不是最近一笔成交均价。" }, "reference_pool_ids": { "type": "array", "items": { "type": "string" }, "description": "历史换算或定价涉及的参考池 ID 列表。" }, "reserves": { "type": [ "object", "null" ], "description": "该时点池子持有的 TSC 与 Asset 储备。" }, "last_trade": { "anyOf": [ { "$ref": "#/components/schemas/Trade" }, { "type": "null" } ], "description": "最近一笔已确认成交；没有成交时为 null。" }, "stats_24h": { "type": "object", "properties": { "start_time": { "type": "integer", "format": "int64", "minimum": 0, "description": "统计区间起始时间，UTC Unix 毫秒。" }, "end_time": { "type": "integer", "format": "int64", "minimum": 0, "description": "统计或查询区间结束时间，UTC Unix 毫秒。" }, "base_volume": { "type": "string", "description": "基础资产成交量，按资产单位表示的十进制字符串。" }, "quote_volume": { "type": "string", "description": "计价资产成交量，单位 TSC，十进制字符串。" }, "trade_count": { "type": "integer", "format": "int64", "minimum": 0, "description": "该记录或区间的成交笔数。" }, "unpriced_trade_count": { "type": "integer", "minimum": 0, "description": "统计期内缺少计价数据的成交数量；非零时成交量统计可能不完整。" } }, "required": [ "start_time", "end_time", "base_volume", "quote_volume", "trade_count", "unpriced_trade_count" ], "description": "过去 24 小时成交量、笔数及时间边界。" }, "tvl": { "type": [ "string", "null" ], "description": "池子总储备价值，单位 TSC，不包含载体；缺少价格时为 null。" }, "position": { "anyOf": [ { "$ref": "#/components/schemas/PositionAccounting" }, { "type": "null" } ], "description": "单实例仓位的初始投入、存续时间和手续费；入金尚未索引时为 null。" }, "fee_apr_24h": { "$ref": "#/components/schemas/FeeApr", "description": "近 24 小时手续费年化估算；不是净利润或收益承诺。" }, "logical_position": { "anyOf": [ { "$ref": "#/components/schemas/LogicalPosition" }, { "type": "null" } ], "description": "跨微池实例延续的同一所有者仓位信息。" } }, "required": [ "api_version", "genesis", "index", "time_unit", "price_decimals", "timestamp_source", "gap_policy", "confirmation_policy", "fee_basis", "reference_asset_id", "pool_id", "asset_id", "base_symbol", "base_precision", "quote_symbol", "quote_asset_id", "coverage", "pool_price", "reference_pool_ids", "reserves", "last_trade", "stats_24h", "tvl", "position", "fee_apr_24h" ] }, "PositionFees": { "type": "object", "properties": { "tsc": { "type": "string", "description": "TSC 数量，按 TSC 单位表示的十进制字符串。" }, "asset": { "type": "string", "description": "资产手续费，按该资产单位表示的十进制字符串；包含记账精度，不是可另行领取的余额。" }, "trade_count": { "type": "integer", "minimum": 0, "description": "该记录或区间的成交笔数。" } }, "required": [ "tsc", "asset", "trade_count" ], "description": "Nominal 0.30% of each confirmed swap input, denominated separately in TSC and the pool Asset. Exact decimal strings retain fractional atomic units. This is an accounting total retained in reserves, not a claimable balance or net profit; rounding dust is excluded." }, "PositionAccounting": { "type": "object", "properties": { "opened_at": { "type": "integer", "description": "仓位入金确认的区块时间，UTC Unix 毫秒。" }, "funding_txid": { "type": "string", "description": "仓位最初入金交易的 ID。" }, "initial_deposit": { "type": "object", "properties": { "tsc": { "type": "string", "description": "初始投入的 TSC 数量，不含载体金额。" }, "asset": { "type": "string", "description": "初始投入的 Asset 数量，按该资产单位表示。" } }, "required": [ "tsc", "asset" ], "description": "该仓位最初投入的 TSC 和 Asset 数量。" }, "closed_at": { "type": [ "integer", "null" ], "description": "仓位关闭的区块时间，UTC Unix 毫秒；未关闭为 null。" }, "exit_txid": { "type": [ "string", "null" ], "description": "关闭仓位的交易 ID；未退出时为 null。" }, "successor_pool_ids": { "type": "array", "items": { "type": "string" }, "description": "退出交易建立的同资产继任池 ID 列表；手续费历史不会直接复制。" }, "fees": { "$ref": "#/components/schemas/PositionFees", "description": "仓位累计的 TSC 和 Asset 手续费，留在储备内。" }, "fees_24h": { "$ref": "#/components/schemas/PositionFees", "description": "近 24 小时的 TSC 和 Asset 手续费，留在储备内。" }, "fee_bps": { "const": 30, "description": "池手续费率，单位基点；30 表示 0.30%。" }, "fee_accounting": { "const": "nominal_input_fee_retained_in_reserves", "description": "手续费数量的统计方法。" }, "carrier_tsc": { "const": "0.001", "description": "仓位锁定的载体金额，单位 TSC；不计入池子 TVL。" } }, "required": [ "opened_at", "funding_txid", "initial_deposit", "closed_at", "exit_txid", "successor_pool_ids", "fees", "fees_24h", "fee_bps", "fee_accounting", "carrier_tsc" ], "description": "Confirmed accounting for this pool identity only. Partial exits preserve old fees and start a separate position. Rebuilt on reorg. No shared LP shares or separate fee collection." }, "FeeApr": { "type": "object", "description": "Backward-looking simple LP fee APR from a complete rolling 24h window. Fee tokens and TVL are valued at the same current pool reserve ratio in TSC. Independent of requested display currency. Not APY, net P&L or a forecast. Percentage points: 10.95 means 10.95%.", "properties": { "status": { "type": "string", "enum": [ "available", "unconfirmed", "closed", "insufficient_liquidity", "index_unavailable", "insufficient_history" ], "description": "能力、交易或统计结果状态；对象和枚举含义见类型。" }, "percent": { "type": [ "string", "null" ], "pattern": "^\\d+(\\.\\d+)?$", "description": "手续费 APR，百分数的十进制字符串；例如 10.95 表示 10.95%；缺少完整数据时为 null。" }, "fee_value_tsc": { "type": [ "string", "null" ], "pattern": "^\\d+(\\.\\d+)?$", "description": "近 24 小时手续费按当前储备价换算的 TSC 价值，不含矿工费、载体或舍入尘埃。" }, "tvl_tsc": { "type": [ "string", "null" ], "pattern": "^\\d+(\\.\\d+)?$", "description": "当前两种储备按同一池价换算的 TSC 总价值，不含载体。" }, "start_time": { "type": "integer", "minimum": 0, "description": "统计区间起始时间，UTC Unix 毫秒。" }, "end_time": { "type": "integer", "minimum": 0, "description": "统计或查询区间结束时间，UTC Unix 毫秒。" }, "annualization_days": { "type": "integer", "const": 365, "description": "年化天数；手续费 APR 使用 365 天。" }, "valuation": { "type": "string", "const": "current_pool_price", "description": "手续费或仓位的估值方法。" }, "basis": { "type": "string", "const": "fees_only", "description": "统计或计算采用的口径。" } }, "required": [ "status", "percent", "fee_value_tsc", "tvl_tsc", "start_time", "end_time", "annualization_days", "valuation", "basis" ] }, "LogicalPosition": { "type": "object", "description": "Cumulative position accounting through confirmed, owner-authorized predecessor instances. Only the selected instance and its canonical ancestors are included; do not sum these cumulative fees across instances. The per-instance position and fee_apr_24h fields remain unchanged.", "properties": { "position_id": { "type": "string", "description": "延续追加和部分退出历史的逻辑仓位 ID。" }, "instance_pool_id": { "type": "string", "description": "该逻辑仓位当前对应的微池实例 ID。" }, "pool_ids": { "type": "array", "items": { "type": "string" }, "description": "参与此记录的微池实例 ID 列表。" }, "opened_at": { "type": "integer", "description": "仓位入金确认的区块时间，UTC Unix 毫秒。" }, "closed_at": { "type": [ "integer", "null" ], "description": "仓位关闭的区块时间，UTC Unix 毫秒；未关闭为 null。" }, "initial_deposit": { "type": "object", "description": "该仓位最初投入的 TSC 和 Asset 数量。" }, "fees": { "type": "object", "description": "仓位累计的 TSC 和 Asset 手续费，留在储备内。" }, "fees_24h": { "type": "object", "description": "近 24 小时的 TSC 和 Asset 手续费，留在储备内。" }, "history": { "type": "array", "items": { "type": "object" }, "description": "该逻辑仓位的追加、替换与退出历史。" }, "fee_apr_24h": { "$ref": "#/components/schemas/FeeApr", "description": "近 24 小时手续费年化估算；不是净利润或收益承诺。" } }, "required": [ "position_id", "instance_pool_id", "pool_ids", "opened_at", "closed_at", "initial_deposit", "fees", "fees_24h", "history", "fee_apr_24h" ] }, "AssetMetadata": { "type": "object", "properties": { "asset_id": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "资产的链上 ID，64 位小写十六进制；只在对应网络有效。" }, "symbol": { "type": "string", "description": "资产展示符号；发行时填 3–11 位大写字母数字，首位字母，不加 TRC20. 前缀。" }, "precision": { "type": "integer", "minimum": 0, "maximum": 18, "description": "资产小数位数；TSC 为 8，其他资产以链上登记值为准。" } }, "required": [ "asset_id", "symbol", "precision" ] }, "AssetPrice": { "type": "object", "properties": { "value": { "anyOf": [ { "type": "string", "pattern": "^[0-9]+(?:\\.[0-9]{1,72})?$" }, { "type": "null" } ], "description": "1 个资产对应的 TSC 数量，十进制字符串，最多 72 位小数；不可用时为 null，不能解释为零。" }, "quote_symbol": { "type": "string", "const": "TSC", "description": "计价符号；当前为 TSC。" }, "status": { "type": "string", "enum": [ "available", "unavailable" ], "description": "available 表示有正储备、索引已追上且节点就绪、无索引错误、最近检查不超过 120 秒；否则为 unavailable。" }, "reason": { "anyOf": [ { "type": "string", "enum": [ "no_liquidity", "index_unavailable" ] }, { "type": "null" } ], "description": "不可用原因：no_liquidity 没有已确认的正储备池；index_unavailable 索引未就绪、过期或暂不可读。可用时为 null。" }, "basis": { "type": "string", "const": "pool_reserves", "description": "固定 pool_reserves：TSC 储备除以资产数量，排除载体金额；从 TSC 储备最多的可用池取价，相同储备按池 ID 升序选择。" }, "pool_id": { "anyOf": [ { "type": "string", "pattern": "^[0-9a-f]{64}$" }, { "type": "null" } ], "description": "参考价格的来源池 ID；没有当前可用价格时为 null。" }, "index": { "anyOf": [ { "$ref": "#/components/schemas/IndexStatus" }, { "type": "null" } ], "description": "行情索引进度与同步状态；数据不完整时不要当作完整实时行情。" } }, "required": [ "value", "quote_symbol", "status", "reason", "basis", "pool_id", "index" ] }, "AssetLookup": { "type": "object", "properties": { "asset_id": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "资产的链上 ID，64 位小写十六进制；只在对应网络有效。" }, "symbol": { "type": "string", "description": "资产展示符号；发行时填 3–11 位大写字母数字，首位字母，不加 TRC20. 前缀。" }, "precision": { "type": "integer", "minimum": 0, "maximum": 18, "description": "资产小数位数；TSC 为 8，其他资产以链上登记值为准。" }, "listed": { "type": "boolean", "description": "是否在平台默认收录列表中；不是资产安全性认证。" }, "pool_count": { "type": "integer", "minimum": 0, "description": "平台登记的该资产池子数量。" }, "genesis": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "当前网络的创世区块哈希，64 位小写十六进制。" }, "metadata": { "anyOf": [ { "$ref": "#/components/schemas/AssetDocumentMetadata" }, { "type": "null" } ], "description": "已确认发行文档中的名称、描述、链接和头像原始 URI；当前覆盖此服务留有发行记录的资产，其余为 null。" }, "metadata_source": { "anyOf": [ { "type": "string", "const": "issuer_document" }, { "type": "null" } ], "description": "元数据来源。" }, "metadata_status": { "type": "string", "enum": [ "available", "unavailable", "unconfirmed" ], "description": "展示资料状态：available 已有注册确认且资料可读；unconfirmed 注册尚未确认；unavailable 此服务没有资料或暂时无法核对。" }, "commit_verified": { "type": "boolean", "description": "本次读取是否确认了发行注册交易，且展示资料绑定本资产和网络。资料不可用时为 false。" }, "icon_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "可直接用于图片展示的 HTTPS 地址；由已确认文档中的 icon.uri 推导，IPFS 使用本服务配置的网关，原始 URI 保留在 metadata.icon.uri。无头像或资料不可用时为 null。此字段用于直连网关；站内校验读取使用 icon_path。" }, "icon_path": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "相对于当前 API 根路径的站内图片读取路径；只为本平台已完成的 IPFS 上传提供，读取会核对 CID、字节数和 SHA-256。其余为 null。" }, "price": { "$ref": "#/components/schemas/AssetPrice", "description": "当前资产的 TSC 参考价格和来源。使用已确认池储备，不是成交均价或兑换报价；没有流动性或索引不可用时 value=null。" }, "chain_symbol": { "type": "string", "description": "完整链上符号；子资产包含命名空间前缀。" }, "issuance": { "anyOf": [ { "$ref": "#/components/schemas/SponsoredIssuance" }, { "type": "null" } ], "description": "子资产的协议、命名空间和 Parent 配置；独立资产不需要。" } }, "required": [ "asset_id", "symbol", "precision", "listed", "pool_count", "genesis", "metadata", "metadata_source", "metadata_status", "commit_verified", "icon_url", "icon_path", "price" ] }, "AssetRecommendations": { "type": "object", "properties": { "genesis": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "当前网络的创世区块哈希，64 位小写十六进制。" }, "featured": { "type": "array", "items": { "$ref": "#/components/schemas/AssetMetadata" }, "description": "部署配置的精选资产列表。" }, "recommended": { "type": "array", "items": { "type": "object", "description": "Asset metadata plus confirmed 24h TSC volume and liquidity ranking fields." }, "description": "按已确认成交量和流动性排序的资产列表。" }, "ranking": { "type": "string", "description": "推荐资产采用的排序口径。" }, "discovery_enabled": { "type": "boolean", "description": "是否启用资产搜索和发现。" } }, "required": [ "genesis", "featured", "recommended", "ranking", "discovery_enabled" ] }, "AssetSearch": { "type": "object", "properties": { "assets": { "type": "array", "items": { "type": "object", "properties": { "asset_id": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "资产的链上 ID，64 位小写十六进制；只在对应网络有效。" }, "symbol": { "type": "string", "description": "资产展示符号；发行时填 3–11 位大写字母数字，首位字母，不加 TRC20. 前缀。" }, "precision": { "type": "integer", "minimum": 0, "maximum": 18, "description": "资产小数位数；TSC 为 8，其他资产以链上登记值为准。" }, "listed": { "type": "boolean", "description": "是否在平台默认收录列表中；不是资产安全性认证。" } }, "required": [ "asset_id", "symbol", "precision", "listed" ] }, "description": "当前查询范围内的资产列表。" }, "page": { "type": "integer", "minimum": 0, "description": "页码，从 1 开始。" }, "has_more": { "type": "boolean", "description": "上游资产目录是否还有下一页；继续传 page+1。当前页无匹配也可能为 true，不是名称搜索结果分页。" }, "total_pages": { "type": "integer", "minimum": 0, "description": "上游资产目录的总页数；完整 Asset ID 的直接查询不返回此字段。" } }, "required": [ "assets", "page", "has_more" ] }, "AssetImport": { "type": "object", "properties": { "asset_id": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "资产的链上 ID，64 位小写十六进制；只在对应网络有效。" } }, "required": [ "asset_id" ], "additionalProperties": false }, "ServiceInfo": { "type": "object", "properties": { "api_version": { "type": "string", "description": "接口版本。" }, "network": { "type": "string", "description": "当前连接的链网络名称。" }, "genesis": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "当前网络的创世区块哈希，64 位小写十六进制。" }, "operator_key": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "第一个交易签名角色的 x-only 公钥。" }, "official_key": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "第二个交易签名角色的 x-only 公钥；角色名不代表官方实际参与。" }, "transaction_format": { "const": "tensorcash-vext-raw", "type": "string", "description": "交易序列化格式，TensorCash 原始交易包含 vExt。" }, "funding_address_type": { "const": "p2wpkh", "type": "string", "description": "支持的资金地址类型；当前为原生见证 P2WPKH。" }, "owner_derivation": { "type": "string", "description": "退出账户或密钥的派生标识；旧 v1 与标准账户 v2 不可混用。" }, "quote_ttl_seconds": { "type": "integer", "minimum": 0, "description": "正式报价有效期，单位秒；当前 300，不锁定 UTXO。" }, "estimate_ttl_seconds": { "type": "integer", "minimum": 0, "description": "预估结果有效期，单位秒；预估不预留池子储备。" }, "fee_units": { "type": "string", "pattern": "^[0-9]+$", "description": "本次交易矿工费，TSC 最小单位整数字符串；1 TSC = 100000000。" }, "carrier_units": { "type": "string", "pattern": "^[0-9]+$", "description": "池子载体金额，单位为 TSC 最小单位；全额退出可取回。" }, "lp_fee_bps_per_pool": { "type": "integer", "minimum": 0, "description": "每个池子的 LP 手续费率，单位基点；30 表示 0.30%。" }, "authentication": { "type": "string", "description": "资金操作的授权方式；由钱包签名授权。" }, "reference_asset_id": { "anyOf": [ { "type": "string", "pattern": "^[0-9a-f]{64}$" }, { "type": "null" } ], "description": "历史参考资产 ID；当前统一使用 TSC，返回 null。" }, "max_body_bytes": { "type": "integer", "minimum": 0, "description": "HTTP 请求体最大字节数。" }, "max_concurrent_requests": { "type": "integer", "minimum": 0, "description": "每个服务实例允许同时处理的公共请求数量。" }, "quote_symbol": { "const": "TSC", "description": "计价符号；当前为 TSC。" }, "swap_pairs": { "const": "asset_tsc", "description": "允许的交易对类型；asset_tsc 表示 Asset/TSC。" }, "max_icon_bytes": { "type": "integer", "const": 51200, "description": "上传图片最大字节数；51200 字节。" } }, "required": [ "api_version", "network", "genesis", "operator_key", "official_key", "transaction_format", "funding_address_type", "owner_derivation", "quote_ttl_seconds", "estimate_ttl_seconds", "fee_units", "carrier_units", "lp_fee_bps_per_pool", "authentication", "reference_asset_id", "max_body_bytes", "max_concurrent_requests", "quote_symbol", "swap_pairs", "max_icon_bytes" ] }, "OutPoint": { "type": "object", "properties": { "txid": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "链上交易 ID，64 位小写十六进制；不同于 quote_id 或 request_id。" }, "vout": { "type": "integer", "minimum": 0, "description": "交易输出位置，从 0 开始。" } }, "required": [ "txid", "vout" ], "additionalProperties": false }, "PoolConfig": { "type": "object", "properties": { "version": { "type": "integer", "const": 1, "description": "该对象协议格式版本。" }, "genesis": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "当前网络的创世区块哈希，64 位小写十六进制。" }, "nonce": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "新池随机数，32 字节小写十六进制；不能复用创建不同实例。" }, "asset_id": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "资产的链上 ID，64 位小写十六进制；只在对应网络有效。" }, "owner_key": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "池所有者退出公钥，32 字节 x-only 公钥，不是私钥。" }, "operator_key": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "第一个交易签名角色的 x-only 公钥。" }, "official_key": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "第二个交易签名角色的 x-only 公钥；角色名不代表官方实际参与。" }, "fee_bps": { "type": "integer", "const": 30, "description": "池手续费率，单位基点；30 表示 0.30%。" }, "carrier_units": { "type": "integer", "const": 100000, "description": "池子载体金额，单位为 TSC 最小单位；全额退出可取回。" } }, "required": [ "version", "genesis", "nonce", "asset_id", "owner_key", "operator_key", "official_key", "fee_bps", "carrier_units" ], "additionalProperties": false }, "PoolDescriptor": { "type": "object", "properties": { "config": { "$ref": "#/components/schemas/PoolConfig", "description": "池子脚本绑定的公开参数。" }, "pool_id": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "微池实例 ID，64 位小写十六进制；不是 Asset ID。" }, "script_pubkey": { "type": "string", "pattern": "^(?:[0-9a-f]{2})*$", "description": "池子 Taproot 锁定脚本，十六进制字符串。" }, "trade_script": { "type": "string", "pattern": "^(?:[0-9a-f]{2})*$", "description": "池子双签交易分支的脚本字节，十六进制。" }, "trade_control": { "type": "string", "pattern": "^(?:[0-9a-f]{2})*$", "description": "交易支出分支的 Taproot 控制块，十六进制。" }, "withdrawal_script": { "type": "string", "pattern": "^(?:[0-9a-f]{2})*$", "description": "LP 独立退出分支的脚本字节，十六进制。" }, "withdrawal_control": { "type": "string", "pattern": "^(?:[0-9a-f]{2})*$", "description": "LP 独立退出分支的 Taproot 控制块，十六进制。" } }, "required": [ "config", "pool_id", "script_pubkey", "trade_script", "trade_control", "withdrawal_script", "withdrawal_control" ], "additionalProperties": false }, "Registration": { "type": "object", "properties": { "descriptor": { "$ref": "#/components/schemas/PoolDescriptor", "description": "包含池子参数、脚本及退出分支的完整公开描述。" }, "native": { "$ref": "#/components/schemas/OutPoint", "description": "池子 TSC 储备的原始入金输出引用。" }, "asset": { "$ref": "#/components/schemas/OutPoint", "description": "原始入金交易中的 Asset 储备输出引用。" }, "owner_signature": { "type": "string", "pattern": "^(?:[0-9a-f]{2})*$", "description": "旧 v1 的登记 Schnorr 签名；未签名时为空字符串。标准账户 v2 使用 owner_proof，此字段仍为空。" }, "owner_proof": { "$ref": "#/components/schemas/OwnerProof", "description": "标准账户 v2 的 LP 所有权声明证明；与旧 owner_signature 不能同时使用。" } }, "required": [ "descriptor", "native", "asset", "owner_signature" ], "additionalProperties": false }, "RecoveryFile": { "type": "object", "properties": { "schema": { "type": "string", "enum": [ "tensorcash-micro-pool-wallet-v1", "tensorcash-micro-pool-wallet-v2" ], "description": "此对象的序列化版本标识。" }, "owner_derivation": { "type": "string", "enum": [ "hkdf-sha256-bip32-master-v1", "standard-account-v1" ], "description": "退出账户或密钥的派生标识；旧 v1 与标准账户 v2 不可混用。" }, "actor": { "type": "string", "description": "操作账户在当前网络的 P2WPKH 地址；仅提供地址不会授权花费。" }, "registration": { "$ref": "#/components/schemas/Registration", "description": "新池登记资料或资产注册交易；结构由所在接口定义。" }, "owner_public_key": { "type": "string", "description": "v2 恢复文件中的原钱包账户压缩公钥。" }, "account_id": { "type": "string", "description": "v2 恢复文件中原钱包账户的 script: 标识。" }, "funding_transaction": { "type": "string", "pattern": "^(?:[0-9a-f]{2})*$", "description": "v2 签名前保存的原始入金交易字节，用于恢复校验；服务端已登记备份可能省略。" } }, "required": [ "schema", "owner_derivation", "actor", "registration" ], "additionalProperties": false }, "EstimateRequest": { "type": "object", "properties": { "input_asset_id": { "oneOf": [ { "type": "string", "const": "TSC" }, { "type": "string", "pattern": "^[0-9a-f]{64}$" } ], "description": "卖出币种；TSC 或 64 位小写十六进制 Asset ID。" }, "output_asset_id": { "oneOf": [ { "type": "string", "const": "TSC" }, { "type": "string", "pattern": "^[0-9a-f]{64}$" } ], "description": "接收币种；当前兑换要求一侧为 TSC。" }, "amount": { "type": "string", "pattern": "^[0-9]+(?:\\.[0-9]+)?$", "description": "卖出金额，按卖出币种单位填写的十进制字符串；不能用 JSON 数字或科学计数法。" } }, "required": [ "input_asset_id", "output_asset_id", "amount" ], "additionalProperties": false, "oneOf": [ { "properties": { "input_asset_id": { "const": "TSC", "description": "卖出币种；TSC 或 64 位小写十六进制 Asset ID。" }, "output_asset_id": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "接收币种；当前兑换要求一侧为 TSC。" } } }, { "properties": { "input_asset_id": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "卖出币种；TSC 或 64 位小写十六进制 Asset ID。" }, "output_asset_id": { "const": "TSC", "description": "接收币种；当前兑换要求一侧为 TSC。" } } } ] }, "Estimate": { "type": "object", "properties": { "input": { "type": "object", "properties": { "asset_id": { "oneOf": [ { "type": "string", "const": "TSC" }, { "type": "string", "pattern": "^[0-9a-f]{64}$" } ], "description": "资产的链上 ID，64 位小写十六进制；只在对应网络有效。" }, "symbol": { "type": "string", "description": "资产展示符号；发行时填 3–11 位大写字母数字，首位字母，不加 TRC20. 前缀。" }, "precision": { "type": "integer", "minimum": 0, "description": "资产小数位数；TSC 为 8，其他资产以链上登记值为准。" } }, "required": [ "asset_id", "symbol", "precision" ], "description": "兑换的输入资产信息。" }, "output": { "type": "object", "properties": { "asset_id": { "oneOf": [ { "type": "string", "const": "TSC" }, { "type": "string", "pattern": "^[0-9a-f]{64}$" } ], "description": "资产的链上 ID，64 位小写十六进制；只在对应网络有效。" }, "symbol": { "type": "string", "description": "资产展示符号；发行时填 3–11 位大写字母数字，首位字母，不加 TRC20. 前缀。" }, "precision": { "type": "integer", "minimum": 0, "description": "资产小数位数；TSC 为 8，其他资产以链上登记值为准。" } }, "required": [ "asset_id", "symbol", "precision" ], "description": "兑换的接收资产信息。" }, "amount_in_units": { "type": "string", "pattern": "^[0-9]+$", "description": "卖出金额的最小单位数量，整数字符串。" }, "amount_out_units": { "type": "string", "pattern": "^[0-9]+$", "description": "预计接收币种的最小单位数量，整数字符串。" }, "amount_out": { "type": "string", "pattern": "^[0-9]+(?:\\.[0-9]+)?$", "description": "预计接收金额，按接收币种单位表示的十进制字符串。" }, "route_kind": { "type": "string", "enum": [ "direct", "split" ], "description": "预估路由类型；direct 单池，split 拆分到多个池。" }, "price_impact_bps": { "type": "integer", "minimum": 0, "description": "价格影响，单位基点；100 表示 1%，不同于滑点和手续费。" }, "pool_ids": { "type": "array", "items": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "description": "参与此记录的微池实例 ID 列表。" }, "path": { "type": "array", "items": { "type": "string" }, "description": "兑换经过的资产符号列表。" }, "network_fee_units": { "type": "string", "pattern": "^[0-9]+$", "description": "预计矿工费，TSC 最小单位整数字符串。" }, "lp_fee_bps_per_pool": { "type": "integer", "minimum": 0, "description": "每个池子的 LP 手续费率，单位基点；30 表示 0.30%。" }, "index": { "$ref": "#/components/schemas/IndexStatus", "description": "行情索引进度与同步状态；数据不完整时不要当作完整实时行情。" }, "quoted_at": { "type": "integer", "minimum": 0, "description": "生成预估时的时间，UTC Unix 秒。" }, "valid_for_seconds": { "type": "integer", "minimum": 0, "description": "预估有效期，单位秒。" } }, "required": [ "input", "output", "amount_in_units", "amount_out_units", "amount_out", "route_kind", "price_impact_bps", "pool_ids", "path", "network_fee_units", "lp_fee_bps_per_pool", "index", "quoted_at", "valid_for_seconds" ] }, "QuoteRequest": { "type": "object", "properties": { "actor": { "type": "string", "minLength": 1, "maxLength": 90, "description": "操作账户在当前网络的 P2WPKH 地址；仅提供地址不会授权花费。" }, "kind": { "type": "string", "enum": [ "create_pool", "add_liquidity", "increase_liquidity", "swap", "remove_liquidity" ], "description": "操作类型：创建、添加、追加、兑换或移除流动性。" }, "asset_id": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "资产的链上 ID，64 位小写十六进制；只在对应网络有效。" }, "pool_id": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "追加或提款时必填的原 Pool ID；创建独立新池时不传。" }, "nonce": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "创建、添加、追加及部分退出时必填的新实例随机数，32 字节小写十六进制。" }, "owner_key": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "创建、添加、追加及部分退出时必填的新实例退出公钥，32 字节 x-only 公钥，不是私钥。" }, "reference_pool_id": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "同一交易对的参考 Pool ID；准备入金时比例偏差超过 1% 返回 LIQUIDITY_PRICE_CHANGED，不锁定签名期间价格。" }, "tsc_amount": { "type": "string", "pattern": "^[0-9]+(?:\\.[0-9]+)?$", "description": "创建、添加、追加时必填的存入 TSC 金额，十进制字符串。" }, "asset_amount": { "type": "string", "pattern": "^[0-9]+(?:\\.[0-9]+)?$", "description": "创建、添加、追加时必填的存入 Asset 金额，按资产单位的十进制字符串。" }, "tsc_in": { "type": "boolean", "default": false, "description": "兑换方向；true 卖出 TSC 买 Asset，false 卖出 Asset 买 TSC。" }, "amount": { "type": "string", "pattern": "^[0-9]+(?:\\.[0-9]+)?$", "description": "kind=swap 时必填的卖出金额；按 tsc_in 指定的卖出币种单位填写十进制字符串。" }, "withdraw_bps": { "type": "integer", "minimum": 1, "maximum": 10000, "description": "kind=remove_liquidity 时必填；10000 为全额退出，1–9999 为部分退出，后者还需要 nonce 与 owner_key。" }, "output_asset_id": { "type": "string", "enum": [ "", "TSC" ], "description": "兼容字段，省略、空字符串或 TSC；当前不支持 Asset 到另一个 Asset 的请求。" }, "min_output_units": { "type": "string", "pattern": "^[0-9]+$", "description": "最低接收数量，按接收币种最小单位填写的整数字符串；准备报价时校验，签名后输出固定。" }, "recovery": { "$ref": "#/components/schemas/RecoveryFile", "description": "已有池子的公开恢复文件；仍需原钱包签名。" } }, "required": [ "actor", "kind", "asset_id" ], "additionalProperties": false, "oneOf": [ { "properties": { "kind": { "const": "increase_liquidity", "description": "操作类型：创建、添加、追加、兑换或移除流动性。" } }, "required": [ "pool_id", "nonce", "owner_key", "tsc_amount", "asset_amount" ] }, { "properties": { "kind": { "enum": [ "create_pool", "add_liquidity" ], "description": "操作类型：创建、添加、追加、兑换或移除流动性。" } }, "required": [ "nonce", "owner_key", "tsc_amount", "asset_amount" ] }, { "properties": { "kind": { "const": "swap", "description": "操作类型：创建、添加、追加、兑换或移除流动性。" } }, "required": [ "amount" ] }, { "properties": { "kind": { "const": "remove_liquidity", "description": "操作类型：创建、添加、追加、兑换或移除流动性。" }, "withdraw_bps": { "const": 10000, "description": "kind=remove_liquidity 时必填；10000 为全额退出，1–9999 为部分退出，后者还需要 nonce 与 owner_key。" } }, "required": [ "pool_id", "withdraw_bps" ] }, { "properties": { "kind": { "const": "remove_liquidity", "description": "操作类型：创建、添加、追加、兑换或移除流动性。" }, "withdraw_bps": { "minimum": 1, "maximum": 9999, "description": "kind=remove_liquidity 时必填；10000 为全额退出，1–9999 为部分退出，后者还需要 nonce 与 owner_key。" } }, "required": [ "pool_id", "withdraw_bps", "nonce", "owner_key" ] } ] }, "QuoteInput": { "type": "object", "properties": { "txid": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "链上交易 ID，64 位小写十六进制；不同于 quote_id 或 request_id。" }, "vout": { "type": "integer", "minimum": 0, "description": "交易输出位置，从 0 开始。" }, "value_units": { "type": "string", "pattern": "^[0-9]+$", "description": "该输入或输出的 TSC 最小单位数量，整数字符串；Asset 数量编码在 output_extension。" }, "script_pub_key": { "type": "string", "pattern": "^(?:[0-9a-f]{2})*$", "description": "输出锁定脚本，十六进制字符串。" }, "output_extension": { "type": "string", "pattern": "^(?:[0-9a-f]{2})*$", "description": "输出的 TensorCash 资产扩展字节，十六进制字符串。" } }, "required": [ "txid", "vout", "value_units", "script_pub_key", "output_extension" ] }, "OperationAmounts": { "type": "object", "properties": { "tsc_units": { "type": "string", "pattern": "^[0-9]+$", "description": "TSC 最小单位整数字符串；1 TSC = 100000000。" }, "asset_units": { "type": "string", "pattern": "^[0-9]+$", "description": "非 TSC 资产数量，按该资产精度表示的最小单位整数字符串。" }, "tsc_in": { "type": "boolean", "description": "兑换方向；true 卖出 TSC 买 Asset，false 卖出 Asset 买 TSC。" }, "withdraw_bps": { "type": "integer", "minimum": 0, "description": "提款比例，1–10000 基点；10000 全额退出，部分退出会生成继任池。" } }, "required": [ "tsc_units", "asset_units", "tsc_in", "withdraw_bps" ] }, "Quote": { "type": "object", "properties": { "schema": { "type": "integer", "const": 1, "description": "此对象的序列化版本标识。" }, "quote_id": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "报价与后续操作 ID；用于 execute 和 operations，不是交易 txid。" }, "expires_at": { "type": "integer", "minimum": 0, "description": "失效时间；交易和审核为 UTC Unix 秒，美元参考价为毫秒。" }, "kind": { "type": "string", "enum": [ "create_pool", "add_liquidity", "increase_liquidity", "swap", "remove_liquidity" ], "description": "操作类型：创建、添加、追加、兑换或移除流动性。" }, "actor": { "type": "string", "description": "操作账户在当前网络的 P2WPKH 地址；仅提供地址不会授权花费。" }, "asset_id": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "资产的链上 ID，64 位小写十六进制；只在对应网络有效。" }, "symbol": { "type": "string", "description": "资产展示符号；发行时填 3–11 位大写字母数字，首位字母，不加 TRC20. 前缀。" }, "precision": { "type": "integer", "minimum": 0, "description": "资产小数位数；TSC 为 8，其他资产以链上登记值为准。" }, "fee_units": { "type": "string", "pattern": "^[0-9]+$", "description": "本次交易矿工费，TSC 最小单位整数字符串；1 TSC = 100000000。" }, "tx_hex": { "type": "string", "pattern": "^(?:[0-9a-f]{2})*$", "description": "原始 TensorCash 交易字节，十六进制；须保留完整签名版本以供恢复。" }, "inputs": { "type": "array", "items": { "$ref": "#/components/schemas/QuoteInput" }, "description": "交易引用的输入及其实际前序输出资料。" }, "created": { "anyOf": [ { "$ref": "#/components/schemas/PoolDescriptor" }, { "type": "null" } ], "description": "本次将创建的池描述；不创建新池时为 null。" }, "retired": { "anyOf": [ { "$ref": "#/components/schemas/PoolDescriptor" }, { "type": "null" } ], "description": "本次将退出或替换的旧池描述；无旧池时为 null。" }, "registration": { "anyOf": [ { "$ref": "#/components/schemas/Registration" }, { "type": "null" } ], "description": "新池登记资料或资产注册交易；结构由所在接口定义。" }, "routes": { "type": "array", "items": { "type": "object", "properties": { "descriptor": { "$ref": "#/components/schemas/PoolDescriptor", "description": "包含池子参数、脚本及退出分支的完整公开描述。" }, "input_index": { "type": "integer", "minimum": 0, "description": "池子输入在交易中的位置，从 0 开始。" }, "output_index": { "type": "integer", "minimum": 0, "description": "池子后继输出在交易中的位置，从 0 开始。" } }, "required": [ "descriptor", "input_index", "output_index" ] }, "description": "本次兑换参与的池及其输入、后继输出位置。" }, "amounts": { "$ref": "#/components/schemas/OperationAmounts", "description": "本次操作的 TSC、Asset 数量和操作方向。" }, "cross_asset": { "anyOf": [ { "type": "object", "properties": { "asset_id": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "资产的链上 ID，64 位小写十六进制；只在对应网络有效。" }, "symbol": { "type": "string", "description": "资产展示符号；发行时填 3–11 位大写字母数字，首位字母，不加 TRC20. 前缀。" }, "precision": { "type": "integer", "minimum": 0, "description": "资产小数位数；TSC 为 8，其他资产以链上登记值为准。" }, "output_units": { "type": "string", "pattern": "^[0-9]+$", "description": "接收资产的最小单位数量，整数字符串。" }, "intermediate_tsc_units": { "type": "string", "pattern": "^[0-9]+$", "description": "历史多跳路由中间 TSC 数量，最小单位整数字符串。" } }, "required": [ "asset_id", "symbol", "precision", "output_units", "intermediate_tsc_units" ] }, { "type": "null" } ], "description": "历史跨资产路由信息；当前 Asset/TSC 接口不支持跨资产请求。" }, "swap_plan": { "anyOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "direct", "split", "multi_hop" ], "description": "操作类型：创建、添加、追加、兑换或移除流动性。" }, "price_impact_bps": { "type": "integer", "minimum": 0, "description": "价格影响，单位基点；100 表示 1%，不同于滑点和手续费。" } }, "required": [ "kind", "price_impact_bps" ] }, { "type": "null" } ], "description": "兑换路由类型和价格影响；非兑换时为 null。" }, "previous_transactions": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^(?:[0-9a-f]{2})*$" }, "description": "txid 到完整前序交易原始字节的映射；须独立重算 txid 和输入金额。" } }, "required": [ "schema", "quote_id", "expires_at", "kind", "actor", "asset_id", "symbol", "precision", "fee_units", "tx_hex", "inputs", "created", "retired", "registration", "routes", "amounts", "cross_asset", "swap_plan", "previous_transactions" ] }, "ExecuteRequest": { "type": "object", "properties": { "quote_id": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "报价与后续操作 ID；用于 execute 和 operations，不是交易 txid。" }, "hex": { "type": "string", "pattern": "^(?:[0-9a-f]{2})*$", "description": "原始 TensorCash 交易的十六进制字节；不是 PSBT 或 EVM 交易。" }, "registration": { "anyOf": [ { "$ref": "#/components/schemas/Registration" }, { "type": "null" } ], "description": "新池登记资料或资产注册交易；结构由所在接口定义。" } }, "required": [ "quote_id", "hex" ], "additionalProperties": false }, "SignedTransaction": { "type": "object", "properties": { "schema": { "type": "string", "const": "tern-signed-transaction-v1", "description": "此对象的序列化版本标识。" }, "genesis": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "当前网络的创世区块哈希，64 位小写十六进制。" }, "quote_id": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "报价与后续操作 ID；用于 execute 和 operations，不是交易 txid。" }, "txid": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "链上交易 ID，64 位小写十六进制；不同于 quote_id 或 request_id。" }, "tx_hex": { "type": "string", "pattern": "^(?:[0-9a-f]{2})*$", "minLength": 2, "description": "原始 TensorCash 交易字节，十六进制；须保留完整签名版本以供恢复。" } }, "required": [ "schema", "genesis", "quote_id", "txid", "tx_hex" ], "additionalProperties": false, "description": "Complete Core transaction, including both trading-service witnesses when required. Persist it locally for independent rebroadcast. No private keys are included. Broadcast acceptance does not guarantee confirmation." }, "Execution": { "type": "object", "properties": { "quote_id": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "报价与后续操作 ID；用于 execute 和 operations，不是交易 txid。" }, "txid": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "链上交易 ID，64 位小写十六进制；不同于 quote_id 或 request_id。" }, "state": { "type": "string", "enum": [ "submitting", "pending", "confirmed", "rechecking" ], "description": "submitting 处理签名或广播；pending 已广播待确认；confirmed 已确认；rechecking 重组后重新检查。" }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "错误说明；无错误时为 null，交易状态仍以 state 为准。" }, "backup": { "anyOf": [ { "$ref": "#/components/schemas/RecoveryFile" }, { "type": "null" } ], "description": "新池的公开恢复资料；没有新池时为 null，不包含私钥。" }, "transaction": { "anyOf": [ { "$ref": "#/components/schemas/SignedTransaction" }, { "type": "null" } ], "description": "原始交易格式与字节，是否完整签名由本接口阶段决定。" } }, "required": [ "quote_id", "txid", "state", "error", "backup" ] }, "Operation": { "type": "object", "properties": { "quote_id": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "报价与后续操作 ID；用于 execute 和 operations，不是交易 txid。" }, "kind": { "type": "string", "enum": [ "create_pool", "add_liquidity", "increase_liquidity", "swap", "remove_liquidity" ], "description": "操作类型：创建、添加、追加、兑换或移除流动性。" }, "actor": { "type": "string", "description": "操作账户在当前网络的 P2WPKH 地址；仅提供地址不会授权花费。" }, "state": { "type": "string", "enum": [ "quoted", "expired", "submitting", "pending", "confirmed", "rechecking" ], "description": "quoted 待签名提交；expired 未提交已过期；submitting 处理中；pending 已广播待确认；confirmed 已确认；rechecking 重组后重新检查。" }, "txid": { "anyOf": [ { "type": "string", "pattern": "^[0-9a-f]{64}$" }, { "type": "null" } ], "description": "链上交易 ID，64 位小写十六进制；不同于 quote_id 或 request_id。" }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "错误说明；无错误时为 null，交易状态仍以 state 为准。" }, "created_at": { "type": "integer", "minimum": 0, "description": "操作记录创建时间，UTC Unix 秒。" }, "expires_at": { "type": "integer", "minimum": 0, "description": "失效时间；交易和审核为 UTC Unix 秒，美元参考价为毫秒。" }, "amounts": { "$ref": "#/components/schemas/OperationAmounts", "description": "本次操作的 TSC、Asset 数量和操作方向。" }, "created_pool_id": { "anyOf": [ { "type": "string", "pattern": "^[0-9a-f]{64}$" }, { "type": "null" } ], "description": "本次新池 ID；没有新池时为 null。" }, "retired_pool_id": { "anyOf": [ { "type": "string", "pattern": "^[0-9a-f]{64}$" }, { "type": "null" } ], "description": "退出或替换的旧池 ID；没有旧池时为 null。" } }, "required": [ "quote_id", "kind", "actor", "state", "txid", "error", "created_at", "expires_at", "amounts", "created_pool_id", "retired_pool_id" ] }, "State": { "type": "object", "properties": { "mode": { "type": "string", "description": "当前服务结算模式，micro_pool_2of2 表示双签微池。" }, "network": { "type": "string", "description": "当前连接的链网络名称。" }, "genesis": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "当前网络的创世区块哈希，64 位小写十六进制。" }, "operator_key": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "第一个交易签名角色的 x-only 公钥。" }, "official_key": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "第二个交易签名角色的 x-only 公钥；角色名不代表官方实际参与。" }, "assets": { "type": "array", "items": { "$ref": "#/components/schemas/AssetMetadata" }, "description": "当前查询范围内的资产列表。" }, "listed_asset_ids": { "type": "array", "items": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "description": "默认收录的 Asset ID 列表。" }, "asset_discovery": { "type": "boolean", "description": "是否启用上游资产发现。" }, "reference_asset_id": { "anyOf": [ { "type": "string", "pattern": "^[0-9a-f]{64}$" }, { "type": "null" } ], "description": "历史参考资产 ID；当前统一使用 TSC，返回 null。" }, "asset_id": { "type": "string", "pattern": "^(?:[0-9a-f]{64})?$", "description": "当前选择的 Asset ID；部署未设置默认资产时可能为空字符串。" }, "symbol": { "type": "string", "description": "资产展示符号；发行时填 3–11 位大写字母数字，首位字母，不加 TRC20. 前缀。" }, "precision": { "type": "integer", "minimum": 0, "description": "资产小数位数；TSC 为 8，其他资产以链上登记值为准。" }, "fee_units": { "type": "string", "pattern": "^[0-9]+$", "description": "本次交易矿工费，TSC 最小单位整数字符串；1 TSC = 100000000。" }, "core_height": { "type": "integer", "minimum": 0, "description": "节点已验证的区块高度。" }, "core_headers": { "type": "integer", "minimum": 0, "description": "节点已知的最高区块头高度。" }, "node_ready": { "type": "boolean", "description": "节点是否已完成同步并可处理交易。" }, "ready": { "type": "boolean", "description": "节点及交易签名服务是否就绪。" }, "halted": { "type": "boolean", "description": "协调服务是否处于暂停状态。" }, "signers": { "type": "array", "items": { "type": "object", "description": "Public signer health and identity; never bearer tokens or private keys." }, "description": "两名交易签名服务的公开身份与健康状态，不包含访问令牌。" }, "balances": { "type": "object", "properties": { "tsc": { "type": "string", "pattern": "^[0-9]+(?:\\.[0-9]+)?$", "description": "TSC 数量，按 TSC 单位表示的十进制字符串。" }, "asset": { "type": "string", "pattern": "^[0-9]+(?:\\.[0-9]+)?$", "description": "所查询地址持有的当前选择 Asset 数量，按该资产精度表示。" } }, "required": [ "tsc", "asset" ], "description": "所查询地址的 TSC 与所选资产余额。" }, "pools": { "type": "array", "items": { "type": "object", "properties": { "pool_id": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "微池实例 ID，64 位小写十六进制；不是 Asset ID。" }, "position_id": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "延续追加和部分退出历史的逻辑仓位 ID。" }, "previous_pool_id": { "anyOf": [ { "type": "string", "pattern": "^[0-9a-f]{64}$" }, { "type": "null" } ], "description": "该实例的前一个微池 ID；首次建立时为 null。" }, "asset_id": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "资产的链上 ID，64 位小写十六进制；只在对应网络有效。" }, "symbol": { "type": "string", "description": "资产展示符号；发行时填 3–11 位大写字母数字，首位字母，不加 TRC20. 前缀。" }, "precision": { "type": "integer", "minimum": 0, "description": "资产小数位数；TSC 为 8，其他资产以链上登记值为准。" }, "actor": { "type": "string", "description": "操作账户在当前网络的 P2WPKH 地址；仅提供地址不会授权花费。" }, "descriptor": { "$ref": "#/components/schemas/PoolDescriptor", "description": "包含池子参数、脚本及退出分支的完整公开描述。" }, "state": { "type": "string", "enum": [ "pending", "active", "exit_available", "closed" ], "description": "当前状态；可选值及阶段解释见此接口。" }, "tsc": { "type": "string", "pattern": "^[0-9]+(?:\\.[0-9]+)?$", "description": "TSC 数量，按 TSC 单位表示的十进制字符串。" }, "asset": { "type": "string", "pattern": "^[0-9]+(?:\\.[0-9]+)?$", "description": "池子 Asset 储备，按该资产单位的十进制字符串。" }, "owned": { "type": "boolean", "description": "查询地址是否为该仓位的所有者。" } }, "required": [ "pool_id", "position_id", "previous_pool_id", "asset_id", "symbol", "precision", "actor", "descriptor", "state", "tsc", "asset", "owned" ] }, "description": "平台登记的池子列表。" }, "operations": { "type": "array", "items": { "type": "object", "description": "Submitted operations for the queried address. Use /operations/{id} for individual status." }, "description": "所查询地址已提交的操作列表。" }, "quote_symbol": { "const": "TSC", "description": "计价符号；当前为 TSC。" }, "tsc_usd_reference": { "$ref": "#/components/schemas/TscUsdReference", "description": "共享的 TSC 美元辅助估值缓存，不参与兑换计算。" }, "chain_id": { "anyOf": [ { "type": "string", "pattern": "^tsc:[0-9a-f]{64}:(public|[0-9a-f]{64})$" }, { "type": "null" } ], "description": "目标网络标识，公共网络格式为 tsc::public。" }, "standard_account_lp_enabled": { "type": "boolean", "description": "是否已允许标准钱包账户创建或替换 LP 仓位。" } }, "required": [ "mode", "network", "genesis", "operator_key", "official_key", "assets", "listed_asset_ids", "asset_discovery", "reference_asset_id", "asset_id", "symbol", "precision", "fee_units", "core_height", "core_headers", "node_ready", "ready", "halted", "signers", "balances", "pools", "operations", "quote_symbol", "tsc_usd_reference", "chain_id", "standard_account_lp_enabled" ] }, "TscUsdReference": { "type": "object", "properties": { "base_symbol": { "const": "TSC", "description": "被定价资产的展示符号。" }, "source": { "const": "SafeTrade", "description": "数据来源标识。" }, "source_market": { "const": "TSC/USDT", "description": "参考价来源市场，TSC/USDT。" }, "status": { "enum": [ "available", "stale", "unavailable" ], "description": "available 价格可用；stale 已过期；unavailable 未获取到价格。后两种状态 usd_price 为 null。" }, "usd_price": { "anyOf": [ { "type": "string", "pattern": "^[0-9]+(?:\\.[0-9]+)?$", "description": "Human decimal amount. Never send a JSON number or exponential notation." }, { "type": "null" } ], "description": "1 TSC 的近似美元价格，十进制字符串；过期或不可用为 null。" }, "observed_at": { "anyOf": [ { "type": "integer", "minimum": 0 }, { "type": "null" } ], "description": "参考价采集时间，UTC Unix 毫秒；不是交易所最新成交时间。" }, "expires_at": { "anyOf": [ { "type": "integer", "minimum": 0 }, { "type": "null" } ], "description": "参考价缓存到期时间，UTC Unix 毫秒；尚无价格时为 null。" }, "time_unit": { "const": "unix_ms", "description": "时间戳单位，行情与参考价为 unix_ms。" }, "approximate": { "const": true, "description": "是否为近似换算；美元展示按 1 USDT 约等于 1 USD。" }, "conversion": { "type": "string", "description": "美元辅助估值的换算假设。" }, "purpose": { "const": "display_only", "description": "参考价用途；display_only 表示只用于显示美元估值。" } }, "required": [ "base_symbol", "source", "source_market", "status", "usd_price", "observed_at", "expires_at", "time_unit", "approximate", "conversion", "purpose" ] }, "UploadedIcon": { "type": "object", "properties": { "cid": { "type": "string", "description": "已经核验并固定存储的 IPFS 内容标识。" }, "url": { "type": "string", "description": "用于显示图片的 HTTPS 网关地址；更换网关不改变链上 uri。" }, "storage": { "const": "ipfs", "type": "string", "description": "头像存储类型；新上传使用 ipfs。" }, "uri": { "type": "string", "description": "写入链上资料的图片地址；平台上传返回 ipfs://CID。" }, "sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "处理后图片字节的 SHA-256 摘要。" }, "bytes": { "type": "integer", "minimum": 1, "maximum": 51200, "description": "处理后图片的字节数。" }, "width": { "type": "integer", "minimum": 1, "maximum": 256, "description": "处理后图片宽度，单位像素。" }, "height": { "type": "integer", "minimum": 1, "maximum": 256, "description": "处理后图片高度，单位像素。" }, "content_type": { "type": "string", "const": "image/webp", "description": "处理后图片的媒体类型。" } }, "required": [ "cid", "url", "storage", "uri", "sha256", "bytes", "width", "height", "content_type" ] }, "SponsoredIssuance": { "type": "object", "properties": { "mode": { "type": "string", "const": "sponsored", "description": "旧版发行草稿中的子资产模式，固定 sponsored；新 /issuances 请求使用 mode: trc20。" }, "protocol": { "type": "string", "pattern": "^[A-Z][A-Z0-9]{2,10}$", "description": "子资产发行命名标准标识，当前为 TRC20。" }, "version": { "type": "integer", "const": 1, "description": "该对象协议格式版本。" }, "namespace": { "type": "string", "pattern": "^[A-Z][A-Z0-9]{2,10}$", "description": "子资产链上名称前缀，当前为 TRC20。" }, "parent_asset_id": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "平台 Parent 的链上 Asset ID。" } }, "required": [ "mode", "protocol", "version", "namespace", "parent_asset_id" ], "additionalProperties": false }, "CreationConfig": { "type": "object", "properties": { "genesis": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "当前网络的创世区块哈希，64 位小写十六进制。" }, "default_mode": { "type": "string", "enum": [ "root", "sponsored" ], "description": "旧 /launches 接口的默认模式；root 独立资产，sponsored 已配置子资产。" }, "root": { "type": "object", "properties": { "enabled": { "type": "boolean", "const": true, "description": "独立父资产模式已定义；不是实时开关，能否发行必须同时检查 availability.enabled。" }, "bond_units": { "type": "string", "const": "500000000", "description": "注册保证金，TSC 最小单位整数字符串；1 TSC = 100000000。" } }, "required": [ "enabled", "bond_units" ], "description": "独立父资产的模式配置；不表示当前发行已开放。" }, "sponsored": { "anyOf": [ { "type": "object", "properties": { "issuance": { "$ref": "#/components/schemas/SponsoredIssuance", "description": "子资产的协议、命名空间和 Parent 配置；独立资产不需要。" }, "bond_units": { "type": "string", "const": "10000", "description": "注册保证金，TSC 最小单位整数字符串；1 TSC = 100000000。" } }, "required": [ "issuance", "bond_units" ] }, { "type": "null" } ], "description": "已配置 Parent 的子资产发行信息；未配置时为 null。" }, "wallet_protocol": { "type": "object", "properties": { "name": { "const": "TWP", "description": "发行签名协议名称，固定 TWP。" }, "draft_revision": { "const": "0.2", "description": "钱包协议草案版本；不同版本不能视为自动兼容。" }, "spec_hash": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "精确钱包协议文档摘要，不能仅按版本号判断兼容。" }, "chain_id": { "anyOf": [ { "type": "string", "pattern": "^tsc:[0-9a-f]{64}:(public|[0-9a-f]{64})$" }, { "type": "null" } ], "description": "目标网络标识，公共网络格式为 tsc::public。" } }, "required": [ "name", "draft_revision", "spec_hash", "chain_id" ], "description": "发行签名请求所采用的协议版本、摘要和网络标识。" }, "availability": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "当前部署是否开放发行；false 时创建请求返回 code 中的错误。" }, "code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "发行关闭时的错误码；启用时为 null。" }, "message": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "发行关闭原因；启用时为 null。" } }, "required": [ "enabled", "code", "message" ], "description": "当前部署的发行能力状态；以 enabled 判断是否开放。" }, "media": { "type": "object", "properties": { "upload_enabled": { "type": "boolean", "description": "当前环境是否允许上传图片。" }, "storage": { "const": "ipfs", "type": "string", "description": "头像存储类型；新上传使用 ipfs。" }, "gateway_base_url": { "type": "string", "description": "显示 IPFS 图片所用的 HTTPS 网关前缀。" }, "max_upload_bytes": { "const": 51200, "type": "integer", "description": "上传图片解码后原始字节上限；51200 字节。" }, "url_schemes": { "type": "array", "items": { "enum": [ "https", "ipfs" ] }, "description": "允许的图片 URL 协议；https 和 ipfs。" }, "metadata_immutable": { "const": true, "type": "boolean", "description": "当前资产发行流程中的链上元数据是否不可修改。" } }, "required": [ "upload_enabled", "storage", "gateway_base_url", "max_upload_bytes", "url_schemes", "metadata_immutable" ], "description": "图标上传、URL 和存储能力配置。" } }, "required": [ "genesis", "default_mode", "root", "sponsored" ] }, "CreationDraft": { "type": "object", "properties": { "asset_id": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "资产的链上 ID，64 位小写十六进制；只在对应网络有效。" }, "name": { "type": "string", "minLength": 1, "maxLength": 80, "description": "资产展示名称，1–80 个字符。" }, "symbol": { "type": "string", "pattern": "^[A-Z][A-Z0-9]{2,10}$", "description": "资产展示符号；发行时填 3–11 位大写字母数字，首位字母，不加 TRC20. 前缀。" }, "description": { "type": "string", "minLength": 1, "maxLength": 2000, "description": "公开资产简介，1–2000 个字符。" }, "decimals": { "type": "integer", "minimum": 0, "maximum": 18, "description": "资产精度，0–18；最小单位数量 = supply × 10^decimals。" }, "supply": { "type": "string", "pattern": "^[0-9]+(?:\\.[0-9]+)?$", "description": "首次发行数量，按资产单位填写的十进制字符串；乘 10^decimals 后须为 uint64 范围内整数，不是实时流通量。" }, "icon_url": { "type": "string", "description": "HTTPS 或 ipfs://CID 图片地址；原样写入元数据，不由服务器下载；与 icon_base64 互斥。" }, "links": { "type": "object", "properties": { "website": { "type": "string", "description": "项目官网 HTTPS 地址。" }, "x": { "type": "string", "description": "项目 X 主页 HTTPS 地址。" }, "telegram": { "type": "string", "description": "Telegram 社区 HTTPS 地址。" }, "discord": { "type": "string", "description": "Discord 社区 HTTPS 地址。" }, "docs": { "type": "string", "description": "项目文档 HTTPS 地址。" }, "github": { "type": "string", "description": "项目代码仓库 HTTPS 地址。" }, "whitepaper": { "type": "string", "description": "项目白皮书 HTTPS 地址。" } }, "additionalProperties": false, "description": "可选社交与资料链接对象，支持 website、x、telegram、discord、docs、github、whitepaper。" }, "issuance": { "anyOf": [ { "$ref": "#/components/schemas/SponsoredIssuance" }, { "type": "null" } ], "description": "子资产的协议、命名空间和 Parent 配置；独立资产不需要。" } }, "required": [ "asset_id", "name", "symbol", "description", "decimals", "supply" ], "additionalProperties": false }, "AssetDocumentMetadata": { "type": "object", "properties": { "protocol": { "const": "tc-asset-meta", "type": "string", "description": "链上资产展示资料的协议名称。" }, "version": { "const": 1, "type": "integer", "description": "该对象协议格式版本。" }, "display_name": { "type": "string", "description": "元数据中的资产展示名称。" }, "summary": { "type": "string", "description": "资产元数据中的公开简介。" }, "links": { "type": "object", "additionalProperties": { "type": "string" }, "description": "可选社交与资料链接对象，支持 website、x、telegram、discord、docs、github、whitepaper。" }, "icon": { "type": "object", "properties": { "uri": { "type": "string", "description": "写入链上资料的图片地址；平台上传返回 ipfs://CID。" } }, "required": [ "uri" ], "description": "头像元数据，uri 为写入链上的地址。" }, "issuance": { "$ref": "#/components/schemas/SponsoredIssuance", "description": "子资产发行标准与 Parent 身份；不是当前实时发行开关。" }, "symbol": { "type": "string", "description": "资产展示符号；发行时填 3–11 位大写字母数字，首位字母，不加 TRC20. 前缀。" }, "chain_symbol": { "type": "string", "description": "完整链上符号；子资产包含命名空间前缀。" } }, "required": [ "protocol", "version", "display_name", "summary", "links" ] }, "CreationPreview": { "type": "object", "properties": { "draft": { "$ref": "#/components/schemas/CreationDraft", "description": "本次发行固定的完整资产资料。" }, "metadata": { "$ref": "#/components/schemas/AssetDocumentMetadata", "description": "资产描述文档中的展示名称、简介、图标和链接。" }, "document": { "type": "string", "description": "写入注册交易的完整资产描述文档。" }, "bond_units": { "type": "string", "pattern": "^[0-9]+$", "description": "注册保证金，TSC 最小单位整数字符串；1 TSC = 100000000。" }, "supply_units": { "type": "string", "pattern": "^[0-9]+$", "description": "首次发行的最小单位数量，整数字符串；等于 supply × 10^decimals。" }, "policy_bits": { "type": "integer", "const": 3, "description": "注册资产的链上策略位字段。" }, "immutable": { "const": true, "type": "boolean", "description": "资产资料在当前发行流程中是否不可修改。" }, "genesis": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "当前网络的创世区块哈希，64 位小写十六进制。" }, "chain_symbol": { "type": "string", "description": "完整链上符号；子资产包含命名空间前缀。" } }, "required": [ "draft", "metadata", "document", "bond_units", "supply_units", "policy_bits", "immutable", "genesis" ] }, "CreationPrepare": { "type": "object", "properties": { "actor": { "type": "string", "description": "操作账户在当前网络的 P2WPKH 地址；仅提供地址不会授权花费。" }, "step": { "type": "string", "enum": [ "register", "mint" ], "description": "发行阶段：register 注册资产，mint 发行初始数量。" }, "draft": { "$ref": "#/components/schemas/CreationDraft", "description": "本次发行固定的完整资产资料。" } }, "required": [ "actor", "step", "draft" ], "additionalProperties": false }, "CreationPreparedTx": { "type": "object", "properties": { "operation": { "type": "string", "enum": [ "asset_create", "asset_mint" ], "description": "交易操作语义；asset_create 注册资产，asset_mint 铸币。" }, "identifier": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "本次资产创建或铸币对应的资产 ID。" }, "state": { "const": "unsigned", "type": "string", "description": "当前状态；可选值及阶段解释见此接口。" }, "hex": { "type": "string", "pattern": "^(?:[0-9a-f]{2})*$", "description": "原始 TensorCash 交易的十六进制字节；不是 PSBT 或 EVM 交易。" }, "psbt": { "const": "", "type": "string", "description": "兼容字段；当前为空字符串，使用 hex 中的原始交易。" }, "fee_units": { "type": "string", "pattern": "^[0-9]+$", "description": "本次交易矿工费，TSC 最小单位整数字符串；1 TSC = 100000000。" }, "change_units": { "type": "string", "pattern": "^[0-9]+$", "description": "找零金额，TSC 最小单位整数字符串。" }, "core_tip_hash": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "构造待签名交易时的链尖区块哈希。" }, "requires_signing": { "const": true, "type": "boolean", "description": "交易是否尚需钱包签名。" }, "broadcast": { "const": false, "type": "boolean", "description": "本次接口是否广播了交易；false 时仍须由调用方广播。" }, "inputs": { "type": "array", "items": { "type": "object", "properties": { "txid": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "链上交易 ID，64 位小写十六进制；不同于 quote_id 或 request_id。" }, "vout": { "type": "integer", "minimum": 0, "description": "交易输出位置，从 0 开始。" }, "value_units": { "type": "string", "pattern": "^[0-9]+$", "description": "该输入或输出的 TSC 最小单位数量，整数字符串；Asset 数量编码在 output_extension。" }, "script_pub_key": { "type": "string", "pattern": "^(?:[0-9a-f]{2})*$", "description": "输出锁定脚本，十六进制字符串。" }, "output_extension": { "type": "string", "pattern": "^(?:[0-9a-f]{2})*$", "description": "输出的 TensorCash 资产扩展字节，十六进制字符串。" } }, "required": [ "txid", "vout", "value_units", "script_pub_key", "output_extension" ] }, "description": "交易引用的输入及其实际前序输出资料。" }, "outputs": { "type": "array", "items": { "type": "object", "properties": { "vout": { "type": "integer", "minimum": 0, "description": "交易输出位置，从 0 开始。" }, "value_units": { "type": "string", "pattern": "^[0-9]+$", "description": "该输入或输出的 TSC 最小单位数量，整数字符串；Asset 数量编码在 output_extension。" }, "script_pub_key": { "type": "string", "pattern": "^(?:[0-9a-f]{2})*$", "description": "输出锁定脚本，十六进制字符串。" }, "output_extension": { "type": "string", "pattern": "^(?:[0-9a-f]{2})*$", "description": "输出的 TensorCash 资产扩展字节，十六进制字符串。" } }, "required": [ "vout", "value_units", "script_pub_key", "output_extension" ] }, "description": "交易输出列表，包含金额、锁定脚本和资产扩展。" } }, "required": [ "operation", "identifier", "state", "hex", "psbt", "fee_units", "change_units", "core_tip_hash", "requires_signing", "broadcast", "inputs", "outputs" ] }, "CreationReview": { "type": "object", "properties": { "schema": { "type": "string", "enum": [ "tern-asset-launch-v1", "tc-asset-launch-v2" ], "description": "此对象的序列化版本标识。" }, "review_id": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "本次待签名交易的审核 ID；与阶段和确切交易绑定。" }, "expires_at": { "type": "integer", "minimum": 0, "description": "失效时间；交易和审核为 UTC Unix 秒，美元参考价为毫秒。" }, "genesis": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "当前网络的创世区块哈希，64 位小写十六进制。" }, "actor": { "type": "string", "description": "操作账户在当前网络的 P2WPKH 地址；仅提供地址不会授权花费。" }, "step": { "type": "string", "enum": [ "register", "mint" ], "description": "发行阶段：register 注册资产，mint 发行初始数量。" }, "draft": { "$ref": "#/components/schemas/CreationDraft", "description": "本次发行固定的完整资产资料。" }, "document": { "type": "string", "description": "写入注册交易的完整资产描述文档。" }, "intent": { "type": "object", "description": "本次注册或铸币的审核意图，绑定资金、描述文档、数量上限和接收方。" }, "prepared": { "$ref": "#/components/schemas/CreationPreparedTx", "description": "未签名交易及构造时的输入输出明细。" }, "previous_transactions": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^(?:[0-9a-f]{2})*$" }, "description": "txid 到完整前序交易原始字节的映射；须独立重算 txid 和输入金额。" }, "chain_symbol": { "type": "string", "description": "完整链上符号；子资产包含命名空间前缀。" } }, "required": [ "schema", "review_id", "expires_at", "genesis", "actor", "step", "draft", "document", "intent", "prepared", "previous_transactions" ] }, "CreationSubmit": { "type": "object", "properties": { "review_id": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "本次待签名交易的审核 ID；与阶段和确切交易绑定。" }, "hex": { "type": "string", "pattern": "^(?:[0-9a-f]{2})*$", "description": "原始 TensorCash 交易的十六进制字节；不是 PSBT 或 EVM 交易。" } }, "required": [ "review_id", "hex" ], "additionalProperties": false }, "CreationSubmission": { "type": "object", "properties": { "asset_id": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "资产的链上 ID，64 位小写十六进制；只在对应网络有效。" }, "step": { "type": "string", "enum": [ "register", "mint" ], "description": "发行阶段：register 注册资产，mint 发行初始数量。" }, "txid": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "链上交易 ID，64 位小写十六进制；不同于 quote_id 或 request_id。" }, "state": { "const": "submitted", "type": "string", "description": "当前状态；可选值及阶段解释见此接口。" } }, "required": [ "asset_id", "step", "txid", "state" ] }, "CreationTxState": { "type": "object", "properties": { "txid": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "链上交易 ID，64 位小写十六进制；不同于 quote_id 或 request_id。" }, "state": { "type": "string", "enum": [ "pending", "confirmed", "not_seen" ], "description": "pending 已提交未确认；confirmed 已确认；not_seen 当前节点未观察到交易。" }, "confirmations": { "type": "integer", "minimum": 0, "description": "当前有效链上的确认次数；重组后可能减少。" } }, "required": [ "txid", "state", "confirmations" ] }, "CreationStatus": { "type": "object", "properties": { "genesis": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "当前网络的创世区块哈希，64 位小写十六进制。" }, "asset_id": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "资产的链上 ID，64 位小写十六进制；只在对应网络有效。" }, "actor": { "type": "string", "description": "操作账户在当前网络的 P2WPKH 地址；仅提供地址不会授权花费。" }, "draft": { "$ref": "#/components/schemas/CreationDraft", "description": "本次发行固定的完整资产资料。" }, "document": { "type": "string", "description": "写入注册交易的完整资产描述文档。" }, "metadata": { "$ref": "#/components/schemas/AssetDocumentMetadata", "description": "资产描述文档中的展示名称、简介、图标和链接。" }, "register": { "$ref": "#/components/schemas/CreationTxState", "description": "注册交易及其当前确认状态。" }, "mint": { "anyOf": [ { "$ref": "#/components/schemas/CreationTxState" }, { "type": "null" } ], "description": "首次铸币交易及确认状态；尚未提交时为 null。" }, "state": { "type": "string", "enum": [ "pending", "ready_to_mint", "complete" ], "description": "pending 注册待确认；ready_to_mint 注册已确认、可准备首次铸币；complete 注册和首次铸币均确认。" }, "immutable": { "type": "boolean", "description": "资产资料在当前发行流程中是否不可修改。" }, "metadata_source": { "type": "string", "description": "元数据来源。" }, "commit_verified": { "type": "boolean", "description": "资产描述是否已与注册交易的链上承诺核对。" }, "chain_symbol": { "type": "string", "description": "完整链上符号；子资产包含命名空间前缀。" } }, "required": [ "genesis", "asset_id", "actor", "draft", "document", "metadata", "register", "mint", "state", "immutable", "metadata_source", "commit_verified" ] }, "CreatedAssetMetadata": { "type": "object", "properties": { "genesis": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "当前网络的创世区块哈希，64 位小写十六进制。" }, "asset_id": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "资产的链上 ID，64 位小写十六进制；只在对应网络有效。" }, "metadata": { "$ref": "#/components/schemas/AssetDocumentMetadata", "description": "资产描述文档中的展示名称、简介、图标和链接。" }, "document": { "type": "string", "description": "写入注册交易的完整资产描述文档。" }, "source": { "type": "string", "const": "issuer_document", "description": "数据来源标识。" }, "immutable": { "type": "boolean", "description": "资产资料在当前发行流程中是否不可修改。" }, "commit_verified": { "type": "boolean", "description": "资产描述是否已与注册交易的链上承诺核对。" }, "registration": { "$ref": "#/components/schemas/CreationTxState", "description": "新池登记资料或资产注册交易；结构由所在接口定义。" }, "chain_symbol": { "type": "string", "description": "完整链上符号；子资产包含命名空间前缀。" }, "issuance": { "anyOf": [ { "$ref": "#/components/schemas/SponsoredIssuance" }, { "type": "null" } ], "description": "子资产的协议、命名空间和 Parent 配置；独立资产不需要。" } }, "required": [ "genesis", "asset_id", "metadata", "document", "source", "immutable", "commit_verified", "registration" ] }, "IssuerAsset": { "type": "object", "properties": { "asset_id": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "资产的链上 ID，64 位小写十六进制；只在对应网络有效。" }, "actor": { "type": "string", "description": "操作账户在当前网络的 P2WPKH 地址；仅提供地址不会授权花费。" }, "name": { "type": "string", "description": "资产展示名称，1–80 个字符。" }, "symbol": { "type": "string", "description": "资产展示符号；发行时填 3–11 位大写字母数字，首位字母，不加 TRC20. 前缀。" }, "precision": { "type": "integer", "minimum": 0, "description": "资产小数位数；TSC 为 8，其他资产以链上登记值为准。" }, "initial_supply": { "type": "string", "pattern": "^[0-9]+(?:\\.[0-9]+)?$", "description": "最初发行时填写的资产数量，十进制字符串；不是当前供应量或钱包余额。" }, "icon_url": { "type": "string", "description": "HTTPS 或 ipfs://CID 图片地址；原样写入元数据，不由服务器下载；与 icon_base64 互斥。" }, "state": { "type": "string", "enum": [ "pending", "ready_to_mint", "complete" ], "description": "当前状态；可选值及阶段解释见此接口。" }, "register": { "$ref": "#/components/schemas/CreationTxState", "description": "注册交易及其当前确认状态。" }, "mint": { "anyOf": [ { "$ref": "#/components/schemas/CreationTxState" }, { "type": "null" } ], "description": "首次铸币交易及确认状态；尚未提交时为 null。" }, "listed": { "type": "boolean", "description": "是否在平台默认收录列表中；不是资产安全性认证。" }, "chain_symbol": { "type": "string", "description": "完整链上符号；子资产包含命名空间前缀。" }, "issuance": { "anyOf": [ { "$ref": "#/components/schemas/SponsoredIssuance" }, { "type": "null" } ], "description": "子资产的协议、命名空间和 Parent 配置；独立资产不需要。" } }, "required": [ "asset_id", "actor", "name", "symbol", "precision", "initial_supply", "icon_url", "state", "register", "mint", "listed" ] }, "IssuerAssets": { "type": "object", "properties": { "genesis": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "当前网络的创世区块哈希，64 位小写十六进制。" }, "actor": { "type": "string", "description": "操作账户在当前网络的 P2WPKH 地址；仅提供地址不会授权花费。" }, "assets": { "type": "array", "items": { "$ref": "#/components/schemas/IssuerAsset" }, "description": "当前查询范围内的资产列表。" }, "next_cursor": { "anyOf": [ { "type": "string", "pattern": "^[0-9a-f]{64}$" }, { "type": "null" } ], "description": "下一页游标；没有下一页时为 null，原样用于下一次请求。" } }, "required": [ "genesis", "actor", "assets", "next_cursor" ] }, "IssuanceRequest": { "type": "object", "properties": { "request_id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "description": "本次发行的小写 UUIDv4；新发行生成一次并保存，重试复用原 ID 和原资料，后续路径 id 使用此值。" }, "chain_id": { "type": "string", "pattern": "^tsc:[0-9a-f]{64}:(public|[0-9a-f]{64})$", "description": "目标网络标识，公共网络格式为 tsc::public。" }, "actor": { "type": "string", "minLength": 1, "maxLength": 90, "description": "操作账户在当前网络的 P2WPKH 地址；仅提供地址不会授权花费。" }, "mode": { "enum": [ "root", "trc20" ], "description": "发行模式；root 为独立资产，trc20 为平台子资产。" }, "name": { "type": "string", "minLength": 1, "maxLength": 80, "description": "资产展示名称，1–80 个字符。" }, "symbol": { "type": "string", "pattern": "^[A-Z][A-Z0-9]{2,10}$", "description": "资产展示符号；发行时填 3–11 位大写字母数字，首位字母，不加 TRC20. 前缀。" }, "description": { "type": "string", "minLength": 1, "maxLength": 2000, "description": "公开资产简介，1–2000 个字符。" }, "decimals": { "type": "integer", "minimum": 0, "maximum": 18, "description": "资产精度，0–18；最小单位数量 = supply × 10^decimals。" }, "supply": { "type": "string", "pattern": "^[0-9]+(?:\\.[0-9]+)?$", "description": "首次发行数量，按资产单位填写的十进制字符串；乘 10^decimals 后须为 uint64 范围内整数，不是实时流通量。" }, "links": { "type": "object", "properties": { "website": { "type": "string", "description": "项目官网 HTTPS 地址。" }, "x": { "type": "string", "description": "项目 X 主页 HTTPS 地址。" }, "telegram": { "type": "string", "description": "Telegram 社区 HTTPS 地址。" }, "discord": { "type": "string", "description": "Discord 社区 HTTPS 地址。" }, "docs": { "type": "string", "description": "项目文档 HTTPS 地址。" }, "github": { "type": "string", "description": "项目代码仓库 HTTPS 地址。" }, "whitepaper": { "type": "string", "description": "项目白皮书 HTTPS 地址。" } }, "additionalProperties": false, "description": "可选社交与资料链接对象，支持 website、x、telegram、discord、docs、github、whitepaper。" }, "icon_url": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 2048, "description": "Direct HTTPS image URL or ipfs://CID[/path], committed verbatim. Server does not fetch, upload or verify caller-hosted image bytes. Mutually exclusive with a non-null icon_base64." }, { "type": "null" } ], "description": "HTTPS 或 ipfs://CID 图片地址；原样写入元数据，不由服务器下载；与 icon_base64 互斥。" }, "icon_base64": { "anyOf": [ { "type": "string", "maxLength": 68268, "contentEncoding": "base64", "description": "Optional PNG/JPEG/WebP bytes, at most 51200 decoded bytes and 2048×2048 pixels. Sanitized and pinned to IPFS inside this request; no separate upload call. Mutually exclusive with a non-null icon_url." }, { "type": "null" } ], "description": "PNG/JPEG/WebP 原始字节的标准 Base64，不带 data: 前缀；最多 51200 字节和 2048×2048 像素，与 icon_url 互斥。" } }, "required": [ "request_id", "chain_id", "actor", "mode", "name", "symbol", "description", "decimals", "supply" ], "additionalProperties": false, "not": { "required": [ "icon_url", "icon_base64" ], "properties": { "icon_url": { "type": "string" }, "icon_base64": { "type": "string" } } } }, "TwpRawTransaction": { "type": "object", "properties": { "format": { "const": "tensorcash-raw-v1", "description": "原始交易的序列化格式。" }, "hex": { "type": "string", "pattern": "^(?:[0-9a-f]{2})*$", "description": "原始 TensorCash 交易的十六进制字节；不是 PSBT 或 EVM 交易。" } }, "required": [ "format", "hex" ], "additionalProperties": false }, "TwpOutput": { "type": "object", "properties": { "nativeUnits": { "type": "string", "pattern": "^[0-9]+$", "description": "此输出的 TSC 金额，最小单位整数字符串。" }, "scriptPubKey": { "type": "string", "pattern": "^(?:[0-9a-f]{2})*$", "description": "输出锁定脚本，十六进制字符串。" }, "outputExtension": { "type": "string", "pattern": "^(?:[0-9a-f]{2})*$", "description": "输出的 TensorCash 资产扩展字节，十六进制字符串。" } }, "required": [ "nativeUnits", "scriptPubKey", "outputExtension" ], "additionalProperties": false }, "TwpSigningInput": { "type": "object", "properties": { "inputIndex": { "type": "integer", "minimum": 0, "description": "本次请求钱包签名的输入位置，从 0 开始。" }, "accountId": { "type": "string", "pattern": "^script:[0-9a-f]{64}$", "description": "签名账户标识，script: 后接账户脚本的 SHA-256；须与实际签名账户一致。" }, "profile": { "const": "twp:tx:p2wpkh-all:1", "description": "钱包输入使用的签名规则标识。" }, "sighash": { "const": "ALL", "description": "签名覆盖范围；ALL 绑定整笔交易的输入输出。" }, "spend": { "type": "object", "properties": { "type": { "const": "p2wpkh", "description": "当前脚本支出类型。" }, "data": { "type": "object", "properties": {}, "required": [], "additionalProperties": false, "description": "签名输入的脚本参数；P2WPKH 输入使用空对象。" } }, "required": [ "type", "data" ], "additionalProperties": false, "description": "签名输入的支出脚本类型及相关资料。" } }, "required": [ "inputIndex", "accountId", "profile", "sighash", "spend" ], "additionalProperties": false }, "TwpTransactionPackage": { "type": "object", "properties": { "chainId": { "type": "string", "pattern": "^tsc:[0-9a-f]{64}:(public|[0-9a-f]{64})$", "description": "钱包交易包的目标网络标识；必须与签名和广播网络一致。" }, "transaction": { "$ref": "#/components/schemas/TwpRawTransaction", "description": "原始交易格式与字节，是否完整签名由本接口阶段决定。" }, "previousTransactions": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^(?:[0-9a-f]{2})*$" }, "description": "txid 到完整前序交易原始字节的映射；须独立重算 txid 和输入金额。" }, "signingInputs": { "type": "array", "items": { "$ref": "#/components/schemas/TwpSigningInput" }, "description": "本次只允许钱包签名的输入列表。" }, "constraints": { "type": "object", "properties": { "maxFeeUnits": { "type": "string", "pattern": "^[0-9]+$", "description": "允许的最大矿工费，TSC 最小单位整数字符串。" }, "exactOutputs": { "type": "array", "items": { "$ref": "#/components/schemas/TwpOutput" }, "description": "签名后必须保持不变的交易输出，顺序也必须一致。" } }, "required": [ "maxFeeUnits", "exactOutputs" ], "additionalProperties": false, "description": "签名必须遵守的费用上限及精确输出限制。" }, "validationMode": { "const": "online", "description": "钱包签名前的校验模式；online 表示须核对当前链状态。" }, "requiredFeatures": { "type": "array", "items": { "type": "string" }, "description": "钱包必须支持的链能力；缺失时不能降低校验要求继续签名。" }, "extensions": { "type": "array", "maxItems": 0, "description": "交易包扩展；当前发行请求为空数组。" }, "presentation": { "type": "object", "properties": { "title": { "type": "string", "description": "钱包审批显示的操作标题。" }, "description": { "type": "string", "description": "钱包展示的操作说明，不代替原始交易校验。" } }, "required": [ "title", "description" ], "additionalProperties": false, "description": "钱包展示的标题与操作说明，不代替交易字节校验。" } }, "required": [ "chainId", "transaction", "previousTransactions", "signingInputs", "constraints", "validationMode", "requiredFeatures", "extensions", "presentation" ], "additionalProperties": false }, "TwpSigningRequest": { "type": "object", "properties": { "method": { "const": "tsc_signTransaction", "description": "交给钱包执行的协议方法名。" }, "params": { "type": "object", "properties": { "apiVersion": { "const": "1.0", "description": "钱包请求 API 版本。" }, "requestId": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "description": "钱包审批请求的小写 UUIDv4；不等于发行资源 request_id。" }, "expiresAt": { "type": "integer", "minimum": 0, "description": "钱包签名请求到期时间，UTC Unix 秒；到期请求不得签名。" }, "package": { "$ref": "#/components/schemas/TwpTransactionPackage", "description": "完整的钱包交易签名包。" } }, "required": [ "apiVersion", "requestId", "expiresAt", "package" ], "additionalProperties": false, "description": "钱包方法的完整参数对象。" } }, "required": [ "method", "params" ], "additionalProperties": false }, "IssuanceResource": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "description": "与最初提交的 request_id 相同；后续 /issuances/{id} 路径使用此值，不使用 asset_id。" }, "chain_id": { "type": "string", "pattern": "^tsc:[0-9a-f]{64}:(public|[0-9a-f]{64})$", "description": "目标网络标识，公共网络格式为 tsc::public。" }, "asset_id": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "资产的链上 ID，64 位小写十六进制；只在对应网络有效。" }, "asset": { "$ref": "#/components/schemas/CreationDraft", "description": "API 为这次发行固定的完整资产资料，包含生成的 Asset ID。" }, "state": { "enum": [ "awaiting_signature", "awaiting_confirmation", "complete" ], "description": "awaiting_signature 等待当前阶段签名；awaiting_confirmation 交易已补齐或已广播、等待确认；complete 注册和初始发行均已确认。" }, "step": { "enum": [ "register", "mint" ], "description": "发行阶段：register 注册资产，mint 发行初始数量。" }, "status": { "anyOf": [ { "$ref": "#/components/schemas/CreationStatus" }, { "type": "null" } ], "description": "链上注册与初始发行的确认状态；注册交易尚未提交时为 null。" }, "wallet_request": { "anyOf": [ { "$ref": "#/components/schemas/TwpSigningRequest" }, { "type": "null" } ], "description": "完整的钱包签名请求对象；仅在 awaiting_signature 且未过期时使用；为 null 时调用 next 获取当前阶段请求。" }, "review_id": { "anyOf": [ { "type": "string", "pattern": "^[0-9a-f]{64}$" }, { "type": "null" } ], "description": "当前阶段交易的审核 ID；没有待审核交易时为 null。" }, "template_id": { "anyOf": [ { "type": "string", "pattern": "^[0-9a-f]{64}$" }, { "type": "null" } ], "description": "当前交易模板摘要；没有待审核交易时为 null。" }, "protocol": { "type": "object", "properties": { "name": { "const": "TWP", "description": "资产展示名称，1–80 个字符。" }, "draft_revision": { "const": "0.2", "description": "钱包协议草案版本；不同版本不能视为自动兼容。" }, "api_version": { "const": "1.0", "description": "接口版本。" }, "spec_hash": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "精确钱包协议文档摘要，不能仅按版本号判断兼容。" } }, "required": [ "name", "draft_revision", "api_version", "spec_hash" ], "description": "此发行接口返回的钱包签名包协议身份。" }, "steps": { "type": "array", "items": { "type": "object", "properties": { "step": { "enum": [ "register", "mint" ], "description": "发行阶段：register 注册资产，mint 发行初始数量。" }, "depends_on": { "anyOf": [ { "const": "register_confirmed" }, { "type": "null" } ], "description": "本阶段的前置条件；mint 依赖 register_confirmed。" } }, "required": [ "step", "depends_on" ] }, "description": "发行阶段及其前置确认条件。" } }, "required": [ "id", "chain_id", "asset_id", "asset", "state", "step", "status", "wallet_request", "review_id", "template_id", "protocol", "steps" ] }, "IssuanceNext": { "type": "object", "properties": { "refresh": { "type": "boolean", "default": false, "description": "默认 false，复用有效审核。true 请求新的未签名审核；先确认没有结果不明确的已签名交易，再重新让用户批准。" } }, "required": [], "additionalProperties": false }, "IssuanceFinalize": { "type": "object", "properties": { "review_id": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "本次待签名交易的审核 ID；与阶段和确切交易绑定。" }, "transaction": { "$ref": "#/components/schemas/TwpRawTransaction", "description": "钱包返回的已签名交易；必须保持原审核的输入、输出、金额和资产扩展。" } }, "required": [ "review_id", "transaction" ], "additionalProperties": false }, "IssuanceFinalized": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "description": "原始 request_id；本次 finalize 仍属于同一次发行。" }, "asset_id": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "资产的链上 ID，64 位小写十六进制；只在对应网络有效。" }, "chain_id": { "type": "string", "pattern": "^tsc:[0-9a-f]{64}:(public|[0-9a-f]{64})$", "description": "目标网络标识，公共网络格式为 tsc::public。" }, "step": { "enum": [ "register", "mint" ], "description": "发行阶段：register 注册资产，mint 发行初始数量。" }, "txid": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "链上交易 ID，64 位小写十六进制；不同于 quote_id 或 request_id。" }, "transaction": { "$ref": "#/components/schemas/TwpRawTransaction", "description": "已经补齐全部必要签名、可广播的原始交易。该接口本身不会广播。" }, "completion": { "const": "finalized", "description": "交易组装结果；finalized 只表示签名已补齐。" }, "broadcast": { "const": false, "description": "本次接口是否广播了交易；false 时仍须由调用方广播。" } }, "required": [ "id", "asset_id", "chain_id", "step", "txid", "transaction", "completion", "broadcast" ], "additionalProperties": false }, "IssuanceBroadcast": { "type": "object", "properties": { "review_id": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "与本次完整交易绑定的审核 ID；属于路径 id 指定的发行阶段。" }, "transaction": { "$ref": "#/components/schemas/TwpRawTransaction", "description": "finalize 返回的完整原始交易；必须逐字节一致，不能提交部分签名、修改矿工费或替换交易。" } }, "required": [ "review_id", "transaction" ], "additionalProperties": false }, "IssuanceBroadcastReceipt": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "description": "原始 request_id；用于查询同一次发行的状态。" }, "asset_id": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "资产的链上 ID，64 位小写十六进制；只在对应网络有效。" }, "chain_id": { "type": "string", "pattern": "^tsc:[0-9a-f]{64}:(public|[0-9a-f]{64})$", "description": "目标网络标识，公共网络格式为 tsc::public。" }, "step": { "enum": [ "register", "mint" ], "description": "发行阶段：register 注册资产，mint 发行初始数量。" }, "txid": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "链上交易 ID，64 位小写十六进制；不同于 quote_id 或 request_id。" }, "state": { "enum": [ "accepted", "rejected", "unknown" ], "description": "accepted 已观察到节点接受（含此前已接受）；rejected 预检查明确拒绝；unknown 提交结果不明确，应保留原交易、查询状态并原样重试。均不代表新的链上确认。" }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "rejected 或 unknown 的说明；accepted 时为 null。" } }, "required": [ "id", "asset_id", "chain_id", "step", "txid", "state", "reason" ], "additionalProperties": false }, "OwnerProof": { "type": "object", "properties": { "profile": { "type": "string", "const": "twp:proof:p2wpkh-ecdsa:1", "description": "钱包输入使用的签名规则标识。" }, "digest": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "结构化声明的摘要，64 位小写十六进制。" }, "envelope": { "type": "object", "description": "钱包签署的完整 TWP 声明信封；须保留原对象，不能修改账户、链或声明内容。" }, "proof": { "type": "object", "properties": { "publicKey": { "type": "string", "pattern": "^(?:[0-9a-f]{2})*$", "description": "钱包账户的压缩 secp256k1 公钥，十六进制。" }, "signature": { "type": "string", "pattern": "^(?:[0-9a-f]{2})*$", "description": "结构化声明的 ECDSA 签名，十六进制。" } }, "required": [ "publicKey", "signature" ], "additionalProperties": false, "description": "账户声明的公钥及 ECDSA 签名。" } }, "required": [ "profile", "digest", "envelope", "proof" ], "additionalProperties": false } } }, "externalDocs": { "description": "HTTP 端点、请求与响应字段、错误和 WebSocket 消息", "url": "../guide.md" }, "security": [], "tags": [ { "name": "Service" }, { "name": "Assets" }, { "name": "Creation" }, { "name": "Trading" }, { "name": "Market" } ] }