# Tern HTTP API 参考

通过 HTTP 请求使用资产查询、发行、交易、流动性和行情接口。以下端点均相对于所选网络的 API 基础地址。

| 网络 | API 基础地址 |
| --- | --- |
| 主网 | `https://tscscan.xyz:19443/mainnet/api/v1` |
| 测试网 | `https://tscscan.xyz:19443/testnet/api/v1` |
| Regtest | `https://tscscan.xyz:19443/regtest/api/v1` |

请求无需 API Key、Cookie 或本站 Origin。JSON 请求使用 `Content-Type: application/json`；图片上传直接发送对应媒体类型的原始字节。三个网络的地址、资产和记录不能混用。

成功的 JSON 响应直接返回所列对象，没有统一 data 包装。错误响应为 `{"code":"错误码","message":"错误说明"}`。HTTP 200 不表示交易已上链确认；发行看 state=complete，交易看 state=confirmed。

金额使用十进制字符串，最小单位数量使用整数字符串；1 TSC = 100000000 最小单位。行情时间为 UTC Unix 毫秒，报价、审核和钱包请求到期时间为 UTC Unix 秒。表中的必填说明对应当前对象；父对象为空或省略时，其子字段不单独出现。

Regtest 已开放独立资产及 TRC20 发行；其他网络和新 LP 入金以各环境能力开关为准。发行能力读取 `GET /launches/config` 的 availability.enabled；LP 能力读取 `GET /state` 的 standard_account_lp_enabled。图标上传和公开查询可独立使用。

发行分注册、首次铸币两阶段：提交 /issuances → 用户审核并签名 → finalize 返回完整交易 → 显式调用 broadcast → 查询原 id → next 获取 mint 签名请求 → 再签名、finalize、broadcast 和查询。两笔交易各签名一次；签名确认应明确说明应用将提交该交易。finalize 不广播，broadcast 不签名；接口不替调用方签名。

## 服务配置

### GET /info

读取服务配置。返回网络身份、交易格式、费用和服务限制。交易签名前应核对固定的网络及签名公钥。

响应 200：返回以下 JSON 对象；交易的最终结果以 state 和链上确认状态为准。

| 字段 | 类型 | 必定出现 | 说明 | 约束 |
| --- | --- | --- | --- | --- |
| api_version | string | 是 | 接口版本。 |  |
| network | string | 是 | 当前连接的链网络名称。 |  |
| genesis | string | 是 | 当前网络的创世区块哈希，64 位小写十六进制。 | 格式："^[0-9a-f]{64}$" |
| operator_key | string | 是 | 第一个交易签名角色的 x-only 公钥。 | 格式："^[0-9a-f]{64}$" |
| official_key | string | 是 | 第二个交易签名角色的 x-only 公钥；角色名不代表官方实际参与。 | 格式："^[0-9a-f]{64}$" |
| transaction_format | string | 是 | 交易序列化格式，TensorCash 原始交易包含 vExt。 | 固定值："tensorcash-vext-raw" |
| funding_address_type | string | 是 | 支持的资金地址类型；当前为原生见证 P2WPKH。 | 固定值："p2wpkh" |
| owner_derivation | string | 是 | 退出账户或密钥的派生标识；旧 v1 与标准账户 v2 不可混用。 |  |
| quote_ttl_seconds | integer | 是 | 正式报价有效期，单位秒；当前 300，不锁定 UTXO。 | 最小值：0 |
| estimate_ttl_seconds | integer | 是 | 预估结果有效期，单位秒；预估不预留池子储备。 | 最小值：0 |
| fee_units | string | 是 | 本次交易矿工费，TSC 最小单位整数字符串；1 TSC = 100000000。 | 格式："^[0-9]+$" |
| carrier_units | string | 是 | 池子载体金额，单位为 TSC 最小单位；全额退出可取回。 | 格式："^[0-9]+$" |
| lp_fee_bps_per_pool | integer | 是 | 每个池子的 LP 手续费率，单位基点；30 表示 0.30%。 | 最小值：0 |
| authentication | string | 是 | 资金操作的授权方式；由钱包签名授权。 |  |
| reference_asset_id | string / null | 是 | 历史参考资产 ID；当前统一使用 TSC，返回 null。 | 格式："^[0-9a-f]{64}$" |
| max_body_bytes | integer | 是 | HTTP 请求体最大字节数。 | 最小值：0 |
| max_concurrent_requests | integer | 是 | 每个服务实例允许同时处理的公共请求数量。 | 最小值：0 |
| quote_symbol | string | 是 | 计价符号；当前为 TSC。 | 固定值："TSC" |
| swap_pairs | string | 是 | 允许的交易对类型；asset_tsc 表示 Asset/TSC。 | 固定值："asset_tsc" |
| max_icon_bytes | integer | 是 | 上传图片最大字节数；51200 字节。 | 固定值：51200 |

错误响应：

| HTTP 状态 | 含义 |
| --- | --- |
| 400 | 请求参数、资产策略或签名无效。 |
| 404 | 未找到资产、池子或操作记录。 |
| 409 | 审核过期、交易内容改变、价格不满足限制或分页游标失效。 |
| 413 | 请求体超过允许字节数。 |
| 415 | 请求 Content-Type 不受支持。 |
| 422 | JSON 字段格式无效或包含未知字段。 |
| 429 | 请求频率或容量达到上限，按 Retry-After 秒数退避。 |
| 503 | 节点、签名服务、索引或上游暂不可用，按 Retry-After 秒数退避。 |

### GET /state

查询余额与服务状态。返回池子目录、同步进度和交易服务状态。传 address 时查询该地址的余额及已提交操作。

参数：

| 字段 | 位置 | 类型 | 必填 | 说明与约束 |
| --- | --- | --- | --- | --- |
| address | query | string | 否 | 当前网络的 P2WPKH 钱包地址；余额和个人操作按此地址查询。  |
| asset_id | query | string | 否 | 资产的链上 ID，64 位小写十六进制；只在对应网络有效。 格式："^[0-9a-f]{64}$" |

响应 200：返回以下 JSON 对象；交易的最终结果以 state 和链上确认状态为准。

| 字段 | 类型 | 必定出现 | 说明 | 约束 |
| --- | --- | --- | --- | --- |
| mode | string | 是 | 当前服务结算模式，micro_pool_2of2 表示双签微池。 |  |
| network | string | 是 | 当前连接的链网络名称。 |  |
| genesis | string | 是 | 当前网络的创世区块哈希，64 位小写十六进制。 | 格式："^[0-9a-f]{64}$" |
| operator_key | string | 是 | 第一个交易签名角色的 x-only 公钥。 | 格式："^[0-9a-f]{64}$" |
| official_key | string | 是 | 第二个交易签名角色的 x-only 公钥；角色名不代表官方实际参与。 | 格式："^[0-9a-f]{64}$" |
| assets | AssetMetadata[] | 是 | 当前查询范围内的资产列表。 |  |
| assets[].asset_id | string | 是 | 资产的链上 ID，64 位小写十六进制；只在对应网络有效。 | 格式："^[0-9a-f]{64}$" |
| assets[].symbol | string | 是 | 资产展示符号；发行时填 3–11 位大写字母数字，首位字母，不加 TRC20. 前缀。 |  |
| assets[].precision | integer | 是 | 资产小数位数；TSC 为 8，其他资产以链上登记值为准。 | 最小值：0；最大值：18 |
| listed_asset_ids | string[] | 是 | 默认收录的 Asset ID 列表。 |  |
| asset_discovery | boolean | 是 | 是否启用上游资产发现。 |  |
| reference_asset_id | string / null | 是 | 历史参考资产 ID；当前统一使用 TSC，返回 null。 | 格式："^[0-9a-f]{64}$" |
| asset_id | string | 是 | 当前选择的 Asset ID；部署未设置默认资产时可能为空字符串。 | 格式："^(?:[0-9a-f]{64})?$" |
| symbol | string | 是 | 资产展示符号；发行时填 3–11 位大写字母数字，首位字母，不加 TRC20. 前缀。 |  |
| precision | integer | 是 | 资产小数位数；TSC 为 8，其他资产以链上登记值为准。 | 最小值：0 |
| fee_units | string | 是 | 本次交易矿工费，TSC 最小单位整数字符串；1 TSC = 100000000。 | 格式："^[0-9]+$" |
| core_height | integer | 是 | 节点已验证的区块高度。 | 最小值：0 |
| core_headers | integer | 是 | 节点已知的最高区块头高度。 | 最小值：0 |
| node_ready | boolean | 是 | 节点是否已完成同步并可处理交易。 |  |
| ready | boolean | 是 | 节点及交易签名服务是否就绪。 |  |
| halted | boolean | 是 | 协调服务是否处于暂停状态。 |  |
| signers | object[] | 是 | 两名交易签名服务的公开身份与健康状态，不包含访问令牌。 |  |
| balances | object | 是 | 所查询地址的 TSC 与所选资产余额。 |  |
| balances.tsc | string | 是 | TSC 数量，按 TSC 单位表示的十进制字符串。 | 格式："^[0-9]+(?:\\.[0-9]+)?$" |
| balances.asset | string | 是 | 所查询地址持有的当前选择 Asset 数量，按该资产精度表示。 | 格式："^[0-9]+(?:\\.[0-9]+)?$" |
| pools | object[] | 是 | 平台登记的池子列表。 |  |
| pools[].pool_id | string | 是 | 微池实例 ID，64 位小写十六进制；不是 Asset ID。 | 格式："^[0-9a-f]{64}$" |
| pools[].position_id | string | 是 | 延续追加和部分退出历史的逻辑仓位 ID。 | 格式："^[0-9a-f]{64}$" |
| pools[].previous_pool_id | string / null | 是 | 该实例的前一个微池 ID；首次建立时为 null。 | 格式："^[0-9a-f]{64}$" |
| pools[].asset_id | string | 是 | 资产的链上 ID，64 位小写十六进制；只在对应网络有效。 | 格式："^[0-9a-f]{64}$" |
| pools[].symbol | string | 是 | 资产展示符号；发行时填 3–11 位大写字母数字，首位字母，不加 TRC20. 前缀。 |  |
| pools[].precision | integer | 是 | 资产小数位数；TSC 为 8，其他资产以链上登记值为准。 | 最小值：0 |
| pools[].actor | string | 是 | 操作账户在当前网络的 P2WPKH 地址；仅提供地址不会授权花费。 |  |
| pools[].descriptor | PoolDescriptor | 是 | 包含池子参数、脚本及退出分支的完整公开描述。 |  |
| pools[].descriptor.config | PoolConfig | 是 | 池子脚本绑定的公开参数。 |  |
| pools[].descriptor.config.version | integer | 是 | 该对象协议格式版本。 | 固定值：1 |
| pools[].descriptor.config.genesis | string | 是 | 当前网络的创世区块哈希，64 位小写十六进制。 | 格式："^[0-9a-f]{64}$" |
| pools[].descriptor.config.nonce | string | 是 | 新池随机数，32 字节小写十六进制；不能复用创建不同实例。 | 格式："^[0-9a-f]{64}$" |
| pools[].descriptor.config.asset_id | string | 是 | 资产的链上 ID，64 位小写十六进制；只在对应网络有效。 | 格式："^[0-9a-f]{64}$" |
| pools[].descriptor.config.owner_key | string | 是 | 池所有者退出公钥，32 字节 x-only 公钥，不是私钥。 | 格式："^[0-9a-f]{64}$" |
| pools[].descriptor.config.operator_key | string | 是 | 第一个交易签名角色的 x-only 公钥。 | 格式："^[0-9a-f]{64}$" |
| pools[].descriptor.config.official_key | string | 是 | 第二个交易签名角色的 x-only 公钥；角色名不代表官方实际参与。 | 格式："^[0-9a-f]{64}$" |
| pools[].descriptor.config.fee_bps | integer | 是 | 池手续费率，单位基点；30 表示 0.30%。 | 固定值：30 |
| pools[].descriptor.config.carrier_units | integer | 是 | 池子载体金额，单位为 TSC 最小单位；全额退出可取回。 | 固定值：100000 |
| pools[].descriptor.pool_id | string | 是 | 微池实例 ID，64 位小写十六进制；不是 Asset ID。 | 格式："^[0-9a-f]{64}$" |
| pools[].descriptor.script_pubkey | string | 是 | 池子 Taproot 锁定脚本，十六进制字符串。 | 格式："^(?:[0-9a-f]{2})*$" |
| pools[].descriptor.trade_script | string | 是 | 池子双签交易分支的脚本字节，十六进制。 | 格式："^(?:[0-9a-f]{2})*$" |
| pools[].descriptor.trade_control | string | 是 | 交易支出分支的 Taproot 控制块，十六进制。 | 格式："^(?:[0-9a-f]{2})*$" |
| pools[].descriptor.withdrawal_script | string | 是 | LP 独立退出分支的脚本字节，十六进制。 | 格式："^(?:[0-9a-f]{2})*$" |
| pools[].descriptor.withdrawal_control | string | 是 | LP 独立退出分支的 Taproot 控制块，十六进制。 | 格式："^(?:[0-9a-f]{2})*$" |
| pools[].state | string | 是 | 当前状态；可选值及阶段解释见此接口。 | 可选值：["pending", "active", "exit_available", "closed"] |
| pools[].tsc | string | 是 | TSC 数量，按 TSC 单位表示的十进制字符串。 | 格式："^[0-9]+(?:\\.[0-9]+)?$" |
| pools[].asset | string | 是 | 池子 Asset 储备，按该资产单位的十进制字符串。 | 格式："^[0-9]+(?:\\.[0-9]+)?$" |
| pools[].owned | boolean | 是 | 查询地址是否为该仓位的所有者。 |  |
| operations | object[] | 是 | 所查询地址已提交的操作列表。 |  |
| quote_symbol | string | 是 | 计价符号；当前为 TSC。 | 固定值："TSC" |
| tsc_usd_reference | TscUsdReference | 是 | 共享的 TSC 美元辅助估值缓存，不参与兑换计算。 |  |
| tsc_usd_reference.base_symbol | string | 是 | 被定价资产的展示符号。 | 固定值："TSC" |
| tsc_usd_reference.source | string | 是 | 数据来源标识。 | 固定值："SafeTrade" |
| tsc_usd_reference.source_market | string | 是 | 参考价来源市场，TSC/USDT。 | 固定值："TSC/USDT" |
| tsc_usd_reference.status | string | 是 | available 价格可用；stale 已过期；unavailable 未获取到价格。后两种状态 usd_price 为 null。 | 可选值：["available", "stale", "unavailable"] |
| tsc_usd_reference.usd_price | string / null | 是 | 1 TSC 的近似美元价格，十进制字符串；过期或不可用为 null。 | 格式："^[0-9]+(?:\\.[0-9]+)?$" |
| tsc_usd_reference.observed_at | integer / null | 是 | 参考价采集时间，UTC Unix 毫秒；不是交易所最新成交时间。 | 最小值：0 |
| tsc_usd_reference.expires_at | integer / null | 是 | 参考价缓存到期时间，UTC Unix 毫秒；尚无价格时为 null。 | 最小值：0 |
| tsc_usd_reference.time_unit | string | 是 | 时间戳单位，行情与参考价为 unix_ms。 | 固定值："unix_ms" |
| tsc_usd_reference.approximate | boolean | 是 | 是否为近似换算；美元展示按 1 USDT 约等于 1 USD。 | 固定值：true |
| tsc_usd_reference.conversion | string | 是 | 美元辅助估值的换算假设。 |  |
| tsc_usd_reference.purpose | string | 是 | 参考价用途；display_only 表示只用于显示美元估值。 | 固定值："display_only" |
| chain_id | string / null | 是 | 目标网络标识，公共网络格式为 tsc:<genesis>:public。 | 格式："^tsc:[0-9a-f]{64}:(public\|[0-9a-f]{64})$" |
| standard_account_lp_enabled | boolean | 是 | 是否已允许标准钱包账户创建或替换 LP 仓位。 |  |

错误响应：

| HTTP 状态 | 含义 |
| --- | --- |
| 400 | 请求参数、资产策略或签名无效。 |
| 404 | 未找到资产、池子或操作记录。 |
| 409 | 审核过期、交易内容改变、价格不满足限制或分页游标失效。 |
| 413 | 请求体超过允许字节数。 |
| 415 | 请求 Content-Type 不受支持。 |
| 422 | JSON 字段格式无效或包含未知字段。 |
| 429 | 请求频率或容量达到上限，按 Retry-After 秒数退避。 |
| 503 | 节点、签名服务、索引或上游暂不可用，按 Retry-After 秒数退避。 |

## 资产查询

### GET /assets

查询精选与推荐资产。返回部署配置的精选资产和按已确认成交量、流动性排序的推荐资产。

响应 200：返回以下 JSON 对象；交易的最终结果以 state 和链上确认状态为准。

| 字段 | 类型 | 必定出现 | 说明 | 约束 |
| --- | --- | --- | --- | --- |
| genesis | string | 是 | 当前网络的创世区块哈希，64 位小写十六进制。 | 格式："^[0-9a-f]{64}$" |
| featured | AssetMetadata[] | 是 | 部署配置的精选资产列表。 |  |
| featured[].asset_id | string | 是 | 资产的链上 ID，64 位小写十六进制；只在对应网络有效。 | 格式："^[0-9a-f]{64}$" |
| featured[].symbol | string | 是 | 资产展示符号；发行时填 3–11 位大写字母数字，首位字母，不加 TRC20. 前缀。 |  |
| featured[].precision | integer | 是 | 资产小数位数；TSC 为 8，其他资产以链上登记值为准。 | 最小值：0；最大值：18 |
| recommended | object[] | 是 | 按已确认成交量和流动性排序的资产列表。 |  |
| ranking | string | 是 | 推荐资产采用的排序口径。 |  |
| discovery_enabled | boolean | 是 | 是否启用资产搜索和发现。 |  |

错误响应：

| HTTP 状态 | 含义 |
| --- | --- |
| 400 | 请求参数、资产策略或签名无效。 |
| 404 | 未找到资产、池子或操作记录。 |
| 409 | 审核过期、交易内容改变、价格不满足限制或分页游标失效。 |
| 413 | 请求体超过允许字节数。 |
| 415 | 请求 Content-Type 不受支持。 |
| 422 | JSON 字段格式无效或包含未知字段。 |
| 429 | 请求频率或容量达到上限，按 Retry-After 秒数退避。 |
| 503 | 节点、签名服务、索引或上游暂不可用，按 Retry-After 秒数退避。 |

### GET /assets/search

搜索资产。完整 Asset ID 直接查询详情；其他关键词按上游每页最多 100 个资产过滤链上符号或 ID 子串。page 从 1 开始，has_more 指上游还有下一页，不是匹配结果分页；当前不按元数据展示名称搜索。普通搜索行保留链上符号。

参数：

| 字段 | 位置 | 类型 | 必填 | 说明与约束 |
| --- | --- | --- | --- | --- |
| q | query | string | 否 | 链上符号或 Asset ID 子串；完整 Asset ID 直接查询。当前不搜索元数据 display_name。  |
| page | query | integer | 否 | 页码，从 1 开始，默认 1。 默认值：1；最小值：1 |

响应 200：返回以下 JSON 对象；交易的最终结果以 state 和链上确认状态为准。

| 字段 | 类型 | 必定出现 | 说明 | 约束 |
| --- | --- | --- | --- | --- |
| assets | object[] | 是 | 当前查询范围内的资产列表。 |  |
| assets[].asset_id | string | 是 | 资产的链上 ID，64 位小写十六进制；只在对应网络有效。 | 格式："^[0-9a-f]{64}$" |
| assets[].symbol | string | 是 | 资产展示符号；发行时填 3–11 位大写字母数字，首位字母，不加 TRC20. 前缀。 |  |
| assets[].precision | integer | 是 | 资产小数位数；TSC 为 8，其他资产以链上登记值为准。 | 最小值：0；最大值：18 |
| assets[].listed | boolean | 是 | 是否在平台默认收录列表中；不是资产安全性认证。 |  |
| page | integer | 是 | 页码，从 1 开始。 | 最小值：0 |
| has_more | boolean | 是 | 上游资产目录是否还有下一页；继续传 page+1。当前页无匹配也可能为 true，不是名称搜索结果分页。 |  |
| total_pages | integer | 否 | 上游资产目录的总页数；完整 Asset ID 的直接查询不返回此字段。 | 最小值：0 |

错误响应：

| HTTP 状态 | 含义 |
| --- | --- |
| 400 | 请求参数、资产策略或签名无效。 |
| 404 | 未找到资产、池子或操作记录。 |
| 409 | 审核过期、交易内容改变、价格不满足限制或分页游标失效。 |
| 413 | 请求体超过允许字节数。 |
| 415 | 请求 Content-Type 不受支持。 |
| 422 | JSON 字段格式无效或包含未知字段。 |
| 429 | 请求频率或容量达到上限，按 Retry-After 秒数退避。 |
| 503 | 节点、签名服务、索引或上游暂不可用，按 Retry-After 秒数退避。 |

### GET /assets/{id}

查询资产信息。使用 Asset ID 查询符号、精度、收录状态、可用发行元数据、头像和当前 TSC 参考价格，并校验网络与资产策略。price 使用已确认储备最多的 TSC 池，不扫描成交历史、不额外查询链接口；无流动性或索引不新鲜时 value=null，不影响基础资产资料读取。美元参考换算另见 /prices/tsc。

参数：

| 字段 | 位置 | 类型 | 必填 | 说明与约束 |
| --- | --- | --- | --- | --- |
| id | path | string | 是 | Asset ID，64 位小写十六进制。 格式："^[0-9a-f]{64}$" |

响应 200：返回以下 JSON 对象；交易的最终结果以 state 和链上确认状态为准。

| 字段 | 类型 | 必定出现 | 说明 | 约束 |
| --- | --- | --- | --- | --- |
| asset_id | string | 是 | 资产的链上 ID，64 位小写十六进制；只在对应网络有效。 | 格式："^[0-9a-f]{64}$" |
| symbol | string | 是 | 资产展示符号；发行时填 3–11 位大写字母数字，首位字母，不加 TRC20. 前缀。 |  |
| precision | integer | 是 | 资产小数位数；TSC 为 8，其他资产以链上登记值为准。 | 最小值：0；最大值：18 |
| listed | boolean | 是 | 是否在平台默认收录列表中；不是资产安全性认证。 |  |
| pool_count | integer | 是 | 平台登记的该资产池子数量。 | 最小值：0 |
| genesis | string | 是 | 当前网络的创世区块哈希，64 位小写十六进制。 | 格式："^[0-9a-f]{64}$" |
| metadata | AssetDocumentMetadata / null | 是 | 已确认发行文档中的名称、描述、链接和头像原始 URI；当前覆盖此服务留有发行记录的资产，其余为 null。 |  |
| metadata.protocol | string | 是 | 链上资产展示资料的协议名称。 | 固定值："tc-asset-meta" |
| metadata.version | integer | 是 | 该对象协议格式版本。 | 固定值：1 |
| metadata.display_name | string | 是 | 元数据中的资产展示名称。 |  |
| metadata.summary | string | 是 | 资产元数据中的公开简介。 |  |
| metadata.links | object | 是 | 可选社交与资料链接对象，支持 website、x、telegram、discord、docs、github、whitepaper。 |  |
| metadata.icon | object | 否 | 头像元数据，uri 为写入链上的地址。 |  |
| metadata.icon.uri | string | 是 | 写入链上资料的图片地址；平台上传返回 ipfs://CID。 |  |
| metadata.issuance | SponsoredIssuance | 否 | 子资产发行标准与 Parent 身份；不是当前实时发行开关。 |  |
| metadata.issuance.mode | string | 是 | 旧版发行草稿中的子资产模式，固定 sponsored；新 /issuances 请求使用 mode: trc20。 | 固定值："sponsored" |
| metadata.issuance.protocol | string | 是 | 子资产发行命名标准标识，当前为 TRC20。 | 格式："^[A-Z][A-Z0-9]{2,10}$" |
| metadata.issuance.version | integer | 是 | 该对象协议格式版本。 | 固定值：1 |
| metadata.issuance.namespace | string | 是 | 子资产链上名称前缀，当前为 TRC20。 | 格式："^[A-Z][A-Z0-9]{2,10}$" |
| metadata.issuance.parent_asset_id | string | 是 | 平台 Parent 的链上 Asset ID。 | 格式："^[0-9a-f]{64}$" |
| metadata.symbol | string | 否 | 资产展示符号；发行时填 3–11 位大写字母数字，首位字母，不加 TRC20. 前缀。 |  |
| metadata.chain_symbol | string | 否 | 完整链上符号；子资产包含命名空间前缀。 |  |
| metadata_source | string / null | 是 | 元数据来源。 | 固定值："issuer_document" |
| metadata_status | string | 是 | 展示资料状态：available 已有注册确认且资料可读；unconfirmed 注册尚未确认；unavailable 此服务没有资料或暂时无法核对。 | 可选值：["available", "unavailable", "unconfirmed"] |
| commit_verified | boolean | 是 | 本次读取是否确认了发行注册交易，且展示资料绑定本资产和网络。资料不可用时为 false。 |  |
| icon_url | string / null | 是 | 可直接用于图片展示的 HTTPS 地址；由已确认文档中的 icon.uri 推导，IPFS 使用本服务配置的网关，原始 URI 保留在 metadata.icon.uri。无头像或资料不可用时为 null。此字段用于直连网关；站内校验读取使用 icon_path。 |  |
| icon_path | string / null | 是 | 相对于当前 API 根路径的站内图片读取路径；只为本平台已完成的 IPFS 上传提供，读取会核对 CID、字节数和 SHA-256。其余为 null。 |  |
| price | AssetPrice | 是 | 当前资产的 TSC 参考价格和来源。使用已确认池储备，不是成交均价或兑换报价；没有流动性或索引不可用时 value=null。 |  |
| price.value | string / null | 是 | 1 个资产对应的 TSC 数量，十进制字符串，最多 72 位小数；不可用时为 null，不能解释为零。 | 格式："^[0-9]+(?:\\.[0-9]{1,72})?$" |
| price.quote_symbol | string | 是 | 计价符号；当前为 TSC。 | 固定值："TSC" |
| price.status | string | 是 | available 表示有正储备、索引已追上且节点就绪、无索引错误、最近检查不超过 120 秒；否则为 unavailable。 | 可选值：["available", "unavailable"] |
| price.reason | string / null | 是 | 不可用原因：no_liquidity 没有已确认的正储备池；index_unavailable 索引未就绪、过期或暂不可读。可用时为 null。 | 可选值：["no_liquidity", "index_unavailable"] |
| price.basis | string | 是 | 固定 pool_reserves：TSC 储备除以资产数量，排除载体金额；从 TSC 储备最多的可用池取价，相同储备按池 ID 升序选择。 | 固定值："pool_reserves" |
| price.pool_id | string / null | 是 | 参考价格的来源池 ID；没有当前可用价格时为 null。 | 格式："^[0-9a-f]{64}$" |
| price.index | IndexStatus / null | 是 | 行情索引进度与同步状态；数据不完整时不要当作完整实时行情。 |  |
| price.index.indexed_height | integer / null | 是 | 索引已处理到的区块高度。 |  |
| price.index.indexed_hash | string / null | 是 | 索引已处理到的区块哈希。 |  |
| price.index.core_height | integer / null | 是 | 节点已验证的区块高度。 |  |
| price.index.core_headers | integer / null | 是 | 节点已知的最高区块头高度。 |  |
| price.index.node_ready | boolean | 是 | 节点是否已完成同步并可处理交易。 |  |
| price.index.caught_up | boolean | 是 | 行情索引是否已追上节点当前高度。 |  |
| price.index.last_checked_at | integer / null | 是 | 最近一次索引检查时间，UTC Unix 毫秒。 |  |
| price.index.error | string / null | 是 | 错误说明；无错误时为 null，交易状态仍以 state 为准。 |  |
| price.index.revision | integer | 是 | 行情索引修订号；用于识别重建或状态变化。 | 最小值：0 |
| chain_symbol | string | 否 | 完整链上符号；子资产包含命名空间前缀。 |  |
| issuance | SponsoredIssuance / null | 否 | 子资产的协议、命名空间和 Parent 配置；独立资产不需要。 |  |
| issuance.mode | string | 是 | 旧版发行草稿中的子资产模式，固定 sponsored；新 /issuances 请求使用 mode: trc20。 | 固定值："sponsored" |
| issuance.protocol | string | 是 | 子资产发行命名标准标识，当前为 TRC20。 | 格式："^[A-Z][A-Z0-9]{2,10}$" |
| issuance.version | integer | 是 | 该对象协议格式版本。 | 固定值：1 |
| issuance.namespace | string | 是 | 子资产链上名称前缀，当前为 TRC20。 | 格式："^[A-Z][A-Z0-9]{2,10}$" |
| issuance.parent_asset_id | string | 是 | 平台 Parent 的链上 Asset ID。 | 格式："^[0-9a-f]{64}$" |

错误响应：

| HTTP 状态 | 含义 |
| --- | --- |
| 400 | 请求参数、资产策略或签名无效。 |
| 404 | 未找到资产、池子或操作记录。 |
| 409 | 审核过期、交易内容改变、价格不满足限制或分页游标失效。 |
| 413 | 请求体超过允许字节数。 |
| 415 | 请求 Content-Type 不受支持。 |
| 422 | JSON 字段格式无效或包含未知字段。 |
| 429 | 请求频率或容量达到上限，按 Retry-After 秒数退避。 |
| 503 | 节点、签名服务、索引或上游暂不可用，按 Retry-After 秒数退避。 |

### POST /assets/import

导入资产到平台目录。校验并保存已有资产资料；不会发行资产、建池或转账。

请求体：

| 字段 | 类型 | 必填 | 说明 | 约束 |
| --- | --- | --- | --- | --- |
| asset_id | string | 是 | 资产的链上 ID，64 位小写十六进制；只在对应网络有效。 | 格式："^[0-9a-f]{64}$" |

响应 200：返回以下 JSON 对象；交易的最终结果以 state 和链上确认状态为准。

