> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cbpayapp.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 创建链上提现

> 从其自身余额链上发送 USDT、USDC 或 BTC。支持的组合:`tron`/`USDT`、`eth`/`USDT`、`eth`/`USDC`、`btc`/`BTC`(GOLD 无链上通道)。`amount + 提现费` 原子扣除并冻结;最终状态通过 `crypto_withdrawal_status_changed` webhook 送达。`failed` 会全额退款。



## OpenAPI

````yaml /openapi.zh.yaml post /v1/crypto/withdrawals
openapi: 3.1.0
info:
  title: CBPay API
  version: '1.89'
  description: >
    CBPay 是一个多币种支付平台:覆盖拉美的法币付款(payout)与收款(payin)、内部转账、链上充值与提现,以及 KYC
    筛查。每个账户持有四个相互独立的虚拟余额——USDT(运营货币)、USDC、BTC 和 GOLD(纯金克数)——它们绝不混合也不会自动兑换。

    payout 和服务费可从四个余额中的任意一个支付:

    用 `PUT /v1/settlement` 设置默认值,或在单笔 payout 中用

    `settlement_asset` 覆盖。


    所有金额均为十进制字符串,遵循各货币的精度(USDT/USDC/GOLD 为 6 位小数,BTC 为 8 位)。错误始终返回

    `{"error": "<code>", "message": "<detail>"}`。
servers:
  - url: https://api.qbank.cl/platform
    description: Live（生产环境，真实资金）
  - url: https://cryptobank.qbank.cl/platform
    description: Test（沙盒，模拟资金 — pk_test_ 密钥）
security:
  - bearerAuth: []
tags:
  - name: 凭证
    description: >-
      每笔操作的品牌化 PDF 凭证,附带公开的签名 QR 真伪校验、每个响应/webhook 中的
      receipt_url,以及最终状态时的自动邮件发送。
  - name: 身份认证
    description: 注册与登录账户成员。会话有效期 24 小时。
  - name: 账户
    description: 调用账户的档案、成员与 API key。
  - name: 余额
    description: 余额、流水历史与外汇汇率。
  - name: 付款(Payouts)
    description: 从你选择的结算余额扣款的法币派发(默认 USDT)。
  - name: 收款(Payins)
    description: 入账到 USDT 余额的法币充值。
  - name: 转账
  - name: 联系人
  - name: 兑换(Swaps)
    description: CBPay 账户之间的免费内部转账(个人或企业,任意组合)。
  - name: 加密货币
    description: 链上充值与提现(TRON、Ethereum 和 Bitcoin)。
  - name: 隔离钱包
    description: 拥有自身余额的链上钱包(企业不限数量;个人每个网络+资产组合 1 个)——创建、导入、发送、导出私钥与自动转发。余额存在于链上,从不进入账本。
  - name: QR Crypto POS
    description: >-
      面向拥有实体 POS 终端的处理商（企业账户）的定额加密货币二维码收款：已验证商户、每笔收款专属地址 +
      二维码、支付早期检测、按商户对账，以及经加密货币提现通道的退款。
  - name: KYC / KYB
  - name: AML 筛查
    description: 身份验证:个人 KYC、企业 KYB,含 AML 筛查、重新筛查与持续监控。
  - name: 钱包筛查
    description: 区块链地址的 AML 风险评估(制裁、非法资金暴露),按次收费;另附提现与充值的免费自动防护。
  - name: 分析
  - name: Webhooks
    description: 接收签名事件通知的订阅。
  - name: 状态
    description: 服务可用性。
  - name: 银行服务
    description: 真实银行账户:通过国际银行通道接收、持有与发送资金。
  - name: 卡片
    description: 以 Just-In-Time 方式从账户 USDT 余额消费的虚拟卡与实体卡,支持按卡设置消费限额。
  - name: 安全(OTP)
    description: >-
      通过 SMS/WhatsApp/email 发送的一次性验证码,保护敏感操作;并提供自助 2FA 偏好设置。仅适用于用户会话——API key
      豁免。
  - name: 通行密钥
    description: >-
      通过 WebAuthn 使用设备生物识别(Face ID、Touch ID、Windows
      Hello、安全密钥)的无密码登录、带备份码的验证器应用(TOTP),以及会话/设备管理。
  - name: 社交登录
    description: >-
      通过令牌交换以 Google、Apple、Microsoft 和 Facebook 实现无密码注册与登录。前端获取提供方凭证;API 验证后签发
      CBPay 会话。
