# DTPG 钱包商户接口（OpenAPI 3）。生成文件，请勿手改 openapi: 3.0.3 info: description: |- 面向商户的钱包接口：充值地址、充值记录、提现、事件（回调）。 - 所有请求都要带 HMAC-SHA256 签名：X-Api-Key、X-Timestamp（Unix 毫秒，与服务器相差不超过 30 秒）、 X-Nonce（16–64 位随机串，同一 key 5 分钟内不可重复）、X-Signature。 - 待签名串：METHOD \n PATH \n CANONICAL_QUERY \n TIMESTAMP \n NONCE \n hex(sha256(BODY))， X-Signature = hex(HMAC-SHA256(API secret, 待签名串))。CANONICAL_QUERY 为查询参数按 key（同 key 按 value）排序、 RFC 3986 编码（空格为 %20）后用 & 连接；没有查询参数或 GET 无 body 时分别为空串与 sha256("")。 - 单个资源直接返回实体；列表按游标分页：?page_size=&page_token=，返回 {<资源复数>: [...], next_page_token} （page_size 默认 20、超过 100 按 100；next_page_token 为空表示没有更多，不透明、原样回传）。 - 时间一律 Unix 毫秒；int64 在 JSON 里是字符串。金额同时给主单位（amount）与最小单位整数（amount_raw）。 - 错误统一为 {code, reason, message, metadata}：按 reason 分支处理，message 只给开发者看。 - 回调（事件）：POST 到商户配置的地址，body 为 {event_id, type, created_at, data}，data 与对应 GET 接口返回一致； 请求头 X-Webhook-Id（= event_id）、X-Timestamp、X-Signature = hex(HMAC-SHA256(回调密钥, X-Timestamp + "\n" + body))。 返回 2xx 视为成功，否则按退避重试；按 event_id 去重，漏收可用 GET /v1/events 补拉。 title: DTPG 钱包商户接口 version: 1.0.0 servers: - url: https://api.dtpg.net security: - ApiKey: [] Nonce: [] Signature: [] Timestamp: [] tags: - description: 资产目录：支持的链、资产，地址校验 name: Catalog x-displayName: 资产目录：支持的链、资产，地址校验 - description: 充值记录与补单 name: Deposit x-displayName: 充值记录与补单 - description: |- 回调事件：补拉与重发 漏收回调时用。事件类型：deposit.confirmed；withdraw.broadcasted / confirmed / failed / rejected name: Event x-displayName: 回调事件：补拉与重发 - description: 用户钱包：充值地址、余额 name: Wallet x-displayName: 用户钱包：充值地址、余额 - description: |- 提现：发起、查询 状态：REQUESTING（待审核）→ PENDING（已审核，签名 / 广播中）→ BROADCASTED（已广播，确认中）→ CONFIRMED； 终态还有 REJECTED（审核拒绝）、FAILED（失败）。每次进入 BROADCASTED / CONFIRMED / FAILED / REJECTED 发一条事件 （withdraw.broadcasted / confirmed / failed / rejected），data 与 GET /v1/withdraws/{withdraw_id} 相同 name: Withdraw x-displayName: 提现：发起、查询 paths: /v1/addresses/validate: post: description: |- 地址校验：格式是否正确、是否平台内地址（平台内地址提现走内部转账，不上链） **API key 权限范围**：`read` operationId: validateAddress requestBody: content: application/json: schema: $ref: '#/components/schemas/ValidateAddressRequest' required: true responses: "200": content: application/json: schema: $ref: '#/components/schemas/AddressValidation' description: OK default: content: application/json: schema: $ref: '#/components/schemas/Error' description: 错误 security: - ApiKey: [] Nonce: [] Signature: [] Timestamp: [] summary: 地址校验：格式是否正确、是否平台内地址（平台内地址提现走内部转账，不上链） tags: - Catalog x-scope: read /v1/assets: get: description: |- 支持的资产：链 × 币种（精度、合约、最小充值 / 提现额、手续费），可按链过滤 **API key 权限范围**：`read` operationId: listAssets parameters: - description: 链代码：可选，不传返回所有启用链的资产 in: query name: chain_code schema: type: string responses: "200": content: application/json: schema: $ref: '#/components/schemas/AssetList' description: OK default: content: application/json: schema: $ref: '#/components/schemas/Error' description: 错误 security: - ApiKey: [] Nonce: [] Signature: [] Timestamp: [] summary: 支持的资产：链 × 币种（精度、合约、最小充值 / 提现额、手续费），可按链过滤 tags: - Catalog x-scope: read /v1/chains: get: description: |- 支持的链：只返回启用的链 **API key 权限范围**：`read` operationId: listChains responses: "200": content: application/json: schema: $ref: '#/components/schemas/ChainList' description: OK default: content: application/json: schema: $ref: '#/components/schemas/Error' description: 错误 security: - ApiKey: [] Nonce: [] Signature: [] Timestamp: [] summary: 支持的链：只返回启用的链 tags: - Catalog x-scope: read /v1/deposits: get: description: |- 充值记录：按 deposit_id 倒序，游标分页 **API key 权限范围**：`read` operationId: listDeposits parameters: - description: 用户ID：可选 in: query name: user_id schema: type: string - description: 链代码：可选 in: query name: chain_code schema: type: string - description: 币种代码：可选 in: query name: token_code schema: type: string - description: 状态：可选 in: query name: status schema: type: string - description: 交易哈希：可选 in: query name: tx_hash schema: type: string - description: 开始时间：按发现时间，Unix 毫秒，含 in: query name: start_time schema: type: string - description: 结束时间：按发现时间，Unix 毫秒，含 in: query name: end_time schema: type: string - description: 每页条数：默认 20，最大 100（超过按 100） in: query name: page_size schema: format: int32 type: integer - description: 分页令牌：上一页返回的 next_page_token，第一页不传；不透明，原样回传 in: query name: page_token schema: type: string responses: "200": content: application/json: schema: $ref: '#/components/schemas/DepositPage' description: OK default: content: application/json: schema: $ref: '#/components/schemas/Error' description: 错误 security: - ApiKey: [] Nonce: [] Signature: [] Timestamp: [] summary: 充值记录：按 deposit_id 倒序，游标分页 tags: - Deposit x-scope: read /v1/deposits/{deposit_id}: get: description: |- 单笔充值 **API key 权限范围**：`read` operationId: getDeposit parameters: - description: 充值ID in: path name: deposit_id required: true schema: type: string responses: "200": content: application/json: schema: $ref: '#/components/schemas/Deposit' description: OK default: content: application/json: schema: $ref: '#/components/schemas/Error' description: 错误 security: - ApiKey: [] Nonce: [] Signature: [] Timestamp: [] summary: 单笔充值 tags: - Deposit x-scope: read /v1/deposits/rescan: post: description: |- 按交易哈希补单：重新识别该交易里转给该用户的充值（漏推送时用）；已识别的不会重复入账 **API key 权限范围**：`deposit` operationId: rescanDeposit requestBody: content: application/json: schema: $ref: '#/components/schemas/RescanDepositRequest' required: true responses: "200": content: application/json: schema: $ref: '#/components/schemas/RescanResult' description: OK default: content: application/json: schema: $ref: '#/components/schemas/Error' description: 错误 security: - ApiKey: [] Nonce: [] Signature: [] Timestamp: [] summary: 按交易哈希补单：重新识别该交易里转给该用户的充值（漏推送时用）；已识别的不会重复入账 tags: - Deposit x-scope: deposit /v1/events: get: description: |- 事件列表：按事件倒序，游标分页；可按投递状态找出没送达的（如 FAILED） **API key 权限范围**：`read` operationId: listEvents parameters: - description: 事件类型：可选 in: query name: type schema: type: string - description: 投递状态：可选 in: query name: delivery_status schema: type: string - description: 开始时间：按事件时间，Unix 毫秒，含 in: query name: start_time schema: type: string - description: 结束时间：按事件时间，Unix 毫秒，含 in: query name: end_time schema: type: string - description: 每页条数：默认 20，最大 100（超过按 100） in: query name: page_size schema: format: int32 type: integer - description: 分页令牌：上一页返回的 next_page_token，第一页不传；不透明，原样回传 in: query name: page_token schema: type: string responses: "200": content: application/json: schema: $ref: '#/components/schemas/EventPage' description: OK default: content: application/json: schema: $ref: '#/components/schemas/Error' description: 错误 security: - ApiKey: [] Nonce: [] Signature: [] Timestamp: [] summary: 事件列表：按事件倒序，游标分页；可按投递状态找出没送达的（如 FAILED） tags: - Event x-scope: read /v1/events/{event_id}/resend: post: description: |- 重发事件：立即按商户当前的回调地址与回调密钥重新投递一次（event_id 不变，商户按它去重） **API key 权限范围**：`read` operationId: resendEvent parameters: - description: 事件ID：evt_ 开头 in: path name: event_id required: true schema: type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/ResendEventRequest' required: true responses: "200": content: application/json: schema: $ref: '#/components/schemas/Event' description: OK default: content: application/json: schema: $ref: '#/components/schemas/Error' description: 错误 security: - ApiKey: [] Nonce: [] Signature: [] Timestamp: [] summary: 重发事件：立即按商户当前的回调地址与回调密钥重新投递一次（event_id 不变，商户按它去重） tags: - Event x-scope: read /v1/wallets/{user_id}/addresses: get: description: |- 用户的全部充值地址；用户不存在返回空列表 **API key 权限范围**：`read` operationId: listAddresses parameters: - description: 用户ID：商户侧用户标识 in: path name: user_id required: true schema: type: string responses: "200": content: application/json: schema: $ref: '#/components/schemas/AddressList' description: OK default: content: application/json: schema: $ref: '#/components/schemas/Error' description: 错误 security: - ApiKey: [] Nonce: [] Signature: [] Timestamp: [] summary: 用户的全部充值地址；用户不存在返回空列表 tags: - Wallet x-scope: read post: description: |- 取或建充值地址：用户钱包不存在则创建，该链地址不存在则派生；幂等，重复调用返回同一地址 **API key 权限范围**：`deposit` operationId: createAddress parameters: - description: 用户ID：商户侧用户标识 in: path name: user_id required: true schema: type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/CreateAddressRequest' required: true responses: "200": content: application/json: schema: $ref: '#/components/schemas/Address' description: OK default: content: application/json: schema: $ref: '#/components/schemas/Error' description: 错误 security: - ApiKey: [] Nonce: [] Signature: [] Timestamp: [] summary: 取或建充值地址：用户钱包不存在则创建，该链地址不存在则派生；幂等，重复调用返回同一地址 tags: - Wallet x-scope: deposit /v1/wallets/{user_id}/balances: get: description: |- 用户余额：按资产列出可用 / 冻结（只含已入账的确认充值与内部转账）；用户不存在返回空列表 **API key 权限范围**：`read` operationId: listBalances parameters: - description: 用户ID：商户侧用户标识 in: path name: user_id required: true schema: type: string responses: "200": content: application/json: schema: $ref: '#/components/schemas/BalanceList' description: OK default: content: application/json: schema: $ref: '#/components/schemas/Error' description: 错误 security: - ApiKey: [] Nonce: [] Signature: [] Timestamp: [] summary: 用户余额：按资产列出可用 / 冻结（只含已入账的确认充值与内部转账）；用户不存在返回空列表 tags: - Wallet x-scope: read /v1/withdraws: get: description: |- 提现记录：按 withdraw_id 倒序，游标分页；按 biz_id 查商户自己的单号 **API key 权限范围**：`read` operationId: listWithdraws parameters: - description: 用户ID：可选 in: query name: user_id schema: type: string - description: 商户单号：可选 in: query name: biz_id schema: type: string - description: 链代码：可选 in: query name: chain_code schema: type: string - description: 币种代码：可选 in: query name: token_code schema: type: string - description: 状态：可选 in: query name: status schema: type: string - description: 交易哈希：可选 in: query name: tx_hash schema: type: string - description: 开始时间：按创建时间，Unix 毫秒，含 in: query name: start_time schema: type: string - description: 结束时间：按创建时间，Unix 毫秒，含 in: query name: end_time schema: type: string - description: 每页条数：默认 20，最大 100（超过按 100） in: query name: page_size schema: format: int32 type: integer - description: 分页令牌：上一页返回的 next_page_token，第一页不传；不透明，原样回传 in: query name: page_token schema: type: string responses: "200": content: application/json: schema: $ref: '#/components/schemas/WithdrawPage' description: OK default: content: application/json: schema: $ref: '#/components/schemas/Error' description: 错误 security: - ApiKey: [] Nonce: [] Signature: [] Timestamp: [] summary: 提现记录：按 withdraw_id 倒序，游标分页；按 biz_id 查商户自己的单号 tags: - Withdraw x-scope: read post: description: |- 发起提现：外部地址进入人工审核；双方都是资金池商户时池内转账（即时完成、不上链） **API key 权限范围**：`withdraw` operationId: createWithdraw requestBody: content: application/json: schema: $ref: '#/components/schemas/CreateWithdrawRequest' required: true responses: "200": content: application/json: schema: $ref: '#/components/schemas/Withdraw' description: OK default: content: application/json: schema: $ref: '#/components/schemas/Error' description: 错误 security: - ApiKey: [] Nonce: [] Signature: [] Timestamp: [] summary: 发起提现：外部地址进入人工审核；双方都是资金池商户时池内转账（即时完成、不上链） tags: - Withdraw x-scope: withdraw /v1/withdraws/{withdraw_id}: get: description: |- 单笔提现 **API key 权限范围**：`read` operationId: getWithdraw parameters: - description: 提现ID in: path name: withdraw_id required: true schema: type: string responses: "200": content: application/json: schema: $ref: '#/components/schemas/Withdraw' description: OK default: content: application/json: schema: $ref: '#/components/schemas/Error' description: 错误 security: - ApiKey: [] Nonce: [] Signature: [] Timestamp: [] summary: 单笔提现 tags: - Withdraw x-scope: read components: schemas: Address: properties: address: type: string chain_code: type: string create_time: description: 创建时间（Unix 毫秒） type: string status: description: ACTIVE type: string user_id: type: string type: object AddressList: properties: addresses: items: $ref: '#/components/schemas/Address' type: array type: object AddressValidation: properties: internal: description: 是否平台内的用户充值地址：是则提现到该地址走内部转账（即时到账、不上链、无手续费） type: boolean normalized_address: description: 规整后的地址（EVM 为全小写）；无效时为空 type: string valid: description: 格式是否正确 type: boolean type: object Asset: properties: chain_code: type: string contract_address: description: 合约地址；原生币为空 type: string decimals: format: int32 type: integer deposit_enabled: type: boolean explorer_url_template: description: 区块浏览器交易链接模板，{txHash} 替换为交易哈希 type: string min_deposit_amount: description: 以下金额为主单位十进制字符串 type: string min_withdraw_amount: type: string token_code: description: 币种代码，如 USDT type: string token_name: type: string withdraw_enabled: type: boolean withdraw_fee: type: string type: object AssetList: properties: assets: items: $ref: '#/components/schemas/Asset' type: array type: object Balance: properties: available: description: 可用（主单位） type: string available_raw: description: 可用（最小单位整数） type: string chain_code: type: string decimals: format: int32 type: integer frozen: description: 冻结（主单位） type: string frozen_raw: description: 冻结（最小单位整数） type: string token_code: type: string update_time: description: 最后变动时间（Unix 毫秒） type: string type: object BalanceList: properties: balances: items: $ref: '#/components/schemas/Balance' type: array type: object Chain: properties: code: description: 链代码：TRON / ETH / BSC type: string evm_chain_id: description: EVM chainId（如 "1"、"56"），TRON 为空 type: string name: type: string type: object ChainList: properties: chains: items: $ref: '#/components/schemas/Chain' type: array type: object CreateAddressRequest: properties: chain_code: description: 链代码 type: string master_key_id: description: 主密钥ID：可选，仅在用户钱包首次创建时生效，不传用商户当前 ACTIVE 主密钥 type: string user_id: description: 用户ID：商户侧用户标识 type: string type: object CreateWithdrawRequest: properties: amount: description: 金额：主单位，如 12.5 type: string biz_id: description: 业务单号：商户侧幂等键，同一商户内唯一 type: string chain_code: description: 链代码：如 TRON / ETH / BSC type: string force_onchain: description: 强制上链：目标是平台资金池内另一个地址时，默认池内转账（即时、不耗 gas、不收手续费）；true 则按普通提现上链 type: boolean to_address: description: 目标地址 type: string token_code: description: 币种：如 USDT type: string user_id: description: 用户ID：商户侧用户标识 type: string type: object Deposit: properties: amount: description: 金额（主单位） type: string amount_raw: description: 金额（最小单位整数） type: string block_number: type: string chain_code: type: string confirm_time: description: 确认入账时间（Unix 毫秒），未确认为 0 type: string confirmations: format: int32 type: integer create_time: description: 发现时间（Unix 毫秒） type: string decimals: format: int32 type: integer deposit_id: type: string from_address: description: 付款地址；内部转账为平台出账热钱包地址 type: string internal: description: 是否平台内部转账（付款方是平台内其它用户，不上链、即时到账） type: boolean log_index: description: 交易内的事件序号（同一交易多笔转账时区分） format: int32 type: integer status: description: PENDING（确认中，不可入账）/ CONFIRMED（已入账）/ FAILED / REORGED / BELOW_MIN（低于最小充值额，只记录不入账） type: string to_address: type: string token_code: type: string tx_hash: description: 链上交易哈希；内部转账为空 type: string user_id: type: string type: object DepositPage: properties: deposits: items: $ref: '#/components/schemas/Deposit' type: array next_page_token: description: 下一页的 page_token；为空表示没有更多 type: string type: object Error: description: 统一错误体 properties: code: description: HTTP 状态码 type: integer message: description: 英文说明，只给开发者看 type: string metadata: additionalProperties: type: string description: 动态参数 type: object reason: description: 稳定的错误标识，如 SIGNATURE_INVALID、DUPLICATE_REQUEST type: string type: object Event: properties: created_at: description: 事件时间（Unix 毫秒） type: string data: description: 事件数据：与对应 GET 接口返回的资源完全一致（deposit.confirmed → GET /v1/deposits/{deposit_id}），为事件发生时的快照 type: object delivery_status: description: 投递状态：PENDING（待投递）/ RETRY（失败等待重试）/ SUCCESS（商户已返回 2xx）/ FAILED（重试用尽） type: string event_id: description: 事件ID（回调请求头 X-Webhook-Id 与 body 里的 event_id） type: string last_http_status: description: 最后一次投递的 HTTP 状态码，没有为 0 format: int32 type: integer retry_count: description: 失败重试轮次（每轮最多即时重试 3 次，之后按退避等待下一轮；超过上限标记 FAILED） format: int32 type: integer type: description: 事件类型：deposit.confirmed / withdraw.broadcasted / withdraw.confirmed / withdraw.failed / withdraw.rejected type: string type: object EventPage: properties: events: items: $ref: '#/components/schemas/Event' type: array next_page_token: description: 下一页的 page_token；为空表示没有更多 type: string type: object RescanDepositRequest: properties: chain_code: description: 链代码 type: string tx_hash: description: 交易哈希 type: string user_id: description: 用户ID：商户侧用户标识 type: string type: object RescanResult: properties: chain_code: type: string items: items: $ref: '#/components/schemas/RescanResultItem' type: array message: type: string result: description: ACCEPTED：至少一笔充值已记录、等待确认入账；SKIPPED：没有可入账的充值 type: string tx_hash: type: string type: object RescanResultItem: properties: amount: description: 金额（主单位） type: string deposit_id: description: 充值ID；为空表示该笔转账被跳过（如原生币、币种未登记） type: string log_index: format: int32 type: integer status: description: 充值状态；被跳过为 SKIPPED type: string to_address: type: string type: object ResendEventRequest: properties: event_id: description: 事件ID：evt_ 开头 type: string type: object ValidateAddressRequest: properties: address: description: 地址 type: string chain_code: description: 链代码 type: string type: object Withdraw: properties: amount: description: 金额（主单位），链上实际转出的金额 type: string amount_raw: description: 金额（最小单位整数） type: string biz_id: description: 商户单号 type: string block_number: type: string broadcast_time: description: 广播时间（Unix 毫秒），未广播为 0 type: string chain_code: type: string confirm_time: description: 确认时间（Unix 毫秒），未确认为 0 type: string confirmations: format: int32 type: integer create_time: description: 创建时间（Unix 毫秒） type: string decimals: format: int32 type: integer fee: description: 手续费（主单位），不上链 type: string from_address: description: 出账热钱包地址：审核通过后才有；池内转账为空 type: string internal: description: 是否池内转账（双方都是资金池商户，不上链、即时完成） type: boolean reason: description: 失败或拒绝原因（FAILED / REJECTED 时有值） type: string status: description: REQUESTING / PENDING / BROADCASTED / CONFIRMED / REJECTED / FAILED type: string to_address: type: string token_code: type: string tx_hash: description: 链上交易哈希：签名后才有；池内转账为空 type: string user_id: type: string withdraw_id: type: string type: object WithdrawPage: properties: next_page_token: description: 下一页的 page_token；为空表示没有更多 type: string withdraws: items: $ref: '#/components/schemas/Withdraw' type: array type: object securitySchemes: ApiKey: description: API key ID in: header name: X-Api-Key type: apiKey Nonce: description: 16–64 位随机串，同一 key 5 分钟内不可重复 in: header name: X-Nonce type: apiKey Signature: description: hex(HMAC-SHA256(API secret, 待签名串)) in: header name: X-Signature type: apiKey Timestamp: description: Unix 毫秒，±30 秒 in: header name: X-Timestamp type: apiKey