| 字段 | 类型 | 必定出现 | 说明 | 约束 |
| --- | --- | --- | --- | --- |
| asset_id | string | 是 | 资产的链上 ID，64 位小写十六进制；只在对应网络有效。 | 格式："^[0-9a-f]{64}$" |
| symbol | string | 是 | 资产展示符号；发行时填 3–11 位大写字母数字，首位字母，不加 TRC20. 前缀。 |  |
| precision | integer | 是 | 资产小数位数；TSC 为 8，其他资产以链上登记值为准。 | 最小值：0；最大值：18 |
| listed | boolean | 是 | 是否在平台默认收录列表中；不是资产安全性认证。 |  |
| pool_count | integer | 是 | 平台登记的该资产池子数量。 | 最小值：0 |
| genesis | string | 是 | 当前网络的创世区块哈希，64 位小写十六进制。 | 格式："^[0-9a-f]{64}$" |
| metadata | AssetDocumentMetadata / null | 是 | 已确认发行文档中的名称、描述、链接和头像原始 URI；当前覆盖此服务留有发行记录的资产，其余为 null。 |  |
| metadata.protocol | string | 是 | 链上资产展示资料的协议名称。 | 固定值："tc-asset-meta" |
| metadata.version | integer | 是 | 该对象协议格式版本。 | 固定值：1 |
| metadata.display_name | string | 是 | 元数据中的资产展示名称。 |  |
| metadata.summary | string | 是 | 资产元数据中的公开简介。 |  |
| metadata.links | object | 是 | 可选社交与资料链接对象，支持 website、x、telegram、discord、docs、github、whitepaper。 |  |
| metadata.icon | object | 否 | 头像元数据，uri 为写入链上的地址。 |  |
| metadata.icon.uri | string | 是 | 写入链上资料的图片地址；平台上传返回 ipfs://CID。 |  |
| metadata.issuance | SponsoredIssuance | 否 | 子资产发行标准与 Parent 身份；不是当前实时发行开关。 |  |
| metadata.issuance.mode | string | 是 | 旧版发行草稿中的子资产模式，固定 sponsored；新 /issuances 请求使用 mode: trc20。 | 固定值："sponsored" |
| metadata.issuance.protocol | string | 是 | 子资产发行命名标准标识，当前为 TRC20。 | 格式："^[A-Z][A-Z0-9]{2,10}$" |
| metadata.issuance.version | integer | 是 | 该对象协议格式版本。 | 固定值：1 |
| metadata.issuance.namespace | string | 是 | 子资产链上名称前缀，当前为 TRC20。 | 格式："^[A-Z][A-Z0-9]{2,10}$" |
| metadata.issuance.parent_asset_id | string | 是 | 平台 Parent 的链上 Asset ID。 | 格式："^[0-9a-f]{64}$" |
| metadata.symbol | string | 否 | 资产展示符号；发行时填 3–11 位大写字母数字，首位字母，不加 TRC20. 前缀。 |  |
| metadata.chain_symbol | string | 否 | 完整链上符号；子资产包含命名空间前缀。 |  |
| metadata_source | string / null | 是 | 元数据来源。 | 固定值："issuer_document" |
| metadata_status | string | 是 | 展示资料状态：available 已有注册确认且资料可读；unconfirmed 注册尚未确认；unavailable 此服务没有资料或暂时无法核对。 | 可选值：["available", "unavailable", "unconfirmed"] |
| commit_verified | boolean | 是 | 本次读取是否确认了发行注册交易，且展示资料绑定本资产和网络。资料不可用时为 false。 |  |
| icon_url | string / null | 是 | 可直接用于图片展示的 HTTPS 地址；由已确认文档中的 icon.uri 推导，IPFS 使用本服务配置的网关，原始 URI 保留在 metadata.icon.uri。无头像或资料不可用时为 null。此字段用于直连网关；站内校验读取使用 icon_path。 |  |
| icon_path | string / null | 是 | 相对于当前 API 根路径的站内图片读取路径；只为本平台已完成的 IPFS 上传提供，读取会核对 CID、字节数和 SHA-256。其余为 null。 |  |
| price | AssetPrice | 是 | 当前资产的 TSC 参考价格和来源。使用已确认池储备，不是成交均价或兑换报价；没有流动性或索引不可用时 value=null。 |  |
| price.value | string / null | 是 | 1 个资产对应的 TSC 数量，十进制字符串，最多 72 位小数；不可用时为 null，不能解释为零。 | 格式："^[0-9]+(?:\\.[0-9]{1,72})?$" |
| price.quote_symbol | string | 是 | 计价符号；当前为 TSC。 | 固定值："TSC" |
| price.status | string | 是 | available 表示有正储备、索引已追上且节点就绪、无索引错误、最近检查不超过 120 秒；否则为 unavailable。 | 可选值：["available", "unavailable"] |
| price.reason | string / null | 是 | 不可用原因：no_liquidity 没有已确认的正储备池；index_unavailable 索引未就绪、过期或暂不可读。可用时为 null。 | 可选值：["no_liquidity", "index_unavailable"] |
| price.basis | string | 是 | 固定 pool_reserves：TSC 储备除以资产数量，排除载体金额；从 TSC 储备最多的可用池取价，相同储备按池 ID 升序选择。 | 固定值："pool_reserves" |
| price.pool_id | string / null | 是 | 参考价格的来源池 ID；没有当前可用价格时为 null。 | 格式："^[0-9a-f]{64}$" |
| price.index | IndexStatus / null | 是 | 行情索引进度与同步状态；数据不完整时不要当作完整实时行情。 |  |
| price.index.indexed_height | integer / null | 是 | 索引已处理到的区块高度。 |  |
| price.index.indexed_hash | string / null | 是 | 索引已处理到的区块哈希。 |  |
| price.index.core_height | integer / null | 是 | 节点已验证的区块高度。 |  |
| price.index.core_headers | integer / null | 是 | 节点已知的最高区块头高度。 |  |
| price.index.node_ready | boolean | 是 | 节点是否已完成同步并可处理交易。 |  |
| price.index.caught_up | boolean | 是 | 行情索引是否已追上节点当前高度。 |  |
| price.index.last_checked_at | integer / null | 是 | 最近一次索引检查时间，UTC Unix 毫秒。 |  |
| price.index.error | string / null | 是 | 错误说明；无错误时为 null，交易状态仍以 state 为准。 |  |
| price.index.revision | integer | 是 | 行情索引修订号；用于识别重建或状态变化。 | 最小值：0 |
| chain_symbol | string | 否 | 完整链上符号；子资产包含命名空间前缀。 |  |
| issuance | SponsoredIssuance / null | 否 | 子资产的协议、命名空间和 Parent 配置；独立资产不需要。 |  |
| issuance.mode | string | 是 | 旧版发行草稿中的子资产模式，固定 sponsored；新 /issuances 请求使用 mode: trc20。 | 固定值："sponsored" |
| issuance.protocol | string | 是 | 子资产发行命名标准标识，当前为 TRC20。 | 格式："^[A-Z][A-Z0-9]{2,10}$" |
| issuance.version | integer | 是 | 该对象协议格式版本。 | 固定值：1 |
| issuance.namespace | string | 是 | 子资产链上名称前缀，当前为 TRC20。 | 格式："^[A-Z][A-Z0-9]{2,10}$" |
| issuance.parent_asset_id | string | 是 | 平台 Parent 的链上 Asset ID。 | 格式："^[0-9a-f]{64}$" |

错误响应：

| HTTP 状态 | 含义 |
| --- | --- |
| 400 | 请求参数、资产策略或签名无效。 |
| 404 | 未找到资产、池子或操作记录。 |
| 409 | 审核过期、交易内容改变、价格不满足限制或分页游标失效。 |
| 413 | 请求体超过允许字节数。 |
| 415 | 请求 Content-Type 不受支持。 |
| 422 | JSON 字段格式无效或包含未知字段。 |
| 429 | 请求频率或容量达到上限，按 Retry-After 秒数退避。 |
| 503 | 节点、签名服务、索引或上游暂不可用，按 Retry-After 秒数退避。 |

## 资产发行

### POST /icons

上传资产头像。请求体直接发送 PNG/JPEG/WebP 原始字节，Content-Type 使用对应图片类型，最多 51200 字节、2048×2048 像素。不接受 JSON、Base64、SVG 或 multipart。服务端处理成最大 256×256 的 WebP 并固定到 IPFS，返回 URI 和图片信息。同一图片重复上传复用结果。创建资产也可直接传 icon_base64，不必先调用此接口。

请求体媒体类型：image/png, image/jpeg, image/webp。直接发送文件字节。

响应 200：返回以下 JSON 对象；交易的最终结果以 state 和链上确认状态为准。

| 字段 | 类型 | 必定出现 | 说明 | 约束 |
| --- | --- | --- | --- | --- |
| cid | string | 是 | 已经核验并固定存储的 IPFS 内容标识。 |  |
| url | string | 是 | 用于显示图片的 HTTPS 网关地址；更换网关不改变链上 uri。 |  |
| storage | string | 是 | 头像存储类型；新上传使用 ipfs。 | 固定值："ipfs" |
| uri | string | 是 | 写入链上资料的图片地址；平台上传返回 ipfs://CID。 |  |
| sha256 | string | 是 | 处理后图片字节的 SHA-256 摘要。 | 格式："^[0-9a-f]{64}$" |
| bytes | integer | 是 | 处理后图片的字节数。 | 最小值：1；最大值：51200 |
| width | integer | 是 | 处理后图片宽度，单位像素。 | 最小值：1；最大值：256 |
| height | integer | 是 | 处理后图片高度，单位像素。 | 最小值：1；最大值：256 |
| content_type | string | 是 | 处理后图片的媒体类型。 | 固定值："image/webp" |

错误响应：

| HTTP 状态 | 含义 |
| --- | --- |
| 400 | 请求参数、资产策略或签名无效。 |
| 404 | 未找到资产、池子或操作记录。 |
| 409 | 审核过期、交易内容改变、价格不满足限制或分页游标失效。 |
| 413 | 上传图片超过 51200 字节。 |
| 415 | 请求 Content-Type 不受支持。 |
| 422 | JSON 字段格式无效或包含未知字段。 |
| 429 | 请求频率或容量达到上限，按 Retry-After 秒数退避。 |
| 503 | 节点、签名服务、索引或上游暂不可用，按 Retry-After 秒数退避。 |

### GET /icons/{name}

读取资产头像。返回图片二进制。支持历史图片，以及本平台记录的 IPFS 图片；后者核对上传时的 CID、字节数与 SHA-256，支持不可变缓存。未知图片不会触发任意地址抓取。

参数：

| 字段 | 位置 | 类型 | 必填 | 说明与约束 |
| --- | --- | --- | --- | --- |
| name | path | string | 是 | 历史图片文件名：SHA-256 摘要加 .webp 或 .png。 格式："^(?:[0-9a-f]{64}\\.(?:webp\|png)\|[A-Za-z0-9]{10,200}\\.webp)$" |

响应 200：返回图片二进制；长期不可变缓存，不返回 JSON。

响应为 image/webp, image/png 二进制。

错误响应：

| HTTP 状态 | 含义 |
| --- | --- |
| 404 | 未找到资产、池子或操作记录。 |
| 429 | 请求频率或容量达到上限，按 Retry-After 秒数退避。 |
| 503 | 节点、签名服务、索引或上游暂不可用，按 Retry-After 秒数退避。 |

### GET /launches/config

查询发行能力与配置。先检查 availability.enabled。root 和 sponsored 是模式配置；当前部署发行未开放时 availability.enabled=false。media 描述图片上传能力。

响应 200：返回以下 JSON 对象；交易的最终结果以 state 和链上确认状态为准。

| 字段 | 类型 | 必定出现 | 说明 | 约束 |
| --- | --- | --- | --- | --- |
| genesis | string | 是 | 当前网络的创世区块哈希，64 位小写十六进制。 | 格式："^[0-9a-f]{64}$" |
| default_mode | string | 是 | 旧 /launches 接口的默认模式；root 独立资产，sponsored 已配置子资产。 | 可选值：["root", "sponsored"] |
| root | object | 是 | 独立父资产的模式配置；不表示当前发行已开放。 |  |
| root.enabled | boolean | 是 | 独立父资产模式已定义；不是实时开关，能否发行必须同时检查 availability.enabled。 | 固定值：true |
| root.bond_units | string | 是 | 注册保证金，TSC 最小单位整数字符串；1 TSC = 100000000。 | 固定值："500000000" |
| sponsored | object / null | 是 | 已配置 Parent 的子资产发行信息；未配置时为 null。 |  |
| sponsored.issuance | SponsoredIssuance | 是 | 子资产的协议、命名空间和 Parent 配置；独立资产不需要。 |  |
| sponsored.issuance.mode | string | 是 | 旧版发行草稿中的子资产模式，固定 sponsored；新 /issuances 请求使用 mode: trc20。 | 固定值："sponsored" |
| sponsored.issuance.protocol | string | 是 | 子资产发行命名标准标识，当前为 TRC20。 | 格式："^[A-Z][A-Z0-9]{2,10}$" |
| sponsored.issuance.version | integer | 是 | 该对象协议格式版本。 | 固定值：1 |
| sponsored.issuance.namespace | string | 是 | 子资产链上名称前缀，当前为 TRC20。 | 格式："^[A-Z][A-Z0-9]{2,10}$" |
| sponsored.issuance.parent_asset_id | string | 是 | 平台 Parent 的链上 Asset ID。 | 格式："^[0-9a-f]{64}$" |
| sponsored.bond_units | string | 是 | 注册保证金，TSC 最小单位整数字符串；1 TSC = 100000000。 | 固定值："10000" |
| wallet_protocol | object | 否 | 发行签名请求所采用的协议版本、摘要和网络标识。 |  |
| wallet_protocol.name | string | 是 | 发行签名协议名称，固定 TWP。 | 固定值："TWP" |
| wallet_protocol.draft_revision | string | 是 | 钱包协议草案版本；不同版本不能视为自动兼容。 | 固定值："0.2" |
| wallet_protocol.spec_hash | string | 是 | 精确钱包协议文档摘要，不能仅按版本号判断兼容。 | 格式："^[0-9a-f]{64}$" |
| wallet_protocol.chain_id | string / null | 是 | 目标网络标识，公共网络格式为 tsc:<genesis>:public。 | 格式："^tsc:[0-9a-f]{64}:(public\|[0-9a-f]{64})$" |
| availability | object | 否 | 当前部署的发行能力状态；以 enabled 判断是否开放。 |  |
| availability.enabled | boolean | 是 | 当前部署是否开放发行；false 时创建请求返回 code 中的错误。 |  |
| availability.code | string / null | 是 | 发行关闭时的错误码；启用时为 null。 |  |
| availability.message | string / null | 是 | 发行关闭原因；启用时为 null。 |  |
| media | object | 否 | 图标上传、URL 和存储能力配置。 |  |
| media.upload_enabled | boolean | 是 | 当前环境是否允许上传图片。 |  |
| media.storage | string | 是 | 头像存储类型；新上传使用 ipfs。 | 固定值："ipfs" |
| media.gateway_base_url | string | 是 | 显示 IPFS 图片所用的 HTTPS 网关前缀。 |  |
| media.max_upload_bytes | integer | 是 | 上传图片解码后原始字节上限；51200 字节。 | 固定值：51200 |
| media.url_schemes | string[] | 是 | 允许的图片 URL 协议；https 和 ipfs。 |  |
| media.metadata_immutable | boolean | 是 | 当前资产发行流程中的链上元数据是否不可修改。 | 固定值：true |

错误响应：

| HTTP 状态 | 含义 |
| --- | --- |
| 400 | 请求参数、资产策略或签名无效。 |
| 404 | 未找到资产、池子或操作记录。 |
| 409 | 审核过期、交易内容改变、价格不满足限制或分页游标失效。 |
| 413 | 请求体超过允许字节数。 |
| 415 | 请求 Content-Type 不受支持。 |
| 422 | JSON 字段格式无效或包含未知字段。 |
| 429 | 请求频率或容量达到上限，按 Retry-After 秒数退避。 |
| 503 | 节点、签名服务、索引或上游暂不可用，按 Retry-After 秒数退避。 |

### GET /launches

查询地址发行的资产。只查询该地址通过平台发行的记录，包含待确认状态；不是钱包余额或全链发行者索引。最多 20 条，next_cursor 为 null 表示没有下一页。

参数：

| 字段 | 位置 | 类型 | 必填 | 说明与约束 |
| --- | --- | --- | --- | --- |
| actor | query | string | 是 | 当前网络的发行者钱包地址；查询其通过平台发行的记录。  |
| q | query | string | 否 | 搜索关键词，可为名称、符号或完整 Asset ID。  |
| cursor | query | string | 否 | 分页游标，原样传入上次返回的 next_cursor。 格式："^[0-9a-f]{64}$" |
| limit | query | integer | 否 | 本页最多返回的记录数量；默认和上限见约束。 默认值：20；最小值：1；最大值：20 |

响应 200：返回以下 JSON 对象；交易的最终结果以 state 和链上确认状态为准。

| 字段 | 类型 | 必定出现 | 说明 | 约束 |
| --- | --- | --- | --- | --- |
| genesis | string | 是 | 当前网络的创世区块哈希，64 位小写十六进制。 | 格式："^[0-9a-f]{64}$" |
| actor | string | 是 | 操作账户在当前网络的 P2WPKH 地址；仅提供地址不会授权花费。 |  |
| assets | IssuerAsset[] | 是 | 当前查询范围内的资产列表。 |  |
| assets[].asset_id | string | 是 | 资产的链上 ID，64 位小写十六进制；只在对应网络有效。 | 格式："^[0-9a-f]{64}$" |
| assets[].actor | string | 是 | 操作账户在当前网络的 P2WPKH 地址；仅提供地址不会授权花费。 |  |
| assets[].name | string | 是 | 资产展示名称，1–80 个字符。 |  |
| assets[].symbol | string | 是 | 资产展示符号；发行时填 3–11 位大写字母数字，首位字母，不加 TRC20. 前缀。 |  |
| assets[].precision | integer | 是 | 资产小数位数；TSC 为 8，其他资产以链上登记值为准。 | 最小值：0 |
| assets[].initial_supply | string | 是 | 最初发行时填写的资产数量，十进制字符串；不是当前供应量或钱包余额。 | 格式："^[0-9]+(?:\\.[0-9]+)?$" |
| assets[].icon_url | string | 是 | HTTPS 或 ipfs://CID 图片地址；原样写入元数据，不由服务器下载；与 icon_base64 互斥。 |  |
| assets[].state | string | 是 | 当前状态；可选值及阶段解释见此接口。 | 可选值：["pending", "ready_to_mint", "complete"] |
| assets[].register | CreationTxState | 是 | 注册交易及其当前确认状态。 |  |
| assets[].register.txid | string | 是 | 链上交易 ID，64 位小写十六进制；不同于 quote_id 或 request_id。 | 格式："^[0-9a-f]{64}$" |
| assets[].register.state | string | 是 | pending 已提交未确认；confirmed 已确认；not_seen 当前节点未观察到交易。 | 可选值：["pending", "confirmed", "not_seen"] |
| assets[].register.confirmations | integer | 是 | 当前有效链上的确认次数；重组后可能减少。 | 最小值：0 |
| assets[].mint | CreationTxState / null | 是 | 首次铸币交易及确认状态；尚未提交时为 null。 |  |
| assets[].mint.txid | string | 是 | 链上交易 ID，64 位小写十六进制；不同于 quote_id 或 request_id。 | 格式："^[0-9a-f]{64}$" |
| assets[].mint.state | string | 是 | pending 已提交未确认；confirmed 已确认；not_seen 当前节点未观察到交易。 | 可选值：["pending", "confirmed", "not_seen"] |
| assets[].mint.confirmations | integer | 是 | 当前有效链上的确认次数；重组后可能减少。 | 最小值：0 |
| assets[].listed | boolean | 是 | 是否在平台默认收录列表中；不是资产安全性认证。 |  |
| assets[].chain_symbol | string | 否 | 完整链上符号；子资产包含命名空间前缀。 |  |
| assets[].issuance | SponsoredIssuance / null | 否 | 子资产的协议、命名空间和 Parent 配置；独立资产不需要。 |  |
| assets[].issuance.mode | string | 是 | 旧版发行草稿中的子资产模式，固定 sponsored；新 /issuances 请求使用 mode: trc20。 | 固定值："sponsored" |
| assets[].issuance.protocol | string | 是 | 子资产发行命名标准标识，当前为 TRC20。 | 格式："^[A-Z][A-Z0-9]{2,10}$" |
| assets[].issuance.version | integer | 是 | 该对象协议格式版本。 | 固定值：1 |
| assets[].issuance.namespace | string | 是 | 子资产链上名称前缀，当前为 TRC20。 | 格式："^[A-Z][A-Z0-9]{2,10}$" |
| assets[].issuance.parent_asset_id | string | 是 | 平台 Parent 的链上 Asset ID。 | 格式："^[0-9a-f]{64}$" |
| next_cursor | string / null | 是 | 下一页游标；没有下一页时为 null，原样用于下一次请求。 | 格式："^[0-9a-f]{64}$" |

错误响应：

| HTTP 状态 | 含义 |
| --- | --- |
| 400 | 请求参数、资产策略或签名无效。 |
| 404 | 未找到资产、池子或操作记录。 |
| 409 | 审核过期、交易内容改变、价格不满足限制或分页游标失效。 |
| 413 | 请求体超过允许字节数。 |
| 415 | 请求 Content-Type 不受支持。 |
| 422 | JSON 字段格式无效或包含未知字段。 |
| 429 | 请求频率或容量达到上限，按 Retry-After 秒数退避。 |
| 503 | 节点、签名服务、索引或上游暂不可用，按 Retry-After 秒数退避。 |

### POST /launches/preview

预览旧版发行资料。校验 draft 并生成链上描述文档，不签名、不广播。仅供已有 /launches 集成使用。

请求体：

| 字段 | 类型 | 必填 | 说明 | 约束 |
| --- | --- | --- | --- | --- |
| asset_id | string | 是 | 资产的链上 ID，64 位小写十六进制；只在对应网络有效。 | 格式："^[0-9a-f]{64}$" |
| name | string | 是 | 资产展示名称，1–80 个字符。 | 最短字符数：1；最长字符数：80 |
| symbol | string | 是 | 资产展示符号；发行时填 3–11 位大写字母数字，首位字母，不加 TRC20. 前缀。 | 格式："^[A-Z][A-Z0-9]{2,10}$" |
| description | string | 是 | 公开资产简介，1–2000 个字符。 | 最短字符数：1；最长字符数：2000 |
| decimals | integer | 是 | 资产精度，0–18；最小单位数量 = supply × 10^decimals。 | 最小值：0；最大值：18 |
| supply | string | 是 | 首次发行数量，按资产单位填写的十进制字符串；乘 10^decimals 后须为 uint64 范围内整数，不是实时流通量。 | 格式："^[0-9]+(?:\\.[0-9]+)?$" |
| icon_url | string | 否 | HTTPS 或 ipfs://CID 图片地址；原样写入元数据，不由服务器下载；与 icon_base64 互斥。 |  |
| links | object | 否 | 可选社交与资料链接对象，支持 website、x、telegram、discord、docs、github、whitepaper。 | 不接受未知字段 |
| links.website | string | 否 | 项目官网 HTTPS 地址。 |  |
| links.x | string | 否 | 项目 X 主页 HTTPS 地址。 |  |
| links.telegram | string | 否 | Telegram 社区 HTTPS 地址。 |  |
| links.discord | string | 否 | Discord 社区 HTTPS 地址。 |  |
| links.docs | string | 否 | 项目文档 HTTPS 地址。 |  |
| links.github | string | 否 | 项目代码仓库 HTTPS 地址。 |  |
| links.whitepaper | string | 否 | 项目白皮书 HTTPS 地址。 |  |
| issuance | SponsoredIssuance / null | 否 | 子资产的协议、命名空间和 Parent 配置；独立资产不需要。 |  |
| issuance.mode | string | 是 | 旧版发行草稿中的子资产模式，固定 sponsored；新 /issuances 请求使用 mode: trc20。 | 固定值："sponsored" |
| issuance.protocol | string | 是 | 子资产发行命名标准标识，当前为 TRC20。 | 格式："^[A-Z][A-Z0-9]{2,10}$" |
| issuance.version | integer | 是 | 该对象协议格式版本。 | 固定值：1 |
| issuance.namespace | string | 是 | 子资产链上名称前缀，当前为 TRC20。 | 格式："^[A-Z][A-Z0-9]{2,10}$" |
| issuance.parent_asset_id | string | 是 | 平台 Parent 的链上 Asset ID。 | 格式："^[0-9a-f]{64}$" |

响应 200：返回以下 JSON 对象；交易的最终结果以 state 和链上确认状态为准。

| 字段 | 类型 | 必定出现 | 说明 | 约束 |
| --- | --- | --- | --- | --- |
| draft | CreationDraft | 是 | 本次发行固定的完整资产资料。 |  |
| draft.asset_id | string | 是 | 资产的链上 ID，64 位小写十六进制；只在对应网络有效。 | 格式："^[0-9a-f]{64}$" |
| draft.name | string | 是 | 资产展示名称，1–80 个字符。 | 最短字符数：1；最长字符数：80 |
| draft.symbol | string | 是 | 资产展示符号；发行时填 3–11 位大写字母数字，首位字母，不加 TRC20. 前缀。 | 格式："^[A-Z][A-Z0-9]{2,10}$" |
| draft.description | string | 是 | 公开资产简介，1–2000 个字符。 | 最短字符数：1；最长字符数：2000 |
| draft.decimals | integer | 是 | 资产精度，0–18；最小单位数量 = supply × 10^decimals。 | 最小值：0；最大值：18 |
| draft.supply | string | 是 | 首次发行数量，按资产单位填写的十进制字符串；乘 10^decimals 后须为 uint64 范围内整数，不是实时流通量。 | 格式："^[0-9]+(?:\\.[0-9]+)?$" |
| draft.icon_url | string | 否 | HTTPS 或 ipfs://CID 图片地址；原样写入元数据，不由服务器下载；与 icon_base64 互斥。 |  |
| draft.links | object | 否 | 可选社交与资料链接对象，支持 website、x、telegram、discord、docs、github、whitepaper。 | 不接受未知字段 |
| draft.links.website | string | 否 | 项目官网 HTTPS 地址。 |  |
| draft.links.x | string | 否 | 项目 X 主页 HTTPS 地址。 |  |
| draft.links.telegram | string | 否 | Telegram 社区 HTTPS 地址。 |  |
| draft.links.discord | string | 否 | Discord 社区 HTTPS 地址。 |  |
| draft.links.docs | string | 否 | 项目文档 HTTPS 地址。 |  |
| draft.links.github | string | 否 | 项目代码仓库 HTTPS 地址。 |  |
| draft.links.whitepaper | string | 否 | 项目白皮书 HTTPS 地址。 |  |
| draft.issuance | SponsoredIssuance / null | 否 | 子资产的协议、命名空间和 Parent 配置；独立资产不需要。 |  |
| draft.issuance.mode | string | 是 | 旧版发行草稿中的子资产模式，固定 sponsored；新 /issuances 请求使用 mode: trc20。 | 固定值："sponsored" |
| draft.issuance.protocol | string | 是 | 子资产发行命名标准标识，当前为 TRC20。 | 格式："^[A-Z][A-Z0-9]{2,10}$" |
| draft.issuance.version | integer | 是 | 该对象协议格式版本。 | 固定值：1 |
| draft.issuance.namespace | string | 是 | 子资产链上名称前缀，当前为 TRC20。 | 格式："^[A-Z][A-Z0-9]{2,10}$" |
| draft.issuance.parent_asset_id | string | 是 | 平台 Parent 的链上 Asset ID。 | 格式："^[0-9a-f]{64}$" |
| metadata | AssetDocumentMetadata | 是 | 资产描述文档中的展示名称、简介、图标和链接。 |  |
| metadata.protocol | string | 是 | 链上资产展示资料的协议名称。 | 固定值："tc-asset-meta" |
| metadata.version | integer | 是 | 该对象协议格式版本。 | 固定值：1 |
| metadata.display_name | string | 是 | 元数据中的资产展示名称。 |  |
| metadata.summary | string | 是 | 资产元数据中的公开简介。 |  |
| metadata.links | object | 是 | 可选社交与资料链接对象，支持 website、x、telegram、discord、docs、github、whitepaper。 |  |
| metadata.icon | object | 否 | 头像元数据，uri 为写入链上的地址。 |  |
| metadata.icon.uri | string | 是 | 写入链上资料的图片地址；平台上传返回 ipfs://CID。 |  |
| metadata.issuance | SponsoredIssuance | 否 | 子资产发行标准与 Parent 身份；不是当前实时发行开关。 |  |
| metadata.issuance.mode | string | 是 | 旧版发行草稿中的子资产模式，固定 sponsored；新 /issuances 请求使用 mode: trc20。 | 固定值："sponsored" |
| metadata.issuance.protocol | string | 是 | 子资产发行命名标准标识，当前为 TRC20。 | 格式："^[A-Z][A-Z0-9]{2,10}$" |
| metadata.issuance.version | integer | 是 | 该对象协议格式版本。 | 固定值：1 |
| metadata.issuance.namespace | string | 是 | 子资产链上名称前缀，当前为 TRC20。 | 格式："^[A-Z][A-Z0-9]{2,10}$" |
| metadata.issuance.parent_asset_id | string | 是 | 平台 Parent 的链上 Asset ID。 | 格式："^[0-9a-f]{64}$" |
| metadata.symbol | string | 否 | 资产展示符号；发行时填 3–11 位大写字母数字，首位字母，不加 TRC20. 前缀。 |  |
| metadata.chain_symbol | string | 否 | 完整链上符号；子资产包含命名空间前缀。 |  |
| document | string | 是 | 写入注册交易的完整资产描述文档。 |  |
| bond_units | string | 是 | 注册保证金，TSC 最小单位整数字符串；1 TSC = 100000000。 | 格式："^[0-9]+$" |
| supply_units | string | 是 | 首次发行的最小单位数量，整数字符串；等于 supply × 10^decimals。 | 格式："^[0-9]+$" |
| policy_bits | integer | 是 | 注册资产的链上策略位字段。 | 固定值：3 |
| immutable | boolean | 是 | 资产资料在当前发行流程中是否不可修改。 | 固定值：true |
| genesis | string | 是 | 当前网络的创世区块哈希，64 位小写十六进制。 | 格式："^[0-9a-f]{64}$" |
| chain_symbol | string | 否 | 完整链上符号；子资产包含命名空间前缀。 |  |

错误响应：

| HTTP 状态 | 含义 |
| --- | --- |
| 400 | 请求参数、资产策略或签名无效。 |
| 404 | 未找到资产、池子或操作记录。 |
| 409 | 审核过期、交易内容改变、价格不满足限制或分页游标失效。 |
| 413 | 请求体超过允许字节数。 |
| 415 | 请求 Content-Type 不受支持。 |
| 422 | JSON 字段格式无效或包含未知字段。 |
| 429 | 请求频率或容量达到上限，按 Retry-After 秒数退避。 |
| 503 | 节点、签名服务、索引或上游暂不可用，按 Retry-After 秒数退避。 |

### POST /launches/prepare

准备旧版发行交易。step=register 注册，注册确认后用原 actor 和 draft 请求 step=mint。返回 300 秒有效的未签名审核，不广播。新集成使用 /issuances。

请求体：

| 字段 | 类型 | 必填 | 说明 | 约束 |
| --- | --- | --- | --- | --- |
| actor | string | 是 | 操作账户在当前网络的 P2WPKH 地址；仅提供地址不会授权花费。 |  |
| step | string | 是 | 发行阶段：register 注册资产，mint 发行初始数量。 | 可选值：["register", "mint"] |
| draft | CreationDraft | 是 | 本次发行固定的完整资产资料。 |  |
| draft.asset_id | string | 是 | 资产的链上 ID，64 位小写十六进制；只在对应网络有效。 | 格式："^[0-9a-f]{64}$" |
| draft.name | string | 是 | 资产展示名称，1–80 个字符。 | 最短字符数：1；最长字符数：80 |
| draft.symbol | string | 是 | 资产展示符号；发行时填 3–11 位大写字母数字，首位字母，不加 TRC20. 前缀。 | 格式："^[A-Z][A-Z0-9]{2,10}$" |
| draft.description | string | 是 | 公开资产简介，1–2000 个字符。 | 最短字符数：1；最长字符数：2000 |
| draft.decimals | integer | 是 | 资产精度，0–18；最小单位数量 = supply × 10^decimals。 | 最小值：0；最大值：18 |
| draft.supply | string | 是 | 首次发行数量，按资产单位填写的十进制字符串；乘 10^decimals 后须为 uint64 范围内整数，不是实时流通量。 | 格式："^[0-9]+(?:\\.[0-9]+)?$" |
| draft.icon_url | string | 否 | HTTPS 或 ipfs://CID 图片地址；原样写入元数据，不由服务器下载；与 icon_base64 互斥。 |  |
| draft.links | object | 否 | 可选社交与资料链接对象，支持 website、x、telegram、discord、docs、github、whitepaper。 | 不接受未知字段 |
| draft.links.website | string | 否 | 项目官网 HTTPS 地址。 |  |
| draft.links.x | string | 否 | 项目 X 主页 HTTPS 地址。 |  |
| draft.links.telegram | string | 否 | Telegram 社区 HTTPS 地址。 |  |
| draft.links.discord | string | 否 | Discord 社区 HTTPS 地址。 |  |
| draft.links.docs | string | 否 | 项目文档 HTTPS 地址。 |  |
| draft.links.github | string | 否 | 项目代码仓库 HTTPS 地址。 |  |
| draft.links.whitepaper | string | 否 | 项目白皮书 HTTPS 地址。 |  |
| draft.issuance | SponsoredIssuance / null | 否 | 子资产的协议、命名空间和 Parent 配置；独立资产不需要。 |  |
| draft.issuance.mode | string | 是 | 旧版发行草稿中的子资产模式，固定 sponsored；新 /issuances 请求使用 mode: trc20。 | 固定值："sponsored" |
| draft.issuance.protocol | string | 是 | 子资产发行命名标准标识，当前为 TRC20。 | 格式："^[A-Z][A-Z0-9]{2,10}$" |
| draft.issuance.version | integer | 是 | 该对象协议格式版本。 | 固定值：1 |
| draft.issuance.namespace | string | 是 | 子资产链上名称前缀，当前为 TRC20。 | 格式："^[A-Z][A-Z0-9]{2,10}$" |
| draft.issuance.parent_asset_id | string | 是 | 平台 Parent 的链上 Asset ID。 | 格式："^[0-9a-f]{64}$" |

响应 200：返回以下 JSON 对象；交易的最终结果以 state 和链上确认状态为准。