paths:
  /v1/crypto/withdrawals:
    post:
      tags:
        - 加密货币
      summary: 创建链上提现
      description: >-
        从其自身余额链上发送 USDT、USDC 或
        BTC。支持的组合:`tron`/`USDT`、`eth`/`USDT`、`eth`/`USDC`、`btc`/`BTC`(GOLD
        无链上通道)。`amount + 提现费` 原子扣除并冻结;最终状态通过 `crypto_withdrawal_status_changed`
        webhook 送达。`failed` 会全额退款。
      operationId: createCryptoWithdrawal
      parameters:
        - $ref: '#/components/parameters/idempotencyKeyHeader'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - amount
              properties:
                chain:
                  type: string
                  enum:
                    - tron
                    - eth
                    - btc
                  default: tron
                asset:
                  type: string
                  enum:
                    - USDT
                    - USDC
                    - BTC
                  default: USDT
                  description: 要发送的资产(USDC 仅支持 `eth`;在 `btc` 上资产默认为 `BTC`)。
                to_address:
                  type: string
                to_contact_id:
                  type: string
                  format: uuid
                  description: 使用联系人为该链保存的地址代替 `to_address`(显式 `to_address` 始终优先)。
                amount:
                  type: string
                  description: 正数十进制字符串,最多 6 位小数(BTC 为 8 位)。
                idempotency_key:
                  type: string
                contact_name:
                  type: string
                  description: 为保存此地址的自动联系人指定名称。
                save_contact:
                  type: boolean
                  default: true
                  description: 地址会自动保存为联系人;传 false 可跳过。
                travel_address:
                  type: string
                  description: >-
                    Travel Rule(FATF R.16)— 超过组织阈值且转往其他机构时,收款机构的 travel
                    address(`ta…` 代码)。付款地址由收款机构提供,因此可省略 `to_address`。
                wallet_type:
                  type: string
                  enum:
                    - self_hosted
                  description: >-
                    Travel Rule — 目的地为账户持有人自己的钱包时声明 `self_hosted`(需要
                    `beneficiary_name`)。
                beneficiary_name:
                  type: string
                  description: >-
                    Travel Rule — 目的持有人的姓名。超过阈值时必填(配合 `travel_address` 或
                    `wallet_type=self_hosted`)。
            examples:
              usdt_tron:
                summary: TRON 上的 USDT
                value:
                  chain: tron
                  to_address: TVJ6njG5Fyrq6XwYok3xPQx8kR7HQx6vXk
                  amount: '100.000000'
                  idempotency_key: withdrawal-2026-07-07-a
              usdc_eth:
                summary: Ethereum 上的 USDC
                value:
                  chain: eth
                  asset: USDC
                  to_address: '0x8f3Ba1c2De4567890aBcDeF1234567890aBcDeF1'
                  amount: '50.000000'
                  idempotency_key: withdrawal-usdc-2026-07-09-a
              btc_bitcoin:
                summary: Bitcoin 上的 BTC
                value:
                  chain: btc
                  to_address: bc1qw508d6qejxtdg4y5r3zarvary0c5xw7kv8f3t4
                  amount: '0.00050000'
                  idempotency_key: withdrawal-btc-2026-07-15-a
              travel_rule_self_hosted:
                summary: 超过 Travel Rule 阈值,转往自托管钱包
                value:
                  chain: tron
                  to_address: TVJ6njG5Fyrq6XwYok3xPQx8kR7HQx6vXk
                  amount: '1500.000000'
                  wallet_type: self_hosted
                  beneficiary_name: Maria Perez
                  idempotency_key: withdrawal-2026-07-12-a
              travel_rule_vasp:
                summary: 超过阈值,转往其他机构(travel address)
                value:
                  chain: tron
                  amount: '1500.000000'
                  travel_address: ta2AQSjBotWQf38c8sxYYK2KfisPoMsTPiYkviErEcoSn1uK
                  beneficiary_name: Maria Perez
                  idempotency_key: withdrawal-2026-07-12-b
      responses:
        '200':
          description: 幂等重放。
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CryptoWithdrawal'
              example:
                withdrawal_id: 6c5d4e3f-2a1b-0c9d-8e7f-6a5b4c3d2e1f
                account_id: 9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d
                idempotency_key: withdrawal-2026-07-07-a
                chain: tron
                asset: USDT
                to_address: TVJ6njG5Fyrq6XwYok3xPQx8kR7HQx6vXk
                amount: '100.000000'
                fee: '1.000000'
                total_debit: '101.000000'
                status: processing
                status_code: ''
                status_message: broadcasted
                tx_id: >-
                  b1946ac92492d2347c6235b4d2611184e0f0f8c9d3a1e2b3c4d5e6f708192a3b
                created_at: '2026-07-07T12:00:00Z'
                updated_at: '2026-07-07T12:00:00Z'
                idempotency_hit: true
        '202':
          description: 提现已受理并广播中。
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CryptoWithdrawal'
              example:
                withdrawal_id: 6c5d4e3f-2a1b-0c9d-8e7f-6a5b4c3d2e1f
                account_id: 9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d
                idempotency_key: withdrawal-2026-07-07-a
                chain: tron
                asset: USDT
                to_address: TVJ6njG5Fyrq6XwYok3xPQx8kR7HQx6vXk
                amount: '100.000000'
                fee: '1.000000'
                total_debit: '101.000000'
                status: processing
                status_code: ''
                status_message: broadcasted
                tx_id: >-
                  b1946ac92492d2347c6235b4d2611184e0f0f8c9d3a1e2b3c4d5e6f708192a3b
                created_at: '2026-07-07T12:00:00Z'
                updated_at: '2026-07-07T12:00:00Z'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/InsufficientFunds'
        '422':
          description: 核心拒绝了该提现;扣款已退回。
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CryptoWithdrawal'
              example:
                withdrawal_id: 6c5d4e3f-2a1b-0c9d-8e7f-6a5b4c3d2e1f
                account_id: 9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d
                idempotency_key: withdrawal-2026-07-07-a
                chain: tron
                asset: USDT
                to_address: TVJ6njG5Fyrq6XwYok3xPQx8kR7HQx6vXk
                amount: '100.000000'
                fee: '1.000000'
                total_debit: '101.000000'
                status: failed
                status_code: core_rejected
                status_message: destination address is invalid
                tx_id: ''
                created_at: '2026-07-07T12:00:00Z'
                updated_at: '2026-07-07T12:00:00Z'
        '503':
          description: 此通道未启用提现(`withdrawals_unavailable`)。
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: withdrawals_unavailable
                message: on-chain withdrawals are not enabled for this corridor yet
