{ "openapi": "3.1.0", "jsonSchemaDialect": "https://json-schema.org/draft/2020-12/schema", "info": { "title": "归集平台第三方 API", "version": "6.0.0", "description": "使用 appID、密钥和 accessToken 接入钱包、到账、归集及回调接口。业务请求采用 HMAC-SHA256 签名，回调正文采用 AES-256-GCM 加密。API 域名由平台单独提供，本文档只列路径；金额与 ID 使用字符串。" }, "security": [ { "AppID": [], "Timestamp": [], "Signature": [], "Bearer": [] } ], "tags": [ { "name": "认证" }, { "name": "概览" }, { "name": "钱包" }, { "name": "归集" }, { "name": "到账" }, { "name": "运维" }, { "name": "回调", "description": "平台主动发送到租户配置的接收地址。" }, { "name": "设置" }, { "name": "通知投递" } ], "paths": { "/open/v1/auth/token": { "post": { "operationId": "auth_token", "summary": "获取 accessToken", "description": "使用 HMAC-SHA256 认证方法、路径、appID、时间戳、accessToken、规范查询串及原始请求体摘要。", "tags": [ "认证" ], "security": [ { "AppID": [], "Timestamp": [], "Signature": [] } ], "parameters": [ { "$ref": "#/components/parameters/AppID" }, { "$ref": "#/components/parameters/Timestamp" }, { "$ref": "#/components/parameters/Signature" } ], "responses": { "200": { "description": "业务成功（创建也为 HTTP 200）。", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } }, "Pragma": { "schema": { "type": "string", "const": "no-cache" } }, "X-Trace-Id": { "description": "本次请求的追踪编号。", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TokenResponse" }, "example": { "code": 0, "message": "", "data": { "access_token": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA", "token_type": "Bearer", "expires_in": 7200, "expires_at": "2030-01-01T02:00:00Z" } } } } }, "400": { "description": "参数或请求格式错误", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "code": { "const": 400 } } } ] }, "example": { "code": 400, "message": "invalid request", "error_code": "INVALID_ARGUMENT", "trace_id": "0123456789abcdef0123456789abcdef" } } }, "headers": { "X-Trace-Id": { "description": "本次请求的追踪编号。", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } } }, "401": { "description": "签名、时间窗口或令牌无效", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "code": { "const": 401 } } } ] }, "example": { "code": 401, "message": "authentication required or expired", "error_code": "TOKEN_INVALID_OR_EXPIRED", "trace_id": "0123456789abcdef0123456789abcdef" } } }, "headers": { "X-Trace-Id": { "description": "本次请求的追踪编号。", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } } }, "403": { "description": "租户停用、删除或过期", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "code": { "const": 403 } } } ] }, "example": { "code": 403, "message": "tenant disabled or expired", "error_code": "TENANT_UNAVAILABLE", "trace_id": "0123456789abcdef0123456789abcdef" } } }, "headers": { "X-Trace-Id": { "description": "本次请求的追踪编号。", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } } }, "413": { "description": "请求体超过服务器显式配置的大小限制", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "code": { "const": 413 } } } ] }, "example": { "code": 413, "message": "request body exceeds configured limit", "error_code": "PAYLOAD_TOO_LARGE", "trace_id": "0123456789abcdef0123456789abcdef" } } }, "headers": { "X-Trace-Id": { "description": "本次请求的追踪编号。", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } } }, "429": { "description": "请求频率超限；读取 Retry-After 秒数", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "code": { "const": 429 } } } ] }, "example": { "code": 429, "message": "too many requests", "error_code": "RATE_LIMITED", "trace_id": "0123456789abcdef0123456789abcdef" } } }, "headers": { "Retry-After": { "description": "建议等待秒数；503 为 1。", "schema": { "type": "string", "pattern": "^[0-9]+$" } }, "X-Trace-Id": { "description": "本次请求的追踪编号。", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } } }, "500": { "description": "内部依赖或业务执行失败", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "code": { "const": 500 } } } ] }, "example": { "code": 500, "message": "internal operation failed", "error_code": "INTERNAL_ERROR", "trace_id": "0123456789abcdef0123456789abcdef" } } }, "headers": { "X-Trace-Id": { "description": "本次请求的追踪编号。", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } } }, "503": { "description": "HTTP 并发槽已满；Retry-After 为 1 秒", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "code": { "const": 503 } } } ] }, "example": { "code": 503, "message": "too many in-flight requests", "error_code": "SERVICE_UNAVAILABLE", "trace_id": "0123456789abcdef0123456789abcdef" } } }, "headers": { "Retry-After": { "description": "建议等待秒数；503 为 1。", "schema": { "type": "string", "pattern": "^[0-9]+$" } }, "X-Trace-Id": { "description": "本次请求的追踪编号。", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } } }, "504": { "description": "操作超过请求截止时间", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "code": { "const": 504 } } } ] }, "example": { "code": 504, "message": "request timed out", "error_code": "REQUEST_TIMEOUT", "trace_id": "0123456789abcdef0123456789abcdef" } } }, "headers": { "X-Trace-Id": { "description": "本次请求的追踪编号。", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } } }, "404": { "description": "路径或方法错误。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": 404, "error_code": "ROUTE_NOT_FOUND", "message": "API route not found", "trace_id": "0123456789abcdef0123456789abcdef" } } } }, "405": { "description": "路径或方法错误。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": 405, "error_code": "METHOD_NOT_ALLOWED", "message": "method not allowed", "trace_id": "0123456789abcdef0123456789abcdef" } } } } } } }, "/open/v1/dashboard": { "get": { "operationId": "dashboard", "summary": "账户概览", "description": "查询当前账户的钱包余额、累计到账及归集任务汇总。余额可能有同步延迟；engine 用于查看服务状态，不代表某笔转账结果。本接口无业务请求参数。", "tags": [ "概览" ], "security": [ { "AppID": [], "Timestamp": [], "Signature": [], "Bearer": [] } ], "parameters": [ { "$ref": "#/components/parameters/AppID" }, { "$ref": "#/components/parameters/Timestamp" }, { "$ref": "#/components/parameters/Signature" } ], "responses": { "200": { "description": "业务成功（创建也为 HTTP 200）。", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } }, "X-Trace-Id": { "description": "本次请求的追踪编号。", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DashboardResponse" }, "example": { "code": 0, "message": "", "data": { "wallet_count": 1, "unsynced_wallet_count": 0, "balance_usdt": "100000000", "balance_trx": "30000000", "collected_usdt": "0", "deposit_usdt": "100000000", "pending_tasks": 0, "engine": [ { "component": "chain-scanner", "status": "running", "detail": "", "updated_at": "2030-01-01T00:00:00Z" } ], "network": "nile" } } } } }, "400": { "description": "参数或请求格式错误", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "code": { "const": 400 } } } ] }, "example": { "code": 400, "message": "invalid request", "error_code": "INVALID_ARGUMENT", "trace_id": "0123456789abcdef0123456789abcdef" } } }, "headers": { "X-Trace-Id": { "description": "本次请求的追踪编号。", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } } }, "401": { "description": "签名、时间窗口或令牌无效", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "code": { "const": 401 } } } ] }, "example": { "code": 401, "message": "authentication required or expired", "error_code": "TOKEN_INVALID_OR_EXPIRED", "trace_id": "0123456789abcdef0123456789abcdef" } } }, "headers": { "X-Trace-Id": { "description": "本次请求的追踪编号。", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } } }, "403": { "description": "租户停用、删除或过期", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "code": { "const": 403 } } } ] }, "example": { "code": 403, "message": "tenant disabled or expired", "error_code": "TENANT_UNAVAILABLE", "trace_id": "0123456789abcdef0123456789abcdef" } } }, "headers": { "X-Trace-Id": { "description": "本次请求的追踪编号。", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } } }, "413": { "description": "请求体超过服务器显式配置的大小限制", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "code": { "const": 413 } } } ] }, "example": { "code": 413, "message": "request body exceeds configured limit", "error_code": "PAYLOAD_TOO_LARGE", "trace_id": "0123456789abcdef0123456789abcdef" } } }, "headers": { "X-Trace-Id": { "description": "本次请求的追踪编号。", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } } }, "429": { "description": "请求频率超限；读取 Retry-After 秒数", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "code": { "const": 429 } } } ] }, "example": { "code": 429, "message": "too many requests", "error_code": "RATE_LIMITED", "trace_id": "0123456789abcdef0123456789abcdef" } } }, "headers": { "Retry-After": { "description": "建议等待秒数；503 为 1。", "schema": { "type": "string", "pattern": "^[0-9]+$" } }, "X-Trace-Id": { "description": "本次请求的追踪编号。", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } } }, "500": { "description": "内部依赖或业务执行失败", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "code": { "const": 500 } } } ] }, "example": { "code": 500, "message": "internal operation failed", "error_code": "INTERNAL_ERROR", "trace_id": "0123456789abcdef0123456789abcdef" } } }, "headers": { "X-Trace-Id": { "description": "本次请求的追踪编号。", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } } }, "503": { "description": "HTTP 并发槽已满；Retry-After 为 1 秒", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "code": { "const": 503 } } } ] }, "example": { "code": 503, "message": "too many in-flight requests", "error_code": "SERVICE_UNAVAILABLE", "trace_id": "0123456789abcdef0123456789abcdef" } } }, "headers": { "Retry-After": { "description": "建议等待秒数；503 为 1。", "schema": { "type": "string", "pattern": "^[0-9]+$" } }, "X-Trace-Id": { "description": "本次请求的追踪编号。", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } } }, "504": { "description": "操作超过请求截止时间", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "code": { "const": 504 } } } ] }, "example": { "code": 504, "message": "request timed out", "error_code": "REQUEST_TIMEOUT", "trace_id": "0123456789abcdef0123456789abcdef" } } }, "headers": { "X-Trace-Id": { "description": "本次请求的追踪编号。", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } } }, "404": { "description": "路径或方法错误。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": 404, "error_code": "ROUTE_NOT_FOUND", "message": "API route not found", "trace_id": "0123456789abcdef0123456789abcdef" } } } }, "405": { "description": "路径或方法错误。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": 405, "error_code": "METHOD_NOT_ALLOWED", "message": "method not allowed", "trace_id": "0123456789abcdef0123456789abcdef" } } } } } } }, "/open/v1/wallets": { "get": { "operationId": "wallet_list", "summary": "钱包列表", "description": "分页查询当前账户的收款钱包、最近同步余额和归集状态。unavailable_wallet_ids 仅覆盖当前页及 selected_wallet_ids 指定的钱包。", "tags": [ "钱包" ], "security": [ { "AppID": [], "Timestamp": [], "Signature": [], "Bearer": [] } ], "parameters": [ { "$ref": "#/components/parameters/AppID" }, { "$ref": "#/components/parameters/Timestamp" }, { "$ref": "#/components/parameters/Signature" }, { "$ref": "#/components/parameters/Page" }, { "$ref": "#/components/parameters/PageSize" }, { "$ref": "#/components/parameters/Filter_address" }, { "$ref": "#/components/parameters/Filter_usdt_min" }, { "$ref": "#/components/parameters/Filter_usdt_max" }, { "$ref": "#/components/parameters/Filter_trx_min" }, { "$ref": "#/components/parameters/Filter_trx_max" }, { "$ref": "#/components/parameters/Filter_hide_zero" }, { "$ref": "#/components/parameters/Filter_hide_zero_trx" }, { "$ref": "#/components/parameters/Filter_last_collected_from" }, { "$ref": "#/components/parameters/Filter_last_collected_to" }, { "$ref": "#/components/parameters/Filter_sort" }, { "$ref": "#/components/parameters/Filter_order" }, { "name": "selected_wallet_ids", "in": "query", "required": false, "schema": { "type": "string" }, "description": "逗号分隔的已选钱包ID，最多1000个。" } ], "responses": { "200": { "description": "业务成功（创建也为 HTTP 200）。", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } }, "X-Trace-Id": { "description": "本次请求的追踪编号。", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletPageResponse" }, "example": { "code": 0, "message": "", "data": { "items": [ { "id": "123456789012345678", "address": "TQyeXvAnmKsBqo6V48RmhAnZpWLmR2D7DM", "custom_id": "customer-001", "chain": "TRON", "network": "nile", "collection_status": "idle", "balance_usdt": "100000000", "balance_trx": "30000000", "balance_block": "12345678", "destination": "TAt8Du9Xw2CmrTHRawGETwiEKpNuKDSjE8", "collected_usdt": "0", "last_collected_at": null, "created_at": "2030-01-01T00:00:00Z" } ], "total": 1, "page": 1, "page_size": 20, "unavailable_wallet_ids": [], "network": "nile" } } } } }, "400": { "description": "参数或请求格式错误", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "code": { "const": 400 } } } ] }, "example": { "code": 400, "message": "invalid request", "error_code": "INVALID_ARGUMENT", "trace_id": "0123456789abcdef0123456789abcdef" } } }, "headers": { "X-Trace-Id": { "description": "本次请求的追踪编号。", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } } }, "401": { "description": "签名、时间窗口或令牌无效", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "code": { "const": 401 } } } ] }, "example": { "code": 401, "message": "authentication required or expired", "error_code": "TOKEN_INVALID_OR_EXPIRED", "trace_id": "0123456789abcdef0123456789abcdef" } } }, "headers": { "X-Trace-Id": { "description": "本次请求的追踪编号。", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } } }, "403": { "description": "租户停用、删除或过期", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "code": { "const": 403 } } } ] }, "example": { "code": 403, "message": "tenant disabled or expired", "error_code": "TENANT_UNAVAILABLE", "trace_id": "0123456789abcdef0123456789abcdef" } } }, "headers": { "X-Trace-Id": { "description": "本次请求的追踪编号。", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } } }, "413": { "description": "请求体超过服务器显式配置的大小限制", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "code": { "const": 413 } } } ] }, "example": { "code": 413, "message": "request body exceeds configured limit", "error_code": "PAYLOAD_TOO_LARGE", "trace_id": "0123456789abcdef0123456789abcdef" } } }, "headers": { "X-Trace-Id": { "description": "本次请求的追踪编号。", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } } }, "429": { "description": "请求频率超限；读取 Retry-After 秒数", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "code": { "const": 429 } } } ] }, "example": { "code": 429, "message": "too many requests", "error_code": "RATE_LIMITED", "trace_id": "0123456789abcdef0123456789abcdef" } } }, "headers": { "Retry-After": { "description": "建议等待秒数；503 为 1。", "schema": { "type": "string", "pattern": "^[0-9]+$" } }, "X-Trace-Id": { "description": "本次请求的追踪编号。", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } } }, "500": { "description": "内部依赖或业务执行失败", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "code": { "const": 500 } } } ] }, "example": { "code": 500, "message": "internal operation failed", "error_code": "INTERNAL_ERROR", "trace_id": "0123456789abcdef0123456789abcdef" } } }, "headers": { "X-Trace-Id": { "description": "本次请求的追踪编号。", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } } }, "503": { "description": "HTTP 并发槽已满；Retry-After 为 1 秒", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "code": { "const": 503 } } } ] }, "example": { "code": 503, "message": "too many in-flight requests", "error_code": "SERVICE_UNAVAILABLE", "trace_id": "0123456789abcdef0123456789abcdef" } } }, "headers": { "Retry-After": { "description": "建议等待秒数；503 为 1。", "schema": { "type": "string", "pattern": "^[0-9]+$" } }, "X-Trace-Id": { "description": "本次请求的追踪编号。", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } } }, "504": { "description": "操作超过请求截止时间", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "code": { "const": 504 } } } ] }, "example": { "code": 504, "message": "request timed out", "error_code": "REQUEST_TIMEOUT", "trace_id": "0123456789abcdef0123456789abcdef" } } }, "headers": { "X-Trace-Id": { "description": "本次请求的追踪编号。", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } } }, "404": { "description": "路径或方法错误。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": 404, "error_code": "ROUTE_NOT_FOUND", "message": "API route not found", "trace_id": "0123456789abcdef0123456789abcdef" } } } }, "405": { "description": "路径或方法错误。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": 405, "error_code": "METHOD_NOT_ALLOWED", "message": "method not allowed", "trace_id": "0123456789abcdef0123456789abcdef" } } } } } }, "post": { "operationId": "wallet_create", "summary": "创建钱包", "description": "创建收款钱包并返回钱包 ID 和 TRON 地址。custom_id 在同一账户内唯一，长度 1 至 32 个字符。参数放 JSON，不返回私钥；创建后通过钱包详情查询余额。", "tags": [ "钱包" ], "security": [ { "AppID": [], "Timestamp": [], "Signature": [], "Bearer": [] } ], "parameters": [ { "$ref": "#/components/parameters/AppID" }, { "$ref": "#/components/parameters/Timestamp" }, { "$ref": "#/components/parameters/Signature" } ], "responses": { "200": { "description": "业务成功（创建也为 HTTP 200）。", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } }, "X-Trace-Id": { "description": "本次请求的追踪编号。", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletIdentityResponse" }, "example": { "code": 0, "message": "", "data": { "id": "123456789012345678", "address": "TQyeXvAnmKsBqo6V48RmhAnZpWLmR2D7DM", "custom_id": "customer-001", "chain": "TRON", "created_at": "2030-01-01T00:00:00Z", "network": "nile" } } } } }, "400": { "description": "参数或请求格式错误", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "code": { "const": 400 } } } ] }, "example": { "code": 400, "message": "invalid request", "error_code": "INVALID_ARGUMENT", "trace_id": "0123456789abcdef0123456789abcdef" } } }, "headers": { "X-Trace-Id": { "description": "本次请求的追踪编号。", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } } }, "401": { "description": "签名、时间窗口或令牌无效", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "code": { "const": 401 } } } ] }, "example": { "code": 401, "message": "authentication required or expired", "error_code": "TOKEN_INVALID_OR_EXPIRED", "trace_id": "0123456789abcdef0123456789abcdef" } } }, "headers": { "X-Trace-Id": { "description": "本次请求的追踪编号。", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } } }, "403": { "description": "租户停用、删除或过期", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "code": { "const": 403 } } } ] }, "example": { "code": 403, "message": "tenant disabled or expired", "error_code": "TENANT_UNAVAILABLE", "trace_id": "0123456789abcdef0123456789abcdef" } } }, "headers": { "X-Trace-Id": { "description": "本次请求的追踪编号。", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } } }, "409": { "description": "幂等参数冲突，或唯一记录冲突", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "code": { "const": 409 } } } ] }, "example": { "code": 409, "message": "conflict: idempotency key already used with another request", "error_code": "IDEMPOTENCY_CONFLICT", "trace_id": "0123456789abcdef0123456789abcdef" } } }, "headers": { "X-Trace-Id": { "description": "本次请求的追踪编号。", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } } }, "413": { "description": "请求体超过服务器显式配置的大小限制", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "code": { "const": 413 } } } ] }, "example": { "code": 413, "message": "request body exceeds configured limit", "error_code": "PAYLOAD_TOO_LARGE", "trace_id": "0123456789abcdef0123456789abcdef" } } }, "headers": { "X-Trace-Id": { "description": "本次请求的追踪编号。", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } } }, "429": { "description": "请求频率超限；读取 Retry-After 秒数", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "code": { "const": 429 } } } ] }, "example": { "code": 429, "message": "too many requests", "error_code": "RATE_LIMITED", "trace_id": "0123456789abcdef0123456789abcdef" } } }, "headers": { "Retry-After": { "description": "建议等待秒数；503 为 1。", "schema": { "type": "string", "pattern": "^[0-9]+$" } }, "X-Trace-Id": { "description": "本次请求的追踪编号。", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } } }, "500": { "description": "内部依赖或业务执行失败", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "code": { "const": 500 } } } ] }, "example": { "code": 500, "message": "internal operation failed", "error_code": "INTERNAL_ERROR", "trace_id": "0123456789abcdef0123456789abcdef" } } }, "headers": { "X-Trace-Id": { "description": "本次请求的追踪编号。", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } } }, "503": { "description": "HTTP 并发槽已满；Retry-After 为 1 秒", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "code": { "const": 503 } } } ] }, "example": { "code": 503, "message": "too many in-flight requests", "error_code": "SERVICE_UNAVAILABLE", "trace_id": "0123456789abcdef0123456789abcdef" } } }, "headers": { "Retry-After": { "description": "建议等待秒数；503 为 1。", "schema": { "type": "string", "pattern": "^[0-9]+$" } }, "X-Trace-Id": { "description": "本次请求的追踪编号。", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } } }, "504": { "description": "操作超过请求截止时间", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "code": { "const": 504 } } } ] }, "example": { "code": 504, "message": "request timed out", "error_code": "REQUEST_TIMEOUT", "trace_id": "0123456789abcdef0123456789abcdef" } } }, "headers": { "X-Trace-Id": { "description": "本次请求的追踪编号。", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } } }, "404": { "description": "路径或方法错误。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": 404, "error_code": "ROUTE_NOT_FOUND", "message": "API route not found", "trace_id": "0123456789abcdef0123456789abcdef" } } } }, "405": { "description": "路径或方法错误。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": 405, "error_code": "METHOD_NOT_ALLOWED", "message": "method not allowed", "trace_id": "0123456789abcdef0123456789abcdef" } } } } }, "requestBody": { "required": true, "description": "业务参数和 request_id 仅放 JSON；不接受 Query 或 Idempotency-Key。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateWalletBody" }, "example": { "custom_id": "customer-001", "request_id": "123e4567-e89b-42d3-a456-426614174000" } } } } } }, "/open/v1/wallets/selection": { "post": { "operationId": "wallet_selection", "summary": "跨页选择钱包", "description": "按 filters 返回可归集的钱包 ID。filters 必须是对象，可为 {}。排除未结束归集任务及归集目标钱包；超过 1000 个返回 400。不分页，按 ID 升序返回；sort/order 不改变结果。不接受 page/page_size。本操作不会占用钱包，也不会创建任务，不要求 request_id。", "tags": [ "钱包" ], "security": [ { "AppID": [], "Timestamp": [], "Signature": [], "Bearer": [] } ], "parameters": [ { "$ref": "#/components/parameters/AppID" }, { "$ref": "#/components/parameters/Timestamp" }, { "$ref": "#/components/parameters/Signature" } ], "responses": { "200": { "description": "业务成功（创建也为 HTTP 200）。", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } }, "X-Trace-Id": { "description": "本次请求的追踪编号。", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SelectionResponse" }, "example": { "code": 0, "message": "", "data": { "wallet_ids": [ "123456789012345678" ], "total": 1, "network": "nile" } } } } }, "400": { "description": "参数或请求格式错误", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "code": { "const": 400 } } } ] }, "example": { "code": 400, "message": "invalid request", "error_code": "INVALID_ARGUMENT", "trace_id": "0123456789abcdef0123456789abcdef" } } }, "headers": { "X-Trace-Id": { "description": "本次请求的追踪编号。", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } } }, "401": { "description": "签名、时间窗口或令牌无效", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "code": { "const": 401 } } } ] }, "example": { "code": 401, "message": "authentication required or expired", "error_code": "TOKEN_INVALID_OR_EXPIRED", "trace_id": "0123456789abcdef0123456789abcdef" } } }, "headers": { "X-Trace-Id": { "description": "本次请求的追踪编号。", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } } }, "403": { "description": "租户停用、删除或过期", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "code": { "const": 403 } } } ] }, "example": { "code": 403, "message": "tenant disabled or expired", "error_code": "TENANT_UNAVAILABLE", "trace_id": "0123456789abcdef0123456789abcdef" } } }, "headers": { "X-Trace-Id": { "description": "本次请求的追踪编号。", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } } }, "413": { "description": "请求体超过服务器显式配置的大小限制", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "code": { "const": 413 } } } ] }, "example": { "code": 413, "message": "request body exceeds configured limit", "error_code": "PAYLOAD_TOO_LARGE", "trace_id": "0123456789abcdef0123456789abcdef" } } }, "headers": { "X-Trace-Id": { "description": "本次请求的追踪编号。", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } } }, "429": { "description": "请求频率超限；读取 Retry-After 秒数", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "code": { "const": 429 } } } ] }, "example": { "code": 429, "message": "too many requests", "error_code": "RATE_LIMITED", "trace_id": "0123456789abcdef0123456789abcdef" } } }, "headers": { "Retry-After": { "description": "建议等待秒数；503 为 1。", "schema": { "type": "string", "pattern": "^[0-9]+$" } }, "X-Trace-Id": { "description": "本次请求的追踪编号。", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } } }, "500": { "description": "内部依赖或业务执行失败", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "code": { "const": 500 } } } ] }, "example": { "code": 500, "message": "internal operation failed", "error_code": "INTERNAL_ERROR", "trace_id": "0123456789abcdef0123456789abcdef" } } }, "headers": { "X-Trace-Id": { "description": "本次请求的追踪编号。", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } } }, "503": { "description": "HTTP 并发槽已满；Retry-After 为 1 秒", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "code": { "const": 503 } } } ] }, "example": { "code": 503, "message": "too many in-flight requests", "error_code": "SERVICE_UNAVAILABLE", "trace_id": "0123456789abcdef0123456789abcdef" } } }, "headers": { "Retry-After": { "description": "建议等待秒数；503 为 1。", "schema": { "type": "string", "pattern": "^[0-9]+$" } }, "X-Trace-Id": { "description": "本次请求的追踪编号。", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } } }, "504": { "description": "操作超过请求截止时间", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "code": { "const": 504 } } } ] }, "example": { "code": 504, "message": "request timed out", "error_code": "REQUEST_TIMEOUT", "trace_id": "0123456789abcdef0123456789abcdef" } } }, "headers": { "X-Trace-Id": { "description": "本次请求的追踪编号。", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } } }, "404": { "description": "路径或方法错误。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": 404, "error_code": "ROUTE_NOT_FOUND", "message": "API route not found", "trace_id": "0123456789abcdef0123456789abcdef" } } } }, "405": { "description": "路径或方法错误。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": 405, "error_code": "METHOD_NOT_ALLOWED", "message": "method not allowed", "trace_id": "0123456789abcdef0123456789abcdef" } } } } }, "requestBody": { "required": true, "description": "只读 POST，参数仅放 JSON，不接受 Query、request_id 或 Idempotency-Key。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SelectWalletBody" }, "example": { "filters": { "hide_zero": true } } } } } } }, "/open/v1/wallets/{id}": { "get": { "operationId": "wallet_detail", "summary": "钱包详情", "description": "查询当前账户的钱包余额与归集状态。不存在或无权访问的 ID 返回 404。destination 为账户统一配置的归集地址。", "tags": [ "钱包" ], "security": [ { "AppID": [], "Timestamp": [], "Signature": [], "Bearer": [] } ], "parameters": [ { "$ref": "#/components/parameters/AppID" }, { "$ref": "#/components/parameters/Timestamp" }, { "$ref": "#/components/parameters/Signature" }, { "$ref": "#/components/parameters/ID" } ], "responses": { "200": { "description": "业务成功（创建也为 HTTP 200）。", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } }, "X-Trace-Id": { "description": "本次请求的追踪编号。", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletResponse" }, "example": { "code": 0, "message": "", "data": { "id": "123456789012345678", "address": "TQyeXvAnmKsBqo6V48RmhAnZpWLmR2D7DM", "custom_id": "customer-001", "chain": "TRON", "network": "nile", "collection_status": "idle", "balance_usdt": "100000000", "balance_trx": "30000000", "balance_block": "12345678", "destination": "TAt8Du9Xw2CmrTHRawGETwiEKpNuKDSjE8", "collected_usdt": "0", "last_collected_at": null, "created_at": "2030-01-01T00:00:00Z" } } } } }, "400": { "description": "参数或请求格式错误", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "code": { "const": 400 } } } ] }, "example": { "code": 400, "message": "invalid request", "error_code": "INVALID_ARGUMENT", "trace_id": "0123456789abcdef0123456789abcdef" } } }, "headers": { "X-Trace-Id": { "description": "本次请求的追踪编号。", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } } }, "401": { "description": "签名、时间窗口或令牌无效", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "code": { "const": 401 } } } ] }, "example": { "code": 401, "message": "authentication required or expired", "error_code": "TOKEN_INVALID_OR_EXPIRED", "trace_id": "0123456789abcdef0123456789abcdef" } } }, "headers": { "X-Trace-Id": { "description": "本次请求的追踪编号。", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } } }, "403": { "description": "租户停用、删除或过期", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "code": { "const": 403 } } } ] }, "example": { "code": 403, "message": "tenant disabled or expired", "error_code": "TENANT_UNAVAILABLE", "trace_id": "0123456789abcdef0123456789abcdef" } } }, "headers": { "X-Trace-Id": { "description": "本次请求的追踪编号。", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } } }, "404": { "description": "对象不存在，或不属于当前租户和网络", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "code": { "const": 404 } } } ] }, "example": { "code": 404, "message": "not found", "error_code": "RESOURCE_NOT_FOUND", "trace_id": "0123456789abcdef0123456789abcdef" } } }, "headers": { "X-Trace-Id": { "description": "本次请求的追踪编号。", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } } }, "413": { "description": "请求体超过服务器显式配置的大小限制", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "code": { "const": 413 } } } ] }, "example": { "code": 413, "message": "request body exceeds configured limit", "error_code": "PAYLOAD_TOO_LARGE", "trace_id": "0123456789abcdef0123456789abcdef" } } }, "headers": { "X-Trace-Id": { "description": "本次请求的追踪编号。", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } } }, "429": { "description": "请求频率超限；读取 Retry-After 秒数", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "code": { "const": 429 } } } ] }, "example": { "code": 429, "message": "too many requests", "error_code": "RATE_LIMITED", "trace_id": "0123456789abcdef0123456789abcdef" } } }, "headers": { "Retry-After": { "description": "建议等待秒数；503 为 1。", "schema": { "type": "string", "pattern": "^[0-9]+$" } }, "X-Trace-Id": { "description": "本次请求的追踪编号。", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } } }, "500": { "description": "内部依赖或业务执行失败", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "code": { "const": 500 } } } ] }, "example": { "code": 500, "message": "internal operation failed", "error_code": "INTERNAL_ERROR", "trace_id": "0123456789abcdef0123456789abcdef" } } }, "headers": { "X-Trace-Id": { "description": "本次请求的追踪编号。", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } } }, "503": { "description": "HTTP 并发槽已满；Retry-After 为 1 秒", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "code": { "const": 503 } } } ] }, "example": { "code": 503, "message": "too many in-flight requests", "error_code": "SERVICE_UNAVAILABLE", "trace_id": "0123456789abcdef0123456789abcdef" } } }, "headers": { "Retry-After": { "description": "建议等待秒数；503 为 1。", "schema": { "type": "string", "pattern": "^[0-9]+$" } }, "X-Trace-Id": { "description": "本次请求的追踪编号。", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } } }, "504": { "description": "操作超过请求截止时间", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "code": { "const": 504 } } } ] }, "example": { "code": 504, "message": "request timed out", "error_code": "REQUEST_TIMEOUT", "trace_id": "0123456789abcdef0123456789abcdef" } } }, "headers": { "X-Trace-Id": { "description": "本次请求的追踪编号。", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } } }, "405": { "description": "路径或方法错误。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": 405, "error_code": "METHOD_NOT_ALLOWED", "message": "method not allowed", "trace_id": "0123456789abcdef0123456789abcdef" } } } } } } }, "/open/v1/sweeps": { "post": { "operationId": "sweep_create", "summary": "创建归集任务", "description": "创建异步归集任务；只使用已配置目标，不允许临时目标或任意地址支付。all 必须传 requested_amount:null；fixed 金额逐钱包使用，余额不足不降额。HTTP 200 内按 wallet_ids 顺序逐项返回 pending 或 failed；逐项 failed 没有 id，不是持久化失败任务。全项失败 HTTP 仍为 200。request_id 为必填 JSON 幂等键；同键同参数返回最初响应。所有业务字段必须放JSON，拒绝任何Query（包括裸问号）。参见 /api/sweep-create 与 /guide/signature。拒绝 Idempotency-Key header。请求不接受 network 参数。", "tags": [ "归集" ], "security": [ { "AppID": [], "Timestamp": [], "Signature": [], "Bearer": [] } ], "parameters": [ { "$ref": "#/components/parameters/AppID" }, { "$ref": "#/components/parameters/Timestamp" }, { "$ref": "#/components/parameters/Signature" } ], "responses": { "200": { "description": "业务成功（创建也为 HTTP 200）。", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } }, "X-Trace-Id": { "description": "本次请求的追踪编号。", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SweepCreateResultResponse" }, "example": { "code": 0, "message": "", "data": { "items": [ { "wallet_id": "123456789012345678", "id": "123456789012345679", "status": "pending", "network": "nile" } ], "network": "nile" } } } } }, "400": { "description": "参数或请求格式错误", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "code": { "const": 400 } } } ] }, "example": { "code": 400, "message": "invalid request", "error_code": "INVALID_ARGUMENT", "trace_id": "0123456789abcdef0123456789abcdef" } } }, "headers": { "X-Trace-Id": { "description": "本次请求的追踪编号。", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } } }, "401": { "description": "签名、时间窗口或令牌无效", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "code": { "const": 401 } } } ] }, "example": { "code": 401, "message": "authentication required or expired", "error_code": "TOKEN_INVALID_OR_EXPIRED", "trace_id": "0123456789abcdef0123456789abcdef" } } }, "headers": { "X-Trace-Id": { "description": "本次请求的追踪编号。", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } } }, "403": { "description": "租户停用、删除或过期", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "code": { "const": 403 } } } ] }, "example": { "code": 403, "message": "tenant disabled or expired", "error_code": "TENANT_UNAVAILABLE", "trace_id": "0123456789abcdef0123456789abcdef" } } }, "headers": { "X-Trace-Id": { "description": "本次请求的追踪编号。", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } } }, "409": { "description": "幂等参数冲突，或唯一记录冲突", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "code": { "const": 409 } } } ] }, "example": { "code": 409, "message": "conflict: idempotency key already used with another request", "error_code": "IDEMPOTENCY_CONFLICT", "trace_id": "0123456789abcdef0123456789abcdef" } } }, "headers": { "X-Trace-Id": { "description": "本次请求的追踪编号。", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } } }, "413": { "description": "请求体超过服务器显式配置的大小限制", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "code": { "const": 413 } } } ] }, "example": { "code": 413, "message": "request body exceeds configured limit", "error_code": "PAYLOAD_TOO_LARGE", "trace_id": "0123456789abcdef0123456789abcdef" } } }, "headers": { "X-Trace-Id": { "description": "本次请求的追踪编号。", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } } }, "429": { "description": "请求频率超限；读取 Retry-After 秒数", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "code": { "const": 429 } } } ] }, "example": { "code": 429, "message": "too many requests", "error_code": "RATE_LIMITED", "trace_id": "0123456789abcdef0123456789abcdef" } } }, "headers": { "Retry-After": { "description": "建议等待秒数；503 为 1。", "schema": { "type": "string", "pattern": "^[0-9]+$" } }, "X-Trace-Id": { "description": "本次请求的追踪编号。", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } } }, "500": { "description": "内部依赖或业务执行失败", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "code": { "const": 500 } } } ] }, "example": { "code": 500, "message": "internal operation failed", "error_code": "INTERNAL_ERROR", "trace_id": "0123456789abcdef0123456789abcdef" } } }, "headers": { "X-Trace-Id": { "description": "本次请求的追踪编号。", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } } }, "503": { "description": "HTTP 并发槽已满；Retry-After 为 1 秒", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "code": { "const": 503 } } } ] }, "example": { "code": 503, "message": "too many in-flight requests", "error_code": "SERVICE_UNAVAILABLE", "trace_id": "0123456789abcdef0123456789abcdef" } } }, "headers": { "Retry-After": { "description": "建议等待秒数；503 为 1。", "schema": { "type": "string", "pattern": "^[0-9]+$" } }, "X-Trace-Id": { "description": "本次请求的追踪编号。", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } } }, "504": { "description": "操作超过请求截止时间", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "code": { "const": 504 } } } ] }, "example": { "code": 504, "message": "request timed out", "error_code": "REQUEST_TIMEOUT", "trace_id": "0123456789abcdef0123456789abcdef" } } }, "headers": { "X-Trace-Id": { "description": "本次请求的追踪编号。", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } } }, "404": { "description": "路径或方法错误。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": 404, "error_code": "ROUTE_NOT_FOUND", "message": "API route not found", "trace_id": "0123456789abcdef0123456789abcdef" } } } }, "405": { "description": "路径或方法错误。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": 405, "error_code": "METHOD_NOT_ALLOWED", "message": "method not allowed", "trace_id": "0123456789abcdef0123456789abcdef" } } } } }, "requestBody": { "required": true, "description": "业务参数和 request_id 仅放 JSON；不接受 Query 或 Idempotency-Key。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSweepBody" }, "example": { "wallet_ids": [ "123456789012345678" ], "sweep_mode": "all", "requested_amount": null, "request_id": "123e4567-e89b-42d3-a456-426614174001" } } } } }, "get": { "operationId": "sweep_list", "summary": "归集列表", "description": "分页查询归集任务，按 ID 降序返回。address 对来源或归集目标做不区分大小写的模糊匹配。status 只接受参数枚举中的值，非法值返回 INVALID_ARGUMENT。", "tags": [ "归集" ], "security": [ { "AppID": [], "Timestamp": [], "Signature": [], "Bearer": [] } ], "parameters": [ { "$ref": "#/components/parameters/AppID" }, { "$ref": "#/components/parameters/Timestamp" }, { "$ref": "#/components/parameters/Signature" }, { "$ref": "#/components/parameters/Page" }, { "$ref": "#/components/parameters/PageSize" }, { "name": "address", "in": "query", "required": false, "description": "不区分大小写的包含匹配，%/_ 保留 LIKE 通配语义；空字符串忽略。匹配归集来源或目标。", "schema": { "type": "string", "examples": [ "TQyeXvAnmKsBqo6V48RmhAnZpWLmR2D7DM" ] } }, { "name": "status", "in": "query", "required": false, "description": "精确匹配任务状态；空字符串不筛选。只接受 pending、ready、signed、broadcast、unknown、succeeded、failed、cancelled，其他值返回 INVALID_ARGUMENT。", "schema": { "type": "string", "examples": [ "pending" ] } } ], "responses": { "200": { "description": "业务成功（创建也为 HTTP 200）。", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } }, "X-Trace-Id": { "description": "本次请求的追踪编号。", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SweepPageResponse" }, "example": { "code": 0, "message": "", "data": { "items": [ { "id": "123456789012345679", "wallet_id": "123456789012345678", "address": "TQyeXvAnmKsBqo6V48RmhAnZpWLmR2D7DM", "kind": "sweep", "sweep_mode": "all", "requested_amount": null, "amount": "0", "destination": "TAt8Du9Xw2CmrTHRawGETwiEKpNuKDSjE8", "status": "pending", "reason": "", "txid": "", "actual_fee": "0", "created_at": "2030-01-01T00:00:00Z", "updated_at": "2030-01-01T00:00:00Z", "webhook": null, "network": "nile", "preparation_stage": "ready", "energy_rental": null, "fee_source": null, "prepared_energy": null, "estimated_wallet_trx_fee": null, "max_wallet_trx_fee": null, "actual_bandwidth_fee": null, "fee_warning": null } ], "total": 1, "page": 1, "page_size": 20, "network": "nile" } } } } }, "400": { "description": "参数或请求格式错误", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "code": { "const": 400 } } } ] }, "example": { "code": 400, "message": "invalid request", "error_code": "INVALID_ARGUMENT", "trace_id": "0123456789abcdef0123456789abcdef" } } }, "headers": { "X-Trace-Id": { "description": "本次请求的追踪编号。", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } } }, "401": { "description": "签名、时间窗口或令牌无效", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "code": { "const": 401 } } } ] }, "example": { "code": 401, "message": "authentication required or expired", "error_code": "TOKEN_INVALID_OR_EXPIRED", "trace_id": "0123456789abcdef0123456789abcdef" } } }, "headers": { "X-Trace-Id": { "description": "本次请求的追踪编号。", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } } }, "403": { "description": "租户停用、删除或过期", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "code": { "const": 403 } } } ] }, "example": { "code": 403, "message": "tenant disabled or expired", "error_code": "TENANT_UNAVAILABLE", "trace_id": "0123456789abcdef0123456789abcdef" } } }, "headers": { "X-Trace-Id": { "description": "本次请求的追踪编号。", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } } }, "413": { "description": "请求体超过服务器显式配置的大小限制", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "code": { "const": 413 } } } ] }, "example": { "code": 413, "message": "request body exceeds configured limit", "error_code": "PAYLOAD_TOO_LARGE", "trace_id": "0123456789abcdef0123456789abcdef" } } }, "headers": { "X-Trace-Id": { "description": "本次请求的追踪编号。", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } } }, "429": { "description": "请求频率超限；读取 Retry-After 秒数", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "code": { "const": 429 } } } ] }, "example": { "code": 429, "message": "too many requests", "error_code": "RATE_LIMITED", "trace_id": "0123456789abcdef0123456789abcdef" } } }, "headers": { "Retry-After": { "description": "建议等待秒数；503 为 1。", "schema": { "type": "string", "pattern": "^[0-9]+$" } }, "X-Trace-Id": { "description": "本次请求的追踪编号。", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } } }, "500": { "description": "内部依赖或业务执行失败", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "code": { "const": 500 } } } ] }, "example": { "code": 500, "message": "internal operation failed", "error_code": "INTERNAL_ERROR", "trace_id": "0123456789abcdef0123456789abcdef" } } }, "headers": { "X-Trace-Id": { "description": "本次请求的追踪编号。", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } } }, "503": { "description": "HTTP 并发槽已满；Retry-After 为 1 秒", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "code": { "const": 503 } } } ] }, "example": { "code": 503, "message": "too many in-flight requests", "error_code": "SERVICE_UNAVAILABLE", "trace_id": "0123456789abcdef0123456789abcdef" } } }, "headers": { "Retry-After": { "description": "建议等待秒数；503 为 1。", "schema": { "type": "string", "pattern": "^[0-9]+$" } }, "X-Trace-Id": { "description": "本次请求的追踪编号。", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } } }, "504": { "description": "操作超过请求截止时间", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "code": { "const": 504 } } } ] }, "example": { "code": 504, "message": "request timed out", "error_code": "REQUEST_TIMEOUT", "trace_id": "0123456789abcdef0123456789abcdef" } } }, "headers": { "X-Trace-Id": { "description": "本次请求的追踪编号。", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } } }, "404": { "description": "路径或方法错误。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": 404, "error_code": "ROUTE_NOT_FOUND", "message": "API route not found", "trace_id": "0123456789abcdef0123456789abcdef" } } } }, "405": { "description": "路径或方法错误。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": 405, "error_code": "METHOD_NOT_ALLOWED", "message": "method not allowed", "trace_id": "0123456789abcdef0123456789abcdef" } } } } } } }, "/open/v1/sweeps/{id}": { "get": { "operationId": "sweep_detail", "summary": "归集详情", "description": "查询归集任务的状态、交易哈希、实际费用及结果通知。amount、actual_fee 在准备或确认前可为 \"0\"，txid 在签名前为空。排队或广播不代表成功，以 status 判断最终结果。", "tags": [ "归集" ], "security": [ { "AppID": [], "Timestamp": [], "Signature": [], "Bearer": [] } ], "parameters": [ { "$ref": "#/components/parameters/AppID" }, { "$ref": "#/components/parameters/Timestamp" }, { "$ref": "#/components/parameters/Signature" }, { "$ref": "#/components/parameters/ID" } ], "responses": { "200": { "description": "业务成功（创建也为 HTTP 200）。", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } }, "X-Trace-Id": { "description": "本次请求的追踪编号。", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SweepResponse" }, "example": { "code": 0, "message": "", "data": { "id": "123456789012345679", "wallet_id": "123456789012345678", "address": "TQyeXvAnmKsBqo6V48RmhAnZpWLmR2D7DM", "kind": "sweep", "sweep_mode": "all", "requested_amount": null, "amount": "0", "destination": "TAt8Du9Xw2CmrTHRawGETwiEKpNuKDSjE8", "status": "pending", "reason": "", "txid": "", "actual_fee": "0", "created_at": "2030-01-01T00:00:00Z", "updated_at": "2030-01-01T00:00:00Z", "webhook": null, "network": "nile", "preparation_stage": "ready", "energy_rental": null, "fee_source": null, "prepared_energy": null, "estimated_wallet_trx_fee": null, "max_wallet_trx_fee": null, "actual_bandwidth_fee": null, "fee_warning": null } } } } }, "400": { "description": "参数或请求格式错误", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "code": { "const": 400 } } } ] }, "example": { "code": 400, "message": "invalid request", "error_code": "INVALID_ARGUMENT", "trace_id": "0123456789abcdef0123456789abcdef" } } }, "headers": { "X-Trace-Id": { "description": "本次请求的追踪编号。", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } } }, "401": { "description": "签名、时间窗口或令牌无效", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "code": { "const": 401 } } } ] }, "example": { "code": 401, "message": "authentication required or expired", "error_code": "TOKEN_INVALID_OR_EXPIRED", "trace_id": "0123456789abcdef0123456789abcdef" } } }, "headers": { "X-Trace-Id": { "description": "本次请求的追踪编号。", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } } }, "403": { "description": "租户停用、删除或过期", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "code": { "const": 403 } } } ] }, "example": { "code": 403, "message": "tenant disabled or expired", "error_code": "TENANT_UNAVAILABLE", "trace_id": "0123456789abcdef0123456789abcdef" } } }, "headers": { "X-Trace-Id": { "description": "本次请求的追踪编号。", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } } }, "404": { "description": "对象不存在，或不属于当前租户和网络", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "code": { "const": 404 } } } ] }, "example": { "code": 404, "message": "not found", "error_code": "RESOURCE_NOT_FOUND", "trace_id": "0123456789abcdef0123456789abcdef" } } }, "headers": { "X-Trace-Id": { "description": "本次请求的追踪编号。", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } } }, "413": { "description": "请求体超过服务器显式配置的大小限制", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "code": { "const": 413 } } } ] }, "example": { "code": 413, "message": "request body exceeds configured limit", "error_code": "PAYLOAD_TOO_LARGE", "trace_id": "0123456789abcdef0123456789abcdef" } } }, "headers": { "X-Trace-Id": { "description": "本次请求的追踪编号。", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } } }, "429": { "description": "请求频率超限；读取 Retry-After 秒数", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "code": { "const": 429 } } } ] }, "example": { "code": 429, "message": "too many requests", "error_code": "RATE_LIMITED", "trace_id": "0123456789abcdef0123456789abcdef" } } }, "headers": { "Retry-After": { "description": "建议等待秒数；503 为 1。", "schema": { "type": "string", "pattern": "^[0-9]+$" } }, "X-Trace-Id": { "description": "本次请求的追踪编号。", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } } }, "500": { "description": "内部依赖或业务执行失败", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "code": { "const": 500 } } } ] }, "example": { "code": 500, "message": "internal operation failed", "error_code": "INTERNAL_ERROR", "trace_id": "0123456789abcdef0123456789abcdef" } } }, "headers": { "X-Trace-Id": { "description": "本次请求的追踪编号。", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } } }, "503": { "description": "HTTP 并发槽已满；Retry-After 为 1 秒", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "code": { "const": 503 } } } ] }, "example": { "code": 503, "message": "too many in-flight requests", "error_code": "SERVICE_UNAVAILABLE", "trace_id": "0123456789abcdef0123456789abcdef" } } }, "headers": { "Retry-After": { "description": "建议等待秒数；503 为 1。", "schema": { "type": "string", "pattern": "^[0-9]+$" } }, "X-Trace-Id": { "description": "本次请求的追踪编号。", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } } }, "504": { "description": "操作超过请求截止时间", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "code": { "const": 504 } } } ] }, "example": { "code": 504, "message": "request timed out", "error_code": "REQUEST_TIMEOUT", "trace_id": "0123456789abcdef0123456789abcdef" } } }, "headers": { "X-Trace-Id": { "description": "本次请求的追踪编号。", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } } }, "405": { "description": "路径或方法错误。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": 405, "error_code": "METHOD_NOT_ALLOWED", "message": "method not allowed", "trace_id": "0123456789abcdef0123456789abcdef" } } } } } } }, "/open/v1/deposits": { "get": { "operationId": "deposit_list", "summary": "到账列表", "description": "查询当前账户的已确认到账。单条对象与到账通知解密正文共用 24 个字段，同一 id、revision 的内容一致。查询返回当前版本，历史通知保留对应事件版本。confirmations 与 block_hash 允许为 null。投递状态通过GET /open/v1/webhooks/{event_id}查询，不嵌入到账对象。仅接受文档列出的查询参数。到账按平台管理员为该租户设置的确认类型认可。状态可能因链重组变为reverted；按到账id和revision处理最新状态，不能把低确认当成已固化。三方不能设置确认类型。同步恢复或核验可能补录较早区块的到账；不要按 block_time 距离当前时间的长短认定无效。已有到账恢复保持原 id、event_id、created_at 和 revision，重复事件不得重复入账。", "tags": [ "到账" ], "security": [ { "AppID": [], "Timestamp": [], "Signature": [], "Bearer": [] } ], "parameters": [ { "$ref": "#/components/parameters/AppID" }, { "$ref": "#/components/parameters/Timestamp" }, { "$ref": "#/components/parameters/Signature" }, { "$ref": "#/components/parameters/Page" }, { "$ref": "#/components/parameters/PageSize" }, { "name": "address", "in": "query", "required": false, "description": "不区分大小写的包含匹配，%/_ 保留 LIKE 通配语义；空字符串忽略。只匹配到账收款地址。", "schema": { "type": "string", "examples": [ "TQyeXvAnmKsBqo6V48RmhAnZpWLmR2D7DM" ] } } ], "responses": { "200": { "description": "业务成功（创建也为 HTTP 200）。", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } }, "X-Trace-Id": { "description": "本次请求的追踪编号。", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DepositPageResponse" }, "example": { "code": 0, "message": "", "data": { "items": [ { "id": "123456789012345680", "event_id": "123456789012345680", "event_type": "deposit.confirmed", "status": "confirmed", "wallet_id": "123456789012345678", "custom_id": "customer-1001", "chain": "TRON", "network": "nile", "asset": "USDT", "token_standard": "TRC20", "decimals": 6, "address": "TQyeXvAnmKsBqo6V48RmhAnZpWLmR2D7DM", "source": "TWkz4y25cWK517vSdMP1N4EWHySqwQ6dMb", "contract": "TXYZopYRdj2D9XRtbG411XZZ3kM5VkAeBf", "amount": "100000000", "txid": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "log_index": 0, "block_number": "12345678", "block_time": "2030-01-01T00:00:00.000000Z", "created_at": "2030-01-01T00:00:00.000000Z", "revision": 1, "confirmation_type": "solidified", "confirmations": null, "block_hash": null } ], "total": 1, "page": 1, "page_size": 20, "network": "nile" } } } } }, "400": { "description": "参数或请求格式错误", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "code": { "const": 400 } } } ] }, "example": { "code": 400, "message": "invalid request", "error_code": "INVALID_ARGUMENT", "trace_id": "0123456789abcdef0123456789abcdef" } } }, "headers": { "X-Trace-Id": { "description": "本次请求的追踪编号。", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } } }, "401": { "description": "签名、时间窗口或令牌无效", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "code": { "const": 401 } } } ] }, "example": { "code": 401, "message": "authentication required or expired", "error_code": "TOKEN_INVALID_OR_EXPIRED", "trace_id": "0123456789abcdef0123456789abcdef" } } }, "headers": { "X-Trace-Id": { "description": "本次请求的追踪编号。", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } } }, "403": { "description": "租户停用、删除或过期", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "code": { "const": 403 } } } ] }, "example": { "code": 403, "message": "tenant disabled or expired", "error_code": "TENANT_UNAVAILABLE", "trace_id": "0123456789abcdef0123456789abcdef" } } }, "headers": { "X-Trace-Id": { "description": "本次请求的追踪编号。", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } } }, "413": { "description": "请求体超过服务器显式配置的大小限制", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "code": { "const": 413 } } } ] }, "example": { "code": 413, "message": "request body exceeds configured limit", "error_code": "PAYLOAD_TOO_LARGE", "trace_id": "0123456789abcdef0123456789abcdef" } } }, "headers": { "X-Trace-Id": { "description": "本次请求的追踪编号。", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } } }, "429": { "description": "请求频率超限；读取 Retry-After 秒数", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "code": { "const": 429 } } } ] }, "example": { "code": 429, "message": "too many requests", "error_code": "RATE_LIMITED", "trace_id": "0123456789abcdef0123456789abcdef" } } }, "headers": { "Retry-After": { "description": "建议等待秒数；503 为 1。", "schema": { "type": "string", "pattern": "^[0-9]+$" } }, "X-Trace-Id": { "description": "本次请求的追踪编号。", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } } }, "500": { "description": "内部依赖或业务执行失败", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "code": { "const": 500 } } } ] }, "example": { "code": 500, "message": "internal operation failed", "error_code": "INTERNAL_ERROR", "trace_id": "0123456789abcdef0123456789abcdef" } } }, "headers": { "X-Trace-Id": { "description": "本次请求的追踪编号。", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } } }, "503": { "description": "HTTP 并发槽已满；Retry-After 为 1 秒", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "code": { "const": 503 } } } ] }, "example": { "code": 503, "message": "too many in-flight requests", "error_code": "SERVICE_UNAVAILABLE", "trace_id": "0123456789abcdef0123456789abcdef" } } }, "headers": { "Retry-After": { "description": "建议等待秒数；503 为 1。", "schema": { "type": "string", "pattern": "^[0-9]+$" } }, "X-Trace-Id": { "description": "本次请求的追踪编号。", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } } }, "504": { "description": "操作超过请求截止时间", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "code": { "const": 504 } } } ] }, "example": { "code": 504, "message": "request timed out", "error_code": "REQUEST_TIMEOUT", "trace_id": "0123456789abcdef0123456789abcdef" } } }, "headers": { "X-Trace-Id": { "description": "本次请求的追踪编号。", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } } }, "404": { "description": "路径或方法错误。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": 404, "error_code": "ROUTE_NOT_FOUND", "message": "API route not found", "trace_id": "0123456789abcdef0123456789abcdef" } } } }, "405": { "description": "路径或方法错误。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": 405, "error_code": "METHOD_NOT_ALLOWED", "message": "method not allowed", "trace_id": "0123456789abcdef0123456789abcdef" } } } } } } }, "/open/v1/deposits/{id}": { "get": { "operationId": "deposit_detail", "summary": "到账详情", "description": "查询当前账户的已确认到账。单条对象与到账通知解密正文共用 24 个字段，同一 id、revision 的内容一致。查询返回当前版本，历史通知保留对应事件版本。confirmations 与 block_hash 允许为 null。投递状态通过GET /open/v1/webhooks/{event_id}查询，不嵌入到账对象。仅接受文档列出的查询参数。到账按平台管理员为该租户设置的确认类型认可。状态可能因链重组变为reverted；按到账id和revision处理最新状态，不能把低确认当成已固化。三方不能设置确认类型。同步恢复或核验可能补录较早区块的到账；不要按 block_time 距离当前时间的长短认定无效。已有到账恢复保持原 id、event_id、created_at 和 revision，重复事件不得重复入账。", "tags": [ "到账" ], "security": [ { "AppID": [], "Timestamp": [], "Signature": [], "Bearer": [] } ], "parameters": [ { "$ref": "#/components/parameters/AppID" }, { "$ref": "#/components/parameters/Timestamp" }, { "$ref": "#/components/parameters/Signature" }, { "$ref": "#/components/parameters/ID" } ], "responses": { "200": { "description": "业务成功（创建也为 HTTP 200）。", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } }, "X-Trace-Id": { "description": "本次请求的追踪编号。", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DepositResponse" }, "example": { "code": 0, "message": "", "data": { "id": "123456789012345680", "event_id": "123456789012345680", "event_type": "deposit.confirmed", "status": "confirmed", "wallet_id": "123456789012345678", "custom_id": "customer-1001", "chain": "TRON", "network": "nile", "asset": "USDT", "token_standard": "TRC20", "decimals": 6, "address": "TQyeXvAnmKsBqo6V48RmhAnZpWLmR2D7DM", "source": "TWkz4y25cWK517vSdMP1N4EWHySqwQ6dMb", "contract": "TXYZopYRdj2D9XRtbG411XZZ3kM5VkAeBf", "amount": "100000000", "txid": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "log_index": 0, "block_number": "12345678", "block_time": "2030-01-01T00:00:00.000000Z", "created_at": "2030-01-01T00:00:00.000000Z", "revision": 1, "confirmation_type": "solidified", "confirmations": null, "block_hash": null } } } } }, "400": { "description": "参数或请求格式错误", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "code": { "const": 400 } } } ] }, "example": { "code": 400, "message": "invalid request", "error_code": "INVALID_ARGUMENT", "trace_id": "0123456789abcdef0123456789abcdef" } } }, "headers": { "X-Trace-Id": { "description": "本次请求的追踪编号。", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } } }, "401": { "description": "签名、时间窗口或令牌无效", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "code": { "const": 401 } } } ] }, "example": { "code": 401, "message": "authentication required or expired", "error_code": "TOKEN_INVALID_OR_EXPIRED", "trace_id": "0123456789abcdef0123456789abcdef" } } }, "headers": { "X-Trace-Id": { "description": "本次请求的追踪编号。", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } } }, "403": { "description": "租户停用、删除或过期", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "code": { "const": 403 } } } ] }, "example": { "code": 403, "message": "tenant disabled or expired", "error_code": "TENANT_UNAVAILABLE", "trace_id": "0123456789abcdef0123456789abcdef" } } }, "headers": { "X-Trace-Id": { "description": "本次请求的追踪编号。", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } } }, "404": { "description": "对象不存在，或不属于当前租户和网络", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "code": { "const": 404 } } } ] }, "example": { "code": 404, "message": "not found", "error_code": "RESOURCE_NOT_FOUND", "trace_id": "0123456789abcdef0123456789abcdef" } } }, "headers": { "X-Trace-Id": { "description": "本次请求的追踪编号。", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } } }, "413": { "description": "请求体超过服务器显式配置的大小限制", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "code": { "const": 413 } } } ] }, "example": { "code": 413, "message": "request body exceeds configured limit", "error_code": "PAYLOAD_TOO_LARGE", "trace_id": "0123456789abcdef0123456789abcdef" } } }, "headers": { "X-Trace-Id": { "description": "本次请求的追踪编号。", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } } }, "429": { "description": "请求频率超限；读取 Retry-After 秒数", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "code": { "const": 429 } } } ] }, "example": { "code": 429, "message": "too many requests", "error_code": "RATE_LIMITED", "trace_id": "0123456789abcdef0123456789abcdef" } } }, "headers": { "Retry-After": { "description": "建议等待秒数；503 为 1。", "schema": { "type": "string", "pattern": "^[0-9]+$" } }, "X-Trace-Id": { "description": "本次请求的追踪编号。", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } } }, "500": { "description": "内部依赖或业务执行失败", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "code": { "const": 500 } } } ] }, "example": { "code": 500, "message": "internal operation failed", "error_code": "INTERNAL_ERROR", "trace_id": "0123456789abcdef0123456789abcdef" } } }, "headers": { "X-Trace-Id": { "description": "本次请求的追踪编号。", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } } }, "503": { "description": "HTTP 并发槽已满；Retry-After 为 1 秒", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "code": { "const": 503 } } } ] }, "example": { "code": 503, "message": "too many in-flight requests", "error_code": "SERVICE_UNAVAILABLE", "trace_id": "0123456789abcdef0123456789abcdef" } } }, "headers": { "Retry-After": { "description": "建议等待秒数；503 为 1。", "schema": { "type": "string", "pattern": "^[0-9]+$" } }, "X-Trace-Id": { "description": "本次请求的追踪编号。", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } } }, "504": { "description": "操作超过请求截止时间", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "code": { "const": 504 } } } ] }, "example": { "code": 504, "message": "request timed out", "error_code": "REQUEST_TIMEOUT", "trace_id": "0123456789abcdef0123456789abcdef" } } }, "headers": { "X-Trace-Id": { "description": "本次请求的追踪编号。", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } } }, "405": { "description": "路径或方法错误。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": 405, "error_code": "METHOD_NOT_ALLOWED", "message": "method not allowed", "trace_id": "0123456789abcdef0123456789abcdef" } } } } } } }, "/healthz": { "get": { "operationId": "healthz", "summary": "健康检查", "description": "无需鉴权，查询接口服务是否可用。成功不代表余额已同步完成或某笔交易成功。", "tags": [ "运维" ], "security": [], "responses": { "200": { "description": "依赖可用。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HealthResponse" }, "example": { "code": 0, "message": "", "data": { "status": "ok", "network": "nile" } } } }, "headers": { "X-Trace-Id": { "description": "本次请求的追踪编号。", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } } }, "500": { "description": "内部依赖或业务执行失败", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "code": { "const": 500 } } } ] }, "example": { "code": 500, "message": "internal operation failed", "error_code": "INTERNAL_ERROR", "trace_id": "0123456789abcdef0123456789abcdef" } } }, "headers": { "X-Trace-Id": { "description": "本次请求的追踪编号。", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } } }, "504": { "description": "操作超过请求截止时间", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "code": { "const": 504 } } } ] }, "example": { "code": 504, "message": "request timed out", "error_code": "REQUEST_TIMEOUT", "trace_id": "0123456789abcdef0123456789abcdef" } } }, "headers": { "X-Trace-Id": { "description": "本次请求的追踪编号。", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } } } } } }, "/openapi.json": { "get": { "operationId": "openapi_document", "summary": "OpenAPI 文档文件", "description": "无需鉴权，返回完整 OpenAPI 3.1 JSON，与文档站下载内容一致。响应没有 code/message/data 外层。", "tags": [ "运维" ], "security": [], "parameters": [ { "name": "If-Modified-Since", "in": "header", "required": false, "description": "可选标准 HTTP 条件请求头。", "schema": { "type": "string" } }, { "name": "Range", "in": "header", "required": false, "description": "可选标准 HTTP 字节范围。", "schema": { "type": "string" } } ], "responses": { "200": { "description": "原始 OpenAPI JSON 文档。", "content": { "application/json": { "schema": { "type": "object", "properties": { "openapi": { "type": "string", "description": "文件声明的 OpenAPI 版本。", "examples": [ "3.1.0" ] }, "info": { "type": "object", "description": "OpenAPI 标题和版本信息。" }, "paths": { "type": "object", "description": "OpenAPI 路径映射。" } }, "required": [ "openapi", "info", "paths" ], "additionalProperties": true } } }, "headers": { "X-Trace-Id": { "description": "本次请求的追踪编号。", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } } }, "206": { "description": "标准 HTTP 范围响应。", "content": { "application/json": { "schema": { "type": "string", "description": "文件的原始字节范围，不一定构成完整 JSON。" } } }, "headers": { "X-Trace-Id": { "description": "本次请求的追踪编号。", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } } }, "304": { "description": "标准条件请求未修改响应，无正文。", "headers": { "X-Trace-Id": { "description": "本次请求的追踪编号。", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } } }, "404": { "description": "文档文件不存在，标准静态文件处理器响应。", "content": { "text/plain": { "schema": { "type": "string" } } }, "headers": { "X-Trace-Id": { "description": "本次请求的追踪编号。", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } } }, "416": { "description": "HTTP Range 不满足，标准静态文件处理器响应。", "content": { "text/plain": { "schema": { "type": "string" } } }, "headers": { "X-Trace-Id": { "description": "本次请求的追踪编号。", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } } }, "503": { "description": "HTTP 并发槽已满；Retry-After 为 1 秒", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "code": { "const": 503 } } } ] }, "example": { "code": 503, "message": "too many in-flight requests", "error_code": "SERVICE_UNAVAILABLE", "trace_id": "0123456789abcdef0123456789abcdef" } } }, "headers": { "Retry-After": { "description": "建议等待秒数；503 为 1。", "schema": { "type": "string", "pattern": "^[0-9]+$" } }, "X-Trace-Id": { "description": "本次请求的追踪编号。", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } } } } } }, "/open/v1/settings/addresses": { "get": { "operationId": "account_addresses", "summary": "查询账户地址", "description": "查询当前账户的 USDT 归集地址，未设置时 collection_address 为空字符串。本接口不会修改配置。", "tags": [ "设置" ], "security": [ { "AppID": [], "Timestamp": [], "Signature": [], "Bearer": [] } ], "parameters": [ { "$ref": "#/components/parameters/AppID" }, { "$ref": "#/components/parameters/Timestamp" }, { "$ref": "#/components/parameters/Signature" } ], "responses": { "200": { "description": "请求成功。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountAddressesResponse" }, "example": { "code": 0, "message": "", "data": { "collection_address": "TAt8Du9Xw2CmrTHRawGETwiEKpNuKDSjE8" } } } }, "headers": { "X-Trace-Id": { "description": "本次请求的追踪编号。", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } } }, "400": { "description": "参数或请求格式错误", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "code": { "const": 400 } } } ] }, "example": { "code": 400, "message": "invalid request", "error_code": "INVALID_ARGUMENT", "trace_id": "0123456789abcdef0123456789abcdef" } } }, "headers": { "X-Trace-Id": { "description": "本次请求的追踪编号。", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } } }, "401": { "description": "签名、时间窗口或令牌无效", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "code": { "const": 401 } } } ] }, "example": { "code": 401, "message": "authentication required or expired", "error_code": "TOKEN_INVALID_OR_EXPIRED", "trace_id": "0123456789abcdef0123456789abcdef" } } }, "headers": { "X-Trace-Id": { "description": "本次请求的追踪编号。", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } } }, "403": { "description": "租户停用、删除或过期", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "code": { "const": 403 } } } ] }, "example": { "code": 403, "message": "tenant disabled or expired", "error_code": "TENANT_UNAVAILABLE", "trace_id": "0123456789abcdef0123456789abcdef" } } }, "headers": { "X-Trace-Id": { "description": "本次请求的追踪编号。", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } } }, "413": { "description": "请求体超过服务器显式配置的大小限制", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "code": { "const": 413 } } } ] }, "example": { "code": 413, "message": "request body exceeds configured limit", "error_code": "PAYLOAD_TOO_LARGE", "trace_id": "0123456789abcdef0123456789abcdef" } } }, "headers": { "X-Trace-Id": { "description": "本次请求的追踪编号。", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } } }, "429": { "description": "请求频率超限；读取 Retry-After 秒数", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "code": { "const": 429 } } } ] }, "example": { "code": 429, "message": "too many requests", "error_code": "RATE_LIMITED", "trace_id": "0123456789abcdef0123456789abcdef" } } }, "headers": { "Retry-After": { "description": "建议等待秒数；503 为 1。", "schema": { "type": "string", "pattern": "^[0-9]+$" } }, "X-Trace-Id": { "description": "本次请求的追踪编号。", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } } }, "500": { "description": "内部依赖或业务执行失败", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "code": { "const": 500 } } } ] }, "example": { "code": 500, "message": "internal operation failed", "error_code": "INTERNAL_ERROR", "trace_id": "0123456789abcdef0123456789abcdef" } } }, "headers": { "X-Trace-Id": { "description": "本次请求的追踪编号。", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } } }, "503": { "description": "HTTP 并发槽已满；Retry-After 为 1 秒", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "code": { "const": 503 } } } ] }, "example": { "code": 503, "message": "too many in-flight requests", "error_code": "SERVICE_UNAVAILABLE", "trace_id": "0123456789abcdef0123456789abcdef" } } }, "headers": { "Retry-After": { "description": "建议等待秒数；503 为 1。", "schema": { "type": "string", "pattern": "^[0-9]+$" } }, "X-Trace-Id": { "description": "本次请求的追踪编号。", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } } }, "504": { "description": "操作超过请求截止时间", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "code": { "const": 504 } } } ] }, "example": { "code": 504, "message": "request timed out", "error_code": "REQUEST_TIMEOUT", "trace_id": "0123456789abcdef0123456789abcdef" } } }, "headers": { "X-Trace-Id": { "description": "本次请求的追踪编号。", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } } }, "404": { "description": "对象不存在，或不属于当前租户和网络", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "code": { "const": 404 } } } ] }, "example": { "code": 404, "message": "record not found", "error_code": "RESOURCE_NOT_FOUND", "trace_id": "0123456789abcdef0123456789abcdef" } } }, "headers": { "X-Trace-Id": { "description": "本次请求的追踪编号。", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } } }, "405": { "description": "路径或方法错误。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": 405, "error_code": "METHOD_NOT_ALLOWED", "message": "method not allowed", "trace_id": "0123456789abcdef0123456789abcdef" } } } } } } }, "/open/v1/settings/addresses/collection": { "post": { "operationId": "collection_address_set", "summary": "设置 USDT 归集地址", "description": "设置统一的 USDT 归集地址。只允许合法的平台外 TRON 地址，禁止使用任何平台管理的收款地址，避免循环归集。实际地址变化会递增版本，并取消尚未签名的旧目标任务；已签名交易仍按原目标确认。相同 request_id 和参数返回原结果，改变参数返回 409。", "tags": [ "设置" ], "security": [ { "AppID": [], "Timestamp": [], "Signature": [], "Bearer": [] } ], "parameters": [ { "$ref": "#/components/parameters/AppID" }, { "$ref": "#/components/parameters/Timestamp" }, { "$ref": "#/components/parameters/Signature" } ], "responses": { "200": { "description": "请求成功。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CollectionAddressSettingResponse" }, "example": { "code": 0, "message": "", "data": { "collection_address": "TAt8Du9Xw2CmrTHRawGETwiEKpNuKDSjE8" } } } }, "headers": { "X-Trace-Id": { "description": "本次请求的追踪编号。", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } } }, "400": { "description": "参数格式错误（INVALID_ARGUMENT），或归集地址属于平台内任意租户的钱包（COLLECTION_ADDRESS_MANAGED）。拒绝时不修改配置、任务或保存成功幂等结果。请使用平台外地址，修改正文后重新签名。", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "code": { "const": 400 } } } ] }, "examples": { "invalid_address": { "summary": "地址格式无效", "value": { "code": 400, "message": "请输入有效的TRON地址", "error_code": "INVALID_ARGUMENT", "trace_id": "0123456789abcdef0123456789abcdef" } }, "managed_address": { "summary": "归集目标为平台钱包", "value": { "code": 400, "error_code": "COLLECTION_ADDRESS_MANAGED", "message": "归集地址不能使用平台内的钱包地址，请填写平台外的钱包地址", "trace_id": "0123456789abcdef0123456789abcdef" } } } } }, "headers": { "X-Trace-Id": { "description": "本次请求的追踪编号。", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } } }, "401": { "description": "签名、时间窗口或令牌无效", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "code": { "const": 401 } } } ] }, "example": { "code": 401, "message": "authentication required or expired", "error_code": "TOKEN_INVALID_OR_EXPIRED", "trace_id": "0123456789abcdef0123456789abcdef" } } }, "headers": { "X-Trace-Id": { "description": "本次请求的追踪编号。", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } } }, "403": { "description": "租户停用、删除或过期", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "code": { "const": 403 } } } ] }, "example": { "code": 403, "message": "tenant disabled or expired", "error_code": "TENANT_UNAVAILABLE", "trace_id": "0123456789abcdef0123456789abcdef" } } }, "headers": { "X-Trace-Id": { "description": "本次请求的追踪编号。", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } } }, "413": { "description": "请求体超过服务器显式配置的大小限制", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "code": { "const": 413 } } } ] }, "example": { "code": 413, "message": "request body exceeds configured limit", "error_code": "PAYLOAD_TOO_LARGE", "trace_id": "0123456789abcdef0123456789abcdef" } } }, "headers": { "X-Trace-Id": { "description": "本次请求的追踪编号。", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } } }, "429": { "description": "请求频率超限；读取 Retry-After 秒数", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "code": { "const": 429 } } } ] }, "example": { "code": 429, "message": "too many requests", "error_code": "RATE_LIMITED", "trace_id": "0123456789abcdef0123456789abcdef" } } }, "headers": { "Retry-After": { "description": "建议等待秒数；503 为 1。", "schema": { "type": "string", "pattern": "^[0-9]+$" } }, "X-Trace-Id": { "description": "本次请求的追踪编号。", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } } }, "500": { "description": "内部依赖或业务执行失败", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "code": { "const": 500 } } } ] }, "example": { "code": 500, "message": "internal operation failed", "error_code": "INTERNAL_ERROR", "trace_id": "0123456789abcdef0123456789abcdef" } } }, "headers": { "X-Trace-Id": { "description": "本次请求的追踪编号。", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } } }, "503": { "description": "HTTP 并发槽已满；Retry-After 为 1 秒", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "code": { "const": 503 } } } ] }, "example": { "code": 503, "message": "too many in-flight requests", "error_code": "SERVICE_UNAVAILABLE", "trace_id": "0123456789abcdef0123456789abcdef" } } }, "headers": { "Retry-After": { "description": "建议等待秒数；503 为 1。", "schema": { "type": "string", "pattern": "^[0-9]+$" } }, "X-Trace-Id": { "description": "本次请求的追踪编号。", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } } }, "504": { "description": "操作超过请求截止时间", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "code": { "const": 504 } } } ] }, "example": { "code": 504, "message": "request timed out", "error_code": "REQUEST_TIMEOUT", "trace_id": "0123456789abcdef0123456789abcdef" } } }, "headers": { "X-Trace-Id": { "description": "本次请求的追踪编号。", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } } }, "404": { "description": "租户当前网络的配置记录不存在。", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "code": { "const": 404 } } } ] }, "example": { "code": 404, "message": "record not found", "error_code": "RESOURCE_NOT_FOUND", "trace_id": "0123456789abcdef0123456789abcdef" } } }, "headers": { "X-Trace-Id": { "description": "本次请求的追踪编号。", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } } }, "409": { "description": "幂等参数冲突，或唯一记录冲突", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "code": { "const": 409 } } } ] }, "example": { "code": 409, "message": "conflict: idempotency key already used with another request", "error_code": "IDEMPOTENCY_CONFLICT", "trace_id": "0123456789abcdef0123456789abcdef" } } }, "headers": { "X-Trace-Id": { "description": "本次请求的追踪编号。", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } } }, "405": { "description": "路径或方法错误。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": 405, "error_code": "METHOD_NOT_ALLOWED", "message": "method not allowed", "trace_id": "0123456789abcdef0123456789abcdef" } } } } }, "requestBody": { "required": true, "description": "业务参数和 request_id 仅放 JSON；不接受 Query 或 Idempotency-Key。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetCollectionAddressBody" }, "example": { "address": "TAt8Du9Xw2CmrTHRawGETwiEKpNuKDSjE8", "request_id": "collection-address-20300101-0001" } } } } } }, "/open/v1/settings/automation": { "get": { "operationId": "automation_get", "summary": "查询自动归集配置", "description": "查询自动归集开关和 USDT 最小值。本接口不会触发归集任务。", "tags": [ "设置" ], "security": [ { "AppID": [], "Timestamp": [], "Signature": [], "Bearer": [] } ], "parameters": [ { "$ref": "#/components/parameters/AppID" }, { "$ref": "#/components/parameters/Timestamp" }, { "$ref": "#/components/parameters/Signature" } ], "responses": { "200": { "description": "请求成功。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AutomationSettingsResponse" }, "example": { "code": 0, "message": "", "data": { "enabled": true, "usdt_minimum": "100000000" } } } }, "headers": { "X-Trace-Id": { "description": "本次请求的追踪编号。", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } } }, "400": { "description": "参数或请求格式错误", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "code": { "const": 400 } } } ] }, "example": { "code": 400, "message": "invalid request", "error_code": "INVALID_ARGUMENT", "trace_id": "0123456789abcdef0123456789abcdef" } } }, "headers": { "X-Trace-Id": { "description": "本次请求的追踪编号。", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } } }, "401": { "description": "签名、时间窗口或令牌无效", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "code": { "const": 401 } } } ] }, "example": { "code": 401, "message": "authentication required or expired", "error_code": "TOKEN_INVALID_OR_EXPIRED", "trace_id": "0123456789abcdef0123456789abcdef" } } }, "headers": { "X-Trace-Id": { "description": "本次请求的追踪编号。", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } } }, "403": { "description": "租户停用、删除或过期", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "code": { "const": 403 } } } ] }, "example": { "code": 403, "message": "tenant disabled or expired", "error_code": "TENANT_UNAVAILABLE", "trace_id": "0123456789abcdef0123456789abcdef" } } }, "headers": { "X-Trace-Id": { "description": "本次请求的追踪编号。", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } } }, "413": { "description": "请求体超过服务器显式配置的大小限制", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "code": { "const": 413 } } } ] }, "example": { "code": 413, "message": "request body exceeds configured limit", "error_code": "PAYLOAD_TOO_LARGE", "trace_id": "0123456789abcdef0123456789abcdef" } } }, "headers": { "X-Trace-Id": { "description": "本次请求的追踪编号。", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } } }, "429": { "description": "请求频率超限；读取 Retry-After 秒数", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "code": { "const": 429 } } } ] }, "example": { "code": 429, "message": "too many requests", "error_code": "RATE_LIMITED", "trace_id": "0123456789abcdef0123456789abcdef" } } }, "headers": { "Retry-After": { "description": "建议等待秒数；503 为 1。", "schema": { "type": "string", "pattern": "^[0-9]+$" } }, "X-Trace-Id": { "description": "本次请求的追踪编号。", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } } }, "500": { "description": "内部依赖或业务执行失败", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "code": { "const": 500 } } } ] }, "example": { "code": 500, "message": "internal operation failed", "error_code": "INTERNAL_ERROR", "trace_id": "0123456789abcdef0123456789abcdef" } } }, "headers": { "X-Trace-Id": { "description": "本次请求的追踪编号。", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } } }, "503": { "description": "HTTP 并发槽已满；Retry-After 为 1 秒", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "code": { "const": 503 } } } ] }, "example": { "code": 503, "message": "too many in-flight requests", "error_code": "SERVICE_UNAVAILABLE", "trace_id": "0123456789abcdef0123456789abcdef" } } }, "headers": { "Retry-After": { "description": "建议等待秒数；503 为 1。", "schema": { "type": "string", "pattern": "^[0-9]+$" } }, "X-Trace-Id": { "description": "本次请求的追踪编号。", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } } }, "504": { "description": "操作超过请求截止时间", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "code": { "const": 504 } } } ] }, "example": { "code": 504, "message": "request timed out", "error_code": "REQUEST_TIMEOUT", "trace_id": "0123456789abcdef0123456789abcdef" } } }, "headers": { "X-Trace-Id": { "description": "本次请求的追踪编号。", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } } }, "404": { "description": "对象不存在，或不属于当前租户和网络", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "code": { "const": 404 } } } ] }, "example": { "code": 404, "message": "record not found", "error_code": "RESOURCE_NOT_FOUND", "trace_id": "0123456789abcdef0123456789abcdef" } } }, "headers": { "X-Trace-Id": { "description": "本次请求的追踪编号。", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } } }, "405": { "description": "路径或方法错误。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": 405, "error_code": "METHOD_NOT_ALLOWED", "message": "method not allowed", "trace_id": "0123456789abcdef0123456789abcdef" } } } } } }, "post": { "operationId": "automation_set", "summary": "设置自动归集", "description": "设置自动归集开关与金额阈值。每天 GMT+8 10:00，对达到阈值的钱包发起全额归集。关闭时取消尚未签名的自动任务，手动任务不受影响。相同 request_id 和参数返回原结果，改变参数返回 409。", "tags": [ "设置" ], "security": [ { "AppID": [], "Timestamp": [], "Signature": [], "Bearer": [] } ], "parameters": [ { "$ref": "#/components/parameters/AppID" }, { "$ref": "#/components/parameters/Timestamp" }, { "$ref": "#/components/parameters/Signature" } ], "responses": { "200": { "description": "请求成功。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AutomationSettingsResponse" }, "example": { "code": 0, "message": "", "data": { "enabled": true, "usdt_minimum": "100000000" } } } }, "headers": { "X-Trace-Id": { "description": "本次请求的追踪编号。", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } } }, "400": { "description": "参数或请求格式错误", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "code": { "const": 400 } } } ] }, "example": { "code": 400, "message": "开启自动归集前，请先绑定USDT归集地址", "error_code": "INVALID_ARGUMENT", "trace_id": "0123456789abcdef0123456789abcdef" } } }, "headers": { "X-Trace-Id": { "description": "本次请求的追踪编号。", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } } }, "401": { "description": "签名、时间窗口或令牌无效", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "code": { "const": 401 } } } ] }, "example": { "code": 401, "message": "authentication required or expired", "error_code": "TOKEN_INVALID_OR_EXPIRED", "trace_id": "0123456789abcdef0123456789abcdef" } } }, "headers": { "X-Trace-Id": { "description": "本次请求的追踪编号。", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } } }, "403": { "description": "租户停用、删除或过期", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "code": { "const": 403 } } } ] }, "example": { "code": 403, "message": "tenant disabled or expired", "error_code": "TENANT_UNAVAILABLE", "trace_id": "0123456789abcdef0123456789abcdef" } } }, "headers": { "X-Trace-Id": { "description": "本次请求的追踪编号。", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } } }, "413": { "description": "请求体超过服务器显式配置的大小限制", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "code": { "const": 413 } } } ] }, "example": { "code": 413, "message": "request body exceeds configured limit", "error_code": "PAYLOAD_TOO_LARGE", "trace_id": "0123456789abcdef0123456789abcdef" } } }, "headers": { "X-Trace-Id": { "description": "本次请求的追踪编号。", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } } }, "429": { "description": "请求频率超限；读取 Retry-After 秒数", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "code": { "const": 429 } } } ] }, "example": { "code": 429, "message": "too many requests", "error_code": "RATE_LIMITED", "trace_id": "0123456789abcdef0123456789abcdef" } } }, "headers": { "Retry-After": { "description": "建议等待秒数；503 为 1。", "schema": { "type": "string", "pattern": "^[0-9]+$" } }, "X-Trace-Id": { "description": "本次请求的追踪编号。", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } } }, "500": { "description": "内部依赖或业务执行失败", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "code": { "const": 500 } } } ] }, "example": { "code": 500, "message": "internal operation failed", "error_code": "INTERNAL_ERROR", "trace_id": "0123456789abcdef0123456789abcdef" } } }, "headers": { "X-Trace-Id": { "description": "本次请求的追踪编号。", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } } }, "503": { "description": "HTTP 并发槽已满；Retry-After 为 1 秒", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "code": { "const": 503 } } } ] }, "example": { "code": 503, "message": "too many in-flight requests", "error_code": "SERVICE_UNAVAILABLE", "trace_id": "0123456789abcdef0123456789abcdef" } } }, "headers": { "Retry-After": { "description": "建议等待秒数；503 为 1。", "schema": { "type": "string", "pattern": "^[0-9]+$" } }, "X-Trace-Id": { "description": "本次请求的追踪编号。", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } } }, "504": { "description": "操作超过请求截止时间", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "code": { "const": 504 } } } ] }, "example": { "code": 504, "message": "request timed out", "error_code": "REQUEST_TIMEOUT", "trace_id": "0123456789abcdef0123456789abcdef" } } }, "headers": { "X-Trace-Id": { "description": "本次请求的追踪编号。", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } } }, "404": { "description": "租户当前网络的配置记录不存在。", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "code": { "const": 404 } } } ] }, "example": { "code": 404, "message": "record not found", "error_code": "RESOURCE_NOT_FOUND", "trace_id": "0123456789abcdef0123456789abcdef" } } }, "headers": { "X-Trace-Id": { "description": "本次请求的追踪编号。", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } } }, "409": { "description": "幂等参数冲突，或唯一记录冲突", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "code": { "const": 409 } } } ] }, "example": { "code": 409, "message": "conflict: idempotency key already used with another request", "error_code": "IDEMPOTENCY_CONFLICT", "trace_id": "0123456789abcdef0123456789abcdef" } } }, "headers": { "X-Trace-Id": { "description": "本次请求的追踪编号。", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } } }, "405": { "description": "路径或方法错误。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": 405, "error_code": "METHOD_NOT_ALLOWED", "message": "method not allowed", "trace_id": "0123456789abcdef0123456789abcdef" } } } } }, "requestBody": { "required": true, "description": "业务参数和 request_id 仅放 JSON；不接受 Query 或 Idempotency-Key。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetAutomationBody" }, "example": { "enabled": true, "usdt_minimum": "100000000", "request_id": "automation-20300101-0001" } } } } } }, "/open/v1/settings/webhook": { "get": { "operationId": "webhook_config_get", "summary": "查询回调配置", "description": "查询回调地址和启用状态。本接口不会向回调地址发送测试请求。", "tags": [ "设置" ], "security": [ { "AppID": [], "Timestamp": [], "Signature": [], "Bearer": [] } ], "parameters": [ { "$ref": "#/components/parameters/AppID" }, { "$ref": "#/components/parameters/Timestamp" }, { "$ref": "#/components/parameters/Signature" } ], "responses": { "200": { "description": "请求成功。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookSettingsResponse" }, "example": { "code": 0, "message": "", "data": { "url": "https://merchant.example.com/guiji/webhook", "enabled": true } } } }, "headers": { "X-Trace-Id": { "description": "本次请求的追踪编号。", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } } }, "400": { "description": "参数或请求格式错误", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "code": { "const": 400 } } } ] }, "example": { "code": 400, "message": "invalid request", "error_code": "INVALID_ARGUMENT", "trace_id": "0123456789abcdef0123456789abcdef" } } }, "headers": { "X-Trace-Id": { "description": "本次请求的追踪编号。", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } } }, "401": { "description": "签名、时间窗口或令牌无效", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "code": { "const": 401 } } } ] }, "example": { "code": 401, "message": "authentication required or expired", "error_code": "TOKEN_INVALID_OR_EXPIRED", "trace_id": "0123456789abcdef0123456789abcdef" } } }, "headers": { "X-Trace-Id": { "description": "本次请求的追踪编号。", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } } }, "403": { "description": "租户停用、删除或过期", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "code": { "const": 403 } } } ] }, "example": { "code": 403, "message": "tenant disabled or expired", "error_code": "TENANT_UNAVAILABLE", "trace_id": "0123456789abcdef0123456789abcdef" } } }, "headers": { "X-Trace-Id": { "description": "本次请求的追踪编号。", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } } }, "413": { "description": "请求体超过服务器显式配置的大小限制", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "code": { "const": 413 } } } ] }, "example": { "code": 413, "message": "request body exceeds configured limit", "error_code": "PAYLOAD_TOO_LARGE", "trace_id": "0123456789abcdef0123456789abcdef" } } }, "headers": { "X-Trace-Id": { "description": "本次请求的追踪编号。", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } } }, "429": { "description": "请求频率超限；读取 Retry-After 秒数", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "code": { "const": 429 } } } ] }, "example": { "code": 429, "message": "too many requests", "error_code": "RATE_LIMITED", "trace_id": "0123456789abcdef0123456789abcdef" } } }, "headers": { "Retry-After": { "description": "建议等待秒数；503 为 1。", "schema": { "type": "string", "pattern": "^[0-9]+$" } }, "X-Trace-Id": { "description": "本次请求的追踪编号。", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } } }, "500": { "description": "内部依赖或业务执行失败", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "code": { "const": 500 } } } ] }, "example": { "code": 500, "message": "internal operation failed", "error_code": "INTERNAL_ERROR", "trace_id": "0123456789abcdef0123456789abcdef" } } }, "headers": { "X-Trace-Id": { "description": "本次请求的追踪编号。", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } } }, "503": { "description": "HTTP 并发槽已满；Retry-After 为 1 秒", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "code": { "const": 503 } } } ] }, "example": { "code": 503, "message": "too many in-flight requests", "error_code": "SERVICE_UNAVAILABLE", "trace_id": "0123456789abcdef0123456789abcdef" } } }, "headers": { "Retry-After": { "description": "建议等待秒数；503 为 1。", "schema": { "type": "string", "pattern": "^[0-9]+$" } }, "X-Trace-Id": { "description": "本次请求的追踪编号。", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } } }, "504": { "description": "操作超过请求截止时间", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "code": { "const": 504 } } } ] }, "example": { "code": 504, "message": "request timed out", "error_code": "REQUEST_TIMEOUT", "trace_id": "0123456789abcdef0123456789abcdef" } } }, "headers": { "X-Trace-Id": { "description": "本次请求的追踪编号。", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } } }, "404": { "description": "对象不存在，或不属于当前租户和网络", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "code": { "const": 404 } } } ] }, "example": { "code": 404, "message": "record not found", "error_code": "RESOURCE_NOT_FOUND", "trace_id": "0123456789abcdef0123456789abcdef" } } }, "headers": { "X-Trace-Id": { "description": "本次请求的追踪编号。", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } } }, "405": { "description": "路径或方法错误。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": 405, "error_code": "METHOD_NOT_ALLOWED", "message": "method not allowed", "trace_id": "0123456789abcdef0123456789abcdef" } } } } } }, "post": { "operationId": "webhook_config_set", "summary": "设置回调配置", "description": "设置公网 HTTPS 回调地址和启用状态，只接受 443 端口。新配置用于后续新轮次，已开始的轮次保留原回调地址。相同 request_id 和参数返回原结果，改变参数返回 409。", "tags": [ "设置" ], "security": [ { "AppID": [], "Timestamp": [], "Signature": [], "Bearer": [] } ], "parameters": [ { "$ref": "#/components/parameters/AppID" }, { "$ref": "#/components/parameters/Timestamp" }, { "$ref": "#/components/parameters/Signature" } ], "responses": { "200": { "description": "请求成功。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookSettingsResponse" }, "example": { "code": 0, "message": "", "data": { "url": "https://merchant.example.com/guiji/webhook", "enabled": true } } } }, "headers": { "X-Trace-Id": { "description": "本次请求的追踪编号。", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } } }, "400": { "description": "参数或请求格式错误", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "code": { "const": 400 } } } ] }, "example": { "code": 400, "message": "webhook URL required when enabled", "error_code": "INVALID_ARGUMENT", "trace_id": "0123456789abcdef0123456789abcdef" } } }, "headers": { "X-Trace-Id": { "description": "本次请求的追踪编号。", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } } }, "401": { "description": "签名、时间窗口或令牌无效", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "code": { "const": 401 } } } ] }, "example": { "code": 401, "message": "authentication required or expired", "error_code": "TOKEN_INVALID_OR_EXPIRED", "trace_id": "0123456789abcdef0123456789abcdef" } } }, "headers": { "X-Trace-Id": { "description": "本次请求的追踪编号。", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } } }, "403": { "description": "租户停用、删除或过期", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "code": { "const": 403 } } } ] }, "example": { "code": 403, "message": "tenant disabled or expired", "error_code": "TENANT_UNAVAILABLE", "trace_id": "0123456789abcdef0123456789abcdef" } } }, "headers": { "X-Trace-Id": { "description": "本次请求的追踪编号。", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } } }, "413": { "description": "请求体超过服务器显式配置的大小限制", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "code": { "const": 413 } } } ] }, "example": { "code": 413, "message": "request body exceeds configured limit", "error_code": "PAYLOAD_TOO_LARGE", "trace_id": "0123456789abcdef0123456789abcdef" } } }, "headers": { "X-Trace-Id": { "description": "本次请求的追踪编号。", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } } }, "429": { "description": "请求频率超限；读取 Retry-After 秒数", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "code": { "const": 429 } } } ] }, "example": { "code": 429, "message": "too many requests", "error_code": "RATE_LIMITED", "trace_id": "0123456789abcdef0123456789abcdef" } } }, "headers": { "Retry-After": { "description": "建议等待秒数；503 为 1。", "schema": { "type": "string", "pattern": "^[0-9]+$" } }, "X-Trace-Id": { "description": "本次请求的追踪编号。", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } } }, "500": { "description": "内部依赖或业务执行失败", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "code": { "const": 500 } } } ] }, "example": { "code": 500, "message": "internal operation failed", "error_code": "INTERNAL_ERROR", "trace_id": "0123456789abcdef0123456789abcdef" } } }, "headers": { "X-Trace-Id": { "description": "本次请求的追踪编号。", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } } }, "503": { "description": "HTTP 并发槽已满；Retry-After 为 1 秒", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "code": { "const": 503 } } } ] }, "example": { "code": 503, "message": "too many in-flight requests", "error_code": "SERVICE_UNAVAILABLE", "trace_id": "0123456789abcdef0123456789abcdef" } } }, "headers": { "Retry-After": { "description": "建议等待秒数；503 为 1。", "schema": { "type": "string", "pattern": "^[0-9]+$" } }, "X-Trace-Id": { "description": "本次请求的追踪编号。", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } } }, "504": { "description": "操作超过请求截止时间", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "code": { "const": 504 } } } ] }, "example": { "code": 504, "message": "request timed out", "error_code": "REQUEST_TIMEOUT", "trace_id": "0123456789abcdef0123456789abcdef" } } }, "headers": { "X-Trace-Id": { "description": "本次请求的追踪编号。", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } } }, "409": { "description": "幂等参数冲突，或唯一记录冲突", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "code": { "const": 409 } } } ] }, "example": { "code": 409, "message": "conflict: idempotency key already used with another request", "error_code": "IDEMPOTENCY_CONFLICT", "trace_id": "0123456789abcdef0123456789abcdef" } } }, "headers": { "X-Trace-Id": { "description": "本次请求的追踪编号。", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } } }, "404": { "description": "路径或方法错误。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": 404, "error_code": "ROUTE_NOT_FOUND", "message": "API route not found", "trace_id": "0123456789abcdef0123456789abcdef" } } } }, "405": { "description": "路径或方法错误。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": 405, "error_code": "METHOD_NOT_ALLOWED", "message": "method not allowed", "trace_id": "0123456789abcdef0123456789abcdef" } } } } }, "requestBody": { "required": true, "description": "业务参数和 request_id 仅放 JSON；不接受 Query 或 Idempotency-Key。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetWebhookBody" }, "example": { "url": "https://merchant.example.com/guiji/webhook", "enabled": true, "request_id": "webhook-config-20300101-0001" } } } } } }, "/open/v1/wallets/preview": { "post": { "operationId": "wallet_preview", "summary": "批量预览钱包", "description": "按钱包 ID 清单查询余额与可归集状态，去重后按首次出现顺序返回。任一 ID 无权访问则整体返回 404。本接口不占用钱包，不需要 request_id。", "tags": [ "钱包" ], "security": [ { "AppID": [], "Timestamp": [], "Signature": [], "Bearer": [] } ], "parameters": [ { "$ref": "#/components/parameters/AppID" }, { "$ref": "#/components/parameters/Timestamp" }, { "$ref": "#/components/parameters/Signature" } ], "responses": { "200": { "description": "请求成功。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletPreviewResponse" }, "example": { "code": 0, "message": "", "data": { "items": [ { "id": "123456789012345678", "address": "TQyeXvAnmKsBqo6V48RmhAnZpWLmR2D7DM", "custom_id": "customer-001", "chain": "TRON", "network": "nile", "collection_status": "idle", "balance_usdt": "100000000", "balance_trx": "30000000", "balance_block": "12345678", "destination": "TAt8Du9Xw2CmrTHRawGETwiEKpNuKDSjE8", "collected_usdt": "0", "last_collected_at": null, "created_at": "2030-01-01T00:00:00Z" } ], "network": "nile" } } } }, "headers": { "X-Trace-Id": { "description": "本次请求的追踪编号。", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } } }, "400": { "description": "参数或请求格式错误", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "code": { "const": 400 } } } ] }, "example": { "code": 400, "message": "invalid request: wallet_ids requires 1..1000 IDs", "error_code": "INVALID_ARGUMENT", "trace_id": "0123456789abcdef0123456789abcdef" } } }, "headers": { "X-Trace-Id": { "description": "本次请求的追踪编号。", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } } }, "401": { "description": "签名、时间窗口或令牌无效", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "code": { "const": 401 } } } ] }, "example": { "code": 401, "message": "authentication required or expired", "error_code": "TOKEN_INVALID_OR_EXPIRED", "trace_id": "0123456789abcdef0123456789abcdef" } } }, "headers": { "X-Trace-Id": { "description": "本次请求的追踪编号。", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } } }, "403": { "description": "租户停用、删除或过期", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "code": { "const": 403 } } } ] }, "example": { "code": 403, "message": "tenant disabled or expired", "error_code": "TENANT_UNAVAILABLE", "trace_id": "0123456789abcdef0123456789abcdef" } } }, "headers": { "X-Trace-Id": { "description": "本次请求的追踪编号。", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } } }, "413": { "description": "请求体超过服务器显式配置的大小限制", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "code": { "const": 413 } } } ] }, "example": { "code": 413, "message": "request body exceeds configured limit", "error_code": "PAYLOAD_TOO_LARGE", "trace_id": "0123456789abcdef0123456789abcdef" } } }, "headers": { "X-Trace-Id": { "description": "本次请求的追踪编号。", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } } }, "429": { "description": "请求频率超限；读取 Retry-After 秒数", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "code": { "const": 429 } } } ] }, "example": { "code": 429, "message": "too many requests", "error_code": "RATE_LIMITED", "trace_id": "0123456789abcdef0123456789abcdef" } } }, "headers": { "Retry-After": { "description": "建议等待秒数；503 为 1。", "schema": { "type": "string", "pattern": "^[0-9]+$" } }, "X-Trace-Id": { "description": "本次请求的追踪编号。", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } } }, "500": { "description": "内部依赖或业务执行失败", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "code": { "const": 500 } } } ] }, "example": { "code": 500, "message": "internal operation failed", "error_code": "INTERNAL_ERROR", "trace_id": "0123456789abcdef0123456789abcdef" } } }, "headers": { "X-Trace-Id": { "description": "本次请求的追踪编号。", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } } }, "503": { "description": "HTTP 并发槽已满；Retry-After 为 1 秒", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "code": { "const": 503 } } } ] }, "example": { "code": 503, "message": "too many in-flight requests", "error_code": "SERVICE_UNAVAILABLE", "trace_id": "0123456789abcdef0123456789abcdef" } } }, "headers": { "Retry-After": { "description": "建议等待秒数；503 为 1。", "schema": { "type": "string", "pattern": "^[0-9]+$" } }, "X-Trace-Id": { "description": "本次请求的追踪编号。", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } } }, "504": { "description": "操作超过请求截止时间", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "code": { "const": 504 } } } ] }, "example": { "code": 504, "message": "request timed out", "error_code": "REQUEST_TIMEOUT", "trace_id": "0123456789abcdef0123456789abcdef" } } }, "headers": { "X-Trace-Id": { "description": "本次请求的追踪编号。", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } } }, "404": { "description": "对象不存在，或不属于当前租户和网络", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "code": { "const": 404 } } } ] }, "example": { "code": 404, "message": "not found", "error_code": "RESOURCE_NOT_FOUND", "trace_id": "0123456789abcdef0123456789abcdef" } } }, "headers": { "X-Trace-Id": { "description": "本次请求的追踪编号。", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } } }, "405": { "description": "路径或方法错误。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": 405, "error_code": "METHOD_NOT_ALLOWED", "message": "method not allowed", "trace_id": "0123456789abcdef0123456789abcdef" } } } } }, "requestBody": { "required": true, "description": "只读 POST，参数仅放 JSON，不接受 Query、request_id 或 Idempotency-Key。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletPreviewBody" }, "example": { "wallet_ids": [ "123456789012345678" ] } } } } } }, "/open/v1/sweeps/estimate": { "post": { "operationId": "sweep_estimate", "summary": "预估归集手续费", "description": "预估所选钱包归集所需的能量、免费带宽、钱包 TRX 费用和平台租赁费用，不创建转账或租赁订单。每次最多 20 个钱包，必须检查每项 status 和 reason；预估结果不保证后续执行成功。本接口不需要 request_id。", "tags": [ "归集" ], "security": [ { "AppID": [], "Timestamp": [], "Signature": [], "Bearer": [] } ], "parameters": [ { "$ref": "#/components/parameters/AppID" }, { "$ref": "#/components/parameters/Timestamp" }, { "$ref": "#/components/parameters/Signature" } ], "responses": { "200": { "description": "请求成功。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SweepEstimateResponse" }, "examples": { "wallet_trx": { "summary": "钱包自身 TRX 足够承担整个准备缺口", "value": { "code": 0, "message": "", "data": { "network": "nile", "destination": "TAt8Du9Xw2CmrTHRawGETwiEKpNuKDSjE8", "destination_version": "1", "sweep_mode": "all", "requested_amount": null, "estimated_at": "2030-01-01T00:00:00Z", "items": [ { "wallet_id": "123456789012345678", "address": "TQyeXvAnmKsBqo6V48RmhAnZpWLmR2D7DM", "amount": "100000000", "status": "estimated", "reason": "", "estimate": { "energy_required": "65000", "energy_from_origin": "0", "caller_energy_required": "65000", "energy_available": "0", "energy_from_resources": "0", "energy_burned": "65000", "energy_fee": "6500000", "bandwidth_required": "350", "staked_bandwidth_available": "0", "free_bandwidth_available": "600", "bandwidth_from_resources": "350", "bandwidth_burned": "0", "bandwidth_fee": "0", "energy_price": "100", "bandwidth_price": "1000", "fee_limit": "7150000", "estimated_fee": "6500000", "balance_usdt": "100000000", "balance_trx": "30000000", "bandwidth_source": "free", "rental_quantity": "0", "rental_cost": "0", "activation_required": "false", "fee_source": "wallet_trx", "prepared_energy": "71500", "max_wallet_trx_fee": "7150000", "free_bandwidth_limit": "600" } } ] } } }, "resources": { "summary": "已有能量足够，无需租赁", "value": { "code": 0, "message": "", "data": { "network": "nile", "destination": "TAt8Du9Xw2CmrTHRawGETwiEKpNuKDSjE8", "destination_version": "1", "sweep_mode": "all", "requested_amount": null, "estimated_at": "2030-01-01T00:00:00Z", "items": [ { "wallet_id": "123456789012345678", "address": "TQyeXvAnmKsBqo6V48RmhAnZpWLmR2D7DM", "amount": "100000000", "status": "estimated", "reason": "", "estimate": { "energy_required": "65000", "energy_from_origin": "0", "caller_energy_required": "65000", "energy_available": "71500", "energy_from_resources": "65000", "energy_burned": "0", "energy_fee": "0", "bandwidth_required": "350", "staked_bandwidth_available": "0", "free_bandwidth_available": "600", "bandwidth_from_resources": "350", "bandwidth_burned": "0", "bandwidth_fee": "0", "energy_price": "100", "bandwidth_price": "1000", "fee_limit": "7150000", "estimated_fee": "0", "balance_usdt": "100000000", "balance_trx": "30000000", "bandwidth_source": "free", "rental_quantity": "0", "rental_cost": "0", "activation_required": "false", "fee_source": "resources", "prepared_energy": "71500", "max_wallet_trx_fee": "0", "free_bandwidth_limit": "600" } } ] } } }, "catfee": { "summary": "钱包 TRX 不足，使用平台能量租赁；示例费用非实时报价", "value": { "code": 0, "message": "", "data": { "network": "nile", "destination": "TAt8Du9Xw2CmrTHRawGETwiEKpNuKDSjE8", "destination_version": "1", "sweep_mode": "all", "requested_amount": null, "estimated_at": "2030-01-01T00:00:00Z", "items": [ { "wallet_id": "123456789012345678", "address": "TQyeXvAnmKsBqo6V48RmhAnZpWLmR2D7DM", "amount": "100000000", "status": "estimated", "reason": "", "estimate": { "energy_required": "65000", "energy_from_origin": "0", "caller_energy_required": "65000", "energy_available": "0", "energy_from_resources": "0", "energy_burned": "65000", "energy_fee": "0", "bandwidth_required": "350", "staked_bandwidth_available": "0", "free_bandwidth_available": "600", "bandwidth_from_resources": "350", "bandwidth_burned": "0", "bandwidth_fee": "0", "energy_price": "100", "bandwidth_price": "1000", "fee_limit": "7150000", "estimated_fee": "0", "balance_usdt": "100000000", "balance_trx": "0", "bandwidth_source": "free", "rental_quantity": "71500", "rental_cost": "1000000", "activation_required": "false", "fee_source": "catfee", "prepared_energy": "71500", "max_wallet_trx_fee": "0", "free_bandwidth_limit": "600" } } ] } } }, "waiting_bandwidth": { "summary": "免费带宽不足；创建任务后等待恢复，预估不购买能量", "value": { "code": 0, "message": "", "data": { "network": "nile", "destination": "TAt8Du9Xw2CmrTHRawGETwiEKpNuKDSjE8", "destination_version": "1", "sweep_mode": "all", "requested_amount": null, "estimated_at": "2030-01-01T00:00:00Z", "items": [ { "wallet_id": "123456789012345678", "address": "TQyeXvAnmKsBqo6V48RmhAnZpWLmR2D7DM", "amount": "100000000", "status": "estimated", "reason": "", "estimate": { "energy_required": "65000", "energy_from_origin": "0", "caller_energy_required": "65000", "energy_available": "0", "energy_from_resources": "0", "energy_burned": "65000", "energy_fee": "6500000", "bandwidth_required": "350", "staked_bandwidth_available": "0", "free_bandwidth_available": "100", "bandwidth_from_resources": "0", "bandwidth_burned": "350", "bandwidth_fee": "0", "energy_price": "100", "bandwidth_price": "1000", "fee_limit": "7150000", "estimated_fee": "6500000", "balance_usdt": "100000000", "balance_trx": "30000000", "bandwidth_source": "waiting", "rental_quantity": "0", "rental_cost": "0", "activation_required": "false", "fee_source": "wallet_trx", "prepared_energy": "71500", "max_wallet_trx_fee": "7150000", "free_bandwidth_limit": "600" } } ] } } } } } }, "headers": { "X-Trace-Id": { "description": "本次请求的追踪编号。", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } } }, "400": { "description": "参数或请求格式错误", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "code": { "const": 400 } } } ] }, "example": { "code": 400, "message": "每次预估请选择1至20个钱包", "error_code": "INVALID_ARGUMENT", "trace_id": "0123456789abcdef0123456789abcdef" } } }, "headers": { "X-Trace-Id": { "description": "本次请求的追踪编号。", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } } }, "401": { "description": "签名、时间窗口或令牌无效", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "code": { "const": 401 } } } ] }, "example": { "code": 401, "message": "authentication required or expired", "error_code": "TOKEN_INVALID_OR_EXPIRED", "trace_id": "0123456789abcdef0123456789abcdef" } } }, "headers": { "X-Trace-Id": { "description": "本次请求的追踪编号。", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } } }, "403": { "description": "租户停用、删除或过期", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "code": { "const": 403 } } } ] }, "example": { "code": 403, "message": "tenant disabled or expired", "error_code": "TENANT_UNAVAILABLE", "trace_id": "0123456789abcdef0123456789abcdef" } } }, "headers": { "X-Trace-Id": { "description": "本次请求的追踪编号。", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } } }, "413": { "description": "请求体超过服务器显式配置的大小限制", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "code": { "const": 413 } } } ] }, "example": { "code": 413, "message": "request body exceeds configured limit", "error_code": "PAYLOAD_TOO_LARGE", "trace_id": "0123456789abcdef0123456789abcdef" } } }, "headers": { "X-Trace-Id": { "description": "本次请求的追踪编号。", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } } }, "429": { "description": "请求频率超限；读取 Retry-After 秒数", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "code": { "const": 429 } } } ] }, "example": { "code": 429, "message": "too many requests", "error_code": "RATE_LIMITED", "trace_id": "0123456789abcdef0123456789abcdef" } } }, "headers": { "Retry-After": { "description": "建议等待秒数；503 为 1。", "schema": { "type": "string", "pattern": "^[0-9]+$" } }, "X-Trace-Id": { "description": "本次请求的追踪编号。", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } } }, "500": { "description": "内部依赖或业务执行失败", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "code": { "const": 500 } } } ] }, "example": { "code": 500, "message": "internal operation failed", "error_code": "INTERNAL_ERROR", "trace_id": "0123456789abcdef0123456789abcdef" } } }, "headers": { "X-Trace-Id": { "description": "本次请求的追踪编号。", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } } }, "503": { "description": "HTTP并发槽已满，或TRON配置/节点不可用。仅并发槽已满时保证Retry-After: 1。", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "code": { "const": 503 } } } ] }, "examples": { "overloaded": { "value": { "code": 503, "message": "too many in-flight requests", "error_code": "SERVICE_UNAVAILABLE", "trace_id": "0123456789abcdef0123456789abcdef" } }, "unconfigured": { "value": { "code": 503, "message": "归集预估服务配置不完整", "error_code": "SERVICE_UNAVAILABLE", "trace_id": "0123456789abcdef0123456789abcdef" } } } } }, "headers": { "Retry-After": { "description": "建议等待秒数；503 为 1。", "schema": { "type": "string", "pattern": "^[0-9]+$" } }, "X-Trace-Id": { "description": "本次请求的追踪编号。", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } } }, "504": { "description": "操作超过请求截止时间", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "code": { "const": 504 } } } ] }, "example": { "code": 504, "message": "request timed out", "error_code": "REQUEST_TIMEOUT", "trace_id": "0123456789abcdef0123456789abcdef" } } }, "headers": { "X-Trace-Id": { "description": "本次请求的追踪编号。", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } } }, "404": { "description": "对象不存在，或不属于当前租户和网络", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "code": { "const": 404 } } } ] }, "example": { "code": 404, "message": "钱包不存在或不属于当前租户及网络", "error_code": "RESOURCE_NOT_FOUND", "trace_id": "0123456789abcdef0123456789abcdef" } } }, "headers": { "X-Trace-Id": { "description": "本次请求的追踪编号。", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } } }, "409": { "description": "归集地址未配置或无效。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": 409, "message": "请先配置USDT归集地址", "error_code": "BUSINESS_CONFLICT", "trace_id": "0123456789abcdef0123456789abcdef" } } }, "headers": { "X-Trace-Id": { "description": "本次请求的追踪编号。", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } } }, "405": { "description": "路径或方法错误。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": 405, "error_code": "METHOD_NOT_ALLOWED", "message": "method not allowed", "trace_id": "0123456789abcdef0123456789abcdef" } } } } }, "requestBody": { "required": true, "description": "只读 POST，参数仅放 JSON，不接受 Query、request_id 或 Idempotency-Key。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SweepEstimateBody" }, "example": { "wallet_ids": [ "123456789012345678" ], "sweep_mode": "all", "requested_amount": null } } } } } }, "/open/v1/webhooks": { "get": { "operationId": "webhook_list", "summary": "查询通知列表", "description": "分页查询到账与归集结果通知的投递状态、次数和最近异常。", "tags": [ "通知投递" ], "security": [ { "AppID": [], "Timestamp": [], "Signature": [], "Bearer": [] } ], "parameters": [ { "$ref": "#/components/parameters/AppID" }, { "$ref": "#/components/parameters/Timestamp" }, { "$ref": "#/components/parameters/Signature" }, { "$ref": "#/components/parameters/Page" }, { "$ref": "#/components/parameters/PageSize" } ], "responses": { "200": { "description": "请求成功。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEventPageResponse" }, "example": { "code": 0, "message": "", "data": { "items": [ { "id": "123456789012345680", "event_type": "deposit.confirmed", "status": "failed", "attempts": 20, "current_round": 1, "next_attempt": null, "deadline_at": "2030-01-01T00:10:00Z", "last_error": "maximum attempts reached", "created_at": "2030-01-01T00:00:00Z", "delivered_at": null, "network": "nile" } ], "total": 1, "page": 1, "page_size": 20, "network": "nile" } } } }, "headers": { "X-Trace-Id": { "description": "本次请求的追踪编号。", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } } }, "400": { "description": "参数或请求格式错误", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "code": { "const": 400 } } } ] }, "example": { "code": 400, "message": "invalid request", "error_code": "INVALID_ARGUMENT", "trace_id": "0123456789abcdef0123456789abcdef" } } }, "headers": { "X-Trace-Id": { "description": "本次请求的追踪编号。", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } } }, "401": { "description": "签名、时间窗口或令牌无效", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "code": { "const": 401 } } } ] }, "example": { "code": 401, "message": "authentication required or expired", "error_code": "TOKEN_INVALID_OR_EXPIRED", "trace_id": "0123456789abcdef0123456789abcdef" } } }, "headers": { "X-Trace-Id": { "description": "本次请求的追踪编号。", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } } }, "403": { "description": "租户停用、删除或过期", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "code": { "const": 403 } } } ] }, "example": { "code": 403, "message": "tenant disabled or expired", "error_code": "TENANT_UNAVAILABLE", "trace_id": "0123456789abcdef0123456789abcdef" } } }, "headers": { "X-Trace-Id": { "description": "本次请求的追踪编号。", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } } }, "413": { "description": "请求体超过服务器显式配置的大小限制", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "code": { "const": 413 } } } ] }, "example": { "code": 413, "message": "request body exceeds configured limit", "error_code": "PAYLOAD_TOO_LARGE", "trace_id": "0123456789abcdef0123456789abcdef" } } }, "headers": { "X-Trace-Id": { "description": "本次请求的追踪编号。", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } } }, "429": { "description": "请求频率超限；读取 Retry-After 秒数", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "code": { "const": 429 } } } ] }, "example": { "code": 429, "message": "too many requests", "error_code": "RATE_LIMITED", "trace_id": "0123456789abcdef0123456789abcdef" } } }, "headers": { "Retry-After": { "description": "建议等待秒数；503 为 1。", "schema": { "type": "string", "pattern": "^[0-9]+$" } }, "X-Trace-Id": { "description": "本次请求的追踪编号。", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } } }, "500": { "description": "内部依赖或业务执行失败", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "code": { "const": 500 } } } ] }, "example": { "code": 500, "message": "internal operation failed", "error_code": "INTERNAL_ERROR", "trace_id": "0123456789abcdef0123456789abcdef" } } }, "headers": { "X-Trace-Id": { "description": "本次请求的追踪编号。", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } } }, "503": { "description": "HTTP 并发槽已满；Retry-After 为 1 秒", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "code": { "const": 503 } } } ] }, "example": { "code": 503, "message": "too many in-flight requests", "error_code": "SERVICE_UNAVAILABLE", "trace_id": "0123456789abcdef0123456789abcdef" } } }, "headers": { "Retry-After": { "description": "建议等待秒数；503 为 1。", "schema": { "type": "string", "pattern": "^[0-9]+$" } }, "X-Trace-Id": { "description": "本次请求的追踪编号。", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } } }, "504": { "description": "操作超过请求截止时间", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "code": { "const": 504 } } } ] }, "example": { "code": 504, "message": "request timed out", "error_code": "REQUEST_TIMEOUT", "trace_id": "0123456789abcdef0123456789abcdef" } } }, "headers": { "X-Trace-Id": { "description": "本次请求的追踪编号。", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } } }, "404": { "description": "路径或方法错误。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": 404, "error_code": "ROUTE_NOT_FOUND", "message": "API route not found", "trace_id": "0123456789abcdef0123456789abcdef" } } } }, "405": { "description": "路径或方法错误。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": 405, "error_code": "METHOD_NOT_ALLOWED", "message": "method not allowed", "trace_id": "0123456789abcdef0123456789abcdef" } } } } } } }, "/open/v1/webhooks/{id}": { "get": { "operationId": "webhook_detail", "summary": "查询通知详情", "description": "查询通知的投递状态和原始业务正文。payload 为该事件的明文对象，与回调解密结果一致；到账查询可能已更新到更高 revision。", "tags": [ "通知投递" ], "security": [ { "AppID": [], "Timestamp": [], "Signature": [], "Bearer": [] } ], "parameters": [ { "$ref": "#/components/parameters/AppID" }, { "$ref": "#/components/parameters/Timestamp" }, { "$ref": "#/components/parameters/Signature" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "description": "规范正 int64 事件 ID，最大 9223372036854775807。", "pattern": "^[1-9][0-9]*$", "examples": [ "123456789012345680" ] } } ], "responses": { "200": { "description": "请求成功。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEventDetailResponse" }, "example": { "code": 0, "message": "", "data": { "id": "123456789012345680", "event_type": "deposit.confirmed", "status": "failed", "attempts": 20, "current_round": 1, "next_attempt": null, "deadline_at": "2030-01-01T00:10:00Z", "last_error": "maximum attempts reached", "created_at": "2030-01-01T00:00:00Z", "delivered_at": null, "payload": { "id": "123456789012345680", "event_id": "123456789012345680", "event_type": "deposit.confirmed", "status": "confirmed", "wallet_id": "123456789012345678", "custom_id": "customer-1001", "chain": "TRON", "network": "nile", "asset": "USDT", "token_standard": "TRC20", "decimals": 6, "address": "TQyeXvAnmKsBqo6V48RmhAnZpWLmR2D7DM", "source": "TWkz4y25cWK517vSdMP1N4EWHySqwQ6dMb", "contract": "TXYZopYRdj2D9XRtbG411XZZ3kM5VkAeBf", "amount": "100000000", "txid": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "log_index": 0, "block_number": "12345678", "block_time": "2030-01-01T00:00:00.000000Z", "created_at": "2030-01-01T00:00:01.000000Z", "revision": 1, "confirmation_type": "solidified", "confirmations": null, "block_hash": null }, "network": "nile" } } } }, "headers": { "X-Trace-Id": { "description": "本次请求的追踪编号。", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } } }, "400": { "description": "参数或请求格式错误", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "code": { "const": 400 } } } ] }, "example": { "code": 400, "message": "invalid request", "error_code": "INVALID_ARGUMENT", "trace_id": "0123456789abcdef0123456789abcdef" } } }, "headers": { "X-Trace-Id": { "description": "本次请求的追踪编号。", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } } }, "401": { "description": "签名、时间窗口或令牌无效", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "code": { "const": 401 } } } ] }, "example": { "code": 401, "message": "authentication required or expired", "error_code": "TOKEN_INVALID_OR_EXPIRED", "trace_id": "0123456789abcdef0123456789abcdef" } } }, "headers": { "X-Trace-Id": { "description": "本次请求的追踪编号。", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } } }, "403": { "description": "租户停用、删除或过期", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "code": { "const": 403 } } } ] }, "example": { "code": 403, "message": "tenant disabled or expired", "error_code": "TENANT_UNAVAILABLE", "trace_id": "0123456789abcdef0123456789abcdef" } } }, "headers": { "X-Trace-Id": { "description": "本次请求的追踪编号。", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } } }, "413": { "description": "请求体超过服务器显式配置的大小限制", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "code": { "const": 413 } } } ] }, "example": { "code": 413, "message": "request body exceeds configured limit", "error_code": "PAYLOAD_TOO_LARGE", "trace_id": "0123456789abcdef0123456789abcdef" } } }, "headers": { "X-Trace-Id": { "description": "本次请求的追踪编号。", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } } }, "429": { "description": "请求频率超限；读取 Retry-After 秒数", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "code": { "const": 429 } } } ] }, "example": { "code": 429, "message": "too many requests", "error_code": "RATE_LIMITED", "trace_id": "0123456789abcdef0123456789abcdef" } } }, "headers": { "Retry-After": { "description": "建议等待秒数；503 为 1。", "schema": { "type": "string", "pattern": "^[0-9]+$" } }, "X-Trace-Id": { "description": "本次请求的追踪编号。", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } } }, "500": { "description": "内部依赖或业务执行失败", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "code": { "const": 500 } } } ] }, "example": { "code": 500, "message": "internal operation failed", "error_code": "INTERNAL_ERROR", "trace_id": "0123456789abcdef0123456789abcdef" } } }, "headers": { "X-Trace-Id": { "description": "本次请求的追踪编号。", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } } }, "503": { "description": "HTTP 并发槽已满；Retry-After 为 1 秒", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "code": { "const": 503 } } } ] }, "example": { "code": 503, "message": "too many in-flight requests", "error_code": "SERVICE_UNAVAILABLE", "trace_id": "0123456789abcdef0123456789abcdef" } } }, "headers": { "Retry-After": { "description": "建议等待秒数；503 为 1。", "schema": { "type": "string", "pattern": "^[0-9]+$" } }, "X-Trace-Id": { "description": "本次请求的追踪编号。", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } } }, "504": { "description": "操作超过请求截止时间", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "code": { "const": 504 } } } ] }, "example": { "code": 504, "message": "request timed out", "error_code": "REQUEST_TIMEOUT", "trace_id": "0123456789abcdef0123456789abcdef" } } }, "headers": { "X-Trace-Id": { "description": "本次请求的追踪编号。", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } } }, "404": { "description": "对象不存在，或不属于当前租户和网络", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "code": { "const": 404 } } } ] }, "example": { "code": 404, "message": "record not found", "error_code": "RESOURCE_NOT_FOUND", "trace_id": "0123456789abcdef0123456789abcdef" } } }, "headers": { "X-Trace-Id": { "description": "本次请求的追踪编号。", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } } }, "405": { "description": "路径或方法错误。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": 405, "error_code": "METHOD_NOT_ALLOWED", "message": "method not allowed", "trace_id": "0123456789abcdef0123456789abcdef" } } } } } } }, "/open/v1/webhooks/{id}/rounds": { "get": { "operationId": "webhook_rounds", "summary": "查询通知轮次", "description": "分页查询通知的全部推送轮次，包括回调地址、开始与截止时间、次数和结果。", "tags": [ "通知投递" ], "security": [ { "AppID": [], "Timestamp": [], "Signature": [], "Bearer": [] } ], "parameters": [ { "$ref": "#/components/parameters/AppID" }, { "$ref": "#/components/parameters/Timestamp" }, { "$ref": "#/components/parameters/Signature" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "description": "规范正 int64 事件 ID，最大 9223372036854775807。", "pattern": "^[1-9][0-9]*$", "examples": [ "123456789012345680" ] } }, { "$ref": "#/components/parameters/Page" }, { "$ref": "#/components/parameters/PageSize" } ], "responses": { "200": { "description": "请求成功。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookRoundPageResponse" }, "example": { "code": 0, "message": "", "data": { "items": [ { "id": "123456789012345679", "event_id": "123456789012345680", "round_no": 2, "url": "https://merchant.example.com/guiji/webhook", "started_at": "2030-01-01T00:00:00Z", "deadline_at": "2030-01-01T00:10:00Z", "finished_at": null, "attempts": 0, "next_attempt": "2030-01-01T00:00:00Z", "status": "pending", "last_error": "", "network": "nile" } ], "total": 1, "page": 1, "page_size": 20, "network": "nile" } } } }, "headers": { "X-Trace-Id": { "description": "本次请求的追踪编号。", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } } }, "400": { "description": "参数或请求格式错误", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "code": { "const": 400 } } } ] }, "example": { "code": 400, "message": "invalid request", "error_code": "INVALID_ARGUMENT", "trace_id": "0123456789abcdef0123456789abcdef" } } }, "headers": { "X-Trace-Id": { "description": "本次请求的追踪编号。", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } } }, "401": { "description": "签名、时间窗口或令牌无效", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "code": { "const": 401 } } } ] }, "example": { "code": 401, "message": "authentication required or expired", "error_code": "TOKEN_INVALID_OR_EXPIRED", "trace_id": "0123456789abcdef0123456789abcdef" } } }, "headers": { "X-Trace-Id": { "description": "本次请求的追踪编号。", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } } }, "403": { "description": "租户停用、删除或过期", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "code": { "const": 403 } } } ] }, "example": { "code": 403, "message": "tenant disabled or expired", "error_code": "TENANT_UNAVAILABLE", "trace_id": "0123456789abcdef0123456789abcdef" } } }, "headers": { "X-Trace-Id": { "description": "本次请求的追踪编号。", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } } }, "413": { "description": "请求体超过服务器显式配置的大小限制", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "code": { "const": 413 } } } ] }, "example": { "code": 413, "message": "request body exceeds configured limit", "error_code": "PAYLOAD_TOO_LARGE", "trace_id": "0123456789abcdef0123456789abcdef" } } }, "headers": { "X-Trace-Id": { "description": "本次请求的追踪编号。", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } } }, "429": { "description": "请求频率超限；读取 Retry-After 秒数", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "code": { "const": 429 } } } ] }, "example": { "code": 429, "message": "too many requests", "error_code": "RATE_LIMITED", "trace_id": "0123456789abcdef0123456789abcdef" } } }, "headers": { "Retry-After": { "description": "建议等待秒数；503 为 1。", "schema": { "type": "string", "pattern": "^[0-9]+$" } }, "X-Trace-Id": { "description": "本次请求的追踪编号。", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } } }, "500": { "description": "内部依赖或业务执行失败", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "code": { "const": 500 } } } ] }, "example": { "code": 500, "message": "internal operation failed", "error_code": "INTERNAL_ERROR", "trace_id": "0123456789abcdef0123456789abcdef" } } }, "headers": { "X-Trace-Id": { "description": "本次请求的追踪编号。", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } } }, "503": { "description": "HTTP 并发槽已满；Retry-After 为 1 秒", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "code": { "const": 503 } } } ] }, "example": { "code": 503, "message": "too many in-flight requests", "error_code": "SERVICE_UNAVAILABLE", "trace_id": "0123456789abcdef0123456789abcdef" } } }, "headers": { "Retry-After": { "description": "建议等待秒数；503 为 1。", "schema": { "type": "string", "pattern": "^[0-9]+$" } }, "X-Trace-Id": { "description": "本次请求的追踪编号。", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } } }, "504": { "description": "操作超过请求截止时间", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "code": { "const": 504 } } } ] }, "example": { "code": 504, "message": "request timed out", "error_code": "REQUEST_TIMEOUT", "trace_id": "0123456789abcdef0123456789abcdef" } } }, "headers": { "X-Trace-Id": { "description": "本次请求的追踪编号。", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } } }, "404": { "description": "对象不存在，或不属于当前租户和网络", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "code": { "const": 404 } } } ] }, "example": { "code": 404, "message": "record not found", "error_code": "RESOURCE_NOT_FOUND", "trace_id": "0123456789abcdef0123456789abcdef" } } }, "headers": { "X-Trace-Id": { "description": "本次请求的追踪编号。", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } } }, "405": { "description": "路径或方法错误。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": 405, "error_code": "METHOD_NOT_ALLOWED", "message": "method not allowed", "trace_id": "0123456789abcdef0123456789abcdef" } } } } } } }, "/open/v1/webhooks/{id}/attempts": { "get": { "operationId": "webhook_attempts", "summary": "查询推送尝试", "description": "分页查询通知的投递尝试，可通过 round_id 限定轮次。返回 HTTP 状态、响应正文、网络错误及截断标记。", "tags": [ "通知投递" ], "security": [ { "AppID": [], "Timestamp": [], "Signature": [], "Bearer": [] } ], "parameters": [ { "$ref": "#/components/parameters/AppID" }, { "$ref": "#/components/parameters/Timestamp" }, { "$ref": "#/components/parameters/Signature" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "description": "规范正 int64 事件 ID，最大 9223372036854775807。", "pattern": "^[1-9][0-9]*$", "examples": [ "123456789012345680" ] } }, { "$ref": "#/components/parameters/Page" }, { "$ref": "#/components/parameters/PageSize" }, { "name": "round_id", "in": "query", "required": false, "description": "规范正 int64 轮次 ID，必须属于路径指定事件；不传查询全部轮次，不能传空字符串。", "schema": { "type": "string", "description": "轮次 ID。", "pattern": "^[1-9][0-9]*$", "examples": [ "123456789012345679" ] } } ], "responses": { "200": { "description": "请求成功。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookAttemptPageResponse" }, "example": { "code": 0, "message": "", "data": { "items": [ { "id": "123456789012345679", "event_id": "123456789012345680", "round_id": "123456789012345678", "round_no": 1, "attempt": 1, "status": "failed", "http_status": 503, "error": "callback HTTP 503; exactly 200 is required", "started_at": "2030-01-01T00:00:00Z", "finished_at": "2030-01-01T00:00:00.012Z", "duration_ms": 12, "response_body": "service unavailable", "response_truncated": false, "created_at": "2030-01-01T00:00:00Z", "network": "nile" } ], "total": 1, "page": 1, "page_size": 20, "network": "nile" } } } }, "headers": { "X-Trace-Id": { "description": "本次请求的追踪编号。", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } } }, "400": { "description": "参数或请求格式错误", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "code": { "const": 400 } } } ] }, "example": { "code": 400, "message": "invalid request", "error_code": "INVALID_ARGUMENT", "trace_id": "0123456789abcdef0123456789abcdef" } } }, "headers": { "X-Trace-Id": { "description": "本次请求的追踪编号。", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } } }, "401": { "description": "签名、时间窗口或令牌无效", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "code": { "const": 401 } } } ] }, "example": { "code": 401, "message": "authentication required or expired", "error_code": "TOKEN_INVALID_OR_EXPIRED", "trace_id": "0123456789abcdef0123456789abcdef" } } }, "headers": { "X-Trace-Id": { "description": "本次请求的追踪编号。", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } } }, "403": { "description": "租户停用、删除或过期", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "code": { "const": 403 } } } ] }, "example": { "code": 403, "message": "tenant disabled or expired", "error_code": "TENANT_UNAVAILABLE", "trace_id": "0123456789abcdef0123456789abcdef" } } }, "headers": { "X-Trace-Id": { "description": "本次请求的追踪编号。", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } } }, "413": { "description": "请求体超过服务器显式配置的大小限制", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "code": { "const": 413 } } } ] }, "example": { "code": 413, "message": "request body exceeds configured limit", "error_code": "PAYLOAD_TOO_LARGE", "trace_id": "0123456789abcdef0123456789abcdef" } } }, "headers": { "X-Trace-Id": { "description": "本次请求的追踪编号。", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } } }, "429": { "description": "请求频率超限；读取 Retry-After 秒数", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "code": { "const": 429 } } } ] }, "example": { "code": 429, "message": "too many requests", "error_code": "RATE_LIMITED", "trace_id": "0123456789abcdef0123456789abcdef" } } }, "headers": { "Retry-After": { "description": "建议等待秒数；503 为 1。", "schema": { "type": "string", "pattern": "^[0-9]+$" } }, "X-Trace-Id": { "description": "本次请求的追踪编号。", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } } }, "500": { "description": "内部依赖或业务执行失败", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "code": { "const": 500 } } } ] }, "example": { "code": 500, "message": "internal operation failed", "error_code": "INTERNAL_ERROR", "trace_id": "0123456789abcdef0123456789abcdef" } } }, "headers": { "X-Trace-Id": { "description": "本次请求的追踪编号。", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } } }, "503": { "description": "HTTP 并发槽已满；Retry-After 为 1 秒", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "code": { "const": 503 } } } ] }, "example": { "code": 503, "message": "too many in-flight requests", "error_code": "SERVICE_UNAVAILABLE", "trace_id": "0123456789abcdef0123456789abcdef" } } }, "headers": { "Retry-After": { "description": "建议等待秒数；503 为 1。", "schema": { "type": "string", "pattern": "^[0-9]+$" } }, "X-Trace-Id": { "description": "本次请求的追踪编号。", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } } }, "504": { "description": "操作超过请求截止时间", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "code": { "const": 504 } } } ] }, "example": { "code": 504, "message": "request timed out", "error_code": "REQUEST_TIMEOUT", "trace_id": "0123456789abcdef0123456789abcdef" } } }, "headers": { "X-Trace-Id": { "description": "本次请求的追踪编号。", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } } }, "404": { "description": "对象不存在，或不属于当前租户和网络", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "code": { "const": 404 } } } ] }, "example": { "code": 404, "message": "record not found", "error_code": "RESOURCE_NOT_FOUND", "trace_id": "0123456789abcdef0123456789abcdef" } } }, "headers": { "X-Trace-Id": { "description": "本次请求的追踪编号。", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } } }, "405": { "description": "路径或方法错误。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": 405, "error_code": "METHOD_NOT_ALLOWED", "message": "method not allowed", "trace_id": "0123456789abcdef0123456789abcdef" } } } } } } }, "/open/v1/webhooks/{id}/redeliver": { "post": { "operationId": "webhook_redeliver", "summary": "重新推送异常通知", "description": "为推送异常的通知开启新一轮，读取当前回调地址，事件 ID 与业务正文不变。每轮最多 20 次、最长 10 分钟。已成功或正在推送的通知不能重推；相同 request_id 和参数返回原结果，改变参数返回 409。", "tags": [ "通知投递" ], "security": [ { "AppID": [], "Timestamp": [], "Signature": [], "Bearer": [] } ], "parameters": [ { "$ref": "#/components/parameters/AppID" }, { "$ref": "#/components/parameters/Timestamp" }, { "$ref": "#/components/parameters/Signature" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "description": "规范正 int64 事件 ID，最大 9223372036854775807。", "pattern": "^[1-9][0-9]*$", "examples": [ "123456789012345680" ] } } ], "responses": { "200": { "description": "请求成功。开启新轮次成功不代表推送成功；配置缺失/关闭时新轮可立即 failed。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookRoundResponse" }, "example": { "code": 0, "message": "", "data": { "id": "123456789012345679", "event_id": "123456789012345680", "round_no": 2, "url": "https://merchant.example.com/guiji/webhook", "started_at": "2030-01-01T00:00:00Z", "deadline_at": "2030-01-01T00:10:00Z", "finished_at": null, "attempts": 0, "next_attempt": "2030-01-01T00:00:00Z", "status": "pending", "last_error": "", "network": "nile" } } } }, "headers": { "X-Trace-Id": { "description": "本次请求的追踪编号。", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } } }, "400": { "description": "参数或请求格式错误", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "code": { "const": 400 } } } ] }, "example": { "code": 400, "message": "request_id requires 16..128 characters", "error_code": "INVALID_ARGUMENT", "trace_id": "0123456789abcdef0123456789abcdef" } } }, "headers": { "X-Trace-Id": { "description": "本次请求的追踪编号。", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } } }, "401": { "description": "签名、时间窗口或令牌无效", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "code": { "const": 401 } } } ] }, "example": { "code": 401, "message": "authentication required or expired", "error_code": "TOKEN_INVALID_OR_EXPIRED", "trace_id": "0123456789abcdef0123456789abcdef" } } }, "headers": { "X-Trace-Id": { "description": "本次请求的追踪编号。", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } } }, "403": { "description": "租户停用、删除或过期", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "code": { "const": 403 } } } ] }, "example": { "code": 403, "message": "tenant disabled or expired", "error_code": "TENANT_UNAVAILABLE", "trace_id": "0123456789abcdef0123456789abcdef" } } }, "headers": { "X-Trace-Id": { "description": "本次请求的追踪编号。", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } } }, "413": { "description": "请求体超过服务器显式配置的大小限制", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "code": { "const": 413 } } } ] }, "example": { "code": 413, "message": "request body exceeds configured limit", "error_code": "PAYLOAD_TOO_LARGE", "trace_id": "0123456789abcdef0123456789abcdef" } } }, "headers": { "X-Trace-Id": { "description": "本次请求的追踪编号。", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } } }, "429": { "description": "请求频率超限；读取 Retry-After 秒数", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "code": { "const": 429 } } } ] }, "example": { "code": 429, "message": "too many requests", "error_code": "RATE_LIMITED", "trace_id": "0123456789abcdef0123456789abcdef" } } }, "headers": { "Retry-After": { "description": "建议等待秒数；503 为 1。", "schema": { "type": "string", "pattern": "^[0-9]+$" } }, "X-Trace-Id": { "description": "本次请求的追踪编号。", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } } }, "500": { "description": "内部依赖或业务执行失败", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "code": { "const": 500 } } } ] }, "example": { "code": 500, "message": "internal operation failed", "error_code": "INTERNAL_ERROR", "trace_id": "0123456789abcdef0123456789abcdef" } } }, "headers": { "X-Trace-Id": { "description": "本次请求的追踪编号。", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } } }, "503": { "description": "HTTP 并发槽已满；Retry-After 为 1 秒", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "code": { "const": 503 } } } ] }, "example": { "code": 503, "message": "too many in-flight requests", "error_code": "SERVICE_UNAVAILABLE", "trace_id": "0123456789abcdef0123456789abcdef" } } }, "headers": { "Retry-After": { "description": "建议等待秒数；503 为 1。", "schema": { "type": "string", "pattern": "^[0-9]+$" } }, "X-Trace-Id": { "description": "本次请求的追踪编号。", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } } }, "504": { "description": "操作超过请求截止时间", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "code": { "const": 504 } } } ] }, "example": { "code": 504, "message": "request timed out", "error_code": "REQUEST_TIMEOUT", "trace_id": "0123456789abcdef0123456789abcdef" } } }, "headers": { "X-Trace-Id": { "description": "本次请求的追踪编号。", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } } }, "404": { "description": "对象不存在，或不属于当前租户和网络", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "code": { "const": 404 } } } ] }, "example": { "code": 404, "message": "record not found", "error_code": "RESOURCE_NOT_FOUND", "trace_id": "0123456789abcdef0123456789abcdef" } } }, "headers": { "X-Trace-Id": { "description": "本次请求的追踪编号。", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } } }, "409": { "description": "通知不是推送异常状态，或request_id与已使用的业务参数冲突。", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Error" }, { "properties": { "code": { "const": 409 } } } ] }, "examples": { "state": { "value": { "code": 409, "message": "only failed notifications can start a new delivery round", "error_code": "BUSINESS_CONFLICT", "trace_id": "0123456789abcdef0123456789abcdef" } }, "idempotency": { "value": { "code": 409, "message": "conflict: idempotency key already used with another request", "error_code": "IDEMPOTENCY_CONFLICT", "trace_id": "0123456789abcdef0123456789abcdef" } } } } }, "headers": { "X-Trace-Id": { "description": "本次请求的追踪编号。", "schema": { "type": "string", "pattern": "^[0-9a-f]{32}$" } } } }, "405": { "description": "路径或方法错误。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": 405, "error_code": "METHOD_NOT_ALLOWED", "message": "method not allowed", "trace_id": "0123456789abcdef0123456789abcdef" } } } } }, "requestBody": { "required": true, "description": "业务参数和 request_id 仅放 JSON；不接受 Query 或 Idempotency-Key。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RedeliverWebhookBody" }, "example": { "request_id": "webhook-redeliver-20300101-0001" } } } } } } }, "components": { "securitySchemes": { "AppID": { "type": "apiKey", "in": "header", "name": "X-App-Id", "description": "平台 appID，规范正 int64 字符串。" }, "Timestamp": { "type": "apiKey", "in": "header", "name": "X-Timestamp", "description": "Unix 秒级时间戳，前后 300 秒。" }, "Signature": { "type": "apiKey", "in": "header", "name": "X-Sign", "description": "使用 HMAC-SHA256 认证方法、路径、appID、时间戳、accessToken、规范查询串及原始请求体摘要。" }, "Bearer": { "type": "http", "scheme": "bearer", "bearerFormat": "base64url(32 random bytes)", "description": "auth/token 获取的当前唯一有效令牌。" } }, "parameters": { "AppID": { "name": "X-App-Id", "in": "header", "required": true, "description": "只允许出现一次。规范正 int64 十进制 appID，无前导零。", "schema": { "type": "string", "description": "应用 ID。", "pattern": "^[1-9][0-9]*$", "examples": [ "123456789012345001" ] } }, "Timestamp": { "name": "X-Timestamp", "in": "header", "required": true, "description": "只允许出现一次。当前 Unix 秒级时间戳，服务器时间前后 300 秒内，规范正 int64 字符串。", "schema": { "type": "string", "description": "秒级时间戳。", "pattern": "^[1-9][0-9]*$", "examples": [ "1893456000" ] } }, "Signature": { "name": "X-Sign", "in": "header", "required": true, "description": "HMAC-SHA256，使用原始 appSecret UTF-8 字节为密钥，签名文本为 method、path、appID、timestamp、accessToken、canonicalQuery、SHA256(rawBody) 七行，每行以 LF 结束。输出 64 位小写十六进制。获取令牌时 accessToken/query/body 为空，仍签名方法及路径。详见请求签名指南。", "schema": { "type": "string", "description": "请求签名。", "pattern": "^[0-9a-f]{64}$", "examples": [ "0000000000000000000000000000000000000000000000000000000000000000" ] } }, "ID": { "name": "id", "in": "path", "required": true, "description": "当前租户、网络的对象 ID。", "schema": { "$ref": "#/components/schemas/InputWalletID" } }, "Page": { "name": "page", "in": "query", "required": false, "description": "页码，≥1；不传或空字符串为 1。以 Query 文本发送。", "schema": { "oneOf": [ { "type": "integer", "minimum": 1, "default": 1 }, { "type": "string", "const": "" } ] } }, "PageSize": { "name": "page_size", "in": "query", "required": false, "description": "每页 1–100 条；不传或空字符串为 20。", "schema": { "oneOf": [ { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 }, { "type": "string", "const": "" } ] } }, "Filter_address": { "name": "address", "in": "query", "required": false, "description": "收款地址模糊匹配，不区分大小写；最长 100 个 UTF-8 字节。空字符串忽略，% 和 _ 保留 LIKE 通配语义。", "schema": { "type": "string", "description": "收款地址模糊匹配，不区分大小写；最长 100 个 UTF-8 字节。空字符串忽略，% 和 _ 保留 LIKE 通配语义。", "examples": [ "TQyeXvAnmKsBqo6V48RmhAnZpWLmR2D7DM" ] } }, "Filter_usdt_min": { "name": "usdt_min", "in": "query", "required": false, "description": "USDT 余额下限，包含边界；六位精度最小单位，0 至 2^256−1，不传或空字符串不限制。", "schema": { "$ref": "#/components/schemas/AmountFilter", "description": "USDT 余额下限，包含边界；六位精度最小单位，0 至 2^256−1，不传或空字符串不限制。" } }, "Filter_usdt_max": { "name": "usdt_max", "in": "query", "required": false, "description": "USDT 余额上限，包含边界；六位精度最小单位，0 至 2^256−1，不传或空字符串不限制。", "schema": { "$ref": "#/components/schemas/AmountFilter", "description": "USDT 余额上限，包含边界；六位精度最小单位，0 至 2^256−1，不传或空字符串不限制。" } }, "Filter_trx_min": { "name": "trx_min", "in": "query", "required": false, "description": "TRX 余额下限，SUN，包含边界；0 至 2^256−1，不传或空字符串不限制。", "schema": { "$ref": "#/components/schemas/AmountFilter", "description": "TRX 余额下限，SUN，包含边界；0 至 2^256−1，不传或空字符串不限制。" } }, "Filter_trx_max": { "name": "trx_max", "in": "query", "required": false, "description": "TRX 余额上限，SUN，包含边界；0 至 2^256−1，不传或空字符串不限制。", "schema": { "$ref": "#/components/schemas/AmountFilter", "description": "TRX 余额上限，SUN，包含边界；0 至 2^256−1，不传或空字符串不限制。" } }, "Filter_hide_zero": { "name": "hide_zero", "in": "query", "required": false, "description": "true 只保留 USDT 余额大于 0 的钱包；不传为 false。", "schema": { "type": "string", "enum": [ "true", "false" ], "default": "false" } }, "Filter_hide_zero_trx": { "name": "hide_zero_trx", "in": "query", "required": false, "description": "true 只保留 TRX 余额大于 0 的钱包；不传为 false。", "schema": { "type": "string", "enum": [ "true", "false" ], "default": "false" } }, "Filter_last_collected_from": { "name": "last_collected_from", "in": "query", "required": false, "description": "最近成功归集时间下限，包含边界；带时区 RFC3339，可含小数秒；不传或空字符串不限制。", "schema": { "type": "string", "description": "最近成功归集时间下限，包含边界；带时区 RFC3339，可含小数秒；不传或空字符串不限制。", "examples": [ "2030-01-01T00:00:00Z" ] } }, "Filter_last_collected_to": { "name": "last_collected_to", "in": "query", "required": false, "description": "最近成功归集时间上限，包含边界；不能早于 from；不传或空字符串不限制。", "schema": { "type": "string", "description": "最近成功归集时间上限，包含边界；不能早于 from；不传或空字符串不限制。", "examples": [ "2030-01-02T00:00:00Z" ] } }, "Filter_sort": { "name": "sort", "in": "query", "required": false, "description": "列表排序字段：created_at、balance_usdt、balance_trx、last_collected_at、collected_usdt；默认 created_at。selection 即使传入也始终按 ID 升序返回。", "schema": { "type": "string", "description": "列表排序字段：created_at、balance_usdt、balance_trx、last_collected_at、collected_usdt；默认 created_at。selection 即使传入也始终按 ID 升序返回。", "enum": [ "created_at", "balance_usdt", "balance_trx", "last_collected_at", "collected_usdt", "" ], "default": "created_at", "examples": [ "created_at" ] } }, "Filter_order": { "name": "order", "in": "query", "required": false, "description": "排序方向仅 asc / desc，默认 desc；selection 返回顺序不受此字段影响。", "schema": { "type": "string", "description": "排序方向仅 asc / desc，默认 desc；selection 返回顺序不受此字段影响。", "enum": [ "asc", "desc", "" ], "default": "desc", "examples": [ "desc" ] } } }, "schemas": { "Error": { "type": "object", "properties": { "code": { "type": "integer", "description": "与 HTTP 状态码相同的错误码。", "examples": [ 400 ] }, "message": { "type": "string", "description": "本次失败的具体说明，供开发者诊断；可能补充字段名，不能用作程序枚举。", "examples": [ "invalid request" ] }, "error_code": { "type": "string", "enum": [ "INVALID_ARGUMENT", "COLLECTION_ADDRESS_MANAGED", "INVALID_AUTH_HEADER", "INVALID_SIGNATURE", "TIMESTAMP_OUT_OF_RANGE", "TOKEN_INVALID_OR_EXPIRED", "TENANT_UNAVAILABLE", "RESOURCE_NOT_FOUND", "ROUTE_NOT_FOUND", "METHOD_NOT_ALLOWED", "IDEMPOTENCY_CONFLICT", "BUSINESS_CONFLICT", "PAYLOAD_TOO_LARGE", "RATE_LIMITED", "SERVICE_BUSY", "SERVICE_UNAVAILABLE", "REQUEST_TIMEOUT", "INTERNAL_ERROR" ], "description": "稳定的错误标识，用于程序分支。不要解析 message 文本。" }, "trace_id": { "type": "string", "pattern": "^[0-9a-f]{32}$", "description": "平台生成的本次 HTTP 请求追踪编号；与 X-Trace-Id 响应头一致。用于排错，与写入幂等 request_id 不同。" } }, "required": [ "code", "error_code", "message", "trace_id" ], "additionalProperties": false }, "Wallet": { "type": "object", "properties": { "id": { "type": "string", "description": "钱包 ID。", "pattern": "^[1-9][0-9]*$", "examples": [ "123456789012345678" ] }, "address": { "type": "string", "description": "平台生成的 TRON Base58Check 收款地址。", "examples": [ "TQyeXvAnmKsBqo6V48RmhAnZpWLmR2D7DM" ] }, "custom_id": { "type": "string", "description": "租户自定义 ID；同一租户内唯一，1–32 个字符，不允许首尾空白。", "minLength": 1, "maxLength": 32, "examples": [ "customer-001" ] }, "chain": { "type": "string", "description": "所属链。", "const": "TRON", "examples": [ "TRON" ] }, "network": { "type": "string", "enum": [ "main", "nile" ], "description": "资产所属网络：main（主网）或 nile（测试网络）。", "examples": [ "nile" ] }, "collection_status": { "type": "string", "description": "idle：暂无任务；collecting：存在任一未结束的归集任务。", "enum": [ "idle", "collecting" ], "examples": [ "idle" ] }, "balance_usdt": { "type": [ "string", "null" ], "description": "已同步的 USDT 余额；最小单位的整数字符串，六位精度，禁止用浮点数处理。首次同步前null，显示待同步，不能当作0。", "pattern": "^[0-9]+$", "examples": [ "100000000" ] }, "balance_trx": { "type": [ "string", "null" ], "description": "已同步的 TRX 余额，单位 SUN；最小单位的整数字符串，六位精度，禁止用浮点数处理。首次同步前null，显示待同步，不能当作0。", "pattern": "^[0-9]+$", "examples": [ "30000000" ] }, "balance_block": { "type": "string", "description": "余额同步时的固化区块参考高度。0 表示尚未完成首次同步；不是实际链上余额为零的证明。", "pattern": "^[0-9]+$", "examples": [ "12345678" ] }, "destination": { "type": "string", "description": "当前租户统一配置的 USDT 归集地址；未绑定时为空字符串，可为外部地址。", "examples": [ "TAt8Du9Xw2CmrTHRawGETwiEKpNuKDSjE8" ] }, "collected_usdt": { "type": "string", "description": "累计成功归集 USDT 金额；最小单位的整数字符串，六位精度，禁止用浮点数处理。", "pattern": "^[0-9]+$", "examples": [ "0" ] }, "last_collected_at": { "anyOf": [ { "type": "string", "description": "最近一次成功归集时间；从未归集为 null。", "format": "date-time", "examples": [ "2030-01-01T00:00:00Z" ] }, { "type": "null" } ] }, "created_at": { "type": "string", "description": "钱包创建时间。", "format": "date-time", "examples": [ "2030-01-01T00:00:00Z" ] } }, "required": [ "id", "address", "custom_id", "chain", "network", "collection_status", "balance_usdt", "balance_trx", "balance_block", "destination", "collected_usdt", "last_collected_at", "created_at" ], "additionalProperties": false }, "WebhookSummary": { "type": "object", "properties": { "id": { "type": "string", "description": "固定通知事件 ID。", "pattern": "^[1-9][0-9]*$", "examples": [ "123456789012345678" ] }, "event_type": { "type": "string", "description": "通知事件类型。", "enum": [ "deposit.confirmed", "sweep.succeeded", "sweep.failed", "sweep.cancelled", "deposit.reverted" ], "examples": [ "deposit.confirmed" ] }, "status": { "type": "string", "description": "pending 待推送；delivering 推送中；delivered 推送成功；failed 推送异常。", "enum": [ "pending", "delivering", "delivered", "failed" ], "examples": [ "pending" ] }, "attempts": { "type": "integer", "description": "当前轮已开始的尝试次数，包含结果未知的尝试。", "examples": [ 0 ], "minimum": 0, "maximum": 20 }, "current_round": { "type": "integer", "description": "当前推送轮次；人工重新推送开启下一轮。", "examples": [ 1 ], "minimum": 1 }, "next_attempt": { "anyOf": [ { "type": "string", "description": "下一次计划推送时间；没有计划时为 null。", "format": "date-time", "examples": [ "2030-01-01T00:00:00Z" ] }, { "type": "null" } ] }, "deadline_at": { "type": "string", "description": "本轮 10 分钟截止时间。", "format": "date-time", "examples": [ "2030-01-01T00:10:00Z" ] }, "last_error": { "type": "string", "description": "最近推送错误；没有错误时为空字符串。", "examples": [ "" ] }, "created_at": { "type": "string", "description": "事件创建时间。", "format": "date-time", "examples": [ "2030-01-01T00:00:00Z" ] }, "delivered_at": { "anyOf": [ { "type": "string", "description": "推送成功时间；尚未成功为 null。", "format": "date-time", "examples": [ "2030-01-01T00:00:00Z" ] }, { "type": "null" } ] }, "network": { "type": "string", "enum": [ "main", "nile" ], "description": "资产所属网络：main（主网）或 nile（测试网络）。", "examples": [ "nile" ] } }, "required": [ "id", "event_type", "status", "attempts", "current_round", "next_attempt", "deadline_at", "last_error", "created_at", "delivered_at", "network" ], "additionalProperties": false }, "Sweep": { "type": "object", "properties": { "id": { "type": "string", "description": "归集任务 ID。", "pattern": "^[1-9][0-9]*$", "examples": [ "123456789012345678" ] }, "wallet_id": { "type": "string", "description": "收款钱包 ID。", "pattern": "^[1-9][0-9]*$", "examples": [ "123456789012345678" ] }, "address": { "type": "string", "description": "归集来源钱包地址。", "examples": [ "TQyeXvAnmKsBqo6V48RmhAnZpWLmR2D7DM" ] }, "kind": { "type": "string", "description": "任务类型。", "const": "sweep", "examples": [ "sweep" ] }, "sweep_mode": { "type": "string", "description": "all 全额归集；fixed 按指定金额归集。", "enum": [ "all", "fixed" ], "examples": [ "all" ] }, "requested_amount": { "anyOf": [ { "type": "string", "description": "fixed 模式的请求金额；all 模式为 null；最小单位的整数字符串，六位精度，禁止用浮点数处理。", "pattern": "^[0-9]+$", "examples": [ "100000000" ] }, { "type": "null" } ] }, "amount": { "type": "string", "description": "任务准备后确定的实际转账金额；准备前为 0；最小单位的整数字符串，六位精度，禁止用浮点数处理。", "pattern": "^[0-9]+$", "examples": [ "100000000" ] }, "destination": { "type": "string", "description": "任务保存的归集目标地址；修改账户配置不会改写已签名交易的目标。", "examples": [ "TAt8Du9Xw2CmrTHRawGETwiEKpNuKDSjE8" ] }, "status": { "type": "string", "description": "归集任务状态。", "enum": [ "pending", "ready", "signed", "broadcast", "unknown", "succeeded", "failed", "cancelled" ], "examples": [ "pending" ] }, "reason": { "type": "string", "description": "失败或取消原因；没有原因时为空字符串。", "examples": [ "" ] }, "txid": { "type": "string", "description": "已保存交易的哈希，通常为 64 位十六进制；签名前为空字符串。", "examples": [ "" ] }, "actual_fee": { "type": "string", "description": "实际链上手续费，TRX 的最小单位 SUN；尚未确认时可能为 0；最小单位的整数字符串，六位精度，禁止用浮点数处理。", "pattern": "^[0-9]+$", "examples": [ "0" ] }, "created_at": { "type": "string", "description": "任务创建时间。", "format": "date-time", "examples": [ "2030-01-01T00:00:00Z" ] }, "updated_at": { "type": "string", "description": "任务最后更新时间。", "format": "date-time", "examples": [ "2030-01-01T00:00:00Z" ] }, "webhook": { "anyOf": [ { "$ref": "#/components/schemas/WebhookSummary" }, { "type": "null" } ], "description": "与本条业务结果关联的通知摘要；未创建通知时为null。通知失败不改变资金结果。" }, "network": { "type": "string", "enum": [ "main", "nile" ], "description": "资产所属网络：main（主网）或 nile（测试网络）。", "examples": [ "nile" ] }, "preparation_stage": { "type": "string", "enum": [ "queued", "waiting_bandwidth", "renting", "waiting_energy", "ready" ], "description": "准备阶段：queued排队、waiting_bandwidth等待免费带宽、renting租赁中、waiting_energy等待能量到账、ready准备完成；最终成功仍以status为准。" }, "energy_rental": { "description": "归集任务唯一的CatFee租赁记录。没有订单记录时energy_rental整体为null。", "anyOf": [ { "$ref": "#/components/schemas/EnergyRental" }, { "type": "null" } ] }, "fee_source": { "type": [ "string", "null" ], "enum": [ "resources", "wallet_trx", "catfee", null ], "description": "费用来源；历史或尚未准备的任务为null，不推断历史支付方式。" }, "prepared_energy": { "anyOf": [ { "type": "string", "pattern": "^(0|[1-9][0-9]*)$", "description": "准备能量额度", "examples": [ "0" ] }, { "type": "null" } ], "description": "准备能量额度；历史或尚未产生该数据时为null。" }, "estimated_wallet_trx_fee": { "anyOf": [ { "type": "string", "pattern": "^(0|[1-9][0-9]*)$", "description": "准备时预计钱包TRX费用SUN", "examples": [ "0" ] }, { "type": "null" } ], "description": "准备时预计钱包TRX费用SUN；历史或尚未产生该数据时为null。" }, "max_wallet_trx_fee": { "anyOf": [ { "type": "string", "pattern": "^(0|[1-9][0-9]*)$", "description": "准备时钱包能量缺口费用上限SUN", "examples": [ "0" ] }, { "type": "null" } ], "description": "准备时钱包能量缺口费用上限SUN；历史或尚未产生该数据时为null。" }, "actual_bandwidth_fee": { "anyOf": [ { "type": "string", "pattern": "^(0|[1-9][0-9]*)$", "description": "回执实际带宽费用SUN", "examples": [ "0" ] }, { "type": "null" } ], "description": "回执实际带宽费用SUN；历史或尚未产生该数据时为null。" }, "fee_warning": { "type": [ "string", "null" ], "description": "链上实际发生非零带宽费时记录异常；不改变真实转账成功状态。" } }, "required": [ "id", "wallet_id", "address", "kind", "sweep_mode", "requested_amount", "amount", "destination", "status", "reason", "txid", "actual_fee", "created_at", "updated_at", "webhook", "network", "preparation_stage", "energy_rental", "fee_source", "prepared_energy", "estimated_wallet_trx_fee", "max_wallet_trx_fee", "actual_bandwidth_fee", "fee_warning" ], "additionalProperties": false, "allOf": [ { "oneOf": [ { "properties": { "sweep_mode": { "const": "all" }, "requested_amount": { "type": "null" } }, "required": [ "sweep_mode", "requested_amount" ] }, { "properties": { "sweep_mode": { "const": "fixed" }, "requested_amount": { "type": "string", "pattern": "^[1-9][0-9]*$", "maxLength": 19, "description": "正int64十进制字符串，数值不得超过9223372036854775807。" } }, "required": [ "sweep_mode", "requested_amount" ] } ] } ] }, "Deposit": { "type": "object", "description": "到账详情 data、到账列表 items[] 和到账通知解密正文共用的 24 字段结构，全部字段必返；confirmations 与 block_hash 允许为 null。查询返回当前版本，历史通知保留对应事件版本；同一 id、revision 的内容一致。不包含投递状态。同步恢复或核验可能补录较早区块的到账；不要按 block_time 距离当前时间的长短认定无效。已有到账恢复保持原 id、event_id、created_at 和 revision，重复事件不得重复入账。", "properties": { "id": { "type": "string", "description": "到账记录 ID，同一链上交易日志在撤销、重新确认后保持不变。", "pattern": "^[1-9][0-9]*$" }, "event_id": { "type": "string", "description": "本次状态事件 ID；重试不变，撤销或重新确认产生新事件 ID。按 event_id 去重，按 id 与 revision 更新到账状态。", "pattern": "^[1-9][0-9]*$" }, "event_type": { "type": "string", "description": "到账状态事件类型：deposit.confirmed 为达到确认门槛，deposit.reverted 为因链重组撤销。", "enum": [ "deposit.confirmed", "deposit.reverted" ] }, "status": { "type": "string", "description": "confirmed 表示达到租户确认门槛；低确认模式仍可能回退。reverted 表示先前认可的到账已因链重组撤销。", "enum": [ "confirmed", "reverted" ] }, "wallet_id": { "type": "string", "description": "收款钱包 ID。", "pattern": "^[1-9][0-9]*$", "examples": [ "123456789012345678" ] }, "custom_id": { "type": "string", "description": "钱包的租户自定义ID，同一租户内唯一，取到账入库时快照。", "minLength": 1, "maxLength": 32 }, "chain": { "type": "string", "description": "所属区块链。", "const": "TRON" }, "network": { "type": "string", "enum": [ "main", "nile" ], "description": "资产所属网络：main（主网）或 nile（测试网络）。", "examples": [ "nile" ] }, "asset": { "type": "string", "description": "资产名称；测试网对应测试代币。资产身份以network+contract为准。", "const": "USDT" }, "token_standard": { "type": "string", "description": "代币协议。", "const": "TRC20" }, "decimals": { "type": "integer", "const": 6, "description": "金额精度，展示金额=amount÷10^decimals。使用整数或十进制定点计算。" }, "address": { "type": "string", "description": "到账收款地址。", "examples": [ "TQyeXvAnmKsBqo6V48RmhAnZpWLmR2D7DM" ] }, "source": { "type": "string", "description": "链上 Transfer 事件的来源地址。", "examples": [ "TWkz4y25cWK517vSdMP1N4EWHySqwQ6dMb" ] }, "contract": { "type": "string", "description": "此笔Transfer的实际代币合约。结合network识别资产；Nile为测试代币，Main为Tether发行的USDT。", "examples": [ "TXYZopYRdj2D9XRtbG411XZZ3kM5VkAeBf" ] }, "amount": { "type": "string", "description": "该条到账记录的 USDT 金额，是否有效由 status 决定；最小单位整数字符串，六位精度，禁止用浮点数处理。", "pattern": "^[1-9][0-9]*$", "examples": [ "100000000" ] }, "txid": { "type": "string", "description": "该条到账对应的交易哈希。", "examples": [ "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" ], "pattern": "^[a-fA-F0-9]{64}$" }, "log_index": { "type": "integer", "description": "交易收据内的日志索引；与网络、交易哈希一起标识链上事件。", "examples": [ 0 ], "minimum": 0 }, "block_number": { "type": "string", "description": "本次到账状态对应的区块高度；低确认模式下不代表已经固化。", "pattern": "^[0-9]+$", "examples": [ "12345678" ] }, "block_time": { "type": "string", "description": "链上区块时间；UTC RFC3339，固定6位小数秒，以Z结尾。不是通知发送时间。", "format": "date-time" }, "created_at": { "type": "string", "description": "平台确认并保存到账的时间；UTC RFC3339，固定6位小数秒，以Z结尾。确认或同步存在延迟时，可能晚于 block_time。", "format": "date-time" }, "revision": { "type": "integer", "minimum": 1, "description": "同一到账记录的状态版本，从1递增。接收方只应用大于本地版本的状态；迟到的旧版本仍应答 SUCCESS。" }, "confirmation_type": { "type": "string", "enum": [ "solidified", "block_1", "block_3", "block_6", "block_12" ], "description": "首次发现该到账时的平台配置快照，仅平台管理员可设置；租户修改后不影响已发现的到账。" }, "confirmations": { "type": [ "integer", "null" ], "minimum": 1, "description": "按区块深度确认时的确认数，交易所在区块计 1；按固化结果确认时为 null。" }, "block_hash": { "type": [ "string", "null" ], "pattern": "^[a-fA-F0-9]{64}$", "description": "当前状态对应的区块哈希；历史固化记录未保存此字段时为null。用于区分相同高度的不同区块。" } }, "required": [ "id", "event_id", "event_type", "status", "wallet_id", "custom_id", "chain", "network", "asset", "token_standard", "decimals", "address", "source", "contract", "amount", "txid", "log_index", "block_number", "block_time", "created_at", "revision", "confirmation_type", "confirmations", "block_hash" ], "additionalProperties": false, "examples": [ { "id": "9002000001", "event_id": "9002000001", "event_type": "deposit.confirmed", "status": "confirmed", "wallet_id": "9003000001", "custom_id": "customer-1001", "chain": "TRON", "network": "nile", "asset": "USDT", "token_standard": "TRC20", "decimals": 6, "address": "TMVQGm1qAQYVdetCeGRRkTWYYrLXuHK2HC", "source": "T9yD14Nj9j7xAB4dbGeiX9h8unkKHxuWwb", "contract": "TXYZopYRdj2D9XRtbG411XZZ3kM5VkAeBf", "amount": "100000000", "txid": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "log_index": 0, "block_number": "68192698", "block_time": "2030-01-01T00:00:00.000000Z", "created_at": "2030-01-01T00:00:01.000000Z", "revision": 1, "confirmation_type": "solidified", "confirmations": null, "block_hash": null } ] }, "EngineStatus": { "type": "object", "properties": { "component": { "type": "string", "description": "服务状态项名称。", "examples": [ "chain-scanner" ] }, "status": { "type": "string", "description": "服务状态文本，不是固定枚举。", "examples": [ "running" ] }, "detail": { "type": "string", "description": "服务状态说明。", "examples": [ "" ] }, "updated_at": { "type": "string", "description": "状态最近更新时间。", "format": "date-time", "examples": [ "2030-01-01T00:00:00Z" ] } }, "required": [ "component", "status", "detail", "updated_at" ], "additionalProperties": false }, "Dashboard": { "type": "object", "properties": { "wallet_count": { "type": "integer", "description": "当前租户、当前网络的钱包数。", "examples": [ 1 ], "minimum": 0 }, "unsynced_wallet_count": { "type": "integer", "description": "balance_block 为 0、尚未完成首次同步的钱包数。", "examples": [ 0 ], "minimum": 0 }, "balance_usdt": { "type": "string", "description": "当前租户、网络的钱包 USDT 余额合计；最小单位的整数字符串，六位精度，禁止用浮点数处理。", "pattern": "^[0-9]+$", "examples": [ "100000000" ] }, "balance_trx": { "type": "string", "description": "当前租户、网络的钱包 TRX 余额合计，SUN；最小单位的整数字符串，六位精度，禁止用浮点数处理。", "pattern": "^[0-9]+$", "examples": [ "30000000" ] }, "collected_usdt": { "type": "string", "description": "累计成功归集 USDT 金额；最小单位的整数字符串，六位精度，禁止用浮点数处理。", "pattern": "^[0-9]+$", "examples": [ "0" ] }, "deposit_usdt": { "type": "string", "description": "已确认到账 USDT 金额累计；最小单位的整数字符串，六位精度，禁止用浮点数处理。", "pattern": "^[0-9]+$", "examples": [ "100000000" ] }, "pending_tasks": { "type": "integer", "description": "当前租户、网络的未结束任务数，含归集。", "examples": [ 0 ], "minimum": 0 }, "engine": { "type": "array", "items": { "$ref": "#/components/schemas/EngineStatus" }, "description": "服务运行状态，仅用于辅助排查同步异常；不代表某笔任务成功，无状态信息时为 []。" }, "network": { "type": "string", "enum": [ "main", "nile" ], "description": "资产所属网络：main（主网）或 nile（测试网络）。", "examples": [ "nile" ] } }, "required": [ "wallet_count", "unsynced_wallet_count", "balance_usdt", "balance_trx", "collected_usdt", "deposit_usdt", "pending_tasks", "engine", "network" ], "additionalProperties": false }, "WalletPage": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Wallet" }, "description": "本页钱包，无结果为 []。" }, "total": { "type": "integer", "description": "满足筛选条件的总记录数。", "examples": [ 1 ], "minimum": 0 }, "page": { "type": "integer", "description": "当前页码。", "examples": [ 1 ], "minimum": 1 }, "page_size": { "type": "integer", "description": "每页条数。", "examples": [ 20 ], "minimum": 1, "maximum": 100 }, "unavailable_wallet_ids": { "type": "array", "items": { "type": "string", "description": "Snowflake ID；使用字符串，避免 JavaScript 数字精度丢失。", "pattern": "^[1-9][0-9]*$", "examples": [ "123456789012345678" ] }, "description": "仅当前页及selected_wallet_ids指定钱包中的不可选ID，与本页钱包状态一致，最多 1100 个。" }, "network": { "type": "string", "enum": [ "main", "nile" ], "description": "资产所属网络：main（主网）或 nile（测试网络）。", "examples": [ "nile" ] } }, "required": [ "items", "total", "page", "page_size", "unavailable_wallet_ids", "network" ], "additionalProperties": false }, "SweepPage": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Sweep" }, "description": "本页归集记录，无结果为 []。" }, "total": { "type": "integer", "description": "满足筛选条件的总记录数。", "examples": [ 1 ], "minimum": 0 }, "page": { "type": "integer", "description": "当前页码。", "examples": [ 1 ], "minimum": 1 }, "page_size": { "type": "integer", "description": "每页条数。", "examples": [ 20 ], "minimum": 1, "maximum": 100 }, "network": { "type": "string", "enum": [ "main", "nile" ], "description": "资产所属网络：main（主网）或 nile（测试网络）。", "examples": [ "nile" ] } }, "required": [ "items", "total", "page", "page_size", "network" ], "additionalProperties": false }, "DepositPage": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Deposit" }, "description": "本页到账记录，无结果为 []。" }, "total": { "type": "integer", "description": "满足筛选条件的总记录数。", "examples": [ 1 ], "minimum": 0 }, "page": { "type": "integer", "description": "当前页码。", "examples": [ 1 ], "minimum": 1 }, "page_size": { "type": "integer", "description": "每页条数。", "examples": [ 20 ], "minimum": 1, "maximum": 100 }, "network": { "type": "string", "enum": [ "main", "nile" ], "description": "资产所属网络：main（主网）或 nile（测试网络）。", "examples": [ "nile" ] } }, "required": [ "items", "total", "page", "page_size", "network" ], "additionalProperties": false }, "Selection": { "type": "object", "properties": { "wallet_ids": { "type": "array", "items": { "type": "string", "description": "Snowflake ID；使用字符串，避免 JavaScript 数字精度丢失。", "pattern": "^[1-9][0-9]*$", "examples": [ "123456789012345678" ] }, "description": "符合条件且可选择的钱包 ID，升序，最多 1000 个。", "maxItems": 1000, "uniqueItems": true }, "total": { "type": "integer", "description": "wallet_ids 的实际长度。", "examples": [ 1 ], "minimum": 0, "maximum": 1000 }, "network": { "type": "string", "enum": [ "main", "nile" ], "description": "资产所属网络：main（主网）或 nile（测试网络）。", "examples": [ "nile" ] } }, "required": [ "wallet_ids", "total", "network" ], "additionalProperties": false }, "SweepCreateAccepted": { "type": "object", "properties": { "wallet_id": { "type": "string", "description": "来源钱包 ID。", "pattern": "^[1-9][0-9]*$", "examples": [ "123456789012345678" ] }, "id": { "type": "string", "description": "已创建的任务 ID。", "pattern": "^[1-9][0-9]*$", "examples": [ "123456789012345678" ] }, "status": { "type": "string", "description": "任务已排队；不代表链上成功。", "const": "pending", "examples": [ "pending" ] }, "network": { "type": "string", "enum": [ "main", "nile" ], "description": "资产所属网络：main（主网）或 nile（测试网络）。", "examples": [ "nile" ] } }, "required": [ "wallet_id", "id", "status", "network" ], "additionalProperties": false }, "SweepCreateRejected": { "type": "object", "properties": { "wallet_id": { "type": "string", "description": "该项输入钱包 ID。", "pattern": "^[1-9][0-9]*$", "examples": [ "123456789012345678" ] }, "status": { "type": "string", "description": "该钱包未创建任务。", "const": "failed", "examples": [ "failed" ] }, "reason": { "type": "string", "description": "逐钱包拒绝原因。", "enum": [ "wallet not found", "collection destination wallet cannot collect to itself", "tenant collection address not configured", "wallet already has an unfinished task" ], "examples": [ "wallet already has an unfinished task" ] }, "network": { "type": "string", "enum": [ "main", "nile" ], "description": "资产所属网络：main（主网）或 nile（测试网络）。", "examples": [ "nile" ] } }, "required": [ "wallet_id", "status", "reason", "network" ], "additionalProperties": false }, "SweepCreateResult": { "type": "object", "properties": { "items": { "type": "array", "items": { "oneOf": [ { "$ref": "#/components/schemas/SweepCreateAccepted" }, { "$ref": "#/components/schemas/SweepCreateRejected" } ] }, "description": "逐钱包结果，顺序与 wallet_ids 一致。全项拒绝时 HTTP 仍为 200。" }, "network": { "type": "string", "enum": [ "main", "nile" ], "description": "资产所属网络：main（主网）或 nile（测试网络）。", "examples": [ "nile" ] } }, "required": [ "items", "network" ], "additionalProperties": false }, "Token": { "type": "object", "properties": { "access_token": { "type": "string", "description": "当前租户唯一有效的第三方访问令牌，32 个随机字节的规范无填充 Base64URL 编码。", "minLength": 43, "maxLength": 43, "pattern": "^[A-Za-z0-9_-]{43}$", "examples": [ "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA" ] }, "token_type": { "type": "string", "description": "令牌类型。", "const": "Bearer", "examples": [ "Bearer" ] }, "expires_in": { "type": "integer", "description": "有效秒数，最多 7200 秒，且不超过租户剩余有效期。", "examples": [ 7200 ], "minimum": 1, "maximum": 7200 }, "expires_at": { "type": "string", "description": "令牌过期时间。", "format": "date-time", "examples": [ "2030-01-01T02:00:00Z" ] } }, "required": [ "access_token", "token_type", "expires_in", "expires_at" ], "additionalProperties": false }, "Health": { "type": "object", "properties": { "status": { "type": "string", "description": "依赖正常。", "const": "ok", "examples": [ "ok" ] }, "network": { "type": "string", "enum": [ "main", "nile" ], "description": "资产所属网络：main（主网）或 nile（测试网络）。", "examples": [ "nile" ] } }, "required": [ "status", "network" ], "additionalProperties": false }, "WalletResponse": { "type": "object", "properties": { "code": { "type": "integer", "const": 0, "description": "业务成功。" }, "message": { "type": "string", "description": "成功时为空字符串。", "const": "", "examples": [ "" ] }, "data": { "$ref": "#/components/schemas/Wallet" } }, "required": [ "code", "message", "data" ], "additionalProperties": false }, "WalletPageResponse": { "type": "object", "properties": { "code": { "type": "integer", "const": 0, "description": "业务成功。" }, "message": { "type": "string", "description": "成功时为空字符串。", "const": "", "examples": [ "" ] }, "data": { "$ref": "#/components/schemas/WalletPage" } }, "required": [ "code", "message", "data" ], "additionalProperties": false }, "SelectionResponse": { "type": "object", "properties": { "code": { "type": "integer", "const": 0, "description": "业务成功。" }, "message": { "type": "string", "description": "成功时为空字符串。", "const": "", "examples": [ "" ] }, "data": { "$ref": "#/components/schemas/Selection" } }, "required": [ "code", "message", "data" ], "additionalProperties": false }, "SweepResponse": { "type": "object", "properties": { "code": { "type": "integer", "const": 0, "description": "业务成功。" }, "message": { "type": "string", "description": "成功时为空字符串。", "const": "", "examples": [ "" ] }, "data": { "$ref": "#/components/schemas/Sweep" } }, "required": [ "code", "message", "data" ], "additionalProperties": false }, "SweepPageResponse": { "type": "object", "properties": { "code": { "type": "integer", "const": 0, "description": "业务成功。" }, "message": { "type": "string", "description": "成功时为空字符串。", "const": "", "examples": [ "" ] }, "data": { "$ref": "#/components/schemas/SweepPage" } }, "required": [ "code", "message", "data" ], "additionalProperties": false }, "SweepCreateResultResponse": { "type": "object", "properties": { "code": { "type": "integer", "const": 0, "description": "业务成功。" }, "message": { "type": "string", "description": "成功时为空字符串。", "const": "", "examples": [ "" ] }, "data": { "$ref": "#/components/schemas/SweepCreateResult" } }, "required": [ "code", "message", "data" ], "additionalProperties": false }, "DepositResponse": { "type": "object", "properties": { "code": { "type": "integer", "const": 0, "description": "业务成功。" }, "message": { "type": "string", "description": "成功时为空字符串。", "const": "", "examples": [ "" ] }, "data": { "$ref": "#/components/schemas/Deposit" } }, "required": [ "code", "message", "data" ], "additionalProperties": false }, "DepositPageResponse": { "type": "object", "properties": { "code": { "type": "integer", "const": 0, "description": "业务成功。" }, "message": { "type": "string", "description": "成功时为空字符串。", "const": "", "examples": [ "" ] }, "data": { "$ref": "#/components/schemas/DepositPage" } }, "required": [ "code", "message", "data" ], "additionalProperties": false }, "TokenResponse": { "type": "object", "properties": { "code": { "type": "integer", "const": 0, "description": "业务成功。" }, "message": { "type": "string", "description": "成功时为空字符串。", "const": "", "examples": [ "" ] }, "data": { "$ref": "#/components/schemas/Token" } }, "required": [ "code", "message", "data" ], "additionalProperties": false }, "HealthResponse": { "type": "object", "properties": { "code": { "type": "integer", "const": 0, "description": "业务成功。" }, "message": { "type": "string", "description": "成功时为空字符串。", "const": "", "examples": [ "" ] }, "data": { "$ref": "#/components/schemas/Health" } }, "required": [ "code", "message", "data" ], "additionalProperties": false }, "DashboardResponse": { "type": "object", "properties": { "code": { "type": "integer", "const": 0, "description": "业务成功。" }, "message": { "type": "string", "description": "成功时为空字符串。", "const": "", "examples": [ "" ] }, "data": { "$ref": "#/components/schemas/Dashboard" } }, "required": [ "code", "message", "data" ], "additionalProperties": false }, "RequestID": { "type": "string", "description": "持久化幂等键，JSON 字符串，UTF-8 字节长度16–128，推荐ASCII UUID。创建钱包/归集、修改业务设置、通知重推必填。同租户同操作同键同参数返回原成功结果；同键异参409。只放JSON body，参与签名，不接受Idempotency-Key头。", "maxLength": 128, "x-minBytes": 16, "x-maxBytes": 128, "examples": [ "123e4567-e89b-42d3-a456-426614174000" ] }, "InputWalletID": { "type": "string", "description": "正 int64 ID 字符串，数值最大 9223372036854775807。建议原样传回响应 ID；不要增加前导零或 +。", "pattern": "^\\+?0*[1-9][0-9]*$", "examples": [ "123456789012345678" ] }, "AmountFilter": { "type": "string", "description": "六位精度最小单位的非负整数字符串，数值不超过 2^256−1；只允许0或不带前导零的十进制整数，不接受正负号、小数或科学计数法。空字符串不限制。", "examples": [ "100000000" ], "pattern": "^(|0|[1-9][0-9]*)$" }, "WalletFilters": { "type": "object", "properties": { "address": { "type": "string", "description": "收款地址模糊匹配，不区分大小写；最长 100 个 UTF-8 字节。空字符串忽略，% 和 _ 保留 LIKE 通配语义。", "examples": [ "TQyeXvAnmKsBqo6V48RmhAnZpWLmR2D7DM" ] }, "usdt_min": { "$ref": "#/components/schemas/AmountFilter", "description": "USDT 余额下限，包含边界；六位精度最小单位，0 至 2^256−1，不传或空字符串不限制。" }, "usdt_max": { "$ref": "#/components/schemas/AmountFilter", "description": "USDT 余额上限，包含边界；六位精度最小单位，0 至 2^256−1，不传或空字符串不限制。" }, "trx_min": { "$ref": "#/components/schemas/AmountFilter", "description": "TRX 余额下限，SUN，包含边界；0 至 2^256−1，不传或空字符串不限制。" }, "trx_max": { "$ref": "#/components/schemas/AmountFilter", "description": "TRX 余额上限，SUN，包含边界；0 至 2^256−1，不传或空字符串不限制。" }, "hide_zero": { "oneOf": [ { "type": "boolean" }, { "type": "string", "enum": [ "true", "false" ] } ], "default": false, "description": "true 只保留 USDT 余额大于 0 的钱包；不传为 false。" }, "hide_zero_trx": { "oneOf": [ { "type": "boolean" }, { "type": "string", "enum": [ "true", "false" ] } ], "default": false, "description": "true 只保留 TRX 余额大于 0 的钱包；不传为 false。" }, "last_collected_from": { "type": "string", "description": "最近成功归集时间下限，包含边界；带时区 RFC3339，可含小数秒；不传或空字符串不限制。", "examples": [ "2030-01-01T00:00:00Z" ] }, "last_collected_to": { "type": "string", "description": "最近成功归集时间上限，包含边界；不能早于 from；不传或空字符串不限制。", "examples": [ "2030-01-02T00:00:00Z" ] }, "sort": { "type": "string", "description": "列表排序字段：created_at、balance_usdt、balance_trx、last_collected_at、collected_usdt；默认 created_at。selection 即使传入也始终按 ID 升序返回。", "enum": [ "created_at", "balance_usdt", "balance_trx", "last_collected_at", "collected_usdt", "" ], "default": "created_at", "examples": [ "created_at" ] }, "order": { "type": "string", "description": "排序方向仅 asc / desc，默认 desc；selection 返回顺序不受此字段影响。", "enum": [ "asc", "desc", "" ], "default": "desc", "examples": [ "desc" ] } }, "required": [], "additionalProperties": false, "description": "跨页选择的筛选对象，必须提供，可为空对象；未知字段、错误类型及反向金额区间返回400。" }, "CreateWalletBody": { "type": "object", "properties": { "custom_id": { "$ref": "#/components/schemas/WalletCustomID" }, "request_id": { "$ref": "#/components/schemas/RequestID" } }, "required": [ "custom_id", "request_id" ], "additionalProperties": false, "description": "创建收款钱包。全部字段放 JSON，只接受 custom_id 与 request_id，不返回私钥；余额通过钱包详情查询。" }, "WalletCustomID": { "type": "string", "description": "1–32 个 Unicode 字符；不允许首尾空白；同一租户唯一。", "minLength": 1, "maxLength": 32, "examples": [ "customer-001" ] }, "SelectWalletBody": { "type": "object", "properties": { "filters": { "$ref": "#/components/schemas/WalletFilters" } }, "required": [ "filters" ], "additionalProperties": false }, "CreateSweepBody": { "oneOf": [ { "type": "object", "properties": { "wallet_ids": { "type": "array", "items": { "$ref": "#/components/schemas/InputWalletID" }, "description": "1–1000 个钱包；按数值去重，重复会拒绝整次请求。", "minItems": 1, "maxItems": 1000, "uniqueItems": true }, "sweep_mode": { "type": "string", "description": "全额归集。", "const": "all", "examples": [ "all" ] }, "requested_amount": { "type": "null", "description": "all 模式必须明确传 null，不能省略。" }, "request_id": { "$ref": "#/components/schemas/RequestID" } }, "required": [ "wallet_ids", "sweep_mode", "requested_amount", "request_id" ], "additionalProperties": false }, { "type": "object", "properties": { "wallet_ids": { "type": "array", "items": { "$ref": "#/components/schemas/InputWalletID" }, "description": "1–1000 个钱包；按数值去重。", "minItems": 1, "maxItems": 1000, "uniqueItems": true }, "sweep_mode": { "type": "string", "description": "指定金额。", "const": "fixed", "examples": [ "fixed" ] }, "requested_amount": { "type": "string", "description": "每个钱包的 USDT 归集金额，六位精度最小单位；规范正整数字符串，无 + 或前导零，最大 9223372036854775807。余额不足时不会降额。", "pattern": "^[1-9][0-9]*$", "examples": [ "100000000" ] }, "request_id": { "$ref": "#/components/schemas/RequestID" } }, "required": [ "wallet_ids", "sweep_mode", "requested_amount", "request_id" ], "additionalProperties": false } ] }, "WebhookEnvelope": { "type": "object", "description": "HTTP POST 的加密请求体。HKDF-SHA256 使用 appSecret 原始 UTF-8 字节为 IKM，appID UTF-8 为 salt，guiji/webhook/v1 为 info，派生32字节AES密钥。AAD为guiji/webhook/v1\\n{app_id}\\n{event_id}\\n{timestamp}，末尾无换行。先验证认证标签再处理明文。无额外回调签名头。", "properties": { "version": { "type": "integer", "const": 1, "description": "回调加密格式版本，固定为1。" }, "algorithm": { "type": "string", "const": "AES-256-GCM", "description": "固定为AES-256-GCM；不支持其他解密算法。" }, "app_id": { "type": "string", "description": "租户 appID。", "pattern": "^[1-9][0-9]*$" }, "event_id": { "type": "string", "description": "固定事件 ID；重试及人工新轮次保持不变。", "pattern": "^[1-9][0-9]*$" }, "timestamp": { "type": "string", "description": "本次投递的 Unix 秒级时间戳，参与 AAD。", "pattern": "^[1-9][0-9]*$" }, "nonce": { "type": "string", "description": "随机 12 字节 nonce 的标准 Base64。", "pattern": "^[A-Za-z0-9+/]{16}$" }, "ciphertext": { "type": "string", "description": "标准 Base64：密文后拼接 16 字节 GCM 认证标签。", "contentEncoding": "base64", "minLength": 24 } }, "required": [ "version", "algorithm", "app_id", "event_id", "timestamp", "nonce", "ciphertext" ], "additionalProperties": false, "examples": [ { "version": 1, "algorithm": "AES-256-GCM", "app_id": "9001000001", "event_id": "9002000001", "timestamp": "1788832800", "nonce": "JWTMRKnDBltShZv3", "ciphertext": "oPs1QZs4wULnm7WKTpjT0LsISZ9SngSJKUVe8nnQ3OZGGcjt/eOqQ68BIpq/5q6wfftELO5YwI/ybnzJr4Q0IH4+6ggP4jhX3MByWpftvkKwvMrQji9oUqrkAQyHBrHsAnL/IZRRgFoNLNnKXmo6wn/QuG2BhKLOij5BTWr6aFqz/dJsW0qMc4H9xYAlXqFF/L1NLHBgLesP8lKCvIf6ykNsISswL5Am2woGvyIFO4XhXaBSEG6HeGTajHrGuz4U6nP6f4RdDw8dpa8p4MBKttgs1PGQ082v5OStrK8k7kAYkNJmB5NHaNJx7b5VR+JDSIj8O7TqaDimzRj0Vinud+mila22odGEHmdy43WUoi6vHQfRiz4IGlhP6j8HrYsP7LTl9Xwb9RYghTH0FxAOTMNFJbNZE1ollzhEWKoAc49rhO3mXbbtwSCNFrq6gyApXnUDH9Cri2ZjSoF6y8RjgCEnRNGrX4tGV4aG5xwARtd0Tf7BICVKTIlcbTrSBcMshQrpWmNcXERCY1sVjmwaiaigZEYmcmvCxsR1CyMVOcg2hqtTgGTgxUWY2hxX/3ophnZOT4TibpTUsJZv/R3TP0pdHUaRIHcNmexWglC/PXVzv8gIpF4OTCX/wJdFwj64JxRkp+a0PQry75S2ejfBaq9+2YJGNPto6TQgWcKFe9oufirVMGnXlJ0qNohsBO/O4CLBCwRt5AWU1F+/LgbiWgptVciVxx8fX4IFRgFlY+u3Vd8Vd+Iv+ETgjwL3aWg7esj70SWOjnln7hJUGUkOS7VRQy7fv6Vi/xLNBtaFaX6u+MMCtg==" } ] }, "TransferResultEvent": { "type": "object", "description": "解密后的归集结果。event_type 前缀区分任务种类，后缀等于 status。", "properties": { "event_id": { "type": "string", "description": "固定事件 ID，必须等于加密外层 event_id。", "pattern": "^[1-9][0-9]*$" }, "event_type": { "type": "string", "enum": [ "sweep.succeeded", "sweep.failed", "sweep.cancelled" ], "description": "归集结果事件，分别为成功、失败或取消；按同一event_id去重。" }, "network": { "type": "string", "enum": [ "main", "nile" ], "description": "资产所属网络：main（主网）或 nile（测试网络）。", "examples": [ "nile" ] }, "task_id": { "type": "string", "description": "归集任务 ID。", "pattern": "^[1-9][0-9]*$" }, "wallet_id": { "type": "string", "description": "关联收款钱包 ID。", "pattern": "^[1-9][0-9]*$" }, "amount": { "type": "string", "description": "归集金额使用USDT六位精度最小单位。尚未确定金额可为0。", "pattern": "^(0|[1-9][0-9]*)$" }, "destination": { "type": "string", "description": "任务固定目标地址。" }, "txid": { "type": "string", "description": "链上交易哈希，尚未生成交易时为空字符串。" }, "status": { "type": "string", "enum": [ "succeeded", "failed", "cancelled" ], "description": "归集任务终态：succeeded成功、failed失败、cancelled取消；推送失败不影响该状态。" }, "reason": { "type": "string", "description": "失败或取消原因；成功为空字符串。" }, "actual_fee": { "type": "string", "description": "实际手续费，TRX最小单位，六位精度；未产生费用为0。", "pattern": "^(0|[1-9][0-9]*)$" } }, "required": [ "event_id", "event_type", "network", "task_id", "wallet_id", "amount", "destination", "txid", "status", "reason", "actual_fee" ], "additionalProperties": false }, "WebhookAcknowledgement": { "type": "object", "description": "提交本地业务事务后应答 HTTP 200 与 code 精确字符串 SUCCESS；最大64KiB，大小写敏感。", "properties": { "code": { "type": "string", "const": "SUCCESS", "description": "业务提交成功后的应答，必须是大写字符串SUCCESS；重复已处理事件同样返回SUCCESS。" } }, "required": [ "code" ], "additionalProperties": true }, "AccountAddresses": { "type": "object", "properties": { "collection_address": { "type": "string", "description": "当前租户统一配置的 USDT 归集目标；未绑定为空字符串，可以是外部 TRON 地址。", "examples": [ "TAt8Du9Xw2CmrTHRawGETwiEKpNuKDSjE8" ] } }, "required": [ "collection_address" ], "additionalProperties": false }, "CollectionAddressSetting": { "type": "object", "properties": { "collection_address": { "type": "string", "description": "保存后的 USDT 归集地址。", "examples": [ "TAt8Du9Xw2CmrTHRawGETwiEKpNuKDSjE8" ] } }, "required": [ "collection_address" ], "additionalProperties": false }, "AutomationSettings": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "自动归集的总开关。", "examples": [ true ] }, "usdt_minimum": { "anyOf": [ { "type": "string", "description": "自动归集触发下限，最小单位 USDT，规范正整数字符串，最大 2^256−1；关闭时可为 null。", "pattern": "^[1-9][0-9]*$", "examples": [ "100000000" ] }, { "type": "null" } ] } }, "required": [ "enabled", "usdt_minimum" ], "additionalProperties": false }, "WebhookSettings": { "type": "object", "properties": { "url": { "type": "string", "description": "公网 HTTPS 回调地址，只允许默认端口或 443；不含用户凭据或片段。关闭时可为空字符串。", "examples": [ "https://merchant.example.com/guiji/webhook" ] }, "enabled": { "type": "boolean", "description": "是否开启新通知轮次的正常投递；开启时必须有合法非空 URL。", "examples": [ true ] } }, "required": [ "url", "enabled" ], "additionalProperties": false }, "SetCollectionAddressBody": { "type": "object", "properties": { "address": { "type": "string", "description": "完整 TRON Base58Check 地址，必须通过校验和，且不能是平台内任何租户的钱包地址。不接受空字符串、私钥或钱包 ID。", "examples": [ "TAt8Du9Xw2CmrTHRawGETwiEKpNuKDSjE8" ] }, "request_id": { "$ref": "#/components/schemas/RequestID" } }, "required": [ "address", "request_id" ], "additionalProperties": false }, "SetAutomationBody": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "自动归集的总开关。", "examples": [ true ] }, "usdt_minimum": { "anyOf": [ { "type": "string", "description": "自动归集触发下限，最小单位 USDT，规范正整数字符串，最大 2^256−1；关闭时可为 null。", "pattern": "^[1-9][0-9]*$", "examples": [ "100000000" ] }, { "type": "null" } ] }, "request_id": { "$ref": "#/components/schemas/RequestID" } }, "required": [ "enabled", "usdt_minimum", "request_id" ], "additionalProperties": false, "allOf": [ { "if": { "properties": { "enabled": { "const": true } }, "required": [ "enabled" ] }, "then": { "properties": { "usdt_minimum": { "type": "string" } } } } ] }, "SetWebhookBody": { "type": "object", "properties": { "url": { "type": "string", "description": "公网 HTTPS 回调地址，只允许默认端口或 443；不含用户凭据或片段。关闭时可为空字符串。", "examples": [ "https://merchant.example.com/guiji/webhook" ] }, "enabled": { "type": "boolean", "description": "是否开启新通知轮次的正常投递；开启时必须有合法非空 URL。", "examples": [ true ] }, "request_id": { "$ref": "#/components/schemas/RequestID" } }, "required": [ "url", "enabled", "request_id" ], "additionalProperties": false, "allOf": [ { "if": { "properties": { "enabled": { "const": true } }, "required": [ "enabled" ] }, "then": { "properties": { "url": { "minLength": 1 } } } } ] }, "WalletPreviewBody": { "type": "object", "properties": { "wallet_ids": { "type": "array", "items": { "type": "string", "description": "规范正 int64 钱包 ID，最大 9223372036854775807；输入重复 ID 按首次出现去重。", "pattern": "^[1-9][0-9]*$", "examples": [ "123456789012345678" ] }, "description": "1–1000 个 ID，去重后保留请求顺序。", "minItems": 1, "maxItems": 1000 } }, "required": [ "wallet_ids" ], "additionalProperties": false }, "WalletPreview": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Wallet" }, "description": "所选钱包，去重并按请求首次出现顺序返回；任何 ID 不属于当前租户和网络则整个请求失败。", "minItems": 1, "maxItems": 1000 }, "network": { "type": "string", "enum": [ "main", "nile" ], "description": "资产所属网络：main（主网）或 nile（测试网络）。", "examples": [ "nile" ] } }, "required": [ "items", "network" ], "additionalProperties": false }, "SweepEstimateBody": { "type": "object", "properties": { "wallet_ids": { "type": "array", "items": { "type": "string", "description": "规范正 int64 钱包 ID，不能重复，最大 9223372036854775807。", "pattern": "^[1-9][0-9]*$", "examples": [ "123456789012345678" ] }, "description": "1–20 个钱包，按输入顺序预估。", "minItems": 1, "maxItems": 20, "uniqueItems": true }, "sweep_mode": { "type": "string", "description": "all 全额归集；fixed 每钱包指定金额。", "enum": [ "all", "fixed" ], "examples": [ "all" ] }, "requested_amount": { "anyOf": [ { "type": "string", "description": "all 必须明确为 null；fixed 必须为规范正 int64 字符串，最大 9223372036854775807，表示每个钱包的 USDT 最小单位金额。", "pattern": "^[1-9][0-9]*$", "examples": [ "100000000" ] }, { "type": "null" } ] } }, "required": [ "wallet_ids", "sweep_mode", "requested_amount" ], "additionalProperties": false, "allOf": [ { "oneOf": [ { "properties": { "sweep_mode": { "const": "all" }, "requested_amount": { "type": "null" } } }, { "properties": { "sweep_mode": { "const": "fixed" }, "requested_amount": { "type": "string" } } } ] } ] }, "SweepResourceEstimate": { "type": "object", "properties": { "energy_required": { "type": "string", "description": "交易总能量需求，单位能量点。以非负整数字符串传递。", "pattern": "^(0|[1-9][0-9]*)$", "examples": [ "65000" ] }, "energy_from_origin": { "type": "string", "description": "合约部署方分担的能量点数。以非负整数字符串传递。", "pattern": "^(0|[1-9][0-9]*)$", "examples": [ "0" ] }, "caller_energy_required": { "type": "string", "description": "调用钱包需要承担的能量点数。以非负整数字符串传递。", "pattern": "^(0|[1-9][0-9]*)$", "examples": [ "65000" ] }, "energy_available": { "type": "string", "description": "钱包当前可用能量点数。以非负整数字符串传递。", "pattern": "^(0|[1-9][0-9]*)$", "examples": [ "0" ] }, "energy_from_resources": { "type": "string", "description": "实际使用已有资源抵扣的能量点数。以非负整数字符串传递。", "pattern": "^(0|[1-9][0-9]*)$", "examples": [ "0" ] }, "energy_burned": { "type": "string", "pattern": "^(0|[1-9][0-9]*)$", "description": "当前已有资源抵扣后的能量缺口；仅wallet_trx路径预计燃烧TRX支付，catfee路径通过租赁补足。", "examples": [ "65000" ] }, "energy_fee": { "type": "string", "pattern": "^(0|[1-9][0-9]*)$", "description": "预计由钱包燃烧的TRX能量费用，SUN；resources和catfee路径为0。", "examples": [ "6500000" ] }, "bandwidth_required": { "type": "string", "description": "预计交易所需带宽，单位字节。以非负整数字符串传递。", "pattern": "^(0|[1-9][0-9]*)$", "examples": [ "350" ] }, "staked_bandwidth_available": { "type": "string", "description": "链上质押或委托带宽，仅作资源信息返回，不计入归集可用额度。归集只允许免费带宽。", "pattern": "^(0|[1-9][0-9]*)$", "examples": [ "0" ] }, "free_bandwidth_available": { "type": "string", "description": "当前可用的免费带宽，单位字节。以非负整数字符串传递。", "pattern": "^(0|[1-9][0-9]*)$", "examples": [ "600" ] }, "bandwidth_from_resources": { "type": "string", "description": "免费带宽可覆盖整笔交易时为完整交易字节数；不足时为0，等待恢复。", "pattern": "^(0|[1-9][0-9]*)$", "examples": [ "350" ] }, "bandwidth_burned": { "type": "string", "description": "当前带宽不足时的交易带宽需求；此时任务等待恢复，不会燃烧TRX。", "pattern": "^(0|[1-9][0-9]*)$", "examples": [ "0" ] }, "bandwidth_fee": { "type": "string", "description": "归集不使用TRX购买带宽，固定为0。", "pattern": "^(0|[1-9][0-9]*)$", "examples": [ "0" ] }, "energy_price": { "type": "string", "description": "每能量点价格，SUN。以非负整数字符串传递。", "pattern": "^(0|[1-9][0-9]*)$", "examples": [ "100" ] }, "bandwidth_price": { "type": "string", "description": "每带宽字节价格，SUN。以非负整数字符串传递。", "pattern": "^(0|[1-9][0-9]*)$", "examples": [ "1000" ] }, "fee_limit": { "type": "string", "pattern": "^(0|[1-9][0-9]*)$", "description": "交易完整能量准备额度折算的SUN上限，不是预计扣款，也不是带宽费用上限。", "examples": [ "7150000" ] }, "estimated_fee": { "type": "string", "pattern": "^(0|[1-9][0-9]*)$", "description": "预计钱包链上TRX支出，等于energy_fee，独立于rental_cost。", "examples": [ "6500000" ] }, "balance_usdt": { "type": "string", "description": "预估时查询的已确认 USDT 余额，最小单位。以非负整数字符串传递。", "pattern": "^(0|[1-9][0-9]*)$", "examples": [ "100000000" ] }, "balance_trx": { "type": "string", "pattern": "^(0|[1-9][0-9]*)$", "description": "确认余额与当前节点余额中的较小值，排除未确认收入并反映未确认支出，SUN。", "examples": [ "30000000" ] }, "bandwidth_source": { "type": "string", "enum": [ "free", "waiting" ], "description": "free使用免费额度；waiting等待免费带宽恢复或地址激活；不使用质押带宽或TRX。", "examples": [ "free" ] }, "rental_quantity": { "type": "string", "pattern": "^(0|[1-9][0-9]*)$", "description": "仅catfee路径非零；能量准备额度减已有能量，最低65000。", "examples": [ "0" ] }, "rental_cost": { "type": "string", "pattern": "^(0|[1-9][0-9]*)$", "description": "仅 catfee 路径的预计租赁费用，SUN，由平台支付；其他路径为 \"0\"。", "examples": [ "0" ] }, "activation_required": { "type": "string", "enum": [ "true", "false" ], "description": "地址是否需要激活。true 时订单同时激活地址，完成后重新核验资源。", "examples": [ "false" ] }, "fee_source": { "type": "string", "enum": [ "resources", "wallet_trx", "catfee" ], "description": "费用来源：resources 为自身能量，wallet_trx 为钱包 TRX，catfee 为平台能量租赁。", "examples": [ "wallet_trx" ] }, "prepared_energy": { "type": "string", "pattern": "^(0|[1-9][0-9]*)$", "description": "模拟总能量加10%后向上取整的准备额度。", "examples": [ "71500" ] }, "max_wallet_trx_fee": { "type": "string", "pattern": "^(0|[1-9][0-9]*)$", "description": "本次准备额度中允许钱包支付的能量缺口费用，SUN；仅wallet_trx路径非零。", "examples": [ "7150000" ] }, "free_bandwidth_limit": { "type": "string", "pattern": "^(0|[1-9][0-9]*)$", "description": "账户免费带宽上限；交易字节数超过此值不能等待恢复解决。", "examples": [ "600" ] } }, "required": [ "energy_required", "energy_from_origin", "caller_energy_required", "energy_available", "energy_from_resources", "energy_burned", "energy_fee", "bandwidth_required", "staked_bandwidth_available", "free_bandwidth_available", "bandwidth_from_resources", "bandwidth_burned", "bandwidth_fee", "energy_price", "bandwidth_price", "fee_limit", "estimated_fee", "balance_usdt", "balance_trx", "bandwidth_source", "rental_quantity", "rental_cost", "activation_required", "fee_source", "prepared_energy", "max_wallet_trx_fee", "free_bandwidth_limit" ], "additionalProperties": false }, "SweepEstimateItem": { "type": "object", "properties": { "wallet_id": { "type": "string", "description": "本项钱包 ID。", "pattern": "^[1-9][0-9]*$", "examples": [ "123456789012345678" ] }, "address": { "type": "string", "description": "本项来源地址。", "examples": [ "TQyeXvAnmKsBqo6V48RmhAnZpWLmR2D7DM" ] }, "amount": { "anyOf": [ { "type": "string", "description": "本次预估金额；无法取得金额时为 null；六位精度最小单位的整数字符串。", "pattern": "^(0|[1-9][0-9]*)$", "examples": [ "100000000" ] }, { "type": "null" } ] }, "status": { "type": "string", "description": "estimated 已取得费用预估；failed 本项不能预估。", "enum": [ "estimated", "failed" ], "examples": [ "estimated" ] }, "reason": { "type": "string", "description": "失败原因；预估成功为空字符串。", "examples": [ "" ] }, "estimate": { "anyOf": [ { "$ref": "#/components/schemas/SweepResourceEstimate" }, { "type": "null" } ], "description": "该钱包预估明细；本项预估失败时为null，原因见reason。" } }, "required": [ "wallet_id", "address", "amount", "status", "reason", "estimate" ], "additionalProperties": false, "allOf": [ { "oneOf": [ { "properties": { "status": { "const": "estimated" }, "amount": { "type": "string", "pattern": "^[1-9][0-9]*$" }, "reason": { "const": "" }, "estimate": { "type": "object" } } }, { "properties": { "status": { "const": "failed" }, "reason": { "minLength": 1 }, "estimate": { "type": "null" } } } ] } ] }, "SweepEstimate": { "type": "object", "properties": { "network": { "type": "string", "enum": [ "main", "nile" ], "description": "资产所属网络：main（主网）或 nile（测试网络）。", "examples": [ "nile" ] }, "destination": { "type": "string", "description": "本次预估使用的租户归集地址。", "examples": [ "TAt8Du9Xw2CmrTHRawGETwiEKpNuKDSjE8" ] }, "destination_version": { "type": "string", "description": "本次预估使用的归集配置版本，不是钱包 ID。", "pattern": "^[1-9][0-9]*$", "examples": [ "1" ] }, "sweep_mode": { "type": "string", "description": "与请求一致。", "enum": [ "all", "fixed" ], "examples": [ "all" ] }, "requested_amount": { "anyOf": [ { "type": "string", "description": "all 必须明确为 null；fixed 必须为规范正 int64 字符串，最大 9223372036854775807，表示每个钱包的 USDT 最小单位金额。", "pattern": "^[1-9][0-9]*$", "examples": [ "100000000" ] }, { "type": "null" } ] }, "estimated_at": { "type": "string", "description": "本次预估响应开始生成的时间。", "format": "date-time", "examples": [ "2030-01-01T00:00:00Z" ] }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/SweepEstimateItem" }, "description": "逐钱包结果，与请求顺序一致。", "minItems": 1, "maxItems": 20 } }, "required": [ "network", "destination", "destination_version", "sweep_mode", "requested_amount", "estimated_at", "items" ], "additionalProperties": false }, "WebhookEventSummary": { "type": "object", "properties": { "id": { "type": "string", "description": "固定通知事件 ID。", "pattern": "^[1-9][0-9]*$", "examples": [ "123456789012345678" ] }, "event_type": { "type": "string", "description": "通知事件类型。", "enum": [ "deposit.confirmed", "sweep.succeeded", "sweep.failed", "sweep.cancelled", "deposit.reverted" ], "examples": [ "deposit.confirmed" ] }, "status": { "type": "string", "description": "pending 待推送；delivering 推送中；delivered 推送成功；failed 推送异常。", "enum": [ "pending", "delivering", "delivered", "failed" ], "examples": [ "pending" ] }, "attempts": { "type": "integer", "description": "当前轮已开始的尝试次数，包含结果未知的尝试。", "examples": [ 0 ], "minimum": 0, "maximum": 20 }, "current_round": { "type": "integer", "description": "当前推送轮次；人工重新推送开启下一轮。", "examples": [ 1 ], "minimum": 1 }, "next_attempt": { "anyOf": [ { "type": "string", "description": "下一次计划推送时间；没有计划时为 null。", "format": "date-time", "examples": [ "2030-01-01T00:00:00Z" ] }, { "type": "null" } ] }, "deadline_at": { "type": "string", "description": "本轮 10 分钟截止时间。", "format": "date-time", "examples": [ "2030-01-01T00:10:00Z" ] }, "last_error": { "type": "string", "description": "最近推送错误；没有错误时为空字符串。", "examples": [ "" ] }, "created_at": { "type": "string", "description": "事件创建时间。", "format": "date-time", "examples": [ "2030-01-01T00:00:00Z" ] }, "delivered_at": { "anyOf": [ { "type": "string", "description": "推送成功时间；尚未成功为 null。", "format": "date-time", "examples": [ "2030-01-01T00:00:00Z" ] }, { "type": "null" } ] }, "network": { "type": "string", "enum": [ "main", "nile" ], "description": "资产所属网络：main（主网）或 nile（测试网络）。", "examples": [ "nile" ] } }, "required": [ "id", "event_type", "status", "attempts", "current_round", "next_attempt", "deadline_at", "last_error", "created_at", "delivered_at", "network" ], "additionalProperties": false }, "WebhookEventDetail": { "type": "object", "properties": { "id": { "type": "string", "description": "固定通知事件 ID。", "pattern": "^[1-9][0-9]*$", "examples": [ "123456789012345678" ] }, "event_type": { "type": "string", "description": "通知事件类型。", "enum": [ "deposit.confirmed", "sweep.succeeded", "sweep.failed", "sweep.cancelled", "deposit.reverted" ], "examples": [ "deposit.confirmed" ] }, "status": { "type": "string", "description": "pending 待推送；delivering 推送中；delivered 推送成功；failed 推送异常。", "enum": [ "pending", "delivering", "delivered", "failed" ], "examples": [ "pending" ] }, "attempts": { "type": "integer", "description": "当前轮已开始的尝试次数，包含结果未知的尝试。", "examples": [ 0 ], "minimum": 0, "maximum": 20 }, "current_round": { "type": "integer", "description": "当前推送轮次；人工重新推送开启下一轮。", "examples": [ 1 ], "minimum": 1 }, "next_attempt": { "anyOf": [ { "type": "string", "description": "下一次计划推送时间；没有计划时为 null。", "format": "date-time", "examples": [ "2030-01-01T00:00:00Z" ] }, { "type": "null" } ] }, "deadline_at": { "type": "string", "description": "本轮 10 分钟截止时间。", "format": "date-time", "examples": [ "2030-01-01T00:10:00Z" ] }, "last_error": { "type": "string", "description": "最近推送错误；没有错误时为空字符串。", "examples": [ "" ] }, "created_at": { "type": "string", "description": "事件创建时间。", "format": "date-time", "examples": [ "2030-01-01T00:00:00Z" ] }, "delivered_at": { "anyOf": [ { "type": "string", "description": "推送成功时间；尚未成功为 null。", "format": "date-time", "examples": [ "2030-01-01T00:00:00Z" ] }, { "type": "null" } ] }, "payload": { "oneOf": [ { "$ref": "#/components/schemas/Deposit" }, { "$ref": "#/components/schemas/TransferResultEvent" } ], "description": "原始业务事件正文，未加密对象；通过当前租户鉴权后返回，字段与回调解密结果相同。" }, "network": { "type": "string", "enum": [ "main", "nile" ], "description": "资产所属网络：main（主网）或 nile（测试网络）。", "examples": [ "nile" ] } }, "required": [ "id", "event_type", "status", "attempts", "current_round", "next_attempt", "deadline_at", "last_error", "created_at", "delivered_at", "payload", "network" ], "additionalProperties": false }, "WebhookRound": { "type": "object", "properties": { "id": { "type": "string", "description": "推送轮次 ID。", "pattern": "^[1-9][0-9]*$", "examples": [ "123456789012345679" ] }, "event_id": { "type": "string", "description": "所属固定事件 ID。", "pattern": "^[1-9][0-9]*$", "examples": [ "123456789012345680" ] }, "round_no": { "type": "integer", "description": "从 1 开始的轮次号。", "examples": [ 2 ], "minimum": 1 }, "url": { "type": "string", "description": "本轮固定回调地址；未配置时为空字符串。", "examples": [ "https://merchant.example.com/guiji/webhook" ] }, "started_at": { "type": "string", "description": "本轮开始时间。", "format": "date-time", "examples": [ "2030-01-01T00:00:00Z" ] }, "deadline_at": { "type": "string", "description": "本轮截止时间，开始后 10 分钟。", "format": "date-time", "examples": [ "2030-01-01T00:10:00Z" ] }, "finished_at": { "anyOf": [ { "type": "string", "description": "本轮结束时间；未结束为 null。", "format": "date-time", "examples": [ "2030-01-01T00:00:00Z" ] }, { "type": "null" } ] }, "attempts": { "type": "integer", "description": "本轮已占用的尝试次数，包含结果未知的尝试。", "examples": [ 0 ], "minimum": 0, "maximum": 20 }, "next_attempt": { "anyOf": [ { "type": "string", "description": "下一次计划投递时间；没有计划时为 null。", "format": "date-time", "examples": [ "2030-01-01T00:00:00Z" ] }, { "type": "null" } ] }, "status": { "type": "string", "description": "pending 待投递；delivering 投递中；delivered 成功；failed 异常。", "enum": [ "pending", "delivering", "delivered", "failed" ], "examples": [ "pending" ] }, "last_error": { "type": "string", "description": "当前轮次最近异常，正常时为空字符串。", "examples": [ "" ] }, "network": { "type": "string", "enum": [ "main", "nile" ], "description": "资产所属网络：main（主网）或 nile（测试网络）。", "examples": [ "nile" ] } }, "required": [ "id", "event_id", "round_no", "url", "started_at", "deadline_at", "finished_at", "attempts", "next_attempt", "status", "last_error", "network" ], "additionalProperties": false }, "WebhookAttempt": { "type": "object", "properties": { "id": { "type": "string", "description": "本次尝试记录 ID。", "pattern": "^[1-9][0-9]*$", "examples": [ "123456789012345679" ] }, "event_id": { "type": "string", "description": "固定事件 ID。", "pattern": "^[1-9][0-9]*$", "examples": [ "123456789012345680" ] }, "round_id": { "type": "string", "description": "所属轮次 ID。", "pattern": "^[1-9][0-9]*$", "examples": [ "123456789012345678" ] }, "round_no": { "type": "integer", "description": "所属轮次号。", "examples": [ 1 ], "minimum": 1 }, "attempt": { "type": "integer", "description": "该轮内的尝试序号。", "examples": [ 1 ], "minimum": 1, "maximum": 20 }, "status": { "type": "string", "description": "sending 正在发送；succeeded 已成功；failed 已失败；unknown 崩溃后结果未知。", "enum": [ "sending", "succeeded", "failed", "unknown" ], "examples": [ "failed" ] }, "http_status": { "anyOf": [ { "type": "integer", "description": "第三方 HTTP 状态码；未取得响应时为 null。", "examples": [ 503 ] }, { "type": "null" } ] }, "error": { "type": "string", "description": "本次网络或应答错误；正常时为空字符串。", "examples": [ "callback HTTP 503; exactly 200 is required" ] }, "started_at": { "type": "string", "description": "发送前入库的尝试开始时间。", "format": "date-time", "examples": [ "2030-01-01T00:00:00Z" ] }, "finished_at": { "anyOf": [ { "type": "string", "description": "本次尝试结束时间；尚未结束为 null。", "format": "date-time", "examples": [ "2030-01-01T00:00:00Z" ] }, { "type": "null" } ] }, "duration_ms": { "anyOf": [ { "type": "integer", "description": "尝试耗时毫秒；尚未结束为 null。", "examples": [ 12 ], "minimum": 0 }, { "type": "null" } ] }, "response_body": { "type": "string", "description": "第三方返回正文保存为纯文本；存储前清理非法UTF-8及NUL，最多64 KiB，超限标记response_truncated并视为失败。可能不是JSON；展示时不得执行HTML。", "examples": [ "service unavailable" ] }, "response_truncated": { "type": "boolean", "description": "正文超过上限或清理后超限时为 true；截断必定视为失败。", "examples": [ false ] }, "created_at": { "type": "string", "description": "尝试记录入库时间。", "format": "date-time", "examples": [ "2030-01-01T00:00:00Z" ] }, "network": { "type": "string", "enum": [ "main", "nile" ], "description": "资产所属网络：main（主网）或 nile（测试网络）。", "examples": [ "nile" ] } }, "required": [ "id", "event_id", "round_id", "round_no", "attempt", "status", "http_status", "error", "started_at", "finished_at", "duration_ms", "response_body", "response_truncated", "created_at", "network" ], "additionalProperties": false }, "RedeliverWebhookBody": { "type": "object", "properties": { "request_id": { "$ref": "#/components/schemas/RequestID" } }, "required": [ "request_id" ], "additionalProperties": false }, "WebhookEventPage": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookEventSummary" }, "description": "本页记录；无结果为 []。" }, "total": { "type": "integer", "description": "满足条件的总记录数。", "examples": [ 1 ], "minimum": 0 }, "page": { "type": "integer", "description": "当前页码。", "examples": [ 1 ], "minimum": 1 }, "page_size": { "type": "integer", "description": "每页条数。", "examples": [ 20 ], "minimum": 1, "maximum": 100 }, "network": { "type": "string", "enum": [ "main", "nile" ], "description": "资产所属网络：main（主网）或 nile（测试网络）。", "examples": [ "nile" ] } }, "required": [ "items", "total", "page", "page_size", "network" ], "additionalProperties": false }, "WebhookRoundPage": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookRound" }, "description": "本页记录；无结果为 []。" }, "total": { "type": "integer", "description": "满足条件的总记录数。", "examples": [ 1 ], "minimum": 0 }, "page": { "type": "integer", "description": "当前页码。", "examples": [ 1 ], "minimum": 1 }, "page_size": { "type": "integer", "description": "每页条数。", "examples": [ 20 ], "minimum": 1, "maximum": 100 }, "network": { "type": "string", "enum": [ "main", "nile" ], "description": "资产所属网络：main（主网）或 nile（测试网络）。", "examples": [ "nile" ] } }, "required": [ "items", "total", "page", "page_size", "network" ], "additionalProperties": false }, "WebhookAttemptPage": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookAttempt" }, "description": "本页记录；无结果为 []。" }, "total": { "type": "integer", "description": "满足条件的总记录数。", "examples": [ 1 ], "minimum": 0 }, "page": { "type": "integer", "description": "当前页码。", "examples": [ 1 ], "minimum": 1 }, "page_size": { "type": "integer", "description": "每页条数。", "examples": [ 20 ], "minimum": 1, "maximum": 100 }, "network": { "type": "string", "enum": [ "main", "nile" ], "description": "资产所属网络：main（主网）或 nile（测试网络）。", "examples": [ "nile" ] } }, "required": [ "items", "total", "page", "page_size", "network" ], "additionalProperties": false }, "AccountAddressesResponse": { "type": "object", "properties": { "code": { "type": "integer", "const": 0, "description": "业务成功。" }, "message": { "type": "string", "description": "成功时为空字符串。", "const": "", "examples": [ "" ] }, "data": { "$ref": "#/components/schemas/AccountAddresses" } }, "required": [ "code", "message", "data" ], "additionalProperties": false }, "CollectionAddressSettingResponse": { "type": "object", "properties": { "code": { "type": "integer", "const": 0, "description": "业务成功。" }, "message": { "type": "string", "description": "成功时为空字符串。", "const": "", "examples": [ "" ] }, "data": { "$ref": "#/components/schemas/CollectionAddressSetting" } }, "required": [ "code", "message", "data" ], "additionalProperties": false }, "AutomationSettingsResponse": { "type": "object", "properties": { "code": { "type": "integer", "const": 0, "description": "业务成功。" }, "message": { "type": "string", "description": "成功时为空字符串。", "const": "", "examples": [ "" ] }, "data": { "$ref": "#/components/schemas/AutomationSettings" } }, "required": [ "code", "message", "data" ], "additionalProperties": false }, "WebhookSettingsResponse": { "type": "object", "properties": { "code": { "type": "integer", "const": 0, "description": "业务成功。" }, "message": { "type": "string", "description": "成功时为空字符串。", "const": "", "examples": [ "" ] }, "data": { "$ref": "#/components/schemas/WebhookSettings" } }, "required": [ "code", "message", "data" ], "additionalProperties": false }, "WalletPreviewResponse": { "type": "object", "properties": { "code": { "type": "integer", "const": 0, "description": "业务成功。" }, "message": { "type": "string", "description": "成功时为空字符串。", "const": "", "examples": [ "" ] }, "data": { "$ref": "#/components/schemas/WalletPreview" } }, "required": [ "code", "message", "data" ], "additionalProperties": false }, "SweepEstimateResponse": { "type": "object", "properties": { "code": { "type": "integer", "const": 0, "description": "业务成功。" }, "message": { "type": "string", "description": "成功时为空字符串。", "const": "", "examples": [ "" ] }, "data": { "$ref": "#/components/schemas/SweepEstimate" } }, "required": [ "code", "message", "data" ], "additionalProperties": false }, "WebhookEventPageResponse": { "type": "object", "properties": { "code": { "type": "integer", "const": 0, "description": "业务成功。" }, "message": { "type": "string", "description": "成功时为空字符串。", "const": "", "examples": [ "" ] }, "data": { "$ref": "#/components/schemas/WebhookEventPage" } }, "required": [ "code", "message", "data" ], "additionalProperties": false }, "WebhookEventDetailResponse": { "type": "object", "properties": { "code": { "type": "integer", "const": 0, "description": "业务成功。" }, "message": { "type": "string", "description": "成功时为空字符串。", "const": "", "examples": [ "" ] }, "data": { "$ref": "#/components/schemas/WebhookEventDetail" } }, "required": [ "code", "message", "data" ], "additionalProperties": false }, "WebhookRoundPageResponse": { "type": "object", "properties": { "code": { "type": "integer", "const": 0, "description": "业务成功。" }, "message": { "type": "string", "description": "成功时为空字符串。", "const": "", "examples": [ "" ] }, "data": { "$ref": "#/components/schemas/WebhookRoundPage" } }, "required": [ "code", "message", "data" ], "additionalProperties": false }, "WebhookAttemptPageResponse": { "type": "object", "properties": { "code": { "type": "integer", "const": 0, "description": "业务成功。" }, "message": { "type": "string", "description": "成功时为空字符串。", "const": "", "examples": [ "" ] }, "data": { "$ref": "#/components/schemas/WebhookAttemptPage" } }, "required": [ "code", "message", "data" ], "additionalProperties": false }, "WebhookRoundResponse": { "type": "object", "properties": { "code": { "type": "integer", "const": 0, "description": "业务成功。" }, "message": { "type": "string", "description": "成功时为空字符串。", "const": "", "examples": [ "" ] }, "data": { "$ref": "#/components/schemas/WebhookRound" } }, "required": [ "code", "message", "data" ], "additionalProperties": false }, "WalletIdentity": { "type": "object", "properties": { "id": { "type": "string", "description": "钱包 ID。", "pattern": "^[1-9][0-9]*$", "examples": [ "123456789012345678" ] }, "address": { "type": "string", "description": "平台生成的 TRON Base58Check 收款地址。", "examples": [ "TQyeXvAnmKsBqo6V48RmhAnZpWLmR2D7DM" ] }, "custom_id": { "type": "string", "description": "租户自定义 ID；同一租户内唯一，1–32 个字符，不允许首尾空白。", "minLength": 1, "maxLength": 32, "examples": [ "customer-001" ] }, "chain": { "type": "string", "description": "所属链。", "const": "TRON", "examples": [ "TRON" ] }, "created_at": { "type": "string", "description": "钱包创建时间。", "format": "date-time", "examples": [ "2030-01-01T00:00:00Z" ] }, "network": { "type": "string", "enum": [ "main", "nile" ], "description": "资产所属网络：main（主网）或 nile（测试网络）。", "examples": [ "nile" ] } }, "required": [ "id", "address", "custom_id", "chain", "created_at", "network" ], "additionalProperties": false }, "WalletIdentityResponse": { "type": "object", "properties": { "code": { "type": "integer", "const": 0, "description": "业务成功。" }, "message": { "type": "string", "description": "成功时为空字符串。", "const": "", "examples": [ "" ] }, "data": { "$ref": "#/components/schemas/WalletIdentity" } }, "required": [ "code", "message", "data" ], "additionalProperties": false }, "EnergyRental": { "type": [ "object", "null" ], "description": "归集任务唯一的CatFee租赁记录。没有订单记录时energy_rental整体为null。", "properties": { "order_id": { "type": [ "string", "null" ], "description": "CatFee订单号；尚未确认创建成功时为null，不能据此再次下单。" }, "quantity": { "type": "string", "pattern": "^[0-9]+$", "description": "租赁能量数量，整数单位，不是TRX金额。" }, "estimated_cost": { "type": "string", "description": "预计平台租赁费用，SUN整数字符串；1000000 SUN=1 TRX。" }, "paid_cost": { "type": "string", "description": "当前记录的实际租赁扣费，SUN；未确认扣费时为0，结合state判断。" }, "activation_cost": { "type": "string", "description": "当前记录的地址激活费用，SUN；没有激活费或尚未确认时为0。" }, "state": { "type": "string", "enum": [ "prepared", "requesting", "unknown", "waiting", "confirmed", "failed", "expired" ], "description": "租赁状态：prepared已准备、requesting请求中、unknown结果未知、waiting等待交付、confirmed已确认、failed失败、expired已过期。" }, "expires_at": { "type": [ "string", "null" ], "format": "date-time", "description": "资源到期时间，RFC3339带时区；尚未取得到期时间时为null。" } }, "required": [ "order_id", "quantity", "estimated_cost", "paid_cost", "activation_cost", "state", "expires_at" ], "additionalProperties": false } } }, "webhooks": { "guijiEvent": { "post": { "operationId": "receiveGuijiEvent", "summary": "接收加密的到账或归集结果通知", "description": "由平台向服务商设置的公网 HTTPS:443 回调地址发起，不是平台接收入站API。每轮最长10分钟，立即首次投递，失败后两次请求开始时间至少间隔30秒，最多20次。单次15秒且受剩余轮次时间限制。只有HTTP200与JSON code=SUCCESS算成功。先验证GCM、核对event_id，再将事件去重和业务处理同一事务提交。解密正文为Deposit 或 TransferResultEvent。", "tags": [ "回调" ], "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEnvelope" }, "example": { "version": 1, "algorithm": "AES-256-GCM", "app_id": "9001000001", "event_id": "9002000001", "timestamp": "1788832800", "nonce": "JWTMRKnDBltShZv3", "ciphertext": "oPs1QZs4wULnm7WKTpjT0LsISZ9SngSJKUVe8nnQ3OZGGcjt/eOqQ68BIpq/5q6wfftELO5YwI/ybnzJr4Q0IH4+6ggP4jhX3MByWpftvkKwvMrQji9oUqrkAQyHBrHsAnL/IZRRgFoNLNnKXmo6wn/QuG2BhKLOij5BTWr6aFqz/dJsW0qMc4H9xYAlXqFF/L1NLHBgLesP8lKCvIf6ykNsISswL5Am2woGvyIFO4XhXaBSEG6HeGTajHrGuz4U6nP6f4RdDw8dpa8p4MBKttgs1PGQ082v5OStrK8k7kAYkNJmB5NHaNJx7b5VR+JDSIj8O7TqaDimzRj0Vinud+mila22odGEHmdy43WUoi6vHQfRiz4IGlhP6j8HrYsP7LTl9Xwb9RYghTH0FxAOTMNFJbNZE1ollzhEWKoAc49rhO3mXbbtwSCNFrq6gyApXnUDH9Cri2ZjSoF6y8RjgCEnRNGrX4tGV4aG5xwARtd0Tf7BICVKTIlcbTrSBcMshQrpWmNcXERCY1sVjmwaiaigZEYmcmvCxsR1CyMVOcg2hqtTgGTgxUWY2hxX/3ophnZOT4TibpTUsJZv/R3TP0pdHUaRIHcNmexWglC/PXVzv8gIpF4OTCX/wJdFwj64JxRkp+a0PQry75S2ejfBaq9+2YJGNPto6TQgWcKFe9oufirVMGnXlJ0qNohsBO/O4CLBCwRt5AWU1F+/LgbiWgptVciVxx8fX4IFRgFlY+u3Vd8Vd+Iv+ETgjwL3aWg7esj70SWOjnln7hJUGUkOS7VRQy7fv6Vi/xLNBtaFaX6u+MMCtg==" } } } }, "responses": { "200": { "description": "接收方已完成可靠处理，平台停止本轮投递。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookAcknowledgement" }, "example": { "code": "SUCCESS" } } } }, "default": { "description": "非200、错误JSON、错误code、超时或正文超64KiB均失败；平台依据轮次规则重试。" } } } } } }