| 字段 | 类型 | 必定出现 | 说明 | 约束 |
| --- | --- | --- | --- | --- |
| schema | string | 是 | 此对象的序列化版本标识。 | 可选值：["tern-asset-launch-v1", "tc-asset-launch-v2"] |
| review_id | string | 是 | 本次待签名交易的审核 ID；与阶段和确切交易绑定。 | 格式："^[0-9a-f]{64}$" |
| expires_at | integer | 是 | 失效时间；交易和审核为 UTC Unix 秒，美元参考价为毫秒。 | 最小值：0 |
| genesis | string | 是 | 当前网络的创世区块哈希，64 位小写十六进制。 | 格式："^[0-9a-f]{64}$" |
| actor | string | 是 | 操作账户在当前网络的 P2WPKH 地址；仅提供地址不会授权花费。 |  |
| step | string | 是 | 发行阶段：register 注册资产，mint 发行初始数量。 | 可选值：["register", "mint"] |
| draft | CreationDraft | 是 | 本次发行固定的完整资产资料。 |  |
| draft.asset_id | string | 是 | 资产的链上 ID，64 位小写十六进制；只在对应网络有效。 | 格式："^[0-9a-f]{64}$" |
| draft.name | string | 是 | 资产展示名称，1–80 个字符。 | 最短字符数：1；最长字符数：80 |
| draft.symbol | string | 是 | 资产展示符号；发行时填 3–11 位大写字母数字，首位字母，不加 TRC20. 前缀。 | 格式："^[A-Z][A-Z0-9]{2,10}$" |
| draft.description | string | 是 | 公开资产简介，1–2000 个字符。 | 最短字符数：1；最长字符数：2000 |
| draft.decimals | integer | 是 | 资产精度，0–18；最小单位数量 = supply × 10^decimals。 | 最小值：0；最大值：18 |
| draft.supply | string | 是 | 首次发行数量，按资产单位填写的十进制字符串；乘 10^decimals 后须为 uint64 范围内整数，不是实时流通量。 | 格式："^[0-9]+(?:\\.[0-9]+)?$" |
| draft.icon_url | string | 否 | HTTPS 或 ipfs://CID 图片地址；原样写入元数据，不由服务器下载；与 icon_base64 互斥。 |  |
| draft.links | object | 否 | 可选社交与资料链接对象，支持 website、x、telegram、discord、docs、github、whitepaper。 | 不接受未知字段 |
| draft.links.website | string | 否 | 项目官网 HTTPS 地址。 |  |
| draft.links.x | string | 否 | 项目 X 主页 HTTPS 地址。 |  |
| draft.links.telegram | string | 否 | Telegram 社区 HTTPS 地址。 |  |
| draft.links.discord | string | 否 | Discord 社区 HTTPS 地址。 |  |
| draft.links.docs | string | 否 | 项目文档 HTTPS 地址。 |  |
| draft.links.github | string | 否 | 项目代码仓库 HTTPS 地址。 |  |
| draft.links.whitepaper | string | 否 | 项目白皮书 HTTPS 地址。 |  |
| draft.issuance | SponsoredIssuance / null | 否 | 子资产的协议、命名空间和 Parent 配置；独立资产不需要。 |  |
| draft.issuance.mode | string | 是 | 旧版发行草稿中的子资产模式，固定 sponsored；新 /issuances 请求使用 mode: trc20。 | 固定值："sponsored" |
| draft.issuance.protocol | string | 是 | 子资产发行命名标准标识，当前为 TRC20。 | 格式："^[A-Z][A-Z0-9]{2,10}$" |
| draft.issuance.version | integer | 是 | 该对象协议格式版本。 | 固定值：1 |
| draft.issuance.namespace | string | 是 | 子资产链上名称前缀，当前为 TRC20。 | 格式："^[A-Z][A-Z0-9]{2,10}$" |
| draft.issuance.parent_asset_id | string | 是 | 平台 Parent 的链上 Asset ID。 | 格式："^[0-9a-f]{64}$" |
| document | string | 是 | 写入注册交易的完整资产描述文档。 |  |
| intent | object | 是 | 本次注册或铸币的审核意图，绑定资金、描述文档、数量上限和接收方。 |  |
| prepared | CreationPreparedTx | 是 | 未签名交易及构造时的输入输出明细。 |  |
| prepared.operation | string | 是 | 交易操作语义；asset_create 注册资产，asset_mint 铸币。 | 可选值：["asset_create", "asset_mint"] |
| prepared.identifier | string | 是 | 本次资产创建或铸币对应的资产 ID。 | 格式："^[0-9a-f]{64}$" |
| prepared.state | string | 是 | 当前状态；可选值及阶段解释见此接口。 | 固定值："unsigned" |
| prepared.hex | string | 是 | 原始 TensorCash 交易的十六进制字节；不是 PSBT 或 EVM 交易。 | 格式："^(?:[0-9a-f]{2})*$" |
| prepared.psbt | string | 是 | 兼容字段；当前为空字符串，使用 hex 中的原始交易。 | 固定值："" |
| prepared.fee_units | string | 是 | 本次交易矿工费，TSC 最小单位整数字符串；1 TSC = 100000000。 | 格式："^[0-9]+$" |
| prepared.change_units | string | 是 | 找零金额，TSC 最小单位整数字符串。 | 格式："^[0-9]+$" |
| prepared.core_tip_hash | string | 是 | 构造待签名交易时的链尖区块哈希。 | 格式："^[0-9a-f]{64}$" |
| prepared.requires_signing | boolean | 是 | 交易是否尚需钱包签名。 | 固定值：true |
| prepared.broadcast | boolean | 是 | 本次接口是否广播了交易；false 时仍须由调用方广播。 | 固定值：false |
| prepared.inputs | object[] | 是 | 交易引用的输入及其实际前序输出资料。 |  |
| prepared.inputs[].txid | string | 是 | 链上交易 ID，64 位小写十六进制；不同于 quote_id 或 request_id。 | 格式："^[0-9a-f]{64}$" |
| prepared.inputs[].vout | integer | 是 | 交易输出位置，从 0 开始。 | 最小值：0 |
| prepared.inputs[].value_units | string | 是 | 该输入或输出的 TSC 最小单位数量，整数字符串；Asset 数量编码在 output_extension。 | 格式："^[0-9]+$" |
| prepared.inputs[].script_pub_key | string | 是 | 输出锁定脚本，十六进制字符串。 | 格式："^(?:[0-9a-f]{2})*$" |
| prepared.inputs[].output_extension | string | 是 | 输出的 TensorCash 资产扩展字节，十六进制字符串。 | 格式："^(?:[0-9a-f]{2})*$" |
| prepared.outputs | object[] | 是 | 交易输出列表，包含金额、锁定脚本和资产扩展。 |  |
| prepared.outputs[].vout | integer | 是 | 交易输出位置，从 0 开始。 | 最小值：0 |
| prepared.outputs[].value_units | string | 是 | 该输入或输出的 TSC 最小单位数量，整数字符串；Asset 数量编码在 output_extension。 | 格式："^[0-9]+$" |
| prepared.outputs[].script_pub_key | string | 是 | 输出锁定脚本，十六进制字符串。 | 格式："^(?:[0-9a-f]{2})*$" |
| prepared.outputs[].output_extension | string | 是 | 输出的 TensorCash 资产扩展字节，十六进制字符串。 | 格式："^(?:[0-9a-f]{2})*$" |
| previous_transactions | object | 是 | txid 到完整前序交易原始字节的映射；须独立重算 txid 和输入金额。 |  |
| chain_symbol | string | 否 | 完整链上符号；子资产包含命名空间前缀。 |  |

错误响应：

| HTTP 状态 | 含义 |
| --- | --- |
| 400 | 请求参数、资产策略或签名无效。 |
| 404 | 未找到资产、池子或操作记录。 |
| 409 | 审核过期、交易内容改变、价格不满足限制或分页游标失效。 |
| 413 | 请求体超过允许字节数。 |
| 415 | 请求 Content-Type 不受支持。 |
| 422 | JSON 字段格式无效或包含未知字段。 |
| 429 | 请求频率或容量达到上限，按 Retry-After 秒数退避。 |
| 503 | 节点、签名服务、索引或上游暂不可用，按 Retry-After 秒数退避。 |

### POST /launches/submit

提交旧版发行签名交易。提交原 review_id 与签名后的 hex，校验后持久保存并广播。HTTP 200 表示已提交，不表示确认；超时后查询原记录，重试同一签名请求。

请求体：

| 字段 | 类型 | 必填 | 说明 | 约束 |
| --- | --- | --- | --- | --- |
| review_id | string | 是 | 本次待签名交易的审核 ID；与阶段和确切交易绑定。 | 格式："^[0-9a-f]{64}$" |
| hex | string | 是 | 原始 TensorCash 交易的十六进制字节；不是 PSBT 或 EVM 交易。 | 格式："^(?:[0-9a-f]{2})*$" |

响应 200：返回以下 JSON 对象；交易的最终结果以 state 和链上确认状态为准。

| 字段 | 类型 | 必定出现 | 说明 | 约束 |
| --- | --- | --- | --- | --- |
| asset_id | string | 是 | 资产的链上 ID，64 位小写十六进制；只在对应网络有效。 | 格式："^[0-9a-f]{64}$" |
| step | string | 是 | 发行阶段：register 注册资产，mint 发行初始数量。 | 可选值：["register", "mint"] |
| txid | string | 是 | 链上交易 ID，64 位小写十六进制；不同于 quote_id 或 request_id。 | 格式："^[0-9a-f]{64}$" |
| state | string | 是 | 当前状态；可选值及阶段解释见此接口。 | 固定值："submitted" |

错误响应：

| HTTP 状态 | 含义 |
| --- | --- |
| 400 | 请求参数、资产策略或签名无效。 |
| 404 | 未找到资产、池子或操作记录。 |
| 409 | 审核过期、交易内容改变、价格不满足限制或分页游标失效。 |
| 413 | 请求体超过允许字节数。 |
| 415 | 请求 Content-Type 不受支持。 |
| 422 | JSON 字段格式无效或包含未知字段。 |
| 429 | 请求频率或容量达到上限，按 Retry-After 秒数退避。 |
| 503 | 节点、签名服务、索引或上游暂不可用，按 Retry-After 秒数退避。 |

### GET /launches/{id}

查询旧版发行状态。路径 id 是 Asset ID。返回注册与首次铸币的确认状态；重组可能回退确认，不能因此自动再铸币。

参数：

| 字段 | 位置 | 类型 | 必填 | 说明与约束 |
| --- | --- | --- | --- | --- |
| id | path | string | 是 | Asset ID，64 位小写十六进制。 格式："^[0-9a-f]{64}$" |

响应 200：返回以下 JSON 对象；交易的最终结果以 state 和链上确认状态为准。

| 字段 | 类型 | 必定出现 | 说明 | 约束 |
| --- | --- | --- | --- | --- |
| genesis | string | 是 | 当前网络的创世区块哈希，64 位小写十六进制。 | 格式："^[0-9a-f]{64}$" |
| asset_id | string | 是 | 资产的链上 ID，64 位小写十六进制；只在对应网络有效。 | 格式："^[0-9a-f]{64}$" |
| actor | string | 是 | 操作账户在当前网络的 P2WPKH 地址；仅提供地址不会授权花费。 |  |
| draft | CreationDraft | 是 | 本次发行固定的完整资产资料。 |  |
| draft.asset_id | string | 是 | 资产的链上 ID，64 位小写十六进制；只在对应网络有效。 | 格式："^[0-9a-f]{64}$" |
| draft.name | string | 是 | 资产展示名称，1–80 个字符。 | 最短字符数：1；最长字符数：80 |
| draft.symbol | string | 是 | 资产展示符号；发行时填 3–11 位大写字母数字，首位字母，不加 TRC20. 前缀。 | 格式："^[A-Z][A-Z0-9]{2,10}$" |
| draft.description | string | 是 | 公开资产简介，1–2000 个字符。 | 最短字符数：1；最长字符数：2000 |
| draft.decimals | integer | 是 | 资产精度，0–18；最小单位数量 = supply × 10^decimals。 | 最小值：0；最大值：18 |
| draft.supply | string | 是 | 首次发行数量，按资产单位填写的十进制字符串；乘 10^decimals 后须为 uint64 范围内整数，不是实时流通量。 | 格式："^[0-9]+(?:\\.[0-9]+)?$" |
| draft.icon_url | string | 否 | HTTPS 或 ipfs://CID 图片地址；原样写入元数据，不由服务器下载；与 icon_base64 互斥。 |  |
| draft.links | object | 否 | 可选社交与资料链接对象，支持 website、x、telegram、discord、docs、github、whitepaper。 | 不接受未知字段 |
| draft.links.website | string | 否 | 项目官网 HTTPS 地址。 |  |
| draft.links.x | string | 否 | 项目 X 主页 HTTPS 地址。 |  |
| draft.links.telegram | string | 否 | Telegram 社区 HTTPS 地址。 |  |
| draft.links.discord | string | 否 | Discord 社区 HTTPS 地址。 |  |
| draft.links.docs | string | 否 | 项目文档 HTTPS 地址。 |  |
| draft.links.github | string | 否 | 项目代码仓库 HTTPS 地址。 |  |
| draft.links.whitepaper | string | 否 | 项目白皮书 HTTPS 地址。 |  |
| draft.issuance | SponsoredIssuance / null | 否 | 子资产的协议、命名空间和 Parent 配置；独立资产不需要。 |  |
| draft.issuance.mode | string | 是 | 旧版发行草稿中的子资产模式，固定 sponsored；新 /issuances 请求使用 mode: trc20。 | 固定值："sponsored" |
| draft.issuance.protocol | string | 是 | 子资产发行命名标准标识，当前为 TRC20。 | 格式："^[A-Z][A-Z0-9]{2,10}$" |
| draft.issuance.version | integer | 是 | 该对象协议格式版本。 | 固定值：1 |
| draft.issuance.namespace | string | 是 | 子资产链上名称前缀，当前为 TRC20。 | 格式："^[A-Z][A-Z0-9]{2,10}$" |
| draft.issuance.parent_asset_id | string | 是 | 平台 Parent 的链上 Asset ID。 | 格式："^[0-9a-f]{64}$" |
| document | string | 是 | 写入注册交易的完整资产描述文档。 |  |
| metadata | AssetDocumentMetadata | 是 | 资产描述文档中的展示名称、简介、图标和链接。 |  |
| metadata.protocol | string | 是 | 链上资产展示资料的协议名称。 | 固定值："tc-asset-meta" |
| metadata.version | integer | 是 | 该对象协议格式版本。 | 固定值：1 |
| metadata.display_name | string | 是 | 元数据中的资产展示名称。 |  |
| metadata.summary | string | 是 | 资产元数据中的公开简介。 |  |
| metadata.links | object | 是 | 可选社交与资料链接对象，支持 website、x、telegram、discord、docs、github、whitepaper。 |  |
| metadata.icon | object | 否 | 头像元数据，uri 为写入链上的地址。 |  |
| metadata.icon.uri | string | 是 | 写入链上资料的图片地址；平台上传返回 ipfs://CID。 |  |
| metadata.issuance | SponsoredIssuance | 否 | 子资产发行标准与 Parent 身份；不是当前实时发行开关。 |  |
| metadata.issuance.mode | string | 是 | 旧版发行草稿中的子资产模式，固定 sponsored；新 /issuances 请求使用 mode: trc20。 | 固定值："sponsored" |
| metadata.issuance.protocol | string | 是 | 子资产发行命名标准标识，当前为 TRC20。 | 格式："^[A-Z][A-Z0-9]{2,10}$" |
| metadata.issuance.version | integer | 是 | 该对象协议格式版本。 | 固定值：1 |
| metadata.issuance.namespace | string | 是 | 子资产链上名称前缀，当前为 TRC20。 | 格式："^[A-Z][A-Z0-9]{2,10}$" |
| metadata.issuance.parent_asset_id | string | 是 | 平台 Parent 的链上 Asset ID。 | 格式："^[0-9a-f]{64}$" |
| metadata.symbol | string | 否 | 资产展示符号；发行时填 3–11 位大写字母数字，首位字母，不加 TRC20. 前缀。 |  |
| metadata.chain_symbol | string | 否 | 完整链上符号；子资产包含命名空间前缀。 |  |
| register | CreationTxState | 是 | 注册交易及其当前确认状态。 |  |
| register.txid | string | 是 | 链上交易 ID，64 位小写十六进制；不同于 quote_id 或 request_id。 | 格式："^[0-9a-f]{64}$" |
| register.state | string | 是 | pending 已提交未确认；confirmed 已确认；not_seen 当前节点未观察到交易。 | 可选值：["pending", "confirmed", "not_seen"] |
| register.confirmations | integer | 是 | 当前有效链上的确认次数；重组后可能减少。 | 最小值：0 |
| mint | CreationTxState / null | 是 | 首次铸币交易及确认状态；尚未提交时为 null。 |  |
| mint.txid | string | 是 | 链上交易 ID，64 位小写十六进制；不同于 quote_id 或 request_id。 | 格式："^[0-9a-f]{64}$" |
| mint.state | string | 是 | pending 已提交未确认；confirmed 已确认；not_seen 当前节点未观察到交易。 | 可选值：["pending", "confirmed", "not_seen"] |
| mint.confirmations | integer | 是 | 当前有效链上的确认次数；重组后可能减少。 | 最小值：0 |
| state | string | 是 | pending 注册待确认；ready_to_mint 注册已确认、可准备首次铸币；complete 注册和首次铸币均确认。 | 可选值：["pending", "ready_to_mint", "complete"] |
| immutable | boolean | 是 | 资产资料在当前发行流程中是否不可修改。 |  |
| metadata_source | string | 是 | 元数据来源。 |  |
| commit_verified | boolean | 是 | 资产描述是否已与注册交易的链上承诺核对。 |  |
| chain_symbol | string | 否 | 完整链上符号；子资产包含命名空间前缀。 |  |

错误响应：

| HTTP 状态 | 含义 |
| --- | --- |
| 400 | 请求参数、资产策略或签名无效。 |
| 404 | 未找到资产、池子或操作记录。 |
| 409 | 审核过期、交易内容改变、价格不满足限制或分页游标失效。 |
| 413 | 请求体超过允许字节数。 |
| 415 | 请求 Content-Type 不受支持。 |
| 422 | JSON 字段格式无效或包含未知字段。 |
| 429 | 请求频率或容量达到上限，按 Retry-After 秒数退避。 |
| 503 | 节点、签名服务、索引或上游暂不可用，按 Retry-After 秒数退避。 |

### POST /launches/{id}/retry

重广播旧版已签名交易。只重广播服务器已经保存的原交易；不生成新交易，不请求新签名。

参数：

| 字段 | 位置 | 类型 | 必填 | 说明与约束 |
| --- | --- | --- | --- | --- |
| id | path | string | 是 | Asset ID，64 位小写十六进制。 格式："^[0-9a-f]{64}$" |

请求体：无。

响应 200：返回以下 JSON 对象；交易的最终结果以 state 和链上确认状态为准。

| 字段 | 类型 | 必定出现 | 说明 | 约束 |
| --- | --- | --- | --- | --- |
| genesis | string | 是 | 当前网络的创世区块哈希，64 位小写十六进制。 | 格式："^[0-9a-f]{64}$" |
| asset_id | string | 是 | 资产的链上 ID，64 位小写十六进制；只在对应网络有效。 | 格式："^[0-9a-f]{64}$" |
| actor | string | 是 | 操作账户在当前网络的 P2WPKH 地址；仅提供地址不会授权花费。 |  |
| draft | CreationDraft | 是 | 本次发行固定的完整资产资料。 |  |
| draft.asset_id | string | 是 | 资产的链上 ID，64 位小写十六进制；只在对应网络有效。 | 格式："^[0-9a-f]{64}$" |
| draft.name | string | 是 | 资产展示名称，1–80 个字符。 | 最短字符数：1；最长字符数：80 |
| draft.symbol | string | 是 | 资产展示符号；发行时填 3–11 位大写字母数字，首位字母，不加 TRC20. 前缀。 | 格式："^[A-Z][A-Z0-9]{2,10}$" |
| draft.description | string | 是 | 公开资产简介，1–2000 个字符。 | 最短字符数：1；最长字符数：2000 |
| draft.decimals | integer | 是 | 资产精度，0–18；最小单位数量 = supply × 10^decimals。 | 最小值：0；最大值：18 |
| draft.supply | string | 是 | 首次发行数量，按资产单位填写的十进制字符串；乘 10^decimals 后须为 uint64 范围内整数，不是实时流通量。 | 格式："^[0-9]+(?:\\.[0-9]+)?$" |
| draft.icon_url | string | 否 | HTTPS 或 ipfs://CID 图片地址；原样写入元数据，不由服务器下载；与 icon_base64 互斥。 |  |
| draft.links | object | 否 | 可选社交与资料链接对象，支持 website、x、telegram、discord、docs、github、whitepaper。 | 不接受未知字段 |
| draft.links.website | string | 否 | 项目官网 HTTPS 地址。 |  |
| draft.links.x | string | 否 | 项目 X 主页 HTTPS 地址。 |  |
| draft.links.telegram | string | 否 | Telegram 社区 HTTPS 地址。 |  |
| draft.links.discord | string | 否 | Discord 社区 HTTPS 地址。 |  |
| draft.links.docs | string | 否 | 项目文档 HTTPS 地址。 |  |
| draft.links.github | string | 否 | 项目代码仓库 HTTPS 地址。 |  |
| draft.links.whitepaper | string | 否 | 项目白皮书 HTTPS 地址。 |  |
| draft.issuance | SponsoredIssuance / null | 否 | 子资产的协议、命名空间和 Parent 配置；独立资产不需要。 |  |
| draft.issuance.mode | string | 是 | 旧版发行草稿中的子资产模式，固定 sponsored；新 /issuances 请求使用 mode: trc20。 | 固定值："sponsored" |
| draft.issuance.protocol | string | 是 | 子资产发行命名标准标识，当前为 TRC20。 | 格式："^[A-Z][A-Z0-9]{2,10}$" |
| draft.issuance.version | integer | 是 | 该对象协议格式版本。 | 固定值：1 |
| draft.issuance.namespace | string | 是 | 子资产链上名称前缀，当前为 TRC20。 | 格式："^[A-Z][A-Z0-9]{2,10}$" |
| draft.issuance.parent_asset_id | string | 是 | 平台 Parent 的链上 Asset ID。 | 格式："^[0-9a-f]{64}$" |
| document | string | 是 | 写入注册交易的完整资产描述文档。 |  |
| metadata | AssetDocumentMetadata | 是 | 资产描述文档中的展示名称、简介、图标和链接。 |  |
| metadata.protocol | string | 是 | 链上资产展示资料的协议名称。 | 固定值："tc-asset-meta" |
| metadata.version | integer | 是 | 该对象协议格式版本。 | 固定值：1 |
| metadata.display_name | string | 是 | 元数据中的资产展示名称。 |  |
| metadata.summary | string | 是 | 资产元数据中的公开简介。 |  |
| metadata.links | object | 是 | 可选社交与资料链接对象，支持 website、x、telegram、discord、docs、github、whitepaper。 |  |
| metadata.icon | object | 否 | 头像元数据，uri 为写入链上的地址。 |  |
| metadata.icon.uri | string | 是 | 写入链上资料的图片地址；平台上传返回 ipfs://CID。 |  |
| metadata.issuance | SponsoredIssuance | 否 | 子资产发行标准与 Parent 身份；不是当前实时发行开关。 |  |
| metadata.issuance.mode | string | 是 | 旧版发行草稿中的子资产模式，固定 sponsored；新 /issuances 请求使用 mode: trc20。 | 固定值："sponsored" |
| metadata.issuance.protocol | string | 是 | 子资产发行命名标准标识，当前为 TRC20。 | 格式："^[A-Z][A-Z0-9]{2,10}$" |
| metadata.issuance.version | integer | 是 | 该对象协议格式版本。 | 固定值：1 |
| metadata.issuance.namespace | string | 是 | 子资产链上名称前缀，当前为 TRC20。 | 格式："^[A-Z][A-Z0-9]{2,10}$" |
| metadata.issuance.parent_asset_id | string | 是 | 平台 Parent 的链上 Asset ID。 | 格式："^[0-9a-f]{64}$" |
| metadata.symbol | string | 否 | 资产展示符号；发行时填 3–11 位大写字母数字，首位字母，不加 TRC20. 前缀。 |  |
| metadata.chain_symbol | string | 否 | 完整链上符号；子资产包含命名空间前缀。 |  |
| register | CreationTxState | 是 | 注册交易及其当前确认状态。 |  |
| register.txid | string | 是 | 链上交易 ID，64 位小写十六进制；不同于 quote_id 或 request_id。 | 格式："^[0-9a-f]{64}$" |
| register.state | string | 是 | pending 已提交未确认；confirmed 已确认；not_seen 当前节点未观察到交易。 | 可选值：["pending", "confirmed", "not_seen"] |
| register.confirmations | integer | 是 | 当前有效链上的确认次数；重组后可能减少。 | 最小值：0 |
| mint | CreationTxState / null | 是 | 首次铸币交易及确认状态；尚未提交时为 null。 |  |
| mint.txid | string | 是 | 链上交易 ID，64 位小写十六进制；不同于 quote_id 或 request_id。 | 格式："^[0-9a-f]{64}$" |
| mint.state | string | 是 | pending 已提交未确认；confirmed 已确认；not_seen 当前节点未观察到交易。 | 可选值：["pending", "confirmed", "not_seen"] |
| mint.confirmations | integer | 是 | 当前有效链上的确认次数；重组后可能减少。 | 最小值：0 |
| state | string | 是 | pending 注册待确认；ready_to_mint 注册已确认、可准备首次铸币；complete 注册和首次铸币均确认。 | 可选值：["pending", "ready_to_mint", "complete"] |
| immutable | boolean | 是 | 资产资料在当前发行流程中是否不可修改。 |  |
| metadata_source | string | 是 | 元数据来源。 |  |
| commit_verified | boolean | 是 | 资产描述是否已与注册交易的链上承诺核对。 |  |
| chain_symbol | string | 否 | 完整链上符号；子资产包含命名空间前缀。 |  |

错误响应：

| HTTP 状态 | 含义 |
| --- | --- |
| 400 | 请求参数、资产策略或签名无效。 |
| 404 | 未找到资产、池子或操作记录。 |
| 409 | 审核过期、交易内容改变、价格不满足限制或分页游标失效。 |
| 413 | 请求体超过允许字节数。 |
| 415 | 请求 Content-Type 不受支持。 |
| 422 | JSON 字段格式无效或包含未知字段。 |
| 429 | 请求频率或容量达到上限，按 Retry-After 秒数退避。 |
| 503 | 节点、签名服务、索引或上游暂不可用，按 Retry-After 秒数退避。 |

### GET /assets/{id}/metadata

查询资产展示资料。当前只覆盖平台留有发行记录且注册已确认的资产；返回链上描述、图标地址和链接，不表示平台验证了项目或社交账户。

参数：

| 字段 | 位置 | 类型 | 必填 | 说明与约束 |
| --- | --- | --- | --- | --- |
| id | path | string | 是 | Asset ID，64 位小写十六进制。 格式："^[0-9a-f]{64}$" |

响应 200：返回以下 JSON 对象；交易的最终结果以 state 和链上确认状态为准。

| 字段 | 类型 | 必定出现 | 说明 | 约束 |
| --- | --- | --- | --- | --- |
| genesis | string | 是 | 当前网络的创世区块哈希，64 位小写十六进制。 | 格式："^[0-9a-f]{64}$" |
| asset_id | string | 是 | 资产的链上 ID，64 位小写十六进制；只在对应网络有效。 | 格式："^[0-9a-f]{64}$" |
| metadata | AssetDocumentMetadata | 是 | 资产描述文档中的展示名称、简介、图标和链接。 |  |
| metadata.protocol | string | 是 | 链上资产展示资料的协议名称。 | 固定值："tc-asset-meta" |
| metadata.version | integer | 是 | 该对象协议格式版本。 | 固定值：1 |
| metadata.display_name | string | 是 | 元数据中的资产展示名称。 |  |
| metadata.summary | string | 是 | 资产元数据中的公开简介。 |  |
| metadata.links | object | 是 | 可选社交与资料链接对象，支持 website、x、telegram、discord、docs、github、whitepaper。 |  |
| metadata.icon | object | 否 | 头像元数据，uri 为写入链上的地址。 |  |
| metadata.icon.uri | string | 是 | 写入链上资料的图片地址；平台上传返回 ipfs://CID。 |  |
| metadata.issuance | SponsoredIssuance | 否 | 子资产发行标准与 Parent 身份；不是当前实时发行开关。 |  |
| metadata.issuance.mode | string | 是 | 旧版发行草稿中的子资产模式，固定 sponsored；新 /issuances 请求使用 mode: trc20。 | 固定值："sponsored" |
| metadata.issuance.protocol | string | 是 | 子资产发行命名标准标识，当前为 TRC20。 | 格式："^[A-Z][A-Z0-9]{2,10}$" |
| metadata.issuance.version | integer | 是 | 该对象协议格式版本。 | 固定值：1 |
| metadata.issuance.namespace | string | 是 | 子资产链上名称前缀，当前为 TRC20。 | 格式："^[A-Z][A-Z0-9]{2,10}$" |
| metadata.issuance.parent_asset_id | string | 是 | 平台 Parent 的链上 Asset ID。 | 格式："^[0-9a-f]{64}$" |
| metadata.symbol | string | 否 | 资产展示符号；发行时填 3–11 位大写字母数字，首位字母，不加 TRC20. 前缀。 |  |
| metadata.chain_symbol | string | 否 | 完整链上符号；子资产包含命名空间前缀。 |  |
| document | string | 是 | 写入注册交易的完整资产描述文档。 |  |
| source | string | 是 | 数据来源标识。 | 固定值："issuer_document" |
| immutable | boolean | 是 | 资产资料在当前发行流程中是否不可修改。 |  |
| commit_verified | boolean | 是 | 资产描述是否已与注册交易的链上承诺核对。 |  |
| registration | CreationTxState | 是 | 新池登记资料或资产注册交易；结构由所在接口定义。 |  |
| registration.txid | string | 是 | 链上交易 ID，64 位小写十六进制；不同于 quote_id 或 request_id。 | 格式："^[0-9a-f]{64}$" |
| registration.state | string | 是 | pending 已提交未确认；confirmed 已确认；not_seen 当前节点未观察到交易。 | 可选值：["pending", "confirmed", "not_seen"] |
| registration.confirmations | integer | 是 | 当前有效链上的确认次数；重组后可能减少。 | 最小值：0 |
| chain_symbol | string | 否 | 完整链上符号；子资产包含命名空间前缀。 |  |
| issuance | SponsoredIssuance / null | 否 | 子资产的协议、命名空间和 Parent 配置；独立资产不需要。 |  |
| issuance.mode | string | 是 | 旧版发行草稿中的子资产模式，固定 sponsored；新 /issuances 请求使用 mode: trc20。 | 固定值："sponsored" |
| issuance.protocol | string | 是 | 子资产发行命名标准标识，当前为 TRC20。 | 格式："^[A-Z][A-Z0-9]{2,10}$" |
| issuance.version | integer | 是 | 该对象协议格式版本。 | 固定值：1 |
| issuance.namespace | string | 是 | 子资产链上名称前缀，当前为 TRC20。 | 格式："^[A-Z][A-Z0-9]{2,10}$" |
| issuance.parent_asset_id | string | 是 | 平台 Parent 的链上 Asset ID。 | 格式："^[0-9a-f]{64}$" |

错误响应：

| HTTP 状态 | 含义 |
| --- | --- |
| 400 | 请求参数、资产策略或签名无效。 |
| 404 | 未找到资产、池子或操作记录。 |
| 409 | 审核过期、交易内容改变、价格不满足限制或分页游标失效。 |
| 413 | 请求体超过允许字节数。 |
| 415 | 请求 Content-Type 不受支持。 |
| 422 | JSON 字段格式无效或包含未知字段。 |
| 429 | 请求频率或容量达到上限，按 Retry-After 秒数退避。 |
| 503 | 节点、签名服务、索引或上游暂不可用，按 Retry-After 秒数退避。 |

### POST /issuances

提交资产发行资料。一次提交资产资料；API 分配 Asset ID，处理可选图片并返回注册阶段的签名请求。不签名、不广播。request_id 是幂等键：相同 ID 和相同资料恢复原记录，资料不同返回 REQUEST_ID_CONFLICT。root 保证金 5 TSC，trc20 保证金 0.0001 TSC，载体与矿工费另计。注册和初始铸币是两笔依赖交易。

请求体：

| 字段 | 类型 | 必填 | 说明 | 约束 |
| --- | --- | --- | --- | --- |
| request_id | string | 是 | 本次发行的小写 UUIDv4；新发行生成一次并保存，重试复用原 ID 和原资料，后续路径 id 使用此值。 | 格式："^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$" |
| chain_id | string | 是 | 目标网络标识，公共网络格式为 tsc:<genesis>:public。 | 格式："^tsc:[0-9a-f]{64}:(public\|[0-9a-f]{64})$" |
| actor | string | 是 | 操作账户在当前网络的 P2WPKH 地址；仅提供地址不会授权花费。 | 最短字符数：1；最长字符数：90 |
| mode | string | 是 | 发行模式；root 为独立资产，trc20 为平台子资产。 | 可选值：["root", "trc20"] |
| name | string | 是 | 资产展示名称，1–80 个字符。 | 最短字符数：1；最长字符数：80 |
| symbol | string | 是 | 资产展示符号；发行时填 3–11 位大写字母数字，首位字母，不加 TRC20. 前缀。 | 格式："^[A-Z][A-Z0-9]{2,10}$" |
| description | string | 是 | 公开资产简介，1–2000 个字符。 | 最短字符数：1；最长字符数：2000 |
| decimals | integer | 是 | 资产精度，0–18；最小单位数量 = supply × 10^decimals。 | 最小值：0；最大值：18 |
| supply | string | 是 | 首次发行数量，按资产单位填写的十进制字符串；乘 10^decimals 后须为 uint64 范围内整数，不是实时流通量。 | 格式："^[0-9]+(?:\\.[0-9]+)?$" |
| links | object | 否 | 可选社交与资料链接对象，支持 website、x、telegram、discord、docs、github、whitepaper。 | 不接受未知字段 |
| links.website | string | 否 | 项目官网 HTTPS 地址。 |  |
| links.x | string | 否 | 项目 X 主页 HTTPS 地址。 |  |
| links.telegram | string | 否 | Telegram 社区 HTTPS 地址。 |  |
| links.discord | string | 否 | Discord 社区 HTTPS 地址。 |  |
| links.docs | string | 否 | 项目文档 HTTPS 地址。 |  |
| links.github | string | 否 | 项目代码仓库 HTTPS 地址。 |  |
| links.whitepaper | string | 否 | 项目白皮书 HTTPS 地址。 |  |
| icon_url | string / null | 否 | HTTPS 或 ipfs://CID 图片地址；原样写入元数据，不由服务器下载；与 icon_base64 互斥。 | 最短字符数：1；最长字符数：2048 |
| icon_base64 | string / null | 否 | PNG/JPEG/WebP 原始字节的标准 Base64，不带 data: 前缀；最多 51200 字节和 2048×2048 像素，与 icon_url 互斥。 | 最长字符数：68268 |

请求示例：

```json
{
  "request_id": "7c51d5ae-cb7d-4a26-891b-77193590d7ba",
  "chain_id": "tsc:2929292929292929292929292929292929292929292929292929292929292929:public",
  "actor": "<issuer-address>",
  "mode": "root",
  "name": "Example Asset",
  "symbol": "EXAMPLE",
  "description": "An example native asset.",
  "decimals": 8,
  "supply": "1000000",
  "icon_url": "https://example.org/icon.webp"
}
```