components:
  parameters:
    idempotencyKeyHeader:
      name: Idempotency-Key
      in: header
      required: false
      description: '`idempotency_key` 请求体字段的替代方式。'
      schema:
        type: string
  schemas:
    CryptoWithdrawal:
      type: object
      properties:
        withdrawal_id:
          type: string
          format: uuid
        account_id:
          type: string
          format: uuid
        idempotency_key:
          type: string
        chain:
          type: string
          enum:
            - tron
            - eth
            - btc
        asset:
          type: string
          example: USDT
        to_address:
          type: string
        amount:
          type: string
        fee:
          type: string
        total_debit:
          type: string
        status:
          type: string
          enum:
            - pending
            - processing
            - completed
            - failed
        status_code:
          type: string
        status_message:
          type: string
        tx_id:
          type: string
        travel_rule_status:
          type: string
          enum:
            - not_required
            - self_hosted_attested
            - approved
          description: 提现按 Travel Rule(FATF R.16)政策评估时返回。
        beneficiary_name:
          type: string
          description: 声明的受益人姓名(Travel Rule 提现)。
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        idempotency_hit:
          type: boolean
    Error:
      type: object
      properties:
        error:
          type: string
          description: 机器可读的错误代码(snake_case)。
          example: insufficient_funds
        message:
          type: string
          description: 人类可读的说明。
  responses:
    BadRequest:
      description: 请求无效(具体校验见 `error` 代码)。
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: invalid_json
            message: 'request body is not valid JSON: unknown field'
    Unauthorized:
      description: 凭证缺失或无效(`unauthorized`)。
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: unauthorized
            message: invalid or missing credentials
    InsufficientFunds:
      description: 账户余额不足以完成此操作(`insufficient_funds`)。
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: insufficient_funds
            message: account balance is not enough for this operation
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: |
        会话 JWT(来自注册/登录)或 API key(`pk_...`)。
        也接受 `X-API-Key: <token>` 作为替代请求头。

````