--- url: /reference/withdraws.md --- # 提现 提现：发起、查询 状态：REQUESTING（待审核）→ PENDING（已审核，签名 / 广播中）→ BROADCASTED（已广播，确认中）→ CONFIRMED； 终态还有 REJECTED（审核拒绝）、FAILED（失败）。每次进入 BROADCASTED / CONFIRMED / FAILED / REJECTED 发一条事件 （withdraw.broadcasted / confirmed / failed / rejected），data 与 GET /v1/withdraws/{withdraw_id} 相同 ## 提现记录 ```http GET /v1/withdraws ``` API key 权限范围: `read` 提现记录：按 withdraw_id 倒序，游标分页；按 biz_id 查商户自己的单号 **请求参数** | 参数 | 位置 | 类型 | 必填 | 说明 | |---|---|---|---|---| | `user_id` | 查询 | string | 否 | 用户ID：可选 | | `biz_id` | 查询 | string | 否 | 商户单号：可选 | | `chain_code` | 查询 | string | 否 | 链代码：可选 | | `token_code` | 查询 | string | 否 | 币种代码：可选 | | `status` | 查询 | string | 否 | 状态：可选 | | `tx_hash` | 查询 | string | 否 | 交易哈希：可选 | | `start_time` | 查询 | string | 否 | 开始时间：按创建时间，Unix 毫秒，含 | | `end_time` | 查询 | string | 否 | 结束时间：按创建时间，Unix 毫秒，含 | | `page_size` | 查询 | integer | 否 | 每页条数：默认 20，最大 100（超过按 100） | | `page_token` | 查询 | string | 否 | 分页令牌：上一页返回的 next_page_token，第一页不传；不透明，原样回传 | **响应** (200, `WithdrawPage`) | 字段 | 类型 | 说明 | |---|---|---| | `next_page_token` | string | 下一页的 page_token；为空表示没有更多 | | `withdraws` | object (Withdraw)\[] | | | `withdraws[].amount` | string | 金额（主单位），链上实际转出的金额 | | `withdraws[].amount_raw` | string | 金额（最小单位整数） | | `withdraws[].biz_id` | string | 商户单号 | | `withdraws[].block_number` | string | | | `withdraws[].broadcast_time` | string | 广播时间（Unix 毫秒），未广播为 0 | | `withdraws[].chain_code` | string | | | `withdraws[].confirm_time` | string | 确认时间（Unix 毫秒），未确认为 0 | | `withdraws[].confirmations` | integer | | | `withdraws[].create_time` | string | 创建时间（Unix 毫秒） | | `withdraws[].decimals` | integer | | | `withdraws[].fee` | string | 手续费（主单位），不上链 | | `withdraws[].from_address` | string | 出账热钱包地址：审核通过后才有；池内转账为空 | | `withdraws[].internal` | boolean | 是否池内转账（双方都是资金池商户，不上链、即时完成） | | `withdraws[].reason` | string | 失败或拒绝原因（FAILED / REJECTED 时有值） | | `withdraws[].status` | string | REQUESTING / PENDING / BROADCASTED / CONFIRMED / REJECTED / FAILED | | `withdraws[].to_address` | string | | | `withdraws[].token_code` | string | | | `withdraws[].tx_hash` | string | 链上交易哈希：签名后才有；池内转账为空 | | `withdraws[].user_id` | string | | | `withdraws[].withdraw_id` | string | | 响应示例： ```json { "next_page_token": "", "withdraws": [ { "amount": "12.5", "amount_raw": "12500000", "biz_id": "order-20261109-0001", "block_number": "77123456", "broadcast_time": "1762650000000", "chain_code": "TRON", "confirm_time": "1762650000000", "confirmations": 0, "create_time": "1762650000000", "decimals": 6, "fee": "", "from_address": "TJRabPrwbZy45sbavfcjinPJC18kjpRTv8", "internal": false, "reason": "AMOUNT_BELOW_MIN", "status": "REQUESTING", "to_address": "TXYZopYRdj2D9XRtbG411XZZ3kM5VkAeBf", "token_code": "USDT", "tx_hash": "3f1c0e…（交易哈希）", "user_id": "u_10001", "withdraw_id": "1987654321098753" } ] } ``` 失败时返回统一错误体，见 [错误处理](/guide/errors)。 ## 发起提现 ```http POST /v1/withdraws ``` API key 权限范围: `withdraw` 发起提现：外部地址进入人工审核；双方都是资金池商户时池内转账（即时完成、不上链） **请求体** | 字段 | 类型 | 说明 | |---|---|---| | `amount` | string | 金额：主单位，如 12.5 | | `biz_id` | string | 业务单号：商户侧幂等键，同一商户内唯一 | | `chain_code` | string | 链代码：如 TRON / ETH / BSC | | `force_onchain` | boolean | 强制上链：目标是平台资金池内另一个地址时，默认池内转账（即时、不耗 gas、不收手续费）；true 则按普通提现上链 | | `to_address` | string | 目标地址 | | `token_code` | string | 币种：如 USDT | | `user_id` | string | 用户ID：商户侧用户标识 | 请求示例： ```json { "amount": "12.5", "biz_id": "order-20261109-0001", "chain_code": "TRON", "force_onchain": false, "to_address": "TXYZopYRdj2D9XRtbG411XZZ3kM5VkAeBf", "token_code": "USDT", "user_id": "u_10001" } ``` **响应** (200, `Withdraw`) | 字段 | 类型 | 说明 | |---|---|---| | `amount` | string | 金额（主单位），链上实际转出的金额 | | `amount_raw` | string | 金额（最小单位整数） | | `biz_id` | string | 商户单号 | | `block_number` | string | | | `broadcast_time` | string | 广播时间（Unix 毫秒），未广播为 0 | | `chain_code` | string | | | `confirm_time` | string | 确认时间（Unix 毫秒），未确认为 0 | | `confirmations` | integer | | | `create_time` | string | 创建时间（Unix 毫秒） | | `decimals` | integer | | | `fee` | string | 手续费（主单位），不上链 | | `from_address` | string | 出账热钱包地址：审核通过后才有；池内转账为空 | | `internal` | boolean | 是否池内转账（双方都是资金池商户，不上链、即时完成） | | `reason` | string | 失败或拒绝原因（FAILED / REJECTED 时有值） | | `status` | string | REQUESTING / PENDING / BROADCASTED / CONFIRMED / REJECTED / FAILED | | `to_address` | string | | | `token_code` | string | | | `tx_hash` | string | 链上交易哈希：签名后才有；池内转账为空 | | `user_id` | string | | | `withdraw_id` | string | | 响应示例： ```json { "amount": "12.5", "amount_raw": "12500000", "biz_id": "order-20261109-0001", "block_number": "77123456", "broadcast_time": "1762650000000", "chain_code": "TRON", "confirm_time": "1762650000000", "confirmations": 0, "create_time": "1762650000000", "decimals": 6, "fee": "", "from_address": "TJRabPrwbZy45sbavfcjinPJC18kjpRTv8", "internal": false, "reason": "AMOUNT_BELOW_MIN", "status": "REQUESTING", "to_address": "TXYZopYRdj2D9XRtbG411XZZ3kM5VkAeBf", "token_code": "USDT", "tx_hash": "3f1c0e…（交易哈希）", "user_id": "u_10001", "withdraw_id": "1987654321098753" } ``` 失败时返回统一错误体，见 [错误处理](/guide/errors)。 ## 单笔提现 ```http GET /v1/withdraws/{withdraw_id} ``` API key 权限范围: `read` 单笔提现 **请求参数** | 参数 | 位置 | 类型 | 必填 | 说明 | |---|---|---|---|---| | `withdraw_id` | 路径 | string | 是 | 提现ID | **响应** (200, `Withdraw`) | 字段 | 类型 | 说明 | |---|---|---| | `amount` | string | 金额（主单位），链上实际转出的金额 | | `amount_raw` | string | 金额（最小单位整数） | | `biz_id` | string | 商户单号 | | `block_number` | string | | | `broadcast_time` | string | 广播时间（Unix 毫秒），未广播为 0 | | `chain_code` | string | | | `confirm_time` | string | 确认时间（Unix 毫秒），未确认为 0 | | `confirmations` | integer | | | `create_time` | string | 创建时间（Unix 毫秒） | | `decimals` | integer | | | `fee` | string | 手续费（主单位），不上链 | | `from_address` | string | 出账热钱包地址：审核通过后才有；池内转账为空 | | `internal` | boolean | 是否池内转账（双方都是资金池商户，不上链、即时完成） | | `reason` | string | 失败或拒绝原因（FAILED / REJECTED 时有值） | | `status` | string | REQUESTING / PENDING / BROADCASTED / CONFIRMED / REJECTED / FAILED | | `to_address` | string | | | `token_code` | string | | | `tx_hash` | string | 链上交易哈希：签名后才有；池内转账为空 | | `user_id` | string | | | `withdraw_id` | string | | 响应示例： ```json { "amount": "12.5", "amount_raw": "12500000", "biz_id": "order-20261109-0001", "block_number": "77123456", "broadcast_time": "1762650000000", "chain_code": "TRON", "confirm_time": "1762650000000", "confirmations": 0, "create_time": "1762650000000", "decimals": 6, "fee": "", "from_address": "TJRabPrwbZy45sbavfcjinPJC18kjpRTv8", "internal": false, "reason": "AMOUNT_BELOW_MIN", "status": "REQUESTING", "to_address": "TXYZopYRdj2D9XRtbG411XZZ3kM5VkAeBf", "token_code": "USDT", "tx_hash": "3f1c0e…（交易哈希）", "user_id": "u_10001", "withdraw_id": "1987654321098753" } ``` 失败时返回统一错误体，见 [错误处理](/guide/errors)。