请求示例：

```json
{
  "request_id": "7c51d5ae-cb7d-4a26-891b-77193590d7ba",
  "chain_id": "tsc:2929292929292929292929292929292929292929292929292929292929292929:public",
  "actor": "<issuer-address>",
  "mode": "root",
  "name": "Example Asset",
  "symbol": "EXAMPLE",
  "description": "An example native asset.",
  "decimals": 8,
  "supply": "1000000",
  "icon_url": "ipfs://QmVeYLY5JCaUdS6vhuA2RANioHhw5ZYEU6eSUijut1d9am"
}
```

请求示例：

```json
{
  "request_id": "7c51d5ae-cb7d-4a26-891b-77193590d7ba",
  "chain_id": "tsc:2929292929292929292929292929292929292929292929292929292929292929:public",
  "actor": "<issuer-address>",
  "mode": "root",
  "name": "Example Asset",
  "symbol": "EXAMPLE",
  "description": "An example native asset.",
  "decimals": 8,
  "supply": "1000000",
  "icon_base64": "iVBORw0KGgoAAAANSUhEUgAAACAAAAAgCAIAAAD8GO2jAAAAKklEQVR4nGMw9v1PU8QwasGoBaMWjFowasGoBaMWjFowasGoBaMWDBULALw6/EwgT7fRAAAAAElFTkSuQmCC"
}
```

请求示例：

```json
{
  "request_id": "7c51d5ae-cb7d-4a26-891b-77193590d7ba",
  "chain_id": "tsc:2929292929292929292929292929292929292929292929292929292929292929:public",
  "actor": "<issuer-address>",
  "mode": "root",
  "name": "Example Asset",
  "symbol": "EXAMPLE",
  "description": "An example native asset.",
  "decimals": 8,
  "supply": "1000000"
}
```

请求示例：

```json
{
  "request_id": "7c51d5ae-cb7d-4a26-891b-77193590d7ba",
  "chain_id": "tsc:2929292929292929292929292929292929292929292929292929292929292929:public",
  "actor": "<issuer-address>",
  "mode": "trc20",
  "name": "Example Asset",
  "symbol": "EXAMPLE",
  "description": "An example native asset.",
  "decimals": 8,
  "supply": "1000000"
}
```

响应 200：返回以下 JSON 对象；交易的最终结果以 state 和链上确认状态为准。

| 字段 | 类型 | 必定出现 | 说明 | 约束 |
| --- | --- | --- | --- | --- |
| id | string | 是 | 与最初提交的 request_id 相同；后续 /issuances/{id} 路径使用此值，不使用 asset_id。 | 格式："^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$" |
| chain_id | string | 是 | 目标网络标识，公共网络格式为 tsc:<genesis>:public。 | 格式："^tsc:[0-9a-f]{64}:(public\|[0-9a-f]{64})$" |
| asset_id | string | 是 | 资产的链上 ID，64 位小写十六进制；只在对应网络有效。 | 格式："^[0-9a-f]{64}$" |
| asset | CreationDraft | 是 | API 为这次发行固定的完整资产资料，包含生成的 Asset ID。 |  |
| asset.asset_id | string | 是 | 资产的链上 ID，64 位小写十六进制；只在对应网络有效。 | 格式："^[0-9a-f]{64}$" |
| asset.name | string | 是 | 资产展示名称，1–80 个字符。 | 最短字符数：1；最长字符数：80 |
| asset.symbol | string | 是 | 资产展示符号；发行时填 3–11 位大写字母数字，首位字母，不加 TRC20. 前缀。 | 格式："^[A-Z][A-Z0-9]{2,10}$" |
| asset.description | string | 是 | 公开资产简介，1–2000 个字符。 | 最短字符数：1；最长字符数：2000 |
| asset.decimals | integer | 是 | 资产精度，0–18；最小单位数量 = supply × 10^decimals。 | 最小值：0；最大值：18 |
| asset.supply | string | 是 | 首次发行数量，按资产单位填写的十进制字符串；乘 10^decimals 后须为 uint64 范围内整数，不是实时流通量。 | 格式："^[0-9]+(?:\\.[0-9]+)?$" |
| asset.icon_url | string | 否 | HTTPS 或 ipfs://CID 图片地址；原样写入元数据，不由服务器下载；与 icon_base64 互斥。 |  |
| asset.links | object | 否 | 可选社交与资料链接对象，支持 website、x、telegram、discord、docs、github、whitepaper。 | 不接受未知字段 |
| asset.links.website | string | 否 | 项目官网 HTTPS 地址。 |  |
| asset.links.x | string | 否 | 项目 X 主页 HTTPS 地址。 |  |
| asset.links.telegram | string | 否 | Telegram 社区 HTTPS 地址。 |  |
| asset.links.discord | string | 否 | Discord 社区 HTTPS 地址。 |  |
| asset.links.docs | string | 否 | 项目文档 HTTPS 地址。 |  |
| asset.links.github | string | 否 | 项目代码仓库 HTTPS 地址。 |  |
| asset.links.whitepaper | string | 否 | 项目白皮书 HTTPS 地址。 |  |
| asset.issuance | SponsoredIssuance / null | 否 | 子资产的协议、命名空间和 Parent 配置；独立资产不需要。 |  |
| asset.issuance.mode | string | 是 | 旧版发行草稿中的子资产模式，固定 sponsored；新 /issuances 请求使用 mode: trc20。 | 固定值："sponsored" |
| asset.issuance.protocol | string | 是 | 子资产发行命名标准标识，当前为 TRC20。 | 格式："^[A-Z][A-Z0-9]{2,10}$" |
| asset.issuance.version | integer | 是 | 该对象协议格式版本。 | 固定值：1 |
| asset.issuance.namespace | string | 是 | 子资产链上名称前缀，当前为 TRC20。 | 格式："^[A-Z][A-Z0-9]{2,10}$" |
| asset.issuance.parent_asset_id | string | 是 | 平台 Parent 的链上 Asset ID。 | 格式："^[0-9a-f]{64}$" |
| state | string | 是 | awaiting_signature 等待当前阶段签名；awaiting_confirmation 交易已补齐或已广播、等待确认；complete 注册和初始发行均已确认。 | 可选值：["awaiting_signature", "awaiting_confirmation", "complete"] |
| step | string | 是 | 发行阶段：register 注册资产，mint 发行初始数量。 | 可选值：["register", "mint"] |
| status | CreationStatus / null | 是 | 链上注册与初始发行的确认状态；注册交易尚未提交时为 null。 |  |
| status.genesis | string | 是 | 当前网络的创世区块哈希，64 位小写十六进制。 | 格式："^[0-9a-f]{64}$" |
| status.asset_id | string | 是 | 资产的链上 ID，64 位小写十六进制；只在对应网络有效。 | 格式："^[0-9a-f]{64}$" |
| status.actor | string | 是 | 操作账户在当前网络的 P2WPKH 地址；仅提供地址不会授权花费。 |  |
| status.draft | CreationDraft | 是 | 本次发行固定的完整资产资料。 |  |
| status.draft.asset_id | string | 是 | 资产的链上 ID，64 位小写十六进制；只在对应网络有效。 | 格式："^[0-9a-f]{64}$" |
| status.draft.name | string | 是 | 资产展示名称，1–80 个字符。 | 最短字符数：1；最长字符数：80 |
| status.draft.symbol | string | 是 | 资产展示符号；发行时填 3–11 位大写字母数字，首位字母，不加 TRC20. 前缀。 | 格式："^[A-Z][A-Z0-9]{2,10}$" |
| status.draft.description | string | 是 | 公开资产简介，1–2000 个字符。 | 最短字符数：1；最长字符数：2000 |
| status.draft.decimals | integer | 是 | 资产精度，0–18；最小单位数量 = supply × 10^decimals。 | 最小值：0；最大值：18 |
| status.draft.supply | string | 是 | 首次发行数量，按资产单位填写的十进制字符串；乘 10^decimals 后须为 uint64 范围内整数，不是实时流通量。 | 格式："^[0-9]+(?:\\.[0-9]+)?$" |
| status.draft.icon_url | string | 否 | HTTPS 或 ipfs://CID 图片地址；原样写入元数据，不由服务器下载；与 icon_base64 互斥。 |  |
| status.draft.links | object | 否 | 可选社交与资料链接对象，支持 website、x、telegram、discord、docs、github、whitepaper。 | 不接受未知字段 |
| status.draft.links.website | string | 否 | 项目官网 HTTPS 地址。 |  |
| status.draft.links.x | string | 否 | 项目 X 主页 HTTPS 地址。 |  |
| status.draft.links.telegram | string | 否 | Telegram 社区 HTTPS 地址。 |  |
| status.draft.links.discord | string | 否 | Discord 社区 HTTPS 地址。 |  |
| status.draft.links.docs | string | 否 | 项目文档 HTTPS 地址。 |  |
| status.draft.links.github | string | 否 | 项目代码仓库 HTTPS 地址。 |  |
| status.draft.links.whitepaper | string | 否 | 项目白皮书 HTTPS 地址。 |  |
| status.draft.issuance | SponsoredIssuance / null | 否 | 子资产的协议、命名空间和 Parent 配置；独立资产不需要。 |  |
| status.draft.issuance.mode | string | 是 | 旧版发行草稿中的子资产模式，固定 sponsored；新 /issuances 请求使用 mode: trc20。 | 固定值："sponsored" |
| status.draft.issuance.protocol | string | 是 | 子资产发行命名标准标识，当前为 TRC20。 | 格式："^[A-Z][A-Z0-9]{2,10}$" |
| status.draft.issuance.version | integer | 是 | 该对象协议格式版本。 | 固定值：1 |
| status.draft.issuance.namespace | string | 是 | 子资产链上名称前缀，当前为 TRC20。 | 格式："^[A-Z][A-Z0-9]{2,10}$" |
| status.draft.issuance.parent_asset_id | string | 是 | 平台 Parent 的链上 Asset ID。 | 格式："^[0-9a-f]{64}$" |
| status.document | string | 是 | 写入注册交易的完整资产描述文档。 |  |
| status.metadata | AssetDocumentMetadata | 是 | 资产描述文档中的展示名称、简介、图标和链接。 |  |
| status.metadata.protocol | string | 是 | 链上资产展示资料的协议名称。 | 固定值："tc-asset-meta" |
| status.metadata.version | integer | 是 | 该对象协议格式版本。 | 固定值：1 |
| status.metadata.display_name | string | 是 | 元数据中的资产展示名称。 |  |
| status.metadata.summary | string | 是 | 资产元数据中的公开简介。 |  |
| status.metadata.links | object | 是 | 可选社交与资料链接对象，支持 website、x、telegram、discord、docs、github、whitepaper。 |  |
| status.metadata.icon | object | 否 | 头像元数据，uri 为写入链上的地址。 |  |
| status.metadata.icon.uri | string | 是 | 写入链上资料的图片地址；平台上传返回 ipfs://CID。 |  |
| status.metadata.issuance | SponsoredIssuance | 否 | 子资产发行标准与 Parent 身份；不是当前实时发行开关。 |  |
| status.metadata.issuance.mode | string | 是 | 旧版发行草稿中的子资产模式，固定 sponsored；新 /issuances 请求使用 mode: trc20。 | 固定值："sponsored" |
| status.metadata.issuance.protocol | string | 是 | 子资产发行命名标准标识，当前为 TRC20。 | 格式："^[A-Z][A-Z0-9]{2,10}$" |
| status.metadata.issuance.version | integer | 是 | 该对象协议格式版本。 | 固定值：1 |
| status.metadata.issuance.namespace | string | 是 | 子资产链上名称前缀，当前为 TRC20。 | 格式："^[A-Z][A-Z0-9]{2,10}$" |
| status.metadata.issuance.parent_asset_id | string | 是 | 平台 Parent 的链上 Asset ID。 | 格式："^[0-9a-f]{64}$" |
| status.metadata.symbol | string | 否 | 资产展示符号；发行时填 3–11 位大写字母数字，首位字母，不加 TRC20. 前缀。 |  |
| status.metadata.chain_symbol | string | 否 | 完整链上符号；子资产包含命名空间前缀。 |  |
| status.register | CreationTxState | 是 | 注册交易及其当前确认状态。 |  |
| status.register.txid | string | 是 | 链上交易 ID，64 位小写十六进制；不同于 quote_id 或 request_id。 | 格式："^[0-9a-f]{64}$" |
| status.register.state | string | 是 | pending 已提交未确认；confirmed 已确认；not_seen 当前节点未观察到交易。 | 可选值：["pending", "confirmed", "not_seen"] |
| status.register.confirmations | integer | 是 | 当前有效链上的确认次数；重组后可能减少。 | 最小值：0 |
| status.mint | CreationTxState / null | 是 | 首次铸币交易及确认状态；尚未提交时为 null。 |  |
| status.mint.txid | string | 是 | 链上交易 ID，64 位小写十六进制；不同于 quote_id 或 request_id。 | 格式："^[0-9a-f]{64}$" |
| status.mint.state | string | 是 | pending 已提交未确认；confirmed 已确认；not_seen 当前节点未观察到交易。 | 可选值：["pending", "confirmed", "not_seen"] |
| status.mint.confirmations | integer | 是 | 当前有效链上的确认次数；重组后可能减少。 | 最小值：0 |
| status.state | string | 是 | pending 注册待确认；ready_to_mint 注册已确认、可准备首次铸币；complete 注册和首次铸币均确认。 | 可选值：["pending", "ready_to_mint", "complete"] |
| status.immutable | boolean | 是 | 资产资料在当前发行流程中是否不可修改。 |  |
| status.metadata_source | string | 是 | 元数据来源。 |  |
| status.commit_verified | boolean | 是 | 资产描述是否已与注册交易的链上承诺核对。 |  |
| status.chain_symbol | string | 否 | 完整链上符号；子资产包含命名空间前缀。 |  |
| wallet_request | TwpSigningRequest / null | 是 | 完整的钱包签名请求对象；仅在 awaiting_signature 且未过期时使用；为 null 时调用 next 获取当前阶段请求。 |  |
| wallet_request.method | string | 是 | 交给钱包执行的协议方法名。 | 固定值："tsc_signTransaction" |
| wallet_request.params | object | 是 | 钱包方法的完整参数对象。 | 不接受未知字段 |
| wallet_request.params.apiVersion | string | 是 | 钱包请求 API 版本。 | 固定值："1.0" |
| wallet_request.params.requestId | string | 是 | 钱包审批请求的小写 UUIDv4；不等于发行资源 request_id。 | 格式："^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$" |
| wallet_request.params.expiresAt | integer | 是 | 钱包签名请求到期时间，UTC Unix 秒；到期请求不得签名。 | 最小值：0 |
| wallet_request.params.package | TwpTransactionPackage | 是 | 完整的钱包交易签名包。 |  |
| wallet_request.params.package.chainId | string | 是 | 钱包交易包的目标网络标识；必须与签名和广播网络一致。 | 格式："^tsc:[0-9a-f]{64}:(public\|[0-9a-f]{64})$" |
| wallet_request.params.package.transaction | TwpRawTransaction | 是 | 原始交易格式与字节，是否完整签名由本接口阶段决定。 |  |
| wallet_request.params.package.transaction.format | string | 是 | 原始交易的序列化格式。 | 固定值："tensorcash-raw-v1" |
| wallet_request.params.package.transaction.hex | string | 是 | 原始 TensorCash 交易的十六进制字节；不是 PSBT 或 EVM 交易。 | 格式："^(?:[0-9a-f]{2})*$" |
| wallet_request.params.package.previousTransactions | object | 是 | txid 到完整前序交易原始字节的映射；须独立重算 txid 和输入金额。 |  |
| wallet_request.params.package.signingInputs | TwpSigningInput[] | 是 | 本次只允许钱包签名的输入列表。 |  |
| wallet_request.params.package.signingInputs[].inputIndex | integer | 是 | 本次请求钱包签名的输入位置，从 0 开始。 | 最小值：0 |
| wallet_request.params.package.signingInputs[].accountId | string | 是 | 签名账户标识，script: 后接账户脚本的 SHA-256；须与实际签名账户一致。 | 格式："^script:[0-9a-f]{64}$" |
| wallet_request.params.package.signingInputs[].profile | string | 是 | 钱包输入使用的签名规则标识。 | 固定值："twp:tx:p2wpkh-all:1" |
| wallet_request.params.package.signingInputs[].sighash | string | 是 | 签名覆盖范围；ALL 绑定整笔交易的输入输出。 | 固定值："ALL" |
| wallet_request.params.package.signingInputs[].spend | object | 是 | 签名输入的支出脚本类型及相关资料。 | 不接受未知字段 |
| wallet_request.params.package.signingInputs[].spend.type | string | 是 | 当前脚本支出类型。 | 固定值："p2wpkh" |
| wallet_request.params.package.signingInputs[].spend.data | object | 是 | 签名输入的脚本参数；P2WPKH 输入使用空对象。 | 不接受未知字段 |
| wallet_request.params.package.constraints | object | 是 | 签名必须遵守的费用上限及精确输出限制。 | 不接受未知字段 |
| wallet_request.params.package.constraints.maxFeeUnits | string | 是 | 允许的最大矿工费，TSC 最小单位整数字符串。 | 格式："^[0-9]+$" |
| wallet_request.params.package.constraints.exactOutputs | TwpOutput[] | 是 | 签名后必须保持不变的交易输出，顺序也必须一致。 |  |
| wallet_request.params.package.constraints.exactOutputs[].nativeUnits | string | 是 | 此输出的 TSC 金额，最小单位整数字符串。 | 格式："^[0-9]+$" |
| wallet_request.params.package.constraints.exactOutputs[].scriptPubKey | string | 是 | 输出锁定脚本，十六进制字符串。 | 格式："^(?:[0-9a-f]{2})*$" |
| wallet_request.params.package.constraints.exactOutputs[].outputExtension | string | 是 | 输出的 TensorCash 资产扩展字节，十六进制字符串。 | 格式："^(?:[0-9a-f]{2})*$" |
| wallet_request.params.package.validationMode | string | 是 | 钱包签名前的校验模式；online 表示须核对当前链状态。 | 固定值："online" |
| wallet_request.params.package.requiredFeatures | string[] | 是 | 钱包必须支持的链能力；缺失时不能降低校验要求继续签名。 |  |
| wallet_request.params.package.extensions | object[] | 是 | 交易包扩展；当前发行请求为空数组。 | 最多元素：0 |
| wallet_request.params.package.presentation | object | 是 | 钱包展示的标题与操作说明，不代替交易字节校验。 | 不接受未知字段 |
| wallet_request.params.package.presentation.title | string | 是 | 钱包审批显示的操作标题。 |  |
| wallet_request.params.package.presentation.description | string | 是 | 钱包展示的操作说明，不代替原始交易校验。 |  |
| review_id | string / null | 是 | 当前阶段交易的审核 ID；没有待审核交易时为 null。 | 格式："^[0-9a-f]{64}$" |
| template_id | string / null | 是 | 当前交易模板摘要；没有待审核交易时为 null。 | 格式："^[0-9a-f]{64}$" |
| protocol | object | 是 | 此发行接口返回的钱包签名包协议身份。 |  |
| protocol.name | string | 是 | 资产展示名称，1–80 个字符。 | 固定值："TWP" |
| protocol.draft_revision | string | 是 | 钱包协议草案版本；不同版本不能视为自动兼容。 | 固定值："0.2" |
| protocol.api_version | string | 是 | 接口版本。 | 固定值："1.0" |
| protocol.spec_hash | string | 是 | 精确钱包协议文档摘要，不能仅按版本号判断兼容。 | 格式："^[0-9a-f]{64}$" |
| steps | object[] | 是 | 发行阶段及其前置确认条件。 |  |
| steps[].step | string | 是 | 发行阶段：register 注册资产，mint 发行初始数量。 | 可选值：["register", "mint"] |
| steps[].depends_on | string / null | 是 | 本阶段的前置条件；mint 依赖 register_confirmed。 | 固定值："register_confirmed" |

错误响应：

| HTTP 状态 | 含义 |
| --- | --- |
| 400 | 请求参数、资产策略或签名无效。 |
| 404 | 未找到资产、池子或操作记录。 |
| 409 | 审核过期、交易内容改变、价格不满足限制或分页游标失效。 |
| 413 | 请求体超过允许字节数。 |
| 415 | 请求 Content-Type 不受支持。 |
| 422 | JSON 字段格式无效或包含未知字段。 |
| 429 | 请求频率或容量达到上限，按 Retry-After 秒数退避。 |
| 503 | 节点、签名服务、索引或上游暂不可用，按 Retry-After 秒数退避。 |

### GET /issuances/{id}

查询发行进度。路径 id 为原 request_id，不是 Asset ID。只读查询，不构造、不签名、不广播；awaiting_confirmation 包含已补齐但尚未广播的交易。complete 表示两阶段均已确认。

参数：

| 字段 | 位置 | 类型 | 必填 | 说明与约束 |
| --- | --- | --- | --- | --- |
| id | path | string | 是 | 原始发行 request_id，小写 UUIDv4。 格式："^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$" |

响应 200：返回以下 JSON 对象；交易的最终结果以 state 和链上确认状态为准。

| 字段 | 类型 | 必定出现 | 说明 | 约束 |
| --- | --- | --- | --- | --- |
| id | string | 是 | 与最初提交的 request_id 相同；后续 /issuances/{id} 路径使用此值，不使用 asset_id。 | 格式："^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$" |
| chain_id | string | 是 | 目标网络标识，公共网络格式为 tsc:<genesis>:public。 | 格式："^tsc:[0-9a-f]{64}:(public\|[0-9a-f]{64})$" |
| asset_id | string | 是 | 资产的链上 ID，64 位小写十六进制；只在对应网络有效。 | 格式："^[0-9a-f]{64}$" |
| asset | CreationDraft | 是 | API 为这次发行固定的完整资产资料，包含生成的 Asset ID。 |  |
| asset.asset_id | string | 是 | 资产的链上 ID，64 位小写十六进制；只在对应网络有效。 | 格式："^[0-9a-f]{64}$" |
| asset.name | string | 是 | 资产展示名称，1–80 个字符。 | 最短字符数：1；最长字符数：80 |
| asset.symbol | string | 是 | 资产展示符号；发行时填 3–11 位大写字母数字，首位字母，不加 TRC20. 前缀。 | 格式："^[A-Z][A-Z0-9]{2,10}$" |
| asset.description | string | 是 | 公开资产简介，1–2000 个字符。 | 最短字符数：1；最长字符数：2000 |
| asset.decimals | integer | 是 | 资产精度，0–18；最小单位数量 = supply × 10^decimals。 | 最小值：0；最大值：18 |
| asset.supply | string | 是 | 首次发行数量，按资产单位填写的十进制字符串；乘 10^decimals 后须为 uint64 范围内整数，不是实时流通量。 | 格式："^[0-9]+(?:\\.[0-9]+)?$" |
| asset.icon_url | string | 否 | HTTPS 或 ipfs://CID 图片地址；原样写入元数据，不由服务器下载；与 icon_base64 互斥。 |  |
| asset.links | object | 否 | 可选社交与资料链接对象，支持 website、x、telegram、discord、docs、github、whitepaper。 | 不接受未知字段 |
| asset.links.website | string | 否 | 项目官网 HTTPS 地址。 |  |
| asset.links.x | string | 否 | 项目 X 主页 HTTPS 地址。 |  |
| asset.links.telegram | string | 否 | Telegram 社区 HTTPS 地址。 |  |
| asset.links.discord | string | 否 | Discord 社区 HTTPS 地址。 |  |
| asset.links.docs | string | 否 | 项目文档 HTTPS 地址。 |  |
| asset.links.github | string | 否 | 项目代码仓库 HTTPS 地址。 |  |
| asset.links.whitepaper | string | 否 | 项目白皮书 HTTPS 地址。 |  |
| asset.issuance | SponsoredIssuance / null | 否 | 子资产的协议、命名空间和 Parent 配置；独立资产不需要。 |  |
| asset.issuance.mode | string | 是 | 旧版发行草稿中的子资产模式，固定 sponsored；新 /issuances 请求使用 mode: trc20。 | 固定值："sponsored" |
| asset.issuance.protocol | string | 是 | 子资产发行命名标准标识，当前为 TRC20。 | 格式："^[A-Z][A-Z0-9]{2,10}$" |
| asset.issuance.version | integer | 是 | 该对象协议格式版本。 | 固定值：1 |
| asset.issuance.namespace | string | 是 | 子资产链上名称前缀，当前为 TRC20。 | 格式："^[A-Z][A-Z0-9]{2,10}$" |
| asset.issuance.parent_asset_id | string | 是 | 平台 Parent 的链上 Asset ID。 | 格式："^[0-9a-f]{64}$" |
| state | string | 是 | awaiting_signature 等待当前阶段签名；awaiting_confirmation 交易已补齐或已广播、等待确认；complete 注册和初始发行均已确认。 | 可选值：["awaiting_signature", "awaiting_confirmation", "complete"] |
| step | string | 是 | 发行阶段：register 注册资产，mint 发行初始数量。 | 可选值：["register", "mint"] |
| status | CreationStatus / null | 是 | 链上注册与初始发行的确认状态；注册交易尚未提交时为 null。 |  |
| status.genesis | string | 是 | 当前网络的创世区块哈希，64 位小写十六进制。 | 格式："^[0-9a-f]{64}$" |
| status.asset_id | string | 是 | 资产的链上 ID，64 位小写十六进制；只在对应网络有效。 | 格式："^[0-9a-f]{64}$" |
| status.actor | string | 是 | 操作账户在当前网络的 P2WPKH 地址；仅提供地址不会授权花费。 |  |
| status.draft | CreationDraft | 是 | 本次发行固定的完整资产资料。 |  |
| status.draft.asset_id | string | 是 | 资产的链上 ID，64 位小写十六进制；只在对应网络有效。 | 格式："^[0-9a-f]{64}$" |
| status.draft.name | string | 是 | 资产展示名称，1–80 个字符。 | 最短字符数：1；最长字符数：80 |
| status.draft.symbol | string | 是 | 资产展示符号；发行时填 3–11 位大写字母数字，首位字母，不加 TRC20. 前缀。 | 格式："^[A-Z][A-Z0-9]{2,10}$" |
| status.draft.description | string | 是 | 公开资产简介，1–2000 个字符。 | 最短字符数：1；最长字符数：2000 |
| status.draft.decimals | integer | 是 | 资产精度，0–18；最小单位数量 = supply × 10^decimals。 | 最小值：0；最大值：18 |
| status.draft.supply | string | 是 | 首次发行数量，按资产单位填写的十进制字符串；乘 10^decimals 后须为 uint64 范围内整数，不是实时流通量。 | 格式："^[0-9]+(?:\\.[0-9]+)?$" |
| status.draft.icon_url | string | 否 | HTTPS 或 ipfs://CID 图片地址；原样写入元数据，不由服务器下载；与 icon_base64 互斥。 |  |
| status.draft.links | object | 否 | 可选社交与资料链接对象，支持 website、x、telegram、discord、docs、github、whitepaper。 | 不接受未知字段 |
| status.draft.links.website | string | 否 | 项目官网 HTTPS 地址。 |  |
| status.draft.links.x | string | 否 | 项目 X 主页 HTTPS 地址。 |  |
| status.draft.links.telegram | string | 否 | Telegram 社区 HTTPS 地址。 |  |
| status.draft.links.discord | string | 否 | Discord 社区 HTTPS 地址。 |  |
| status.draft.links.docs | string | 否 | 项目文档 HTTPS 地址。 |  |
| status.draft.links.github | string | 否 | 项目代码仓库 HTTPS 地址。 |  |
| status.draft.links.whitepaper | string | 否 | 项目白皮书 HTTPS 地址。 |  |
| status.draft.issuance | SponsoredIssuance / null | 否 | 子资产的协议、命名空间和 Parent 配置；独立资产不需要。 |  |
| status.draft.issuance.mode | string | 是 | 旧版发行草稿中的子资产模式，固定 sponsored；新 /issuances 请求使用 mode: trc20。 | 固定值："sponsored" |
| status.draft.issuance.protocol | string | 是 | 子资产发行命名标准标识，当前为 TRC20。 | 格式："^[A-Z][A-Z0-9]{2,10}$" |
| status.draft.issuance.version | integer | 是 | 该对象协议格式版本。 | 固定值：1 |
| status.draft.issuance.namespace | string | 是 | 子资产链上名称前缀，当前为 TRC20。 | 格式："^[A-Z][A-Z0-9]{2,10}$" |
| status.draft.issuance.parent_asset_id | string | 是 | 平台 Parent 的链上 Asset ID。 | 格式："^[0-9a-f]{64}$" |
| status.document | string | 是 | 写入注册交易的完整资产描述文档。 |  |
| status.metadata | AssetDocumentMetadata | 是 | 资产描述文档中的展示名称、简介、图标和链接。 |  |
| status.metadata.protocol | string | 是 | 链上资产展示资料的协议名称。 | 固定值："tc-asset-meta" |
| status.metadata.version | integer | 是 | 该对象协议格式版本。 | 固定值：1 |
| status.metadata.display_name | string | 是 | 元数据中的资产展示名称。 |  |
| status.metadata.summary | string | 是 | 资产元数据中的公开简介。 |  |
| status.metadata.links | object | 是 | 可选社交与资料链接对象，支持 website、x、telegram、discord、docs、github、whitepaper。 |  |
| status.metadata.icon | object | 否 | 头像元数据，uri 为写入链上的地址。 |  |
| status.metadata.icon.uri | string | 是 | 写入链上资料的图片地址；平台上传返回 ipfs://CID。 |  |
| status.metadata.issuance | SponsoredIssuance | 否 | 子资产发行标准与 Parent 身份；不是当前实时发行开关。 |  |
| status.metadata.issuance.mode | string | 是 | 旧版发行草稿中的子资产模式，固定 sponsored；新 /issuances 请求使用 mode: trc20。 | 固定值："sponsored" |
| status.metadata.issuance.protocol | string | 是 | 子资产发行命名标准标识，当前为 TRC20。 | 格式："^[A-Z][A-Z0-9]{2,10}$" |
| status.metadata.issuance.version | integer | 是 | 该对象协议格式版本。 | 固定值：1 |
| status.metadata.issuance.namespace | string | 是 | 子资产链上名称前缀，当前为 TRC20。 | 格式："^[A-Z][A-Z0-9]{2,10}$" |
| status.metadata.issuance.parent_asset_id | string | 是 | 平台 Parent 的链上 Asset ID。 | 格式："^[0-9a-f]{64}$" |
| status.metadata.symbol | string | 否 | 资产展示符号；发行时填 3–11 位大写字母数字，首位字母，不加 TRC20. 前缀。 |  |
| status.metadata.chain_symbol | string | 否 | 完整链上符号；子资产包含命名空间前缀。 |  |
| status.register | CreationTxState | 是 | 注册交易及其当前确认状态。 |  |
| status.register.txid | string | 是 | 链上交易 ID，64 位小写十六进制；不同于 quote_id 或 request_id。 | 格式："^[0-9a-f]{64}$" |
| status.register.state | string | 是 | pending 已提交未确认；confirmed 已确认；not_seen 当前节点未观察到交易。 | 可选值：["pending", "confirmed", "not_seen"] |
| status.register.confirmations | integer | 是 | 当前有效链上的确认次数；重组后可能减少。 | 最小值：0 |
| status.mint | CreationTxState / null | 是 | 首次铸币交易及确认状态；尚未提交时为 null。 |  |
| status.mint.txid | string | 是 | 链上交易 ID，64 位小写十六进制；不同于 quote_id 或 request_id。 | 格式："^[0-9a-f]{64}$" |
| status.mint.state | string | 是 | pending 已提交未确认；confirmed 已确认；not_seen 当前节点未观察到交易。 | 可选值：["pending", "confirmed", "not_seen"] |
| status.mint.confirmations | integer | 是 | 当前有效链上的确认次数；重组后可能减少。 | 最小值：0 |
| status.state | string | 是 | pending 注册待确认；ready_to_mint 注册已确认、可准备首次铸币；complete 注册和首次铸币均确认。 | 可选值：["pending", "ready_to_mint", "complete"] |
| status.immutable | boolean | 是 | 资产资料在当前发行流程中是否不可修改。 |  |
| status.metadata_source | string | 是 | 元数据来源。 |  |
| status.commit_verified | boolean | 是 | 资产描述是否已与注册交易的链上承诺核对。 |  |
| status.chain_symbol | string | 否 | 完整链上符号；子资产包含命名空间前缀。 |  |
| wallet_request | TwpSigningRequest / null | 是 | 完整的钱包签名请求对象；仅在 awaiting_signature 且未过期时使用；为 null 时调用 next 获取当前阶段请求。 |  |
| wallet_request.method | string | 是 | 交给钱包执行的协议方法名。 | 固定值："tsc_signTransaction" |
| wallet_request.params | object | 是 | 钱包方法的完整参数对象。 | 不接受未知字段 |
| wallet_request.params.apiVersion | string | 是 | 钱包请求 API 版本。 | 固定值："1.0" |
| wallet_request.params.requestId | string | 是 | 钱包审批请求的小写 UUIDv4；不等于发行资源 request_id。 | 格式："^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$" |
| wallet_request.params.expiresAt | integer | 是 | 钱包签名请求到期时间，UTC Unix 秒；到期请求不得签名。 | 最小值：0 |
| wallet_request.params.package | TwpTransactionPackage | 是 | 完整的钱包交易签名包。 |  |
| wallet_request.params.package.chainId | string | 是 | 钱包交易包的目标网络标识；必须与签名和广播网络一致。 | 格式："^tsc:[0-9a-f]{64}:(public\|[0-9a-f]{64})$" |
| wallet_request.params.package.transaction | TwpRawTransaction | 是 | 原始交易格式与字节，是否完整签名由本接口阶段决定。 |  |
| wallet_request.params.package.transaction.format | string | 是 | 原始交易的序列化格式。 | 固定值："tensorcash-raw-v1" |
| wallet_request.params.package.transaction.hex | string | 是 | 原始 TensorCash 交易的十六进制字节；不是 PSBT 或 EVM 交易。 | 格式："^(?:[0-9a-f]{2})*$" |
| wallet_request.params.package.previousTransactions | object | 是 | txid 到完整前序交易原始字节的映射；须独立重算 txid 和输入金额。 |  |
| wallet_request.params.package.signingInputs | TwpSigningInput[] | 是 | 本次只允许钱包签名的输入列表。 |  |
| wallet_request.params.package.signingInputs[].inputIndex | integer | 是 | 本次请求钱包签名的输入位置，从 0 开始。 | 最小值：0 |
| wallet_request.params.package.signingInputs[].accountId | string | 是 | 签名账户标识，script: 后接账户脚本的 SHA-256；须与实际签名账户一致。 | 格式："^script:[0-9a-f]{64}$" |
| wallet_request.params.package.signingInputs[].profile | string | 是 | 钱包输入使用的签名规则标识。 | 固定值："twp:tx:p2wpkh-all:1" |
| wallet_request.params.package.signingInputs[].sighash | string | 是 | 签名覆盖范围；ALL 绑定整笔交易的输入输出。 | 固定值："ALL" |
| wallet_request.params.package.signingInputs[].spend | object | 是 | 签名输入的支出脚本类型及相关资料。 | 不接受未知字段 |
| wallet_request.params.package.signingInputs[].spend.type | string | 是 | 当前脚本支出类型。 | 固定值："p2wpkh" |
| wallet_request.params.package.signingInputs[].spend.data | object | 是 | 签名输入的脚本参数；P2WPKH 输入使用空对象。 | 不接受未知字段 |
| wallet_request.params.package.constraints | object | 是 | 签名必须遵守的费用上限及精确输出限制。 | 不接受未知字段 |
| wallet_request.params.package.constraints.maxFeeUnits | string | 是 | 允许的最大矿工费，TSC 最小单位整数字符串。 | 格式："^[0-9]+$" |
| wallet_request.params.package.constraints.exactOutputs | TwpOutput[] | 是 | 签名后必须保持不变的交易输出，顺序也必须一致。 |  |
| wallet_request.params.package.constraints.exactOutputs[].nativeUnits | string | 是 | 此输出的 TSC 金额，最小单位整数字符串。 | 格式："^[0-9]+$" |
| wallet_request.params.package.constraints.exactOutputs[].scriptPubKey | string | 是 | 输出锁定脚本，十六进制字符串。 | 格式："^(?:[0-9a-f]{2})*$" |
| wallet_request.params.package.constraints.exactOutputs[].outputExtension | string | 是 | 输出的 TensorCash 资产扩展字节，十六进制字符串。 | 格式："^(?:[0-9a-f]{2})*$" |
| wallet_request.params.package.validationMode | string | 是 | 钱包签名前的校验模式；online 表示须核对当前链状态。 | 固定值："online" |
| wallet_request.params.package.requiredFeatures | string[] | 是 | 钱包必须支持的链能力；缺失时不能降低校验要求继续签名。 |  |
| wallet_request.params.package.extensions | object[] | 是 | 交易包扩展；当前发行请求为空数组。 | 最多元素：0 |
| wallet_request.params.package.presentation | object | 是 | 钱包展示的标题与操作说明，不代替交易字节校验。 | 不接受未知字段 |
| wallet_request.params.package.presentation.title | string | 是 | 钱包审批显示的操作标题。 |  |
| wallet_request.params.package.presentation.description | string | 是 | 钱包展示的操作说明，不代替原始交易校验。 |  |
| review_id | string / null | 是 | 当前阶段交易的审核 ID；没有待审核交易时为 null。 | 格式："^[0-9a-f]{64}$" |
| template_id | string / null | 是 | 当前交易模板摘要；没有待审核交易时为 null。 | 格式："^[0-9a-f]{64}$" |
| protocol | object | 是 | 此发行接口返回的钱包签名包协议身份。 |  |
| protocol.name | string | 是 | 资产展示名称，1–80 个字符。 | 固定值："TWP" |
| protocol.draft_revision | string | 是 | 钱包协议草案版本；不同版本不能视为自动兼容。 | 固定值："0.2" |
| protocol.api_version | string | 是 | 接口版本。 | 固定值："1.0" |
| protocol.spec_hash | string | 是 | 精确钱包协议文档摘要，不能仅按版本号判断兼容。 | 格式："^[0-9a-f]{64}$" |
| steps | object[] | 是 | 发行阶段及其前置确认条件。 |  |
| steps[].step | string | 是 | 发行阶段：register 注册资产，mint 发行初始数量。 | 可选值：["register", "mint"] |
| steps[].depends_on | string / null | 是 | 本阶段的前置条件；mint 依赖 register_confirmed。 | 固定值："register_confirmed" |

错误响应：

| HTTP 状态 | 含义 |
| --- | --- |
| 400 | 请求参数、资产策略或签名无效。 |
| 404 | 未找到资产、池子或操作记录。 |
| 409 | 审核过期、交易内容改变、价格不满足限制或分页游标失效。 |
| 413 | 请求体超过允许字节数。 |
| 415 | 请求 Content-Type 不受支持。 |
| 422 | JSON 字段格式无效或包含未知字段。 |
| 429 | 请求频率或容量达到上限，按 Retry-After 秒数退避。 |
| 503 | 节点、签名服务、索引或上游暂不可用，按 Retry-After 秒数退避。 |

### POST /issuances/{id}/next

获取当前或下一阶段签名请求。正文 {} 复用现有有效审核，或在注册确认后准备首次铸币。无需重传资产资料。refresh=true 显式请求新的未签名审核；有结果不明确的已签交易时先核对原交易，不能自动替换。

参数：

| 字段 | 位置 | 类型 | 必填 | 说明与约束 |
| --- | --- | --- | --- | --- |
| id | path | string | 是 | 原始发行 request_id，小写 UUIDv4。 格式："^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$" |

请求体：

| 字段 | 类型 | 必填 | 说明 | 约束 |
| --- | --- | --- | --- | --- |
| refresh | boolean | 否 | 默认 false，复用有效审核。true 请求新的未签名审核；先确认没有结果不明确的已签名交易，再重新让用户批准。 | 默认值：false |

请求示例：

```json
{}
```

请求示例：

```json
{
  "refresh": true
}
```

响应 200：返回以下 JSON 对象；交易的最终结果以 state 和链上确认状态为准。

| 字段 | 类型 | 必定出现 | 说明 | 约束 |
| --- | --- | --- | --- | --- |
| id | string | 是 | 与最初提交的 request_id 相同；后续 /issuances/{id} 路径使用此值，不使用 asset_id。 | 格式："^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$" |
| chain_id | string | 是 | 目标网络标识，公共网络格式为 tsc:<genesis>:public。 | 格式："^tsc:[0-9a-f]{64}:(public\|[0-9a-f]{64})$" |
| asset_id | string | 是 | 资产的链上 ID，64 位小写十六进制；只在对应网络有效。 | 格式："^[0-9a-f]{64}$" |
| asset | CreationDraft | 是 | API 为这次发行固定的完整资产资料，包含生成的 Asset ID。 |  |
| asset.asset_id | string | 是 | 资产的链上 ID，64 位小写十六进制；只在对应网络有效。 | 格式："^[0-9a-f]{64}$" |
| asset.name | string | 是 | 资产展示名称，1–80 个字符。 | 最短字符数：1；最长字符数：80 |
| asset.symbol | string | 是 | 资产展示符号；发行时填 3–11 位大写字母数字，首位字母，不加 TRC20. 前缀。 | 格式："^[A-Z][A-Z0-9]{2,10}$" |
| asset.description | string | 是 | 公开资产简介，1–2000 个字符。 | 最短字符数：1；最长字符数：2000 |
| asset.decimals | integer | 是 | 资产精度，0–18；最小单位数量 = supply × 10^decimals。 | 最小值：0；最大值：18 |
| asset.supply | string | 是 | 首次发行数量，按资产单位填写的十进制字符串；乘 10^decimals 后须为 uint64 范围内整数，不是实时流通量。 | 格式："^[0-9]+(?:\\.[0-9]+)?$" |
| asset.icon_url | string | 否 | HTTPS 或 ipfs://CID 图片地址；原样写入元数据，不由服务器下载；与 icon_base64 互斥。 |  |
| asset.links | object | 否 | 可选社交与资料链接对象，支持 website、x、telegram、discord、docs、github、whitepaper。 | 不接受未知字段 |
| asset.links.website | string | 否 | 项目官网 HTTPS 地址。 |  |
| asset.links.x | string | 否 | 项目 X 主页 HTTPS 地址。 |  |
| asset.links.telegram | string | 否 | Telegram 社区 HTTPS 地址。 |  |
| asset.links.discord | string | 否 | Discord 社区 HTTPS 地址。 |  |
| asset.links.docs | string | 否 | 项目文档 HTTPS 地址。 |  |
| asset.links.github | string | 否 | 项目代码仓库 HTTPS 地址。 |  |
| asset.links.whitepaper | string | 否 | 项目白皮书 HTTPS 地址。 |  |
| asset.issuance | SponsoredIssuance / null | 否 | 子资产的协议、命名空间和 Parent 配置；独立资产不需要。 |  |
| asset.issuance.mode | string | 是 | 旧版发行草稿中的子资产模式，固定 sponsored；新 /issuances 请求使用 mode: trc20。 | 固定值："sponsored" |
| asset.issuance.protocol | string | 是 | 子资产发行命名标准标识，当前为 TRC20。 | 格式："^[A-Z][A-Z0-9]{2,10}$" |
| asset.issuance.version | integer | 是 | 该对象协议格式版本。 | 固定值：1 |
| asset.issuance.namespace | string | 是 | 子资产链上名称前缀，当前为 TRC20。 | 格式："^[A-Z][A-Z0-9]{2,10}$" |
| asset.issuance.parent_asset_id | string | 是 | 平台 Parent 的链上 Asset ID。 | 格式："^[0-9a-f]{64}$" |
| state | string | 是 | awaiting_signature 等待当前阶段签名；awaiting_confirmation 交易已补齐或已广播、等待确认；complete 注册和初始发行均已确认。 | 可选值：["awaiting_signature", "awaiting_confirmation", "complete"] |
| step | string | 是 | 发行阶段：register 注册资产，mint 发行初始数量。 | 可选值：["register", "mint"] |
| status | CreationStatus / null | 是 | 链上注册与初始发行的确认状态；注册交易尚未提交时为 null。 |  |
| status.genesis | string | 是 | 当前网络的创世区块哈希，64 位小写十六进制。 | 格式："^[0-9a-f]{64}$" |
| status.asset_id | string | 是 | 资产的链上 ID，64 位小写十六进制；只在对应网络有效。 | 格式："^[0-9a-f]{64}$" |
| status.actor | string | 是 | 操作账户在当前网络的 P2WPKH 地址；仅提供地址不会授权花费。 |  |
| status.draft | CreationDraft | 是 | 本次发行固定的完整资产资料。 |  |
| status.draft.asset_id | string | 是 | 资产的链上 ID，64 位小写十六进制；只在对应网络有效。 | 格式："^[0-9a-f]{64}$" |
| status.draft.name | string | 是 | 资产展示名称，1–80 个字符。 | 最短字符数：1；最长字符数：80 |
| status.draft.symbol | string | 是 | 资产展示符号；发行时填 3–11 位大写字母数字，首位字母，不加 TRC20. 前缀。 | 格式："^[A-Z][A-Z0-9]{2,10}$" |
| status.draft.description | string | 是 | 公开资产简介，1–2000 个字符。 | 最短字符数：1；最长字符数：2000 |
| status.draft.decimals | integer | 是 | 资产精度，0–18；最小单位数量 = supply × 10^decimals。 | 最小值：0；最大值：18 |
| status.draft.supply | string | 是 | 首次发行数量，按资产单位填写的十进制字符串；乘 10^decimals 后须为 uint64 范围内整数，不是实时流通量。 | 格式："^[0-9]+(?:\\.[0-9]+)?$" |
| status.draft.icon_url | string | 否 | HTTPS 或 ipfs://CID 图片地址；原样写入元数据，不由服务器下载；与 icon_base64 互斥。 |  |
| status.draft.links | object | 否 | 可选社交与资料链接对象，支持 website、x、telegram、discord、docs、github、whitepaper。 | 不接受未知字段 |
| status.draft.links.website | string | 否 | 项目官网 HTTPS 地址。 |  |
| status.draft.links.x | string | 否 | 项目 X 主页 HTTPS 地址。 |  |
| status.draft.links.telegram | string | 否 | Telegram 社区 HTTPS 地址。 |  |
| status.draft.links.discord | string | 否 | Discord 社区 HTTPS 地址。 |  |
| status.draft.links.docs | string | 否 | 项目文档 HTTPS 地址。 |  |
| status.draft.links.github | string | 否 | 项目代码仓库 HTTPS 地址。 |  |
| status.draft.links.whitepaper | string | 否 | 项目白皮书 HTTPS 地址。 |  |
| status.draft.issuance | SponsoredIssuance / null | 否 | 子资产的协议、命名空间和 Parent 配置；独立资产不需要。 |  |
| status.draft.issuance.mode | string | 是 | 旧版发行草稿中的子资产模式，固定 sponsored；新 /issuances 请求使用 mode: trc20。 | 固定值："sponsored" |
| status.draft.issuance.protocol | string | 是 | 子资产发行命名标准标识，当前为 TRC20。 | 格式："^[A-Z][A-Z0-9]{2,10}$" |
| status.draft.issuance.version | integer | 是 | 该对象协议格式版本。 | 固定值：1 |
| status.draft.issuance.namespace | string | 是 | 子资产链上名称前缀，当前为 TRC20。 | 格式："^[A-Z][A-Z0-9]{2,10}$" |
| status.draft.issuance.parent_asset_id | string | 是 | 平台 Parent 的链上 Asset ID。 | 格式："^[0-9a-f]{64}$" |
| status.document | string | 是 | 写入注册交易的完整资产描述文档。 |  |
| status.metadata | AssetDocumentMetadata | 是 | 资产描述文档中的展示名称、简介、图标和链接。 |  |
| status.metadata.protocol | string | 是 | 链上资产展示资料的协议名称。 | 固定值："tc-asset-meta" |
| status.metadata.version | integer | 是 | 该对象协议格式版本。 | 固定值：1 |
| status.metadata.display_name | string | 是 | 元数据中的资产展示名称。 |  |
| status.metadata.summary | string | 是 | 资产元数据中的公开简介。 |  |
| status.metadata.links | object | 是 | 可选社交与资料链接对象，支持 website、x、telegram、discord、docs、github、whitepaper。 |  |
| status.metadata.icon | object | 否 | 头像元数据，uri 为写入链上的地址。 |  |
| status.metadata.icon.uri | string | 是 | 写入链上资料的图片地址；平台上传返回 ipfs://CID。 |  |
| status.metadata.issuance | SponsoredIssuance | 否 | 子资产发行标准与 Parent 身份；不是当前实时发行开关。 |  |
| status.metadata.issuance.mode | string | 是 | 旧版发行草稿中的子资产模式，固定 sponsored；新 /issuances 请求使用 mode: trc20。 | 固定值："sponsored" |
| status.metadata.issuance.protocol | string | 是 | 子资产发行命名标准标识，当前为 TRC20。 | 格式："^[A-Z][A-Z0-9]{2,10}$" |
| status.metadata.issuance.version | integer | 是 | 该对象协议格式版本。 | 固定值：1 |
| status.metadata.issuance.namespace | string | 是 | 子资产链上名称前缀，当前为 TRC20。 | 格式："^[A-Z][A-Z0-9]{2,10}$" |
| status.metadata.issuance.parent_asset_id | string | 是 | 平台 Parent 的链上 Asset ID。 | 格式："^[0-9a-f]{64}$" |
| status.metadata.symbol | string | 否 | 资产展示符号；发行时填 3–11 位大写字母数字，首位字母，不加 TRC20. 前缀。 |  |
| status.metadata.chain_symbol | string | 否 | 完整链上符号；子资产包含命名空间前缀。 |  |
| status.register | CreationTxState | 是 | 注册交易及其当前确认状态。 |  |
| status.register.txid | string | 是 | 链上交易 ID，64 位小写十六进制；不同于 quote_id 或 request_id。 | 格式："^[0-9a-f]{64}$" |
| status.register.state | string | 是 | pending 已提交未确认；confirmed 已确认；not_seen 当前节点未观察到交易。 | 可选值：["pending", "confirmed", "not_seen"] |
| status.register.confirmations | integer | 是 | 当前有效链上的确认次数；重组后可能减少。 | 最小值：0 |
| status.mint | CreationTxState / null | 是 | 首次铸币交易及确认状态；尚未提交时为 null。 |  |
| status.mint.txid | string | 是 | 链上交易 ID，64 位小写十六进制；不同于 quote_id 或 request_id。 | 格式："^[0-9a-f]{64}$" |
| status.mint.state | string | 是 | pending 已提交未确认；confirmed 已确认；not_seen 当前节点未观察到交易。 | 可选值：["pending", "confirmed", "not_seen"] |
| status.mint.confirmations | integer | 是 | 当前有效链上的确认次数；重组后可能减少。 | 最小值：0 |
| status.state | string | 是 | pending 注册待确认；ready_to_mint 注册已确认、可准备首次铸币；complete 注册和首次铸币均确认。 | 可选值：["pending", "ready_to_mint", "complete"] |
| status.immutable | boolean | 是 | 资产资料在当前发行流程中是否不可修改。 |  |
| status.metadata_source | string | 是 | 元数据来源。 |  |
| status.commit_verified | boolean | 是 | 资产描述是否已与注册交易的链上承诺核对。 |  |
| status.chain_symbol | string | 否 | 完整链上符号；子资产包含命名空间前缀。 |  |
| wallet_request | TwpSigningRequest / null | 是 | 完整的钱包签名请求对象；仅在 awaiting_signature 且未过期时使用；为 null 时调用 next 获取当前阶段请求。 |  |
| wallet_request.method | string | 是 | 交给钱包执行的协议方法名。 | 固定值："tsc_signTransaction" |
| wallet_request.params | object | 是 | 钱包方法的完整参数对象。 | 不接受未知字段 |
| wallet_request.params.apiVersion | string | 是 | 钱包请求 API 版本。 | 固定值："1.0" |
| wallet_request.params.requestId | string | 是 | 钱包审批请求的小写 UUIDv4；不等于发行资源 request_id。 | 格式："^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$" |
| wallet_request.params.expiresAt | integer | 是 | 钱包签名请求到期时间，UTC Unix 秒；到期请求不得签名。 | 最小值：0 |
| wallet_request.params.package | TwpTransactionPackage | 是 | 完整的钱包交易签名包。 |  |
| wallet_request.params.package.chainId | string | 是 | 钱包交易包的目标网络标识；必须与签名和广播网络一致。 | 格式："^tsc:[0-9a-f]{64}:(public\|[0-9a-f]{64})$" |
| wallet_request.params.package.transaction | TwpRawTransaction | 是 | 原始交易格式与字节，是否完整签名由本接口阶段决定。 |  |
| wallet_request.params.package.transaction.format | string | 是 | 原始交易的序列化格式。 | 固定值："tensorcash-raw-v1" |
| wallet_request.params.package.transaction.hex | string | 是 | 原始 TensorCash 交易的十六进制字节；不是 PSBT 或 EVM 交易。 | 格式："^(?:[0-9a-f]{2})*$" |
| wallet_request.params.package.previousTransactions | object | 是 | txid 到完整前序交易原始字节的映射；须独立重算 txid 和输入金额。 |  |
| wallet_request.params.package.signingInputs | TwpSigningInput[] | 是 | 本次只允许钱包签名的输入列表。 |  |
| wallet_request.params.package.signingInputs[].inputIndex | integer | 是 | 本次请求钱包签名的输入位置，从 0 开始。 | 最小值：0 |
| wallet_request.params.package.signingInputs[].accountId | string | 是 | 签名账户标识，script: 后接账户脚本的 SHA-256；须与实际签名账户一致。 | 格式："^script:[0-9a-f]{64}$" |
| wallet_request.params.package.signingInputs[].profile | string | 是 | 钱包输入使用的签名规则标识。 | 固定值："twp:tx:p2wpkh-all:1" |
| wallet_request.params.package.signingInputs[].sighash | string | 是 | 签名覆盖范围；ALL 绑定整笔交易的输入输出。 | 固定值："ALL" |
| wallet_request.params.package.signingInputs[].spend | object | 是 | 签名输入的支出脚本类型及相关资料。 | 不接受未知字段 |
| wallet_request.params.package.signingInputs[].spend.type | string | 是 | 当前脚本支出类型。 | 固定值："p2wpkh" |
| wallet_request.params.package.signingInputs[].spend.data | object | 是 | 签名输入的脚本参数；P2WPKH 输入使用空对象。 | 不接受未知字段 |
| wallet_request.params.package.constraints | object | 是 | 签名必须遵守的费用上限及精确输出限制。 | 不接受未知字段 |
| wallet_request.params.package.constraints.maxFeeUnits | string | 是 | 允许的最大矿工费，TSC 最小单位整数字符串。 | 格式："^[0-9]+$" |
| wallet_request.params.package.constraints.exactOutputs | TwpOutput[] | 是 | 签名后必须保持不变的交易输出，顺序也必须一致。 |  |
| wallet_request.params.package.constraints.exactOutputs[].nativeUnits | string | 是 | 此输出的 TSC 金额，最小单位整数字符串。 | 格式："^[0-9]+$" |
| wallet_request.params.package.constraints.exactOutputs[].scriptPubKey | string | 是 | 输出锁定脚本，十六进制字符串。 | 格式："^(?:[0-9a-f]{2})*$" |
| wallet_request.params.package.constraints.exactOutputs[].outputExtension | string | 是 | 输出的 TensorCash 资产扩展字节，十六进制字符串。 | 格式："^(?:[0-9a-f]{2})*$" |
| wallet_request.params.package.validationMode | string | 是 | 钱包签名前的校验模式；online 表示须核对当前链状态。 | 固定值："online" |
| wallet_request.params.package.requiredFeatures | string[] | 是 | 钱包必须支持的链能力；缺失时不能降低校验要求继续签名。 |  |
| wallet_request.params.package.extensions | object[] | 是 | 交易包扩展；当前发行请求为空数组。 | 最多元素：0 |
| wallet_request.params.package.presentation | object | 是 | 钱包展示的标题与操作说明，不代替交易字节校验。 | 不接受未知字段 |
| wallet_request.params.package.presentation.title | string | 是 | 钱包审批显示的操作标题。 |  |
| wallet_request.params.package.presentation.description | string | 是 | 钱包展示的操作说明，不代替原始交易校验。 |  |
| review_id | string / null | 是 | 当前阶段交易的审核 ID；没有待审核交易时为 null。 | 格式："^[0-9a-f]{64}$" |
| template_id | string / null | 是 | 当前交易模板摘要；没有待审核交易时为 null。 | 格式："^[0-9a-f]{64}$" |
| protocol | object | 是 | 此发行接口返回的钱包签名包协议身份。 |  |
| protocol.name | string | 是 | 资产展示名称，1–80 个字符。 | 固定值："TWP" |
| protocol.draft_revision | string | 是 | 钱包协议草案版本；不同版本不能视为自动兼容。 | 固定值："0.2" |
| protocol.api_version | string | 是 | 接口版本。 | 固定值："1.0" |
| protocol.spec_hash | string | 是 | 精确钱包协议文档摘要，不能仅按版本号判断兼容。 | 格式："^[0-9a-f]{64}$" |
| steps | object[] | 是 | 发行阶段及其前置确认条件。 |  |
| steps[].step | string | 是 | 发行阶段：register 注册资产，mint 发行初始数量。 | 可选值：["register", "mint"] |
| steps[].depends_on | string / null | 是 | 本阶段的前置条件；mint 依赖 register_confirmed。 | 固定值："register_confirmed" |

错误响应：

| HTTP 状态 | 含义 |
| --- | --- |
| 400 | 请求参数、资产策略或签名无效。 |
| 404 | 未找到资产、池子或操作记录。 |
| 409 | 审核过期、交易内容改变、价格不满足限制或分页游标失效。 |
| 413 | 请求体超过允许字节数。 |
| 415 | 请求 Content-Type 不受支持。 |
| 422 | JSON 字段格式无效或包含未知字段。 |
| 429 | 请求频率或容量达到上限，按 Retry-After 秒数退避。 |
| 503 | 节点、签名服务、索引或上游暂不可用，按 Retry-After 秒数退避。 |

### POST /issuances/{id}/finalize

校验签名并返回完整交易。提交当前 review_id 和钱包签名结果 transaction。拒绝改动已审核的输入、输出和资产资料；TRC20 必要时补齐 Parent 签名。保存完整交易后返回 transaction 和 txid。不会广播，finalized 不表示链上确认。同一审核和原签名结果可安全重试。

参数：

| 字段 | 位置 | 类型 | 必填 | 说明与约束 |
| --- | --- | --- | --- | --- |
| id | path | string | 是 | 原始发行 request_id，小写 UUIDv4。 格式："^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$" |

请求体：

| 字段 | 类型 | 必填 | 说明 | 约束 |
| --- | --- | --- | --- | --- |
| review_id | string | 是 | 本次待签名交易的审核 ID；与阶段和确切交易绑定。 | 格式："^[0-9a-f]{64}$" |
| transaction | TwpRawTransaction | 是 | 钱包返回的已签名交易；必须保持原审核的输入、输出、金额和资产扩展。 |  |
| transaction.format | string | 是 | 原始交易的序列化格式。 | 固定值："tensorcash-raw-v1" |
| transaction.hex | string | 是 | 原始 TensorCash 交易的十六进制字节；不是 PSBT 或 EVM 交易。 | 格式："^(?:[0-9a-f]{2})*$" |

响应 200：返回以下 JSON 对象；交易的最终结果以 state 和链上确认状态为准。

| 字段 | 类型 | 必定出现 | 说明 | 约束 |
| --- | --- | --- | --- | --- |
| id | string | 是 | 原始 request_id；本次 finalize 仍属于同一次发行。 | 格式："^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$" |
| asset_id | string | 是 | 资产的链上 ID，64 位小写十六进制；只在对应网络有效。 | 格式："^[0-9a-f]{64}$" |
| chain_id | string | 是 | 目标网络标识，公共网络格式为 tsc:<genesis>:public。 | 格式："^tsc:[0-9a-f]{64}:(public\|[0-9a-f]{64})$" |
| step | string | 是 | 发行阶段：register 注册资产，mint 发行初始数量。 | 可选值：["register", "mint"] |
| txid | string | 是 | 链上交易 ID，64 位小写十六进制；不同于 quote_id 或 request_id。 | 格式："^[0-9a-f]{64}$" |
| transaction | TwpRawTransaction | 是 | 已经补齐全部必要签名、可广播的原始交易。该接口本身不会广播。 |  |
| transaction.format | string | 是 | 原始交易的序列化格式。 | 固定值："tensorcash-raw-v1" |
| transaction.hex | string | 是 | 原始 TensorCash 交易的十六进制字节；不是 PSBT 或 EVM 交易。 | 格式："^(?:[0-9a-f]{2})*$" |
| completion | string | 是 | 交易组装结果；finalized 只表示签名已补齐。 | 固定值："finalized" |
| broadcast | boolean | 是 | 本次接口是否广播了交易；false 时仍须由调用方广播。 | 固定值：false |

错误响应：

| HTTP 状态 | 含义 |
| --- | --- |
| 400 | 请求参数、资产策略或签名无效。 |
| 404 | 未找到资产、池子或操作记录。 |
| 409 | 审核过期、交易内容改变、价格不满足限制或分页游标失效。 |
| 413 | 请求体超过允许字节数。 |
| 415 | 请求 Content-Type 不受支持。 |
| 422 | JSON 字段格式无效或包含未知字段。 |
| 429 | 请求频率或容量达到上限，按 Retry-After 秒数退避。 |
| 503 | 节点、签名服务、索引或上游暂不可用，按 Retry-After 秒数退避。 |

### POST /issuances/{id}/broadcast

提交已补齐的原交易。在用户已批准提交这笔交易后，传入 finalize 返回的完整 transaction 和原 review_id。只通过当前网络 TSCScan 预检、广播；不构造、签名或替换交易。不需要额外钱包调用。accepted 包含此前已接受的交易；unknown 应保留原字节、查询状态并原样重试。链上确认以 GET /issuances/{id} 为准。

参数：

| 字段 | 位置 | 类型 | 必填 | 说明与约束 |
| --- | --- | --- | --- | --- |
| id | path | string | 是 | 原始发行 request_id，小写 UUIDv4。 格式："^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$" |

请求体：

| 字段 | 类型 | 必填 | 说明 | 约束 |
| --- | --- | --- | --- | --- |
| review_id | string | 是 | 与本次完整交易绑定的审核 ID；属于路径 id 指定的发行阶段。 | 格式："^[0-9a-f]{64}$" |
| transaction | TwpRawTransaction | 是 | finalize 返回的完整原始交易；必须逐字节一致，不能提交部分签名、修改矿工费或替换交易。 |  |
| transaction.format | string | 是 | 原始交易的序列化格式。 | 固定值："tensorcash-raw-v1" |
| transaction.hex | string | 是 | 原始 TensorCash 交易的十六进制字节；不是 PSBT 或 EVM 交易。 | 格式："^(?:[0-9a-f]{2})*$" |

响应 200：返回以下 JSON 对象；交易的最终结果以 state 和链上确认状态为准。

| 字段 | 类型 | 必定出现 | 说明 | 约束 |
| --- | --- | --- | --- | --- |
| id | string | 是 | 原始 request_id；用于查询同一次发行的状态。 | 格式："^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$" |
| asset_id | string | 是 | 资产的链上 ID，64 位小写十六进制；只在对应网络有效。 | 格式："^[0-9a-f]{64}$" |
| chain_id | string | 是 | 目标网络标识，公共网络格式为 tsc:<genesis>:public。 | 格式："^tsc:[0-9a-f]{64}:(public\|[0-9a-f]{64})$" |
| step | string | 是 | 发行阶段：register 注册资产，mint 发行初始数量。 | 可选值：["register", "mint"] |
| txid | string | 是 | 链上交易 ID，64 位小写十六进制；不同于 quote_id 或 request_id。 | 格式："^[0-9a-f]{64}$" |
| state | string | 是 | accepted 已观察到节点接受（含此前已接受）；rejected 预检查明确拒绝；unknown 提交结果不明确，应保留原交易、查询状态并原样重试。均不代表新的链上确认。 | 可选值：["accepted", "rejected", "unknown"] |
| reason | string / null | 是 | rejected 或 unknown 的说明；accepted 时为 null。 |  |

错误响应：

| HTTP 状态 | 含义 |
| --- | --- |
| 400 | 请求参数、资产策略或签名无效。 |
| 404 | 未找到资产、池子或操作记录。 |
| 409 | 审核过期、交易内容改变、价格不满足限制或分页游标失效。 |
| 413 | 请求体超过允许字节数。 |
| 415 | 请求 Content-Type 不受支持。 |
| 422 | JSON 字段格式无效或包含未知字段。 |
| 429 | 请求频率或容量达到上限，按 Retry-After 秒数退避。 |
| 503 | 节点、签名服务、索引或上游暂不可用，按 Retry-After 秒数退避。 |

## 交易与流动性

### POST /estimate

预估兑换数量。提供卖出币种、接收币种及卖出金额，至少一侧为 TSC。返回数量和路由；有效期 15 秒，不预留储备，不需要签名。

请求体：

| 字段 | 类型 | 必填 | 说明 | 约束 |
| --- | --- | --- | --- | --- |
| input_asset_id | string | 是 | 卖出币种；TSC 或 64 位小写十六进制 Asset ID。 | 固定值："TSC"；格式："^[0-9a-f]{64}$" |
| output_asset_id | string | 是 | 接收币种；当前兑换要求一侧为 TSC。 | 固定值："TSC"；格式："^[0-9a-f]{64}$" |
| amount | string | 是 | 卖出金额，按卖出币种单位填写的十进制字符串；不能用 JSON 数字或科学计数法。 | 格式："^[0-9]+(?:\\.[0-9]+)?$" |
| input_asset_id | string | 否 | 卖出币种；TSC 或 64 位小写十六进制 Asset ID。 | 固定值："TSC" |
| output_asset_id | string | 否 | 接收币种；当前兑换要求一侧为 TSC。 | 格式："^[0-9a-f]{64}$" |
| input_asset_id | string | 否 | 卖出币种；TSC 或 64 位小写十六进制 Asset ID。 | 格式："^[0-9a-f]{64}$" |
| output_asset_id | string | 否 | 接收币种；当前兑换要求一侧为 TSC。 | 固定值："TSC" |

请求示例：

```json
{
  "input_asset_id": "TSC",
  "output_asset_id": "67c31777dbeb592406cd2758479c63b86b9ec5916178146b4e9a58f7897a1838",
  "amount": "1"
}
```

响应 200：返回以下 JSON 对象；交易的最终结果以 state 和链上确认状态为准。

| 字段 | 类型 | 必定出现 | 说明 | 约束 |
| --- | --- | --- | --- | --- |
| input | object | 是 | 兑换的输入资产信息。 |  |
| input.asset_id | string | 是 | 资产的链上 ID，64 位小写十六进制；只在对应网络有效。 | 固定值："TSC"；格式："^[0-9a-f]{64}$" |
| input.symbol | string | 是 | 资产展示符号；发行时填 3–11 位大写字母数字，首位字母，不加 TRC20. 前缀。 |  |
| input.precision | integer | 是 | 资产小数位数；TSC 为 8，其他资产以链上登记值为准。 | 最小值：0 |
| output | object | 是 | 兑换的接收资产信息。 |  |
| output.asset_id | string | 是 | 资产的链上 ID，64 位小写十六进制；只在对应网络有效。 | 固定值："TSC"；格式："^[0-9a-f]{64}$" |
| output.symbol | string | 是 | 资产展示符号；发行时填 3–11 位大写字母数字，首位字母，不加 TRC20. 前缀。 |  |
| output.precision | integer | 是 | 资产小数位数；TSC 为 8，其他资产以链上登记值为准。 | 最小值：0 |
| amount_in_units | string | 是 | 卖出金额的最小单位数量，整数字符串。 | 格式："^[0-9]+$" |
| amount_out_units | string | 是 | 预计接收币种的最小单位数量，整数字符串。 | 格式："^[0-9]+$" |
| amount_out | string | 是 | 预计接收金额，按接收币种单位表示的十进制字符串。 | 格式："^[0-9]+(?:\\.[0-9]+)?$" |
| route_kind | string | 是 | 预估路由类型；direct 单池，split 拆分到多个池。 | 可选值：["direct", "split"] |
| price_impact_bps | integer | 是 | 价格影响，单位基点；100 表示 1%，不同于滑点和手续费。 | 最小值：0 |
| pool_ids | string[] | 是 | 参与此记录的微池实例 ID 列表。 |  |
| path | string[] | 是 | 兑换经过的资产符号列表。 |  |
| network_fee_units | string | 是 | 预计矿工费，TSC 最小单位整数字符串。 | 格式："^[0-9]+$" |
| lp_fee_bps_per_pool | integer | 是 | 每个池子的 LP 手续费率，单位基点；30 表示 0.30%。 | 最小值：0 |
| index | IndexStatus | 是 | 行情索引进度与同步状态；数据不完整时不要当作完整实时行情。 |  |
| index.indexed_height | integer / null | 是 | 索引已处理到的区块高度。 |  |
| index.indexed_hash | string / null | 是 | 索引已处理到的区块哈希。 |  |
| index.core_height | integer / null | 是 | 节点已验证的区块高度。 |  |
| index.core_headers | integer / null | 是 | 节点已知的最高区块头高度。 |  |
| index.node_ready | boolean | 是 | 节点是否已完成同步并可处理交易。 |  |
| index.caught_up | boolean | 是 | 行情索引是否已追上节点当前高度。 |  |
| index.last_checked_at | integer / null | 是 | 最近一次索引检查时间，UTC Unix 毫秒。 |  |
| index.error | string / null | 是 | 错误说明；无错误时为 null，交易状态仍以 state 为准。 |  |
| index.revision | integer | 是 | 行情索引修订号；用于识别重建或状态变化。 | 最小值：0 |
| quoted_at | integer | 是 | 生成预估时的时间，UTC Unix 秒。 | 最小值：0 |
| valid_for_seconds | integer | 是 | 预估有效期，单位秒。 | 最小值：0 |

错误响应：

| HTTP 状态 | 含义 |
| --- | --- |
| 400 | 请求参数、资产策略或签名无效。 |
| 404 | 未找到资产、池子或操作记录。 |
| 409 | 审核过期、交易内容改变、价格不满足限制或分页游标失效。 |
| 413 | 请求体超过允许字节数。 |
| 415 | 请求 Content-Type 不受支持。 |
| 422 | JSON 字段格式无效或包含未知字段。 |
| 429 | 请求频率或容量达到上限，按 Retry-After 秒数退避。 |
| 503 | 节点、签名服务、索引或上游暂不可用，按 Retry-After 秒数退避。 |

### POST /quote

构造交易报价。根据 kind 构造创建、添加、追加、兑换或提款的未签名交易。有效期 300 秒，不锁定 UTXO；签名后输入输出金额固定。新池操作须先保存恢复资料。当前新 LP 功能门槛关闭时返回 RECOVERY_NOT_VALIDATED。

请求体：

| 字段 | 类型 | 必填 | 说明 | 约束 |
| --- | --- | --- | --- | --- |
| actor | string | 是 | 操作账户在当前网络的 P2WPKH 地址；仅提供地址不会授权花费。 | 最短字符数：1；最长字符数：90 |
| kind | string | 是 | 操作类型：创建、添加、追加、兑换或移除流动性。 | 可选值：["create_pool", "add_liquidity", "increase_liquidity", "swap", "remove_liquidity"] |
| asset_id | string | 是 | 资产的链上 ID，64 位小写十六进制；只在对应网络有效。 | 格式："^[0-9a-f]{64}$" |
| pool_id | string | 否 | 追加或提款时必填的原 Pool ID；创建独立新池时不传。 | 格式："^[0-9a-f]{64}$" |
| nonce | string | 否 | 创建、添加、追加及部分退出时必填的新实例随机数，32 字节小写十六进制。 | 格式："^[0-9a-f]{64}$" |
| owner_key | string | 否 | 创建、添加、追加及部分退出时必填的新实例退出公钥，32 字节 x-only 公钥，不是私钥。 | 格式："^[0-9a-f]{64}$" |
| reference_pool_id | string | 否 | 同一交易对的参考 Pool ID；准备入金时比例偏差超过 1% 返回 LIQUIDITY_PRICE_CHANGED，不锁定签名期间价格。 | 格式："^[0-9a-f]{64}$" |
| tsc_amount | string | 否 | 创建、添加、追加时必填的存入 TSC 金额，十进制字符串。 | 格式："^[0-9]+(?:\\.[0-9]+)?$" |
| asset_amount | string | 否 | 创建、添加、追加时必填的存入 Asset 金额，按资产单位的十进制字符串。 | 格式："^[0-9]+(?:\\.[0-9]+)?$" |
| tsc_in | boolean | 否 | 兑换方向；true 卖出 TSC 买 Asset，false 卖出 Asset 买 TSC。 | 默认值：false |
| amount | string | 否 | kind=swap 时必填的卖出金额；按 tsc_in 指定的卖出币种单位填写十进制字符串。 | 格式："^[0-9]+(?:\\.[0-9]+)?$" |
| withdraw_bps | integer | 否 | kind=remove_liquidity 时必填；10000 为全额退出，1–9999 为部分退出，后者还需要 nonce 与 owner_key。 | 最小值：1；最大值：10000 |
| output_asset_id | string | 否 | 兼容字段，省略、空字符串或 TSC；当前不支持 Asset 到另一个 Asset 的请求。 | 可选值：["", "TSC"] |
| min_output_units | string | 否 | 最低接收数量，按接收币种最小单位填写的整数字符串；准备报价时校验，签名后输出固定。 | 格式："^[0-9]+$" |
| recovery | RecoveryFile | 否 | 已有池子的公开恢复文件；仍需原钱包签名。 |  |
| recovery.schema | string | 是 | 此对象的序列化版本标识。 | 可选值：["tensorcash-micro-pool-wallet-v1", "tensorcash-micro-pool-wallet-v2"] |
| recovery.owner_derivation | string | 是 | 退出账户或密钥的派生标识；旧 v1 与标准账户 v2 不可混用。 | 可选值：["hkdf-sha256-bip32-master-v1", "standard-account-v1"] |
| recovery.actor | string | 是 | 操作账户在当前网络的 P2WPKH 地址；仅提供地址不会授权花费。 |  |
| recovery.registration | Registration | 是 | 新池登记资料或资产注册交易；结构由所在接口定义。 |  |
| recovery.registration.descriptor | PoolDescriptor | 是 | 包含池子参数、脚本及退出分支的完整公开描述。 |  |
| recovery.registration.descriptor.config | PoolConfig | 是 | 池子脚本绑定的公开参数。 |  |
| recovery.registration.descriptor.config.version | integer | 是 | 该对象协议格式版本。 | 固定值：1 |
| recovery.registration.descriptor.config.genesis | string | 是 | 当前网络的创世区块哈希，64 位小写十六进制。 | 格式："^[0-9a-f]{64}$" |
| recovery.registration.descriptor.config.nonce | string | 是 | 新池随机数，32 字节小写十六进制；不能复用创建不同实例。 | 格式："^[0-9a-f]{64}$" |
| recovery.registration.descriptor.config.asset_id | string | 是 | 资产的链上 ID，64 位小写十六进制；只在对应网络有效。 | 格式："^[0-9a-f]{64}$" |
| recovery.registration.descriptor.config.owner_key | string | 是 | 池所有者退出公钥，32 字节 x-only 公钥，不是私钥。 | 格式："^[0-9a-f]{64}$" |
| recovery.registration.descriptor.config.operator_key | string | 是 | 第一个交易签名角色的 x-only 公钥。 | 格式："^[0-9a-f]{64}$" |
| recovery.registration.descriptor.config.official_key | string | 是 | 第二个交易签名角色的 x-only 公钥；角色名不代表官方实际参与。 | 格式："^[0-9a-f]{64}$" |
| recovery.registration.descriptor.config.fee_bps | integer | 是 | 池手续费率，单位基点；30 表示 0.30%。 | 固定值：30 |
| recovery.registration.descriptor.config.carrier_units | integer | 是 | 池子载体金额，单位为 TSC 最小单位；全额退出可取回。 | 固定值：100000 |
| recovery.registration.descriptor.pool_id | string | 是 | 微池实例 ID，64 位小写十六进制；不是 Asset ID。 | 格式："^[0-9a-f]{64}$" |
| recovery.registration.descriptor.script_pubkey | string | 是 | 池子 Taproot 锁定脚本，十六进制字符串。 | 格式："^(?:[0-9a-f]{2})*$" |
| recovery.registration.descriptor.trade_script | string | 是 | 池子双签交易分支的脚本字节，十六进制。 | 格式："^(?:[0-9a-f]{2})*$" |
| recovery.registration.descriptor.trade_control | string | 是 | 交易支出分支的 Taproot 控制块，十六进制。 | 格式："^(?:[0-9a-f]{2})*$" |
| recovery.registration.descriptor.withdrawal_script | string | 是 | LP 独立退出分支的脚本字节，十六进制。 | 格式："^(?:[0-9a-f]{2})*$" |
| recovery.registration.descriptor.withdrawal_control | string | 是 | LP 独立退出分支的 Taproot 控制块，十六进制。 | 格式："^(?:[0-9a-f]{2})*$" |
| recovery.registration.native | OutPoint | 是 | 池子 TSC 储备的原始入金输出引用。 |  |
| recovery.registration.native.txid | string | 是 | 链上交易 ID，64 位小写十六进制；不同于 quote_id 或 request_id。 | 格式："^[0-9a-f]{64}$" |
| recovery.registration.native.vout | integer | 是 | 交易输出位置，从 0 开始。 | 最小值：0 |
| recovery.registration.asset | OutPoint | 是 | 原始入金交易中的 Asset 储备输出引用。 |  |
| recovery.registration.asset.txid | string | 是 | 链上交易 ID，64 位小写十六进制；不同于 quote_id 或 request_id。 | 格式："^[0-9a-f]{64}$" |
| recovery.registration.asset.vout | integer | 是 | 交易输出位置，从 0 开始。 | 最小值：0 |
| recovery.registration.owner_signature | string | 是 | 旧 v1 的登记 Schnorr 签名；未签名时为空字符串。标准账户 v2 使用 owner_proof，此字段仍为空。 | 格式："^(?:[0-9a-f]{2})*$" |
| recovery.registration.owner_proof | OwnerProof | 否 | 标准账户 v2 的 LP 所有权声明证明；与旧 owner_signature 不能同时使用。 |  |
| recovery.registration.owner_proof.profile | string | 是 | 钱包输入使用的签名规则标识。 | 固定值："twp:proof:p2wpkh-ecdsa:1" |
| recovery.registration.owner_proof.digest | string | 是 | 结构化声明的摘要，64 位小写十六进制。 | 格式："^[0-9a-f]{64}$" |
| recovery.registration.owner_proof.envelope | object | 是 | 钱包签署的完整 TWP 声明信封；须保留原对象，不能修改账户、链或声明内容。 |  |
| recovery.registration.owner_proof.proof | object | 是 | 账户声明的公钥及 ECDSA 签名。 | 不接受未知字段 |
| recovery.registration.owner_proof.proof.publicKey | string | 是 | 钱包账户的压缩 secp256k1 公钥，十六进制。 | 格式："^(?:[0-9a-f]{2})*$" |
| recovery.registration.owner_proof.proof.signature | string | 是 | 结构化声明的 ECDSA 签名，十六进制。 | 格式："^(?:[0-9a-f]{2})*$" |
| recovery.owner_public_key | string | 否 | v2 恢复文件中的原钱包账户压缩公钥。 |  |
| recovery.account_id | string | 否 | v2 恢复文件中原钱包账户的 script: 标识。 |  |
| recovery.funding_transaction | string | 否 | v2 签名前保存的原始入金交易字节，用于恢复校验；服务端已登记备份可能省略。 | 格式："^(?:[0-9a-f]{2})*$" |
| kind | string | 否 | 操作类型：创建、添加、追加、兑换或移除流动性。 | 固定值："increase_liquidity" |
| kind | string | 否 | 操作类型：创建、添加、追加、兑换或移除流动性。 | 可选值：["create_pool", "add_liquidity"] |
| kind | string | 否 | 操作类型：创建、添加、追加、兑换或移除流动性。 | 固定值："swap" |
| kind | string | 否 | 操作类型：创建、添加、追加、兑换或移除流动性。 | 固定值："remove_liquidity" |
| withdraw_bps | integer | 是 | kind=remove_liquidity 时必填；10000 为全额退出，1–9999 为部分退出，后者还需要 nonce 与 owner_key。 | 固定值：10000 |
| withdraw_bps | object | 是 | kind=remove_liquidity 时必填；10000 为全额退出，1–9999 为部分退出，后者还需要 nonce 与 owner_key。 | 最小值：1；最大值：9999 |

请求示例：

```json
{
  "actor": "YOUR_P2WPKH_ADDRESS",
  "asset_id": "67c31777dbeb592406cd2758479c63b86b9ec5916178146b4e9a58f7897a1838",
  "kind": "swap",
  "tsc_in": true,
  "amount": "1",
  "min_output_units": "1"
}
```

请求示例：

```json
{
  "actor": "YOUR_P2WPKH_ADDRESS",
  "asset_id": "67c31777dbeb592406cd2758479c63b86b9ec5916178146b4e9a58f7897a1838",
  "kind": "swap",
  "tsc_in": false,
  "amount": "10",
  "min_output_units": "1"
}
```

请求示例：

```json
{
  "actor": "YOUR_P2WPKH_ADDRESS",
  "asset_id": "67c31777dbeb592406cd2758479c63b86b9ec5916178146b4e9a58f7897a1838",
  "kind": "create_pool",
  "nonce": "1111111111111111111111111111111111111111111111111111111111111111",
  "owner_key": "3333333333333333333333333333333333333333333333333333333333333333",
  "tsc_amount": "5",
  "asset_amount": "500"
}
```

请求示例：

```json
{
  "actor": "YOUR_P2WPKH_ADDRESS",
  "asset_id": "67c31777dbeb592406cd2758479c63b86b9ec5916178146b4e9a58f7897a1838",
  "kind": "add_liquidity",
  "nonce": "1111111111111111111111111111111111111111111111111111111111111111",
  "owner_key": "3333333333333333333333333333333333333333333333333333333333333333",
  "tsc_amount": "5",
  "asset_amount": "500"
}
```

请求示例：

```json
{
  "actor": "YOUR_P2WPKH_ADDRESS",
  "asset_id": "67c31777dbeb592406cd2758479c63b86b9ec5916178146b4e9a58f7897a1838",
  "kind": "increase_liquidity",
  "pool_id": "4444444444444444444444444444444444444444444444444444444444444444",
  "nonce": "1111111111111111111111111111111111111111111111111111111111111111",
  "owner_key": "3333333333333333333333333333333333333333333333333333333333333333",
  "tsc_amount": "1",
  "asset_amount": "100"
}
```

请求示例：

```json
{
  "actor": "YOUR_P2WPKH_ADDRESS",
  "asset_id": "67c31777dbeb592406cd2758479c63b86b9ec5916178146b4e9a58f7897a1838",
  "kind": "remove_liquidity",
  "pool_id": "4444444444444444444444444444444444444444444444444444444444444444",
  "withdraw_bps": 10000
}
```

请求示例：

```json
{
  "actor": "YOUR_P2WPKH_ADDRESS",
  "asset_id": "67c31777dbeb592406cd2758479c63b86b9ec5916178146b4e9a58f7897a1838",
  "kind": "remove_liquidity",
  "pool_id": "4444444444444444444444444444444444444444444444444444444444444444",
  "withdraw_bps": 5000,
  "nonce": "1111111111111111111111111111111111111111111111111111111111111111",
  "owner_key": "3333333333333333333333333333333333333333333333333333333333333333"
}
```

响应 200：返回以下 JSON 对象；交易的最终结果以 state 和链上确认状态为准。

| 字段 | 类型 | 必定出现 | 说明 | 约束 |
| --- | --- | --- | --- | --- |
| schema | integer | 是 | 此对象的序列化版本标识。 | 固定值：1 |
| quote_id | string | 是 | 报价与后续操作 ID；用于 execute 和 operations，不是交易 txid。 | 格式："^[0-9a-f]{64}$" |
| expires_at | integer | 是 | 失效时间；交易和审核为 UTC Unix 秒，美元参考价为毫秒。 | 最小值：0 |
| kind | string | 是 | 操作类型：创建、添加、追加、兑换或移除流动性。 | 可选值：["create_pool", "add_liquidity", "increase_liquidity", "swap", "remove_liquidity"] |
| actor | string | 是 | 操作账户在当前网络的 P2WPKH 地址；仅提供地址不会授权花费。 |  |
| asset_id | string | 是 | 资产的链上 ID，64 位小写十六进制；只在对应网络有效。 | 格式："^[0-9a-f]{64}$" |
| symbol | string | 是 | 资产展示符号；发行时填 3–11 位大写字母数字，首位字母，不加 TRC20. 前缀。 |  |
| precision | integer | 是 | 资产小数位数；TSC 为 8，其他资产以链上登记值为准。 | 最小值：0 |
| fee_units | string | 是 | 本次交易矿工费，TSC 最小单位整数字符串；1 TSC = 100000000。 | 格式："^[0-9]+$" |
| tx_hex | string | 是 | 原始 TensorCash 交易字节，十六进制；须保留完整签名版本以供恢复。 | 格式："^(?:[0-9a-f]{2})*$" |
| inputs | QuoteInput[] | 是 | 交易引用的输入及其实际前序输出资料。 |  |
| inputs[].txid | string | 是 | 链上交易 ID，64 位小写十六进制；不同于 quote_id 或 request_id。 | 格式："^[0-9a-f]{64}$" |
| inputs[].vout | integer | 是 | 交易输出位置，从 0 开始。 | 最小值：0 |
| inputs[].value_units | string | 是 | 该输入或输出的 TSC 最小单位数量，整数字符串；Asset 数量编码在 output_extension。 | 格式："^[0-9]+$" |
| inputs[].script_pub_key | string | 是 | 输出锁定脚本，十六进制字符串。 | 格式："^(?:[0-9a-f]{2})*$" |
| inputs[].output_extension | string | 是 | 输出的 TensorCash 资产扩展字节，十六进制字符串。 | 格式："^(?:[0-9a-f]{2})*$" |
| created | PoolDescriptor / null | 是 | 本次将创建的池描述；不创建新池时为 null。 |  |
| created.config | PoolConfig | 是 | 池子脚本绑定的公开参数。 |  |
| created.config.version | integer | 是 | 该对象协议格式版本。 | 固定值：1 |
| created.config.genesis | string | 是 | 当前网络的创世区块哈希，64 位小写十六进制。 | 格式："^[0-9a-f]{64}$" |
| created.config.nonce | string | 是 | 新池随机数，32 字节小写十六进制；不能复用创建不同实例。 | 格式："^[0-9a-f]{64}$" |
| created.config.asset_id | string | 是 | 资产的链上 ID，64 位小写十六进制；只在对应网络有效。 | 格式："^[0-9a-f]{64}$" |
| created.config.owner_key | string | 是 | 池所有者退出公钥，32 字节 x-only 公钥，不是私钥。 | 格式："^[0-9a-f]{64}$" |
| created.config.operator_key | string | 是 | 第一个交易签名角色的 x-only 公钥。 | 格式："^[0-9a-f]{64}$" |
| created.config.official_key | string | 是 | 第二个交易签名角色的 x-only 公钥；角色名不代表官方实际参与。 | 格式："^[0-9a-f]{64}$" |
| created.config.fee_bps | integer | 是 | 池手续费率，单位基点；30 表示 0.30%。 | 固定值：30 |
| created.config.carrier_units | integer | 是 | 池子载体金额，单位为 TSC 最小单位；全额退出可取回。 | 固定值：100000 |
| created.pool_id | string | 是 | 微池实例 ID，64 位小写十六进制；不是 Asset ID。 | 格式："^[0-9a-f]{64}$" |
| created.script_pubkey | string | 是 | 池子 Taproot 锁定脚本，十六进制字符串。 | 格式："^(?:[0-9a-f]{2})*$" |
| created.trade_script | string | 是 | 池子双签交易分支的脚本字节，十六进制。 | 格式："^(?:[0-9a-f]{2})*$" |
| created.trade_control | string | 是 | 交易支出分支的 Taproot 控制块，十六进制。 | 格式："^(?:[0-9a-f]{2})*$" |
| created.withdrawal_script | string | 是 | LP 独立退出分支的脚本字节，十六进制。 | 格式："^(?:[0-9a-f]{2})*$" |
| created.withdrawal_control | string | 是 | LP 独立退出分支的 Taproot 控制块，十六进制。 | 格式："^(?:[0-9a-f]{2})*$" |
| retired | PoolDescriptor / null | 是 | 本次将退出或替换的旧池描述；无旧池时为 null。 |  |
| retired.config | PoolConfig | 是 | 池子脚本绑定的公开参数。 |  |
| retired.config.version | integer | 是 | 该对象协议格式版本。 | 固定值：1 |
| retired.config.genesis | string | 是 | 当前网络的创世区块哈希，64 位小写十六进制。 | 格式："^[0-9a-f]{64}$" |
| retired.config.nonce | string | 是 | 新池随机数，32 字节小写十六进制；不能复用创建不同实例。 | 格式："^[0-9a-f]{64}$" |
| retired.config.asset_id | string | 是 | 资产的链上 ID，64 位小写十六进制；只在对应网络有效。 | 格式："^[0-9a-f]{64}$" |
| retired.config.owner_key | string | 是 | 池所有者退出公钥，32 字节 x-only 公钥，不是私钥。 | 格式："^[0-9a-f]{64}$" |
| retired.config.operator_key | string | 是 | 第一个交易签名角色的 x-only 公钥。 | 格式："^[0-9a-f]{64}$" |
| retired.config.official_key | string | 是 | 第二个交易签名角色的 x-only 公钥；角色名不代表官方实际参与。 | 格式："^[0-9a-f]{64}$" |
| retired.config.fee_bps | integer | 是 | 池手续费率，单位基点；30 表示 0.30%。 | 固定值：30 |
| retired.config.carrier_units | integer | 是 | 池子载体金额，单位为 TSC 最小单位；全额退出可取回。 | 固定值：100000 |
| retired.pool_id | string | 是 | 微池实例 ID，64 位小写十六进制；不是 Asset ID。 | 格式："^[0-9a-f]{64}$" |
| retired.script_pubkey | string | 是 | 池子 Taproot 锁定脚本，十六进制字符串。 | 格式："^(?:[0-9a-f]{2})*$" |
| retired.trade_script | string | 是 | 池子双签交易分支的脚本字节，十六进制。 | 格式："^(?:[0-9a-f]{2})*$" |
| retired.trade_control | string | 是 | 交易支出分支的 Taproot 控制块，十六进制。 | 格式："^(?:[0-9a-f]{2})*$" |
| retired.withdrawal_script | string | 是 | LP 独立退出分支的脚本字节，十六进制。 | 格式："^(?:[0-9a-f]{2})*$" |
| retired.withdrawal_control | string | 是 | LP 独立退出分支的 Taproot 控制块，十六进制。 | 格式："^(?:[0-9a-f]{2})*$" |
| registration | Registration / null | 是 | 新池登记资料或资产注册交易；结构由所在接口定义。 |  |
| registration.descriptor | PoolDescriptor | 是 | 包含池子参数、脚本及退出分支的完整公开描述。 |  |
| registration.descriptor.config | PoolConfig | 是 | 池子脚本绑定的公开参数。 |  |
| registration.descriptor.config.version | integer | 是 | 该对象协议格式版本。 | 固定值：1 |
| registration.descriptor.config.genesis | string | 是 | 当前网络的创世区块哈希，64 位小写十六进制。 | 格式："^[0-9a-f]{64}$" |
| registration.descriptor.config.nonce | string | 是 | 新池随机数，32 字节小写十六进制；不能复用创建不同实例。 | 格式："^[0-9a-f]{64}$" |
| registration.descriptor.config.asset_id | string | 是 | 资产的链上 ID，64 位小写十六进制；只在对应网络有效。 | 格式："^[0-9a-f]{64}$" |
| registration.descriptor.config.owner_key | string | 是 | 池所有者退出公钥，32 字节 x-only 公钥，不是私钥。 | 格式："^[0-9a-f]{64}$" |
| registration.descriptor.config.operator_key | string | 是 | 第一个交易签名角色的 x-only 公钥。 | 格式："^[0-9a-f]{64}$" |
| registration.descriptor.config.official_key | string | 是 | 第二个交易签名角色的 x-only 公钥；角色名不代表官方实际参与。 | 格式："^[0-9a-f]{64}$" |
| registration.descriptor.config.fee_bps | integer | 是 | 池手续费率，单位基点；30 表示 0.30%。 | 固定值：30 |
| registration.descriptor.config.carrier_units | integer | 是 | 池子载体金额，单位为 TSC 最小单位；全额退出可取回。 | 固定值：100000 |
| registration.descriptor.pool_id | string | 是 | 微池实例 ID，64 位小写十六进制；不是 Asset ID。 | 格式："^[0-9a-f]{64}$" |
| registration.descriptor.script_pubkey | string | 是 | 池子 Taproot 锁定脚本，十六进制字符串。 | 格式："^(?:[0-9a-f]{2})*$" |
| registration.descriptor.trade_script | string | 是 | 池子双签交易分支的脚本字节，十六进制。 | 格式："^(?:[0-9a-f]{2})*$" |
| registration.descriptor.trade_control | string | 是 | 交易支出分支的 Taproot 控制块，十六进制。 | 格式："^(?:[0-9a-f]{2})*$" |
| registration.descriptor.withdrawal_script | string | 是 | LP 独立退出分支的脚本字节，十六进制。 | 格式："^(?:[0-9a-f]{2})*$" |
| registration.descriptor.withdrawal_control | string | 是 | LP 独立退出分支的 Taproot 控制块，十六进制。 | 格式："^(?:[0-9a-f]{2})*$" |
| registration.native | OutPoint | 是 | 池子 TSC 储备的原始入金输出引用。 |  |
| registration.native.txid | string | 是 | 链上交易 ID，64 位小写十六进制；不同于 quote_id 或 request_id。 | 格式："^[0-9a-f]{64}$" |
| registration.native.vout | integer | 是 | 交易输出位置，从 0 开始。 | 最小值：0 |
| registration.asset | OutPoint | 是 | 原始入金交易中的 Asset 储备输出引用。 |  |
| registration.asset.txid | string | 是 | 链上交易 ID，64 位小写十六进制；不同于 quote_id 或 request_id。 | 格式："^[0-9a-f]{64}$" |
| registration.asset.vout | integer | 是 | 交易输出位置，从 0 开始。 | 最小值：0 |
| registration.owner_signature | string | 是 | 旧 v1 的登记 Schnorr 签名；未签名时为空字符串。标准账户 v2 使用 owner_proof，此字段仍为空。 | 格式："^(?:[0-9a-f]{2})*$" |
| registration.owner_proof | OwnerProof | 否 | 标准账户 v2 的 LP 所有权声明证明；与旧 owner_signature 不能同时使用。 |  |
| registration.owner_proof.profile | string | 是 | 钱包输入使用的签名规则标识。 | 固定值："twp:proof:p2wpkh-ecdsa:1" |
| registration.owner_proof.digest | string | 是 | 结构化声明的摘要，64 位小写十六进制。 | 格式："^[0-9a-f]{64}$" |
| registration.owner_proof.envelope | object | 是 | 钱包签署的完整 TWP 声明信封；须保留原对象，不能修改账户、链或声明内容。 |  |
| registration.owner_proof.proof | object | 是 | 账户声明的公钥及 ECDSA 签名。 | 不接受未知字段 |
| registration.owner_proof.proof.publicKey | string | 是 | 钱包账户的压缩 secp256k1 公钥，十六进制。 | 格式："^(?:[0-9a-f]{2})*$" |
| registration.owner_proof.proof.signature | string | 是 | 结构化声明的 ECDSA 签名，十六进制。 | 格式："^(?:[0-9a-f]{2})*$" |
| routes | object[] | 是 | 本次兑换参与的池及其输入、后继输出位置。 |  |
| routes[].descriptor | PoolDescriptor | 是 | 包含池子参数、脚本及退出分支的完整公开描述。 |  |
| routes[].descriptor.config | PoolConfig | 是 | 池子脚本绑定的公开参数。 |  |
| routes[].descriptor.config.version | integer | 是 | 该对象协议格式版本。 | 固定值：1 |
| routes[].descriptor.config.genesis | string | 是 | 当前网络的创世区块哈希，64 位小写十六进制。 | 格式："^[0-9a-f]{64}$" |
| routes[].descriptor.config.nonce | string | 是 | 新池随机数，32 字节小写十六进制；不能复用创建不同实例。 | 格式："^[0-9a-f]{64}$" |
| routes[].descriptor.config.asset_id | string | 是 | 资产的链上 ID，64 位小写十六进制；只在对应网络有效。 | 格式："^[0-9a-f]{64}$" |
| routes[].descriptor.config.owner_key | string | 是 | 池所有者退出公钥，32 字节 x-only 公钥，不是私钥。 | 格式："^[0-9a-f]{64}$" |
| routes[].descriptor.config.operator_key | string | 是 | 第一个交易签名角色的 x-only 公钥。 | 格式："^[0-9a-f]{64}$" |
| routes[].descriptor.config.official_key | string | 是 | 第二个交易签名角色的 x-only 公钥；角色名不代表官方实际参与。 | 格式："^[0-9a-f]{64}$" |
| routes[].descriptor.config.fee_bps | integer | 是 | 池手续费率，单位基点；30 表示 0.30%。 | 固定值：30 |
| routes[].descriptor.config.carrier_units | integer | 是 | 池子载体金额，单位为 TSC 最小单位；全额退出可取回。 | 固定值：100000 |
| routes[].descriptor.pool_id | string | 是 | 微池实例 ID，64 位小写十六进制；不是 Asset ID。 | 格式："^[0-9a-f]{64}$" |
| routes[].descriptor.script_pubkey | string | 是 | 池子 Taproot 锁定脚本，十六进制字符串。 | 格式："^(?:[0-9a-f]{2})*$" |
| routes[].descriptor.trade_script | string | 是 | 池子双签交易分支的脚本字节，十六进制。 | 格式："^(?:[0-9a-f]{2})*$" |
| routes[].descriptor.trade_control | string | 是 | 交易支出分支的 Taproot 控制块，十六进制。 | 格式："^(?:[0-9a-f]{2})*$" |
| routes[].descriptor.withdrawal_script | string | 是 | LP 独立退出分支的脚本字节，十六进制。 | 格式："^(?:[0-9a-f]{2})*$" |
| routes[].descriptor.withdrawal_control | string | 是 | LP 独立退出分支的 Taproot 控制块，十六进制。 | 格式："^(?:[0-9a-f]{2})*$" |
| routes[].input_index | integer | 是 | 池子输入在交易中的位置，从 0 开始。 | 最小值：0 |
| routes[].output_index | integer | 是 | 池子后继输出在交易中的位置，从 0 开始。 | 最小值：0 |
| amounts | OperationAmounts | 是 | 本次操作的 TSC、Asset 数量和操作方向。 |  |
| amounts.tsc_units | string | 是 | TSC 最小单位整数字符串；1 TSC = 100000000。 | 格式："^[0-9]+$" |
| amounts.asset_units | string | 是 | 非 TSC 资产数量，按该资产精度表示的最小单位整数字符串。 | 格式："^[0-9]+$" |
| amounts.tsc_in | boolean | 是 | 兑换方向；true 卖出 TSC 买 Asset，false 卖出 Asset 买 TSC。 |  |
| amounts.withdraw_bps | integer | 是 | 提款比例，1–10000 基点；10000 全额退出，部分退出会生成继任池。 | 最小值：0 |
| cross_asset | object / null | 是 | 历史跨资产路由信息；当前 Asset/TSC 接口不支持跨资产请求。 |  |
| cross_asset.asset_id | string | 是 | 资产的链上 ID，64 位小写十六进制；只在对应网络有效。 | 格式："^[0-9a-f]{64}$" |
| cross_asset.symbol | string | 是 | 资产展示符号；发行时填 3–11 位大写字母数字，首位字母，不加 TRC20. 前缀。 |  |
| cross_asset.precision | integer | 是 | 资产小数位数；TSC 为 8，其他资产以链上登记值为准。 | 最小值：0 |
| cross_asset.output_units | string | 是 | 接收资产的最小单位数量，整数字符串。 | 格式："^[0-9]+$" |
| cross_asset.intermediate_tsc_units | string | 是 | 历史多跳路由中间 TSC 数量，最小单位整数字符串。 | 格式："^[0-9]+$" |
| swap_plan | object / null | 是 | 兑换路由类型和价格影响；非兑换时为 null。 |  |
| swap_plan.kind | string | 是 | 操作类型：创建、添加、追加、兑换或移除流动性。 | 可选值：["direct", "split", "multi_hop"] |
| swap_plan.price_impact_bps | integer | 是 | 价格影响，单位基点；100 表示 1%，不同于滑点和手续费。 | 最小值：0 |
| previous_transactions | object | 是 | txid 到完整前序交易原始字节的映射；须独立重算 txid 和输入金额。 |  |

错误响应：

| HTTP 状态 | 含义 |
| --- | --- |
| 400 | 请求参数、资产策略或签名无效。 |
| 404 | 未找到资产、池子或操作记录。 |
| 409 | 审核过期、交易内容改变、价格不满足限制或分页游标失效。 |
| 413 | 请求体超过允许字节数。 |
| 415 | 请求 Content-Type 不受支持。 |
| 422 | JSON 字段格式无效或包含未知字段。 |
| 429 | 请求频率或容量达到上限，按 Retry-After 秒数退避。 |
| 503 | 节点、签名服务、索引或上游暂不可用，按 Retry-After 秒数退避。 |

### POST /execute

提交已签名报价交易。提交 quote_id 和保持原模板的已签名 hex。quote.created 非 null 时需要 registration。相同 ID 和相同签名字节恢复同一操作；更改字节返回 TRANSACTION_CHANGED。HTTP 200 仍可能处于 submitting 或带 error，应继续查询原操作。

请求体：

| 字段 | 类型 | 必填 | 说明 | 约束 |
| --- | --- | --- | --- | --- |
| quote_id | string | 是 | 报价与后续操作 ID；用于 execute 和 operations，不是交易 txid。 | 格式："^[0-9a-f]{64}$" |
| hex | string | 是 | 原始 TensorCash 交易的十六进制字节；不是 PSBT 或 EVM 交易。 | 格式："^(?:[0-9a-f]{2})*$" |
| registration | Registration / null | 否 | 新池登记资料或资产注册交易；结构由所在接口定义。 |  |
| registration.descriptor | PoolDescriptor | 是 | 包含池子参数、脚本及退出分支的完整公开描述。 |  |
| registration.descriptor.config | PoolConfig | 是 | 池子脚本绑定的公开参数。 |  |
| registration.descriptor.config.version | integer | 是 | 该对象协议格式版本。 | 固定值：1 |
| registration.descriptor.config.genesis | string | 是 | 当前网络的创世区块哈希，64 位小写十六进制。 | 格式："^[0-9a-f]{64}$" |
| registration.descriptor.config.nonce | string | 是 | 新池随机数，32 字节小写十六进制；不能复用创建不同实例。 | 格式："^[0-9a-f]{64}$" |
| registration.descriptor.config.asset_id | string | 是 | 资产的链上 ID，64 位小写十六进制；只在对应网络有效。 | 格式："^[0-9a-f]{64}$" |
| registration.descriptor.config.owner_key | string | 是 | 池所有者退出公钥，32 字节 x-only 公钥，不是私钥。 | 格式："^[0-9a-f]{64}$" |
| registration.descriptor.config.operator_key | string | 是 | 第一个交易签名角色的 x-only 公钥。 | 格式："^[0-9a-f]{64}$" |
| registration.descriptor.config.official_key | string | 是 | 第二个交易签名角色的 x-only 公钥；角色名不代表官方实际参与。 | 格式："^[0-9a-f]{64}$" |
| registration.descriptor.config.fee_bps | integer | 是 | 池手续费率，单位基点；30 表示 0.30%。 | 固定值：30 |
| registration.descriptor.config.carrier_units | integer | 是 | 池子载体金额，单位为 TSC 最小单位；全额退出可取回。 | 固定值：100000 |
| registration.descriptor.pool_id | string | 是 | 微池实例 ID，64 位小写十六进制；不是 Asset ID。 | 格式："^[0-9a-f]{64}$" |
| registration.descriptor.script_pubkey | string | 是 | 池子 Taproot 锁定脚本，十六进制字符串。 | 格式："^(?:[0-9a-f]{2})*$" |
| registration.descriptor.trade_script | string | 是 | 池子双签交易分支的脚本字节，十六进制。 | 格式："^(?:[0-9a-f]{2})*$" |
| registration.descriptor.trade_control | string | 是 | 交易支出分支的 Taproot 控制块，十六进制。 | 格式："^(?:[0-9a-f]{2})*$" |
| registration.descriptor.withdrawal_script | string | 是 | LP 独立退出分支的脚本字节，十六进制。 | 格式："^(?:[0-9a-f]{2})*$" |
| registration.descriptor.withdrawal_control | string | 是 | LP 独立退出分支的 Taproot 控制块，十六进制。 | 格式："^(?:[0-9a-f]{2})*$" |
| registration.native | OutPoint | 是 | 池子 TSC 储备的原始入金输出引用。 |  |
| registration.native.txid | string | 是 | 链上交易 ID，64 位小写十六进制；不同于 quote_id 或 request_id。 | 格式："^[0-9a-f]{64}$" |
| registration.native.vout | integer | 是 | 交易输出位置，从 0 开始。 | 最小值：0 |
| registration.asset | OutPoint | 是 | 原始入金交易中的 Asset 储备输出引用。 |  |
| registration.asset.txid | string | 是 | 链上交易 ID，64 位小写十六进制；不同于 quote_id 或 request_id。 | 格式："^[0-9a-f]{64}$" |
| registration.asset.vout | integer | 是 | 交易输出位置，从 0 开始。 | 最小值：0 |
| registration.owner_signature | string | 是 | 旧 v1 的登记 Schnorr 签名；未签名时为空字符串。标准账户 v2 使用 owner_proof，此字段仍为空。 | 格式："^(?:[0-9a-f]{2})*$" |
| registration.owner_proof | OwnerProof | 否 | 标准账户 v2 的 LP 所有权声明证明；与旧 owner_signature 不能同时使用。 |  |
| registration.owner_proof.profile | string | 是 | 钱包输入使用的签名规则标识。 | 固定值："twp:proof:p2wpkh-ecdsa:1" |
| registration.owner_proof.digest | string | 是 | 结构化声明的摘要，64 位小写十六进制。 | 格式："^[0-9a-f]{64}$" |
| registration.owner_proof.envelope | object | 是 | 钱包签署的完整 TWP 声明信封；须保留原对象，不能修改账户、链或声明内容。 |  |
| registration.owner_proof.proof | object | 是 | 账户声明的公钥及 ECDSA 签名。 | 不接受未知字段 |
| registration.owner_proof.proof.publicKey | string | 是 | 钱包账户的压缩 secp256k1 公钥，十六进制。 | 格式："^(?:[0-9a-f]{2})*$" |
| registration.owner_proof.proof.signature | string | 是 | 结构化声明的 ECDSA 签名，十六进制。 | 格式："^(?:[0-9a-f]{2})*$" |

响应 200：返回以下 JSON 对象；交易的最终结果以 state 和链上确认状态为准。

| 字段 | 类型 | 必定出现 | 说明 | 约束 |
| --- | --- | --- | --- | --- |
| quote_id | string | 是 | 报价与后续操作 ID；用于 execute 和 operations，不是交易 txid。 | 格式："^[0-9a-f]{64}$" |
| txid | string | 是 | 链上交易 ID，64 位小写十六进制；不同于 quote_id 或 request_id。 | 格式："^[0-9a-f]{64}$" |
| state | string | 是 | submitting 处理签名或广播；pending 已广播待确认；confirmed 已确认；rechecking 重组后重新检查。 | 可选值：["submitting", "pending", "confirmed", "rechecking"] |
| error | string / null | 是 | 错误说明；无错误时为 null，交易状态仍以 state 为准。 |  |
| backup | RecoveryFile / null | 是 | 新池的公开恢复资料；没有新池时为 null，不包含私钥。 |  |
| backup.schema | string | 是 | 此对象的序列化版本标识。 | 可选值：["tensorcash-micro-pool-wallet-v1", "tensorcash-micro-pool-wallet-v2"] |
| backup.owner_derivation | string | 是 | 退出账户或密钥的派生标识；旧 v1 与标准账户 v2 不可混用。 | 可选值：["hkdf-sha256-bip32-master-v1", "standard-account-v1"] |
| backup.actor | string | 是 | 操作账户在当前网络的 P2WPKH 地址；仅提供地址不会授权花费。 |  |
| backup.registration | Registration | 是 | 新池登记资料或资产注册交易；结构由所在接口定义。 |  |
| backup.registration.descriptor | PoolDescriptor | 是 | 包含池子参数、脚本及退出分支的完整公开描述。 |  |
| backup.registration.descriptor.config | PoolConfig | 是 | 池子脚本绑定的公开参数。 |  |
| backup.registration.descriptor.config.version | integer | 是 | 该对象协议格式版本。 | 固定值：1 |
| backup.registration.descriptor.config.genesis | string | 是 | 当前网络的创世区块哈希，64 位小写十六进制。 | 格式："^[0-9a-f]{64}$" |
| backup.registration.descriptor.config.nonce | string | 是 | 新池随机数，32 字节小写十六进制；不能复用创建不同实例。 | 格式："^[0-9a-f]{64}$" |
| backup.registration.descriptor.config.asset_id | string | 是 | 资产的链上 ID，64 位小写十六进制；只在对应网络有效。 | 格式："^[0-9a-f]{64}$" |
| backup.registration.descriptor.config.owner_key | string | 是 | 池所有者退出公钥，32 字节 x-only 公钥，不是私钥。 | 格式："^[0-9a-f]{64}$" |
| backup.registration.descriptor.config.operator_key | string | 是 | 第一个交易签名角色的 x-only 公钥。 | 格式："^[0-9a-f]{64}$" |
| backup.registration.descriptor.config.official_key | string | 是 | 第二个交易签名角色的 x-only 公钥；角色名不代表官方实际参与。 | 格式："^[0-9a-f]{64}$" |
| backup.registration.descriptor.config.fee_bps | integer | 是 | 池手续费率，单位基点；30 表示 0.30%。 | 固定值：30 |
| backup.registration.descriptor.config.carrier_units | integer | 是 | 池子载体金额，单位为 TSC 最小单位；全额退出可取回。 | 固定值：100000 |
| backup.registration.descriptor.pool_id | string | 是 | 微池实例 ID，64 位小写十六进制；不是 Asset ID。 | 格式："^[0-9a-f]{64}$" |
| backup.registration.descriptor.script_pubkey | string | 是 | 池子 Taproot 锁定脚本，十六进制字符串。 | 格式："^(?:[0-9a-f]{2})*$" |
| backup.registration.descriptor.trade_script | string | 是 | 池子双签交易分支的脚本字节，十六进制。 | 格式："^(?:[0-9a-f]{2})*$" |
| backup.registration.descriptor.trade_control | string | 是 | 交易支出分支的 Taproot 控制块，十六进制。 | 格式："^(?:[0-9a-f]{2})*$" |
| backup.registration.descriptor.withdrawal_script | string | 是 | LP 独立退出分支的脚本字节，十六进制。 | 格式："^(?:[0-9a-f]{2})*$" |
| backup.registration.descriptor.withdrawal_control | string | 是 | LP 独立退出分支的 Taproot 控制块，十六进制。 | 格式："^(?:[0-9a-f]{2})*$" |
| backup.registration.native | OutPoint | 是 | 池子 TSC 储备的原始入金输出引用。 |  |
| backup.registration.native.txid | string | 是 | 链上交易 ID，64 位小写十六进制；不同于 quote_id 或 request_id。 | 格式："^[0-9a-f]{64}$" |
| backup.registration.native.vout | integer | 是 | 交易输出位置，从 0 开始。 | 最小值：0 |
| backup.registration.asset | OutPoint | 是 | 原始入金交易中的 Asset 储备输出引用。 |  |
| backup.registration.asset.txid | string | 是 | 链上交易 ID，64 位小写十六进制；不同于 quote_id 或 request_id。 | 格式："^[0-9a-f]{64}$" |
| backup.registration.asset.vout | integer | 是 | 交易输出位置，从 0 开始。 | 最小值：0 |
| backup.registration.owner_signature | string | 是 | 旧 v1 的登记 Schnorr 签名；未签名时为空字符串。标准账户 v2 使用 owner_proof，此字段仍为空。 | 格式："^(?:[0-9a-f]{2})*$" |
| backup.registration.owner_proof | OwnerProof | 否 | 标准账户 v2 的 LP 所有权声明证明；与旧 owner_signature 不能同时使用。 |  |
| backup.registration.owner_proof.profile | string | 是 | 钱包输入使用的签名规则标识。 | 固定值："twp:proof:p2wpkh-ecdsa:1" |
| backup.registration.owner_proof.digest | string | 是 | 结构化声明的摘要，64 位小写十六进制。 | 格式："^[0-9a-f]{64}$" |
| backup.registration.owner_proof.envelope | object | 是 | 钱包签署的完整 TWP 声明信封；须保留原对象，不能修改账户、链或声明内容。 |  |
| backup.registration.owner_proof.proof | object | 是 | 账户声明的公钥及 ECDSA 签名。 | 不接受未知字段 |
| backup.registration.owner_proof.proof.publicKey | string | 是 | 钱包账户的压缩 secp256k1 公钥，十六进制。 | 格式："^(?:[0-9a-f]{2})*$" |
| backup.registration.owner_proof.proof.signature | string | 是 | 结构化声明的 ECDSA 签名，十六进制。 | 格式："^(?:[0-9a-f]{2})*$" |
| backup.owner_public_key | string | 否 | v2 恢复文件中的原钱包账户压缩公钥。 |  |
| backup.account_id | string | 否 | v2 恢复文件中原钱包账户的 script: 标识。 |  |
| backup.funding_transaction | string | 否 | v2 签名前保存的原始入金交易字节，用于恢复校验；服务端已登记备份可能省略。 | 格式："^(?:[0-9a-f]{2})*$" |
| transaction | SignedTransaction / null | 否 | 原始交易格式与字节，是否完整签名由本接口阶段决定。 |  |
| transaction.schema | string | 是 | 此对象的序列化版本标识。 | 固定值："tern-signed-transaction-v1" |
| transaction.genesis | string | 是 | 当前网络的创世区块哈希，64 位小写十六进制。 | 格式："^[0-9a-f]{64}$" |
| transaction.quote_id | string | 是 | 报价与后续操作 ID；用于 execute 和 operations，不是交易 txid。 | 格式："^[0-9a-f]{64}$" |
| transaction.txid | string | 是 | 链上交易 ID，64 位小写十六进制；不同于 quote_id 或 request_id。 | 格式："^[0-9a-f]{64}$" |
| transaction.tx_hex | string | 是 | 原始 TensorCash 交易字节，十六进制；须保留完整签名版本以供恢复。 | 最短字符数：2；格式："^(?:[0-9a-f]{2})*$" |

错误响应：

| HTTP 状态 | 含义 |
| --- | --- |
| 400 | 请求参数、资产策略或签名无效。 |
| 404 | 未找到资产、池子或操作记录。 |
| 409 | 审核过期、交易内容改变、价格不满足限制或分页游标失效。 |
| 413 | 请求体超过允许字节数。 |
| 415 | 请求 Content-Type 不受支持。 |
| 422 | JSON 字段格式无效或包含未知字段。 |
| 429 | 请求频率或容量达到上限，按 Retry-After 秒数退避。 |
| 503 | 节点、签名服务、索引或上游暂不可用，按 Retry-After 秒数退避。 |

### GET /operations/{id}

查询交易操作状态。路径 id 为 quote_id，不是链上 txid。只读，不重广播，约每 5 秒更新；已确认记录可能因重组变为 rechecking。不返回完整签名交易。

参数：

| 字段 | 位置 | 类型 | 必填 | 说明与约束 |
| --- | --- | --- | --- | --- |
| id | path | string | 是 | 报价 quote_id，64 位小写十六进制。 格式："^[0-9a-f]{64}$" |

响应 200：返回以下 JSON 对象；交易的最终结果以 state 和链上确认状态为准。

| 字段 | 类型 | 必定出现 | 说明 | 约束 |
| --- | --- | --- | --- | --- |
| quote_id | string | 是 | 报价与后续操作 ID；用于 execute 和 operations，不是交易 txid。 | 格式："^[0-9a-f]{64}$" |
| kind | string | 是 | 操作类型：创建、添加、追加、兑换或移除流动性。 | 可选值：["create_pool", "add_liquidity", "increase_liquidity", "swap", "remove_liquidity"] |
| actor | string | 是 | 操作账户在当前网络的 P2WPKH 地址；仅提供地址不会授权花费。 |  |
| state | string | 是 | quoted 待签名提交；expired 未提交已过期；submitting 处理中；pending 已广播待确认；confirmed 已确认；rechecking 重组后重新检查。 | 可选值：["quoted", "expired", "submitting", "pending", "confirmed", "rechecking"] |
| txid | string / null | 是 | 链上交易 ID，64 位小写十六进制；不同于 quote_id 或 request_id。 | 格式："^[0-9a-f]{64}$" |
| error | string / null | 是 | 错误说明；无错误时为 null，交易状态仍以 state 为准。 |  |
| created_at | integer | 是 | 操作记录创建时间，UTC Unix 秒。 | 最小值：0 |
| expires_at | integer | 是 | 失效时间；交易和审核为 UTC Unix 秒，美元参考价为毫秒。 | 最小值：0 |
| amounts | OperationAmounts | 是 | 本次操作的 TSC、Asset 数量和操作方向。 |  |
| amounts.tsc_units | string | 是 | TSC 最小单位整数字符串；1 TSC = 100000000。 | 格式："^[0-9]+$" |
| amounts.asset_units | string | 是 | 非 TSC 资产数量，按该资产精度表示的最小单位整数字符串。 | 格式："^[0-9]+$" |
| amounts.tsc_in | boolean | 是 | 兑换方向；true 卖出 TSC 买 Asset，false 卖出 Asset 买 TSC。 |  |
| amounts.withdraw_bps | integer | 是 | 提款比例，1–10000 基点；10000 全额退出，部分退出会生成继任池。 | 最小值：0 |
| created_pool_id | string / null | 是 | 本次新池 ID；没有新池时为 null。 | 格式："^[0-9a-f]{64}$" |
| retired_pool_id | string / null | 是 | 退出或替换的旧池 ID；没有旧池时为 null。 | 格式："^[0-9a-f]{64}$" |

错误响应：

| HTTP 状态 | 含义 |
| --- | --- |
| 400 | 请求参数、资产策略或签名无效。 |
| 404 | 未找到资产、池子或操作记录。 |
| 409 | 审核过期、交易内容改变、价格不满足限制或分页游标失效。 |
| 413 | 请求体超过允许字节数。 |
| 415 | 请求 Content-Type 不受支持。 |
| 422 | JSON 字段格式无效或包含未知字段。 |
| 429 | 请求频率或容量达到上限，按 Retry-After 秒数退避。 |
| 503 | 节点、签名服务、索引或上游暂不可用，按 Retry-After 秒数退避。 |

### GET /pools/{id}/backup

读取池子恢复资料。路径 id 为 Pool ID。返回公开恢复资料，不包含私钥；独立退出还需要原钱包及可用链查询和广播服务。

参数：

| 字段 | 位置 | 类型 | 必填 | 说明与约束 |
| --- | --- | --- | --- | --- |
| id | path | string | 是 | 微池 Pool ID，64 位小写十六进制。 格式："^[0-9a-f]{64}$" |

响应 200：返回以下 JSON 对象；交易的最终结果以 state 和链上确认状态为准。

| 字段 | 类型 | 必定出现 | 说明 | 约束 |
| --- | --- | --- | --- | --- |
| schema | string | 是 | 此对象的序列化版本标识。 | 可选值：["tensorcash-micro-pool-wallet-v1", "tensorcash-micro-pool-wallet-v2"] |
| owner_derivation | string | 是 | 退出账户或密钥的派生标识；旧 v1 与标准账户 v2 不可混用。 | 可选值：["hkdf-sha256-bip32-master-v1", "standard-account-v1"] |
| actor | string | 是 | 操作账户在当前网络的 P2WPKH 地址；仅提供地址不会授权花费。 |  |
| registration | Registration | 是 | 新池登记资料或资产注册交易；结构由所在接口定义。 |  |
| registration.descriptor | PoolDescriptor | 是 | 包含池子参数、脚本及退出分支的完整公开描述。 |  |
| registration.descriptor.config | PoolConfig | 是 | 池子脚本绑定的公开参数。 |  |
| registration.descriptor.config.version | integer | 是 | 该对象协议格式版本。 | 固定值：1 |
| registration.descriptor.config.genesis | string | 是 | 当前网络的创世区块哈希，64 位小写十六进制。 | 格式："^[0-9a-f]{64}$" |
| registration.descriptor.config.nonce | string | 是 | 新池随机数，32 字节小写十六进制；不能复用创建不同实例。 | 格式："^[0-9a-f]{64}$" |
| registration.descriptor.config.asset_id | string | 是 | 资产的链上 ID，64 位小写十六进制；只在对应网络有效。 | 格式："^[0-9a-f]{64}$" |
| registration.descriptor.config.owner_key | string | 是 | 池所有者退出公钥，32 字节 x-only 公钥，不是私钥。 | 格式："^[0-9a-f]{64}$" |
| registration.descriptor.config.operator_key | string | 是 | 第一个交易签名角色的 x-only 公钥。 | 格式："^[0-9a-f]{64}$" |
| registration.descriptor.config.official_key | string | 是 | 第二个交易签名角色的 x-only 公钥；角色名不代表官方实际参与。 | 格式："^[0-9a-f]{64}$" |
| registration.descriptor.config.fee_bps | integer | 是 | 池手续费率，单位基点；30 表示 0.30%。 | 固定值：30 |
| registration.descriptor.config.carrier_units | integer | 是 | 池子载体金额，单位为 TSC 最小单位；全额退出可取回。 | 固定值：100000 |
| registration.descriptor.pool_id | string | 是 | 微池实例 ID，64 位小写十六进制；不是 Asset ID。 | 格式："^[0-9a-f]{64}$" |
| registration.descriptor.script_pubkey | string | 是 | 池子 Taproot 锁定脚本，十六进制字符串。 | 格式："^(?:[0-9a-f]{2})*$" |
| registration.descriptor.trade_script | string | 是 | 池子双签交易分支的脚本字节，十六进制。 | 格式："^(?:[0-9a-f]{2})*$" |
| registration.descriptor.trade_control | string | 是 | 交易支出分支的 Taproot 控制块，十六进制。 | 格式："^(?:[0-9a-f]{2})*$" |
| registration.descriptor.withdrawal_script | string | 是 | LP 独立退出分支的脚本字节，十六进制。 | 格式："^(?:[0-9a-f]{2})*$" |
| registration.descriptor.withdrawal_control | string | 是 | LP 独立退出分支的 Taproot 控制块，十六进制。 | 格式："^(?:[0-9a-f]{2})*$" |
| registration.native | OutPoint | 是 | 池子 TSC 储备的原始入金输出引用。 |  |
| registration.native.txid | string | 是 | 链上交易 ID，64 位小写十六进制；不同于 quote_id 或 request_id。 | 格式："^[0-9a-f]{64}$" |
| registration.native.vout | integer | 是 | 交易输出位置，从 0 开始。 | 最小值：0 |
| registration.asset | OutPoint | 是 | 原始入金交易中的 Asset 储备输出引用。 |  |
| registration.asset.txid | string | 是 | 链上交易 ID，64 位小写十六进制；不同于 quote_id 或 request_id。 | 格式："^[0-9a-f]{64}$" |
| registration.asset.vout | integer | 是 | 交易输出位置，从 0 开始。 | 最小值：0 |
| registration.owner_signature | string | 是 | 旧 v1 的登记 Schnorr 签名；未签名时为空字符串。标准账户 v2 使用 owner_proof，此字段仍为空。 | 格式："^(?:[0-9a-f]{2})*$" |
| registration.owner_proof | OwnerProof | 否 | 标准账户 v2 的 LP 所有权声明证明；与旧 owner_signature 不能同时使用。 |  |
| registration.owner_proof.profile | string | 是 | 钱包输入使用的签名规则标识。 | 固定值："twp:proof:p2wpkh-ecdsa:1" |
| registration.owner_proof.digest | string | 是 | 结构化声明的摘要，64 位小写十六进制。 | 格式："^[0-9a-f]{64}$" |
| registration.owner_proof.envelope | object | 是 | 钱包签署的完整 TWP 声明信封；须保留原对象，不能修改账户、链或声明内容。 |  |
| registration.owner_proof.proof | object | 是 | 账户声明的公钥及 ECDSA 签名。 | 不接受未知字段 |
| registration.owner_proof.proof.publicKey | string | 是 | 钱包账户的压缩 secp256k1 公钥，十六进制。 | 格式："^(?:[0-9a-f]{2})*$" |
| registration.owner_proof.proof.signature | string | 是 | 结构化声明的 ECDSA 签名，十六进制。 | 格式："^(?:[0-9a-f]{2})*$" |
| owner_public_key | string | 否 | v2 恢复文件中的原钱包账户压缩公钥。 |  |
| account_id | string | 否 | v2 恢复文件中原钱包账户的 script: 标识。 |  |
| funding_transaction | string | 否 | v2 签名前保存的原始入金交易字节，用于恢复校验；服务端已登记备份可能省略。 | 格式："^(?:[0-9a-f]{2})*$" |

错误响应：

| HTTP 状态 | 含义 |
| --- | --- |
| 400 | 请求参数、资产策略或签名无效。 |
| 404 | 未找到资产、池子或操作记录。 |
| 409 | 审核过期、交易内容改变、价格不满足限制或分页游标失效。 |
| 413 | 请求体超过允许字节数。 |
| 415 | 请求 Content-Type 不受支持。 |
| 422 | JSON 字段格式无效或包含未知字段。 |
| 429 | 请求频率或容量达到上限，按 Retry-After 秒数退避。 |
| 503 | 节点、签名服务、索引或上游暂不可用，按 Retry-After 秒数退避。 |

## 行情

### GET /market

查询行情目录。返回网络、索引状态、支持的 K 线周期、资产和池子目录；行情仅包含已确认且已索引的数据。

响应 200：返回以下 JSON 对象；交易的最终结果以 state 和链上确认状态为准。

| 字段 | 类型 | 必定出现 | 说明 | 约束 |
| --- | --- | --- | --- | --- |
| api_version | string | 是 | 接口版本。 | 固定值："1" |
| genesis | string | 是 | 当前网络的创世区块哈希，64 位小写十六进制。 |  |
| index | IndexStatus | 是 | 行情索引进度与同步状态；数据不完整时不要当作完整实时行情。 |  |
| index.indexed_height | integer / null | 是 | 索引已处理到的区块高度。 |  |
| index.indexed_hash | string / null | 是 | 索引已处理到的区块哈希。 |  |
| index.core_height | integer / null | 是 | 节点已验证的区块高度。 |  |
| index.core_headers | integer / null | 是 | 节点已知的最高区块头高度。 |  |
| index.node_ready | boolean | 是 | 节点是否已完成同步并可处理交易。 |  |
| index.caught_up | boolean | 是 | 行情索引是否已追上节点当前高度。 |  |
| index.last_checked_at | integer / null | 是 | 最近一次索引检查时间，UTC Unix 毫秒。 |  |
| index.error | string / null | 是 | 错误说明；无错误时为 null，交易状态仍以 state 为准。 |  |
| index.revision | integer | 是 | 行情索引修订号；用于识别重建或状态变化。 | 最小值：0 |
| time_unit | string | 是 | 时间戳单位，行情与参考价为 unix_ms。 | 固定值："unix_ms" |
| price_decimals | integer | 是 | 行情内部计算的价格精度。 | 固定值：72 |
| timestamp_source | string | 是 | 行情时间来源；使用已确认区块时间。 | 固定值："block_time" |
| gap_policy | string | 是 | 无成交周期的处理方式；carry_forward 沿用上一收盘价，成交量为零。 | 固定值："omit" |
| confirmation_policy | string | 是 | 成交纳入行情统计的确认规则。 | 固定值："canonical_block_1_confirmation" |
| fee_basis | string | 是 | 行情手续费统计口径。 | 固定值："pool_reserve_delta_including_lp_fee_excluding_network_fee" |
| reference_asset_id | null | 是 | 历史参考资产 ID；当前统一使用 TSC，返回 null。 |  |
| intervals | string[] | 是 | 支持的 K 线周期列表。 |  |
| assets | object[] | 是 | 当前查询范围内的资产列表。 |  |
| assets[].asset_id | string | 是 | 资产的链上 ID，64 位小写十六进制；只在对应网络有效。 |  |
| assets[].symbol | string | 是 | 资产展示符号；发行时填 3–11 位大写字母数字，首位字母，不加 TRC20. 前缀。 |  |
| assets[].precision | integer | 是 | 资产小数位数；TSC 为 8，其他资产以链上登记值为准。 | 最小值：0 |
| pools | object[] | 是 | 平台登记的池子列表。 |  |
| pools[].pool_id | string | 是 | 微池实例 ID，64 位小写十六进制；不是 Asset ID。 |  |
| pools[].asset_id | string | 是 | 资产的链上 ID，64 位小写十六进制；只在对应网络有效。 |  |

错误响应：

| HTTP 状态 | 含义 |
| --- | --- |
| 400 | 请求参数、资产策略或签名无效。 |
| 404 | 未找到资产、池子或操作记录。 |
| 409 | 审核过期、交易内容改变、价格不满足限制或分页游标失效。 |
| 503 | 节点、签名服务、索引或上游暂不可用，按 Retry-After 秒数退避。 |
| 429 | 请求频率或容量达到上限，按 Retry-After 秒数退避。 |

### GET /pools/{id}/ticker

查询池子最新行情。返回当前储备价、储备、最近成交、24 小时统计、仓位手续费和 APR；交易后储备价与整笔成交均价是不同字段。

参数：

| 字段 | 位置 | 类型 | 必填 | 说明与约束 |
| --- | --- | --- | --- | --- |
| id | path | string | 是 | 微池 Pool ID，64 位小写十六进制。 格式："^[0-9a-f]{64}$" |
| quote | query | string | 否 | 计价币种；当前只支持 TSC。 可选值：["TSC"]；默认值："TSC" |

响应 200：返回以下 JSON 对象；交易的最终结果以 state 和链上确认状态为准。

| 字段 | 类型 | 必定出现 | 说明 | 约束 |
| --- | --- | --- | --- | --- |
| api_version | string | 是 | 接口版本。 | 固定值："1" |
| genesis | string | 是 | 当前网络的创世区块哈希，64 位小写十六进制。 |  |
| index | IndexStatus | 是 | 行情索引进度与同步状态；数据不完整时不要当作完整实时行情。 |  |
| index.indexed_height | integer / null | 是 | 索引已处理到的区块高度。 |  |
| index.indexed_hash | string / null | 是 | 索引已处理到的区块哈希。 |  |
| index.core_height | integer / null | 是 | 节点已验证的区块高度。 |  |
| index.core_headers | integer / null | 是 | 节点已知的最高区块头高度。 |  |
| index.node_ready | boolean | 是 | 节点是否已完成同步并可处理交易。 |  |
| index.caught_up | boolean | 是 | 行情索引是否已追上节点当前高度。 |  |
| index.last_checked_at | integer / null | 是 | 最近一次索引检查时间，UTC Unix 毫秒。 |  |
| index.error | string / null | 是 | 错误说明；无错误时为 null，交易状态仍以 state 为准。 |  |
| index.revision | integer | 是 | 行情索引修订号；用于识别重建或状态变化。 | 最小值：0 |
| time_unit | string | 是 | 时间戳单位，行情与参考价为 unix_ms。 | 固定值："unix_ms" |
| price_decimals | integer | 是 | 行情内部计算的价格精度。 | 固定值：72 |
| timestamp_source | string | 是 | 行情时间来源；使用已确认区块时间。 | 固定值："block_time" |
| gap_policy | string | 是 | 无成交周期的处理方式；carry_forward 沿用上一收盘价，成交量为零。 | 固定值："omit" |
| confirmation_policy | string | 是 | 成交纳入行情统计的确认规则。 | 固定值："canonical_block_1_confirmation" |
| fee_basis | string | 是 | 行情手续费统计口径。 | 固定值："pool_reserve_delta_including_lp_fee_excluding_network_fee" |
| reference_asset_id | null | 是 | 历史参考资产 ID；当前统一使用 TSC，返回 null。 |  |
| pool_id | string | 是 | 微池实例 ID，64 位小写十六进制；不是 Asset ID。 |  |
| asset_id | string | 是 | 资产的链上 ID，64 位小写十六进制；只在对应网络有效。 |  |
| base_symbol | string | 是 | 被定价资产的展示符号。 |  |
| base_precision | integer | 是 | 基础资产的小数位数。 | 最小值：0 |
| quote_symbol | string | 是 | 计价符号；当前为 TSC。 | 可选值：["TSC"] |
| quote_asset_id | string / null | 是 | 计价资产 ID；TSC 是原生币，没有非 TSC Asset ID。 |  |
| coverage | object | 是 | 本池行情记录的定价覆盖情况。 |  |
| coverage.total_trades | integer | 是 | 该池已索引的总成交笔数。 | 最小值：0 |
| coverage.priced_trades | integer | 是 | 具备所选计价币种价格的成交数量。 | 最小值：0 |
| coverage.unpriced_trades | integer | 是 | 缺少计价信息的成交笔数；不等于没有成交。 | 最小值：0 |
| pool_price | string / null | 是 | 当前已确认储备比价格，单位 TSC/Asset；不是最近一笔成交均价。 |  |
| reference_pool_ids | string[] | 是 | 历史换算或定价涉及的参考池 ID 列表。 |  |
| reserves | object / null | 是 | 该时点池子持有的 TSC 与 Asset 储备。 |  |
| last_trade | Trade / null | 是 | 最近一笔已确认成交；没有成交时为 null。 |  |
| last_trade.id | string | 是 | 成交记录的稳定 ID，用于去重；同一交易可包含多个池成交。 |  |
| last_trade.pool_id | string | 是 | 微池实例 ID，64 位小写十六进制；不是 Asset ID。 |  |
| last_trade.txid | string | 是 | 链上交易 ID，64 位小写十六进制；不同于 quote_id 或 request_id。 |  |
| last_trade.block_hash | string | 是 | 成交所在区块的哈希，64 位小写十六进制。 |  |
| last_trade.native_base_units | string | 是 | 本次成交的基础资产最小单位数量。 |  |
| last_trade.native_quote_units | string | 是 | 本次成交的计价资产最小单位数量。 |  |
| last_trade.block_height | integer | 是 | 成交所在区块高度。 | 最小值：0 |
| last_trade.transaction_index | integer | 是 | 交易在区块中的位置，从 0 开始。 | 最小值：0 |
| last_trade.input_index | integer | 是 | 池子输入在交易中的位置，从 0 开始。 | 最小值：0 |
| last_trade.time | integer | 是 | 成交所在区块时间，UTC Unix 毫秒。 | 最小值：0 |
| last_trade.side | string | 是 | 相对于基础 Asset 的买入或卖出方向。 | 可选值：["buy", "sell"] |
| last_trade.price | string / null | 是 | 本笔成交均价，单位 TSC/Asset；计价成交量除以基础资产成交量，不是交易后池价。 |  |
| last_trade.base_volume | string / null | 是 | 基础资产成交量，按资产单位表示的十进制字符串。 |  |
| last_trade.quote_volume | string / null | 是 | 计价资产成交量，单位 TSC，十进制字符串。 |  |
| last_trade.quote_source | object / null | 是 | 该成交的计价来源。 |  |
| last_trade.pool_price_before | string / null | 是 | 兑换前储备比价格，单位 TSC/Asset；缺少记录时为 null。 |  |
| last_trade.reserves_before | object / null | 是 | 兑换前实际储备的最小单位数量，不包含可退载体。 |  |
| last_trade.reserves_before.tsc_units | string | 是 | TSC 最小单位整数字符串；1 TSC = 100000000。 |  |
| last_trade.reserves_before.asset_units | string | 是 | 非 TSC 资产数量，按该资产精度表示的最小单位整数字符串。 |  |
| last_trade.pool_price_after | string / null | 是 | 兑换后储备比价格，单位 TSC/Asset；缺少记录时为 null。 |  |
| last_trade.reserves_after | object / null | 是 | 兑换后实际储备的最小单位数量，不包含可退载体。 |  |
| last_trade.reserves_after.tsc_units | string | 是 | TSC 最小单位整数字符串；1 TSC = 100000000。 |  |
| last_trade.reserves_after.asset_units | string | 是 | 非 TSC 资产数量，按该资产精度表示的最小单位整数字符串。 |  |
| stats_24h | object | 是 | 过去 24 小时成交量、笔数及时间边界。 |  |
| stats_24h.start_time | integer | 是 | 统计区间起始时间，UTC Unix 毫秒。 | 最小值：0 |
| stats_24h.end_time | integer | 是 | 统计或查询区间结束时间，UTC Unix 毫秒。 | 最小值：0 |
| stats_24h.base_volume | string | 是 | 基础资产成交量，按资产单位表示的十进制字符串。 |  |
| stats_24h.quote_volume | string | 是 | 计价资产成交量，单位 TSC，十进制字符串。 |  |
| stats_24h.trade_count | integer | 是 | 该记录或区间的成交笔数。 | 最小值：0 |
| stats_24h.unpriced_trade_count | integer | 是 | 统计期内缺少计价数据的成交数量；非零时成交量统计可能不完整。 | 最小值：0 |
| tvl | string / null | 是 | 池子总储备价值，单位 TSC，不包含载体；缺少价格时为 null。 |  |
| position | PositionAccounting / null | 是 | 单实例仓位的初始投入、存续时间和手续费；入金尚未索引时为 null。 |  |
| position.opened_at | integer | 是 | 仓位入金确认的区块时间，UTC Unix 毫秒。 |  |
| position.funding_txid | string | 是 | 仓位最初入金交易的 ID。 |  |
| position.initial_deposit | object | 是 | 该仓位最初投入的 TSC 和 Asset 数量。 |  |
| position.initial_deposit.tsc | string | 是 | 初始投入的 TSC 数量，不含载体金额。 |  |
| position.initial_deposit.asset | string | 是 | 初始投入的 Asset 数量，按该资产单位表示。 |  |
| position.closed_at | integer / null | 是 | 仓位关闭的区块时间，UTC Unix 毫秒；未关闭为 null。 |  |
| position.exit_txid | string / null | 是 | 关闭仓位的交易 ID；未退出时为 null。 |  |
| position.successor_pool_ids | string[] | 是 | 退出交易建立的同资产继任池 ID 列表；手续费历史不会直接复制。 |  |
| position.fees | PositionFees | 是 | 仓位累计的 TSC 和 Asset 手续费，留在储备内。 |  |
| position.fees.tsc | string | 是 | TSC 数量，按 TSC 单位表示的十进制字符串。 |  |
| position.fees.asset | string | 是 | 资产手续费，按该资产单位表示的十进制字符串；包含记账精度，不是可另行领取的余额。 |  |
| position.fees.trade_count | integer | 是 | 该记录或区间的成交笔数。 | 最小值：0 |
| position.fees_24h | PositionFees | 是 | 近 24 小时的 TSC 和 Asset 手续费，留在储备内。 |  |
| position.fees_24h.tsc | string | 是 | TSC 数量，按 TSC 单位表示的十进制字符串。 |  |
| position.fees_24h.asset | string | 是 | 资产手续费，按该资产单位表示的十进制字符串；包含记账精度，不是可另行领取的余额。 |  |
| position.fees_24h.trade_count | integer | 是 | 该记录或区间的成交笔数。 | 最小值：0 |
| position.fee_bps | integer | 是 | 池手续费率，单位基点；30 表示 0.30%。 | 固定值：30 |
| position.fee_accounting | string | 是 | 手续费数量的统计方法。 | 固定值："nominal_input_fee_retained_in_reserves" |
| position.carrier_tsc | string | 是 | 仓位锁定的载体金额，单位 TSC；不计入池子 TVL。 | 固定值："0.001" |
| fee_apr_24h | FeeApr | 是 | 近 24 小时手续费年化估算；不是净利润或收益承诺。 |  |
| fee_apr_24h.status | string | 是 | 能力、交易或统计结果状态；对象和枚举含义见类型。 | 可选值：["available", "unconfirmed", "closed", "insufficient_liquidity", "index_unavailable", "insufficient_history"] |
| fee_apr_24h.percent | string / null | 是 | 手续费 APR，百分数的十进制字符串；例如 10.95 表示 10.95%；缺少完整数据时为 null。 | 格式："^\\d+(\\.\\d+)?$" |
| fee_apr_24h.fee_value_tsc | string / null | 是 | 近 24 小时手续费按当前储备价换算的 TSC 价值，不含矿工费、载体或舍入尘埃。 | 格式："^\\d+(\\.\\d+)?$" |
| fee_apr_24h.tvl_tsc | string / null | 是 | 当前两种储备按同一池价换算的 TSC 总价值，不含载体。 | 格式："^\\d+(\\.\\d+)?$" |
| fee_apr_24h.start_time | integer | 是 | 统计区间起始时间，UTC Unix 毫秒。 | 最小值：0 |
| fee_apr_24h.end_time | integer | 是 | 统计或查询区间结束时间，UTC Unix 毫秒。 | 最小值：0 |
| fee_apr_24h.annualization_days | integer | 是 | 年化天数；手续费 APR 使用 365 天。 | 固定值：365 |
| fee_apr_24h.valuation | string | 是 | 手续费或仓位的估值方法。 | 固定值："current_pool_price" |
| fee_apr_24h.basis | string | 是 | 统计或计算采用的口径。 | 固定值："fees_only" |
| logical_position | LogicalPosition / null | 否 | 跨微池实例延续的同一所有者仓位信息。 |  |
| logical_position.position_id | string | 是 | 延续追加和部分退出历史的逻辑仓位 ID。 |  |
| logical_position.instance_pool_id | string | 是 | 该逻辑仓位当前对应的微池实例 ID。 |  |
| logical_position.pool_ids | string[] | 是 | 参与此记录的微池实例 ID 列表。 |  |
| logical_position.opened_at | integer | 是 | 仓位入金确认的区块时间，UTC Unix 毫秒。 |  |
| logical_position.closed_at | integer / null | 是 | 仓位关闭的区块时间，UTC Unix 毫秒；未关闭为 null。 |  |
| logical_position.initial_deposit | object | 是 | 该仓位最初投入的 TSC 和 Asset 数量。 |  |
| logical_position.fees | object | 是 | 仓位累计的 TSC 和 Asset 手续费，留在储备内。 |  |
| logical_position.fees_24h | object | 是 | 近 24 小时的 TSC 和 Asset 手续费，留在储备内。 |  |
| logical_position.history | object[] | 是 | 该逻辑仓位的追加、替换与退出历史。 |  |
| logical_position.fee_apr_24h | FeeApr | 是 | 近 24 小时手续费年化估算；不是净利润或收益承诺。 |  |
| logical_position.fee_apr_24h.status | string | 是 | 能力、交易或统计结果状态；对象和枚举含义见类型。 | 可选值：["available", "unconfirmed", "closed", "insufficient_liquidity", "index_unavailable", "insufficient_history"] |
| logical_position.fee_apr_24h.percent | string / null | 是 | 手续费 APR，百分数的十进制字符串；例如 10.95 表示 10.95%；缺少完整数据时为 null。 | 格式："^\\d+(\\.\\d+)?$" |
| logical_position.fee_apr_24h.fee_value_tsc | string / null | 是 | 近 24 小时手续费按当前储备价换算的 TSC 价值，不含矿工费、载体或舍入尘埃。 | 格式："^\\d+(\\.\\d+)?$" |
| logical_position.fee_apr_24h.tvl_tsc | string / null | 是 | 当前两种储备按同一池价换算的 TSC 总价值，不含载体。 | 格式："^\\d+(\\.\\d+)?$" |
| logical_position.fee_apr_24h.start_time | integer | 是 | 统计区间起始时间，UTC Unix 毫秒。 | 最小值：0 |
| logical_position.fee_apr_24h.end_time | integer | 是 | 统计或查询区间结束时间，UTC Unix 毫秒。 | 最小值：0 |
| logical_position.fee_apr_24h.annualization_days | integer | 是 | 年化天数；手续费 APR 使用 365 天。 | 固定值：365 |
| logical_position.fee_apr_24h.valuation | string | 是 | 手续费或仓位的估值方法。 | 固定值："current_pool_price" |
| logical_position.fee_apr_24h.basis | string | 是 | 统计或计算采用的口径。 | 固定值："fees_only" |

错误响应：

| HTTP 状态 | 含义 |
| --- | --- |
| 400 | 请求参数、资产策略或签名无效。 |
| 404 | 未找到资产、池子或操作记录。 |
| 409 | 审核过期、交易内容改变、价格不满足限制或分页游标失效。 |
| 503 | 节点、签名服务、索引或上游暂不可用，按 Retry-After 秒数退避。 |
| 429 | 请求频率或容量达到上限，按 Retry-After 秒数退避。 |

### GET /pools/{id}/candles

查询池子 K 线。按 interval 查询 OHLCV。时间为 UTC Unix 毫秒；price_basis 区分储备价和成交均价。gap_policy=carry_forward 时空周期沿用前收盘价、成交量为零；每页最多 1000 个周期，以 next_end_time 翻页。

参数：

| 字段 | 位置 | 类型 | 必填 | 说明与约束 |
| --- | --- | --- | --- | --- |
| id | path | string | 是 | 微池 Pool ID，64 位小写十六进制。 格式："^[0-9a-f]{64}$" |
| quote | query | string | 否 | 计价币种；当前只支持 TSC。 可选值：["TSC"]；默认值："TSC" |
| interval | query | string | 否 | K 线周期：1m、5m、15m、30m、1h、4h、1d、1w。 可选值：["1m", "5m", "15m", "30m", "1h", "4h", "1d", "1w"]；默认值："1h" |
| start_time | query | integer | 否 | Inclusive UTC Unix milliseconds; candle open time for candles. 最小值：0 |
| end_time | query | integer | 否 | K 线查询结束时间，UTC Unix 毫秒；不传时查询最新区间。 最小值：0 |
| limit | query | integer | 否 | 本页最多返回的记录数量；默认和上限见约束。 默认值：300；最小值：1；最大值：1000 |
| price_basis | query | string | 否 | spot 为交易后储备价；execution 为成交均价。 可选值：["execution", "spot"]；默认值："execution" |
| gap_policy | query | string | 否 | carry_forward 补齐无成交周期；不传则返回原有稀疏数据。 可选值：["omit", "carry_forward"]；默认值："omit" |

响应 200：返回以下 JSON 对象；交易的最终结果以 state 和链上确认状态为准。

| 字段 | 类型 | 必定出现 | 说明 | 约束 |
| --- | --- | --- | --- | --- |
| api_version | string | 是 | 接口版本。 | 固定值："1" |
| genesis | string | 是 | 当前网络的创世区块哈希，64 位小写十六进制。 |  |
| index | IndexStatus | 是 | 行情索引进度与同步状态；数据不完整时不要当作完整实时行情。 |  |
| index.indexed_height | integer / null | 是 | 索引已处理到的区块高度。 |  |
| index.indexed_hash | string / null | 是 | 索引已处理到的区块哈希。 |  |
| index.core_height | integer / null | 是 | 节点已验证的区块高度。 |  |
| index.core_headers | integer / null | 是 | 节点已知的最高区块头高度。 |  |
| index.node_ready | boolean | 是 | 节点是否已完成同步并可处理交易。 |  |
| index.caught_up | boolean | 是 | 行情索引是否已追上节点当前高度。 |  |
| index.last_checked_at | integer / null | 是 | 最近一次索引检查时间，UTC Unix 毫秒。 |  |
| index.error | string / null | 是 | 错误说明；无错误时为 null，交易状态仍以 state 为准。 |  |
| index.revision | integer | 是 | 行情索引修订号；用于识别重建或状态变化。 | 最小值：0 |
| time_unit | string | 是 | 时间戳单位，行情与参考价为 unix_ms。 | 固定值："unix_ms" |
| price_decimals | integer | 是 | 行情内部计算的价格精度。 | 固定值：72 |
| timestamp_source | string | 是 | 行情时间来源；使用已确认区块时间。 | 固定值："block_time" |
| gap_policy | string | 是 | 无成交周期的处理方式；carry_forward 沿用上一收盘价，成交量为零。 | 可选值：["omit", "carry_forward"] |
| confirmation_policy | string | 是 | 成交纳入行情统计的确认规则。 | 固定值："canonical_block_1_confirmation" |
| fee_basis | string | 是 | 行情手续费统计口径。 | 固定值："pool_reserve_delta_including_lp_fee_excluding_network_fee" |
| reference_asset_id | null | 是 | 历史参考资产 ID；当前统一使用 TSC，返回 null。 |  |
| pool_id | string | 是 | 微池实例 ID，64 位小写十六进制；不是 Asset ID。 |  |
| asset_id | string | 是 | 资产的链上 ID，64 位小写十六进制；只在对应网络有效。 |  |
| base_symbol | string | 是 | 被定价资产的展示符号。 |  |
| base_precision | integer | 是 | 基础资产的小数位数。 | 最小值：0 |
| quote_symbol | string | 是 | 计价符号；当前为 TSC。 | 可选值：["TSC"] |
| quote_asset_id | string / null | 是 | 计价资产 ID；TSC 是原生币，没有非 TSC Asset ID。 |  |
| coverage | object | 是 | 本池行情记录的定价覆盖情况。 |  |
| coverage.total_trades | integer | 是 | 该池已索引的总成交笔数。 | 最小值：0 |
| coverage.priced_trades | integer | 是 | 具备所选计价币种价格的成交数量。 | 最小值：0 |
| coverage.unpriced_trades | integer | 是 | 缺少计价信息的成交笔数；不等于没有成交。 | 最小值：0 |
| interval | string | 是 | K 线周期：1m、5m、15m、30m、1h、4h、1d、1w。 |  |
| has_more | boolean | 是 | 是否还有下一页；继续使用本响应的游标。 |  |
| next_end_time | integer / null | 是 | 下一页 K 线查询的 end_time，UTC Unix 毫秒；无下一页为 null。 |  |
| candles | Candle[] | 是 | 当前页的 K 线列表，按时间排列。 |  |
| candles[].open_time | integer | 是 | K 线周期起始时间，UTC Unix 毫秒。 | 最小值：0 |
| candles[].close_time | integer | 是 | 该 K 线周期的结束时间，UTC Unix 毫秒。 | 最小值：0 |
| candles[].trade_count | integer | 是 | 该记录或区间的成交笔数。 | 最小值：0 |
| candles[].open | string | 是 | 本周期首个价格，单位 TSC/Asset，精确十进制字符串。 |  |
| candles[].high | string | 是 | 本周期最高价格，单位 TSC/Asset，精确十进制字符串。 |  |
| candles[].low | string | 是 | 本周期最低价格，单位 TSC/Asset，精确十进制字符串。 |  |
| candles[].close | string | 是 | 本周期最后价格，单位 TSC/Asset，精确十进制字符串。 |  |
| candles[].base_volume | string | 是 | 基础资产成交量，按资产单位表示的十进制字符串。 |  |
| candles[].quote_volume | string | 是 | 计价资产成交量，单位 TSC，十进制字符串。 |  |
| candles[].is_closed | boolean | 是 | K 线周期是否已结束；未结束的蜡烛仍可能更新。 |  |
| candles[].is_filled | boolean | 否 | 是否为无成交周期的延续价格；true 时 OHLC 沿用前收盘、成交量和笔数为零。 |  |
| candles[].source_open_time | integer | 否 | 延续价格来源的真实 K 线起始时间，UTC Unix 毫秒；真实成交周期等于 open_time。 | 最小值：0 |
| price_basis | string | 是 | spot 使用交易后储备价；execution 使用成交均价。 | 可选值：["execution", "spot"] |
| range_start | integer | 否 | 本页归一化时间范围的起点，含边界，UTC Unix 毫秒；补齐模式返回。 | 最小值：0 |
| range_end | integer | 否 | 本页归一化时间范围的终点，不含边界，UTC Unix 毫秒；补齐模式返回。 | 最小值：0 |

错误响应：

| HTTP 状态 | 含义 |
| --- | --- |
| 400 | 请求参数、资产策略或签名无效。 |
| 404 | 未找到资产、池子或操作记录。 |
| 409 | 审核过期、交易内容改变、价格不满足限制或分页游标失效。 |
| 503 | 节点、签名服务、索引或上游暂不可用，按 Retry-After 秒数退避。 |
| 429 | 请求频率或容量达到上限，按 Retry-After 秒数退避。 |

### GET /pools/{id}/trades

查询池子成交记录。返回已确认成交，使用 next_cursor 翻页。重组或查询快照失效时重新读取，不能自行拼接不一致页面。

参数：

| 字段 | 位置 | 类型 | 必填 | 说明与约束 |
| --- | --- | --- | --- | --- |
| id | path | string | 是 | 微池 Pool ID，64 位小写十六进制。 格式："^[0-9a-f]{64}$" |
| quote | query | string | 否 | 计价币种；当前只支持 TSC。 可选值：["TSC"]；默认值："TSC" |
| start_time | query | integer | 否 | Inclusive UTC Unix milliseconds; candle open time for candles. 最小值：0 |
| end_time | query | integer | 否 | K 线查询结束时间，UTC Unix 毫秒；不传时查询最新区间。 最小值：0 |
| limit | query | integer | 否 | 本页最多返回的记录数量；默认和上限见约束。 默认值：100；最小值：1；最大值：1000 |
| cursor | query | string | 否 | 分页游标，原样传入上次返回的 next_cursor。  |

响应 200：返回以下 JSON 对象；交易的最终结果以 state 和链上确认状态为准。

| 字段 | 类型 | 必定出现 | 说明 | 约束 |
| --- | --- | --- | --- | --- |
| api_version | string | 是 | 接口版本。 | 固定值："1" |
| genesis | string | 是 | 当前网络的创世区块哈希，64 位小写十六进制。 |  |
| index | IndexStatus | 是 | 行情索引进度与同步状态；数据不完整时不要当作完整实时行情。 |  |
| index.indexed_height | integer / null | 是 | 索引已处理到的区块高度。 |  |
| index.indexed_hash | string / null | 是 | 索引已处理到的区块哈希。 |  |
| index.core_height | integer / null | 是 | 节点已验证的区块高度。 |  |
| index.core_headers | integer / null | 是 | 节点已知的最高区块头高度。 |  |
| index.node_ready | boolean | 是 | 节点是否已完成同步并可处理交易。 |  |
| index.caught_up | boolean | 是 | 行情索引是否已追上节点当前高度。 |  |
| index.last_checked_at | integer / null | 是 | 最近一次索引检查时间，UTC Unix 毫秒。 |  |
| index.error | string / null | 是 | 错误说明；无错误时为 null，交易状态仍以 state 为准。 |  |
| index.revision | integer | 是 | 行情索引修订号；用于识别重建或状态变化。 | 最小值：0 |
| time_unit | string | 是 | 时间戳单位，行情与参考价为 unix_ms。 | 固定值："unix_ms" |
| price_decimals | integer | 是 | 行情内部计算的价格精度。 | 固定值：72 |
| timestamp_source | string | 是 | 行情时间来源；使用已确认区块时间。 | 固定值："block_time" |
| gap_policy | string | 是 | 无成交周期的处理方式；carry_forward 沿用上一收盘价，成交量为零。 | 固定值："omit" |
| confirmation_policy | string | 是 | 成交纳入行情统计的确认规则。 | 固定值："canonical_block_1_confirmation" |
| fee_basis | string | 是 | 行情手续费统计口径。 | 固定值："pool_reserve_delta_including_lp_fee_excluding_network_fee" |
| reference_asset_id | null | 是 | 历史参考资产 ID；当前统一使用 TSC，返回 null。 |  |
| pool_id | string | 是 | 微池实例 ID，64 位小写十六进制；不是 Asset ID。 |  |
| asset_id | string | 是 | 资产的链上 ID，64 位小写十六进制；只在对应网络有效。 |  |
| base_symbol | string | 是 | 被定价资产的展示符号。 |  |
| base_precision | integer | 是 | 基础资产的小数位数。 | 最小值：0 |
| quote_symbol | string | 是 | 计价符号；当前为 TSC。 | 可选值：["TSC"] |
| quote_asset_id | string / null | 是 | 计价资产 ID；TSC 是原生币，没有非 TSC Asset ID。 |  |
| coverage | object | 是 | 本池行情记录的定价覆盖情况。 |  |
| coverage.total_trades | integer | 是 | 该池已索引的总成交笔数。 | 最小值：0 |
| coverage.priced_trades | integer | 是 | 具备所选计价币种价格的成交数量。 | 最小值：0 |
| coverage.unpriced_trades | integer | 是 | 缺少计价信息的成交笔数；不等于没有成交。 | 最小值：0 |
| has_more | boolean | 是 | 是否还有下一页；继续使用本响应的游标。 |  |
| next_cursor | string / null | 是 | 下一页游标；没有下一页时为 null，原样用于下一次请求。 |  |
| trades | Trade[] | 是 | 本页已确认成交列表。 |  |
| trades[].id | string | 是 | 成交记录的稳定 ID，用于去重；同一交易可包含多个池成交。 |  |
| trades[].pool_id | string | 是 | 微池实例 ID，64 位小写十六进制；不是 Asset ID。 |  |
| trades[].txid | string | 是 | 链上交易 ID，64 位小写十六进制；不同于 quote_id 或 request_id。 |  |
| trades[].block_hash | string | 是 | 成交所在区块的哈希，64 位小写十六进制。 |  |
| trades[].native_base_units | string | 是 | 本次成交的基础资产最小单位数量。 |  |
| trades[].native_quote_units | string | 是 | 本次成交的计价资产最小单位数量。 |  |
| trades[].block_height | integer | 是 | 成交所在区块高度。 | 最小值：0 |
| trades[].transaction_index | integer | 是 | 交易在区块中的位置，从 0 开始。 | 最小值：0 |
| trades[].input_index | integer | 是 | 池子输入在交易中的位置，从 0 开始。 | 最小值：0 |
| trades[].time | integer | 是 | 成交所在区块时间，UTC Unix 毫秒。 | 最小值：0 |
| trades[].side | string | 是 | 相对于基础 Asset 的买入或卖出方向。 | 可选值：["buy", "sell"] |
| trades[].price | string / null | 是 | 本笔成交均价，单位 TSC/Asset；计价成交量除以基础资产成交量，不是交易后池价。 |  |
| trades[].base_volume | string / null | 是 | 基础资产成交量，按资产单位表示的十进制字符串。 |  |
| trades[].quote_volume | string / null | 是 | 计价资产成交量，单位 TSC，十进制字符串。 |  |
| trades[].quote_source | object / null | 是 | 该成交的计价来源。 |  |
| trades[].pool_price_before | string / null | 是 | 兑换前储备比价格，单位 TSC/Asset；缺少记录时为 null。 |  |
| trades[].reserves_before | object / null | 是 | 兑换前实际储备的最小单位数量，不包含可退载体。 |  |
| trades[].reserves_before.tsc_units | string | 是 | TSC 最小单位整数字符串；1 TSC = 100000000。 |  |
| trades[].reserves_before.asset_units | string | 是 | 非 TSC 资产数量，按该资产精度表示的最小单位整数字符串。 |  |
| trades[].pool_price_after | string / null | 是 | 兑换后储备比价格，单位 TSC/Asset；缺少记录时为 null。 |  |
| trades[].reserves_after | object / null | 是 | 兑换后实际储备的最小单位数量，不包含可退载体。 |  |
| trades[].reserves_after.tsc_units | string | 是 | TSC 最小单位整数字符串；1 TSC = 100000000。 |  |
| trades[].reserves_after.asset_units | string | 是 | 非 TSC 资产数量，按该资产精度表示的最小单位整数字符串。 |  |

错误响应：

| HTTP 状态 | 含义 |
| --- | --- |
| 400 | 请求参数、资产策略或签名无效。 |
| 404 | 未找到资产、池子或操作记录。 |
| 409 | 审核过期、交易内容改变、价格不满足限制或分页游标失效。 |
| 503 | 节点、签名服务、索引或上游暂不可用，按 Retry-After 秒数退避。 |
| 429 | 请求频率或容量达到上限，按 Retry-After 秒数退避。 |

### GET /prices/tsc

查询 TSC 美元参考价。返回共享 SafeTrade TSC/USDT 缓存，只用于辅助美元展示。stale 或 unavailable 时 usd_price=null；不参与报价、滑点、TVL 的 TSC 计算。

响应 200：返回以下 JSON 对象；交易的最终结果以 state 和链上确认状态为准。

| 字段 | 类型 | 必定出现 | 说明 | 约束 |
| --- | --- | --- | --- | --- |
| base_symbol | string | 是 | 被定价资产的展示符号。 | 固定值："TSC" |
| source | string | 是 | 数据来源标识。 | 固定值："SafeTrade" |
| source_market | string | 是 | 参考价来源市场，TSC/USDT。 | 固定值："TSC/USDT" |
| status | string | 是 | available 价格可用；stale 已过期；unavailable 未获取到价格。后两种状态 usd_price 为 null。 | 可选值：["available", "stale", "unavailable"] |
| usd_price | string / null | 是 | 1 TSC 的近似美元价格，十进制字符串；过期或不可用为 null。 | 格式："^[0-9]+(?:\\.[0-9]+)?$" |
| observed_at | integer / null | 是 | 参考价采集时间，UTC Unix 毫秒；不是交易所最新成交时间。 | 最小值：0 |
| expires_at | integer / null | 是 | 参考价缓存到期时间，UTC Unix 毫秒；尚无价格时为 null。 | 最小值：0 |
| time_unit | string | 是 | 时间戳单位，行情与参考价为 unix_ms。 | 固定值："unix_ms" |
| approximate | boolean | 是 | 是否为近似换算；美元展示按 1 USDT 约等于 1 USD。 | 固定值：true |
| conversion | string | 是 | 美元辅助估值的换算假设。 |  |
| purpose | string | 是 | 参考价用途；display_only 表示只用于显示美元估值。 | 固定值："display_only" |

错误响应：

| HTTP 状态 | 含义 |
| --- | --- |
| 400 | 请求参数、资产策略或签名无效。 |
| 404 | 未找到资产、池子或操作记录。 |
| 409 | 审核过期、交易内容改变、价格不满足限制或分页游标失效。 |
| 413 | 请求体超过允许字节数。 |
| 415 | 请求 Content-Type 不受支持。 |
| 422 | JSON 字段格式无效或包含未知字段。 |
| 429 | 请求频率或容量达到上限，按 Retry-After 秒数退避。 |
| 503 | 节点、签名服务、索引或上游暂不可用，按 Retry-After 秒数退避。 |

### GET /stream

订阅 WebSocket 行情。升级为 WebSocket，协议 tern.market.v1。使用 subscribe 订阅池子的 ticker、candles、trades；首次返回 snapshot，之后返回带序号的 update，重新连接从 snapshot 开始。

响应 101：WebSocket 协议升级成功。

错误响应：

| HTTP 状态 | 含义 |
| --- | --- |
| 429 | 请求频率或容量达到上限，按 Retry-After 秒数退避。 |

## 错误码与重试

| code | 处理方式 |
| --- | --- |
| ISSUANCE_UNAVAILABLE | 当前环境未开放发行。 |
| RECOVERY_NOT_VALIDATED | 新 LP 操作尚未通过本环境的独立恢复验收。 |
| WRONG_NETWORK | 检查所选 URL 路径、chain_id 与钱包网络。 |
| REQUEST_ID_CONFLICT | 原 request_id 已绑定不同资料；恢复原资料，仅新发行生成新 ID。 |
| TRANSACTION_CHANGED | 签名结果改变了审核交易或与原执行记录不同。 |
| QUOTE_EXPIRED | 未签名审核已过期；核对原交易状态后再显式请求新审核。 |
| PRICE_CHANGED / LIQUIDITY_PRICE_CHANGED | 报价或入金比例不满足请求限制，重新获取报价并审核。 |
| INVALID_ICON | 检查图片格式、大小、URL，以及 icon_url / icon_base64 互斥。 |
| IPFS_PENDING / IPFS_UNAVAILABLE | 保留原图片与 request_id，按退避时间重试。 |
| IPFS_NOT_CONFIGURED | 当前环境未配置平台上传，可在新请求中使用自有图片 URL。 |
| MEDIA_CAPACITY | 达到图片容量或上传频率限制。 |

429 / 503 优先遵守 Retry-After 秒数。提交超时后先查询原 ID，保留原签名与完整交易，不自动换 ID、改金额或重新铸币。链重组可能回退确认状态。

## WebSocket 消息

连接 `wss://tscscan.xyz:19443/{network}/api/v1/stream`。发送 subscribe：

```json
{"op":"subscribe","id":"garden-chart","params":{"pool_id":"POOL_ID","quote":"TSC","interval":"1m","price_basis":"spot","limit":300}}
```

params.pool_id 为微池 ID；quote 仅支持 TSC；interval 使用上述 8 种周期；price_basis 为 spot 或 execution；limit 默认 300，上限 1000；可选 end_time 为 UTC Unix 毫秒。一次连接只有一个订阅，再次 subscribe 替换原订阅。

服务先返回 hello 和 subscribed。行情封装为 `{"id":"garden-chart","event":{...}}`。snapshot 的 data 包含完整 candles、ticker、trades；update 使用 data.upsert 更新 K 线，data.remove 列出删除的 open_time。数据字段使用对应 REST 响应定义。

每个事件有 seq；update 的 previous_seq 必须等于上次 seq。不连续、重连或重组后重新订阅取得 snapshot。发送 `{"op":"ping"}` 返回 pong，`{"op":"unsubscribe"}` 取消订阅。连接上限 128、每连接每分钟 60 条文本指令、消息上限 8 KiB；65 秒无客户端消息或 Pong 会断开。