> ## 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.

# 验证挑战签名并链接钱包

> 验证 nonce 挑战的签名并将外部钱包链接到账户。钱包保持
 `custody=client`:客户保留密钥,可在外部消费;链接仅证明地址的所有权。

 特定错误:`invalid_payload`、`invalid_signature`、
 `signature_mismatch`、`verification_failed`、`challenge_consumed`、
 `challenge_expired`、`proof_not_signable`。



## OpenAPI

````yaml /openapi.zh.yaml post /v1/wallet-links/verify
openapi: 3.1.0
info:
  title: CBPay API
  version: '2.62'
  description: >
    CBPay 是一个多币种支付平台:覆盖拉美的法币付款(payout)与收款(payin)、内部转账、链上充值与提现,以及 KYC
    筛查。每个账户持有四个相互独立的虚拟余额——USDT(运营货币)、USDC、BTC 和 GOLD(纯金克数)——可通过兑换(swap)按需转换。

    payout 和服务费可从四个余额中的任意一个支付(用 `PUT /v1/settlement`

    设置默认值,或在单笔 payout 中用 `settlement_asset` 覆盖);payin

    可自动兑换为你选择的资产(`default_payin_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: 法币充值(二维码、转账、专属账户、pull 收款、卡片、checkout 链接)自动入账——默认入账 USDT,也可自动兑换为你选择的结算资产。
  - name: 收银台(Checkout)
    description: >-
      通用收银台链接(`POST /v1/payins`,`method:
      "checkout"`)与公开支付页端点——多国法币、每个链接专属临时钱包的加密货币支付,以及 CBPay 直接支付,按你选择的资产结算。
  - name: 已保存卡片(Stored cards)
    description: 在 3-D Secure 支付中经付款人明确同意保存的卡片(COF)。可列出、吊销并按需扣款(MIT),无需再次索要卡片信息。
  - name: 订阅(Subscriptions)
    description: 由平台调度器管理的已保存卡片周期性扣款——按日、周、月或年,支持暂停/恢复/取消与自动催收。
  - name: 转账
    description: CBPay 账户之间的免费内部转账(个人或企业,任意组合)。
  - name: 联系人
    description: 按账户维护的收款人通讯录(CBPay、银行与加密货币目的地),支持手机号匹配与每次发送时自动保存。
  - name: 兑换(Swaps)
    description: 按账户报价即时兑换账户的 USDT、USDC、BTC 与 GOLD 余额。
  - name: 加密货币
    description: 链上充值与提现(TRON、Ethereum 和 Bitcoin)。
  - name: 隔离钱包
    description: 拥有自身余额的链上钱包(企业不限数量;个人每个网络+资产组合 1 个)——创建、导入、发送、导出私钥与自动转发。余额存在于链上,从不进入账本。
  - name: 签名证明
    description: 使用钱包进行加密消息签名(EIP-191 ETH/EVM、TIP-191 TRON)——创建、列出、查询和吊销具有公开验证功能的签名证明。
  - name: 钱包链接
    description: 通过签名 nonce 挑战将外部钱包(custody=client)链接到你的账户——创建挑战、验证签名、列出和吊销链接。
  - name: QR Crypto POS
    description: >-
      面向拥有实体 POS 终端的处理商（企业账户）的定额加密货币二维码收款：已验证商户、每笔收款专属地址 +
      二维码、支付早期检测、按商户对账，以及经加密货币提现通道的退款。
  - name: KYC / KYB
    description: 身份验证:个人 KYC、企业 KYB——你自己的入驻验证,以及企业账户的第三方验证。
  - name: AML 筛查
    description: 针对个人与企业的独立 AML 筛查(制裁、PEP 与负面媒体名单),含重新筛查、持续监控与可下载的 PDF 报告。
  - name: 钱包筛查
    description: 区块链地址的 AML 风险评估(制裁、非法资金暴露),按次收费;另附提现与充值的免费自动防护。
  - name: Qscore
    description: >-
      API 优先的信用局。签发完整的信用报告，评分为 1-999（A-E 等级，无数据时为 SC），查询主体的最新评分，并管理 ARCO
      争议。智利先行，设计上与国家无关。每份签发的报告都带有公开验证码。
  - name: 分析
  - name: Webhooks
    description: 接收签名事件通知的订阅。
  - name: 状态
    description: 服务可用性。
  - name: 银行服务
    description: 真实银行账户:通过国际银行通道接收、持有与发送资金。
  - name: 卡片
    description: 以 Just-In-Time 方式从你选择的余额(USDT、USDC、BTC 或 GOLD)消费的虚拟卡与实体卡,支持按卡设置消费限额。
  - 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 会话。
  - name: 实时事件
    description: >-
      Server-Sent Events 流，实时推送账户内（管理员则为整个组织）发生的所有事件，支持通过 `Last-Event-ID`
      重放、可选的初始快照，以及 90 天可查询历史。
paths:
  /v1/wallet-links/verify:
    post:
      tags:
        - 钱包链接
      summary: 验证挑战签名并链接钱包
      description: |-
        验证 nonce 挑战的签名并将外部钱包链接到账户。钱包保持
         `custody=client`:客户保留密钥,可在外部消费;链接仅证明地址的所有权。

         特定错误:`invalid_payload`、`invalid_signature`、
         `signature_mismatch`、`verification_failed`、`challenge_consumed`、
         `challenge_expired`、`proof_not_signable`。
      operationId: verifyWalletLink
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - nonce
                - signature
              properties:
                nonce:
                  type: string
                  description: 挑战的 nonce(来自 `POST /v1/wallet-links/challenges`)。
                signature:
                  type: string
                  description: 封装的签名(EIP-191 / TIP-191)。
            example:
              nonce: 9f2c41d2a887f3e4b219c6d2e8f1a5b7
              signature: >-
                8ba1f109551bd432803012645ac136ddd64dba72a0c9e0b1f5b1a2c3d4e5f60718293a4b5c6d7e8f90112233445566778899aabbccddeeff00112233445566771b
      responses:
        '200':
          description: 钱包已链接。
          content:
            application/json:
              schema:
                type: object
                properties:
                  link:
                    $ref: '#/components/schemas/WalletLink'
                  proof:
                    $ref: '#/components/schemas/SignatureProof'
              example:
                link:
                  link_id: d52e7b91-4c68-4f89-1b23-5d7e9f0a2c46
                  account_id: ae8c1f02-3b45-4c67-9d12-8f0e5a6b7c8d
                  chain: eth
                  address: '0x71C7656EC7ab88b098defB751B7401B5f6d8976F'
                  status: linked
                  expires_at: '2026-08-21T14:13:11Z'
                  created_at: '2026-08-21T14:03:11Z'
                  proof_id: c41d2a88-7f3e-4b21-9c6d-2e8f1a5b7d90
                  verified_at: '2026-08-21T14:05:41Z'
                proof:
                  proof_id: c41d2a88-7f3e-4b21-9c6d-2e8f1a5b7d90
                  account_id: ae8c1f02-3b45-4c67-9d12-8f0e5a6b7c8d
                  chain: eth
                  address: '0x71C7656EC7ab88b098defB751B7401B5f6d8976F'
                  purpose: wallet_link
                  envelope: |-
                    CBPay Signature Proof
                    Domain: https://api.qbank.cl/platform
                    Purpose: wallet_link
                    Wallet: 0x71C7656EC7ab88b098defB751B7401B5f6d8976F
                    Account: ae8c1f02-3b45-4c67-9d12-8f0e5a6b7c8d
                    Nonce: 9f2c41d2a887f3e4b219c6d2e8f1a5b7
                    Issued: 2026-08-21T14:03:11Z
                    Expires: 2026-08-21T14:13:11Z
                  nonce: 9f2c41d2a887f3e4b219c6d2e8f1a5b7
                  signature: >-
                    8ba1f109551bd432803012645ac136ddd64dba72a0c9e0b1f5b1a2c3d4e5f60718293a4b5c6d7e8f90112233445566778899aabbccddeeff00112233445566771b
                  message_hash: >-
                    5c35a1c2e9f84d1b7a06e3f2d49871c5b6a0e4d38f71c2b5963a84d0e1f2c3b4
                  proof_code: Gc41d2a887f3e4b219c6d2e8f1a5b7d90a1b2c3d4e5f60718293a
                  status: signed
                  issued_at: '2026-08-21T14:03:11Z'
                  expires_at: '2026-08-21T14:13:11Z'
                  signed_at: '2026-08-21T14:05:41Z'
                  created_at: '2026-08-21T14:03:11Z'
                  verify_url: >-
                    https://api.qbank.cl/platform/v1/public/signature-proofs/Gc41d2a887f3e4b219c6d2e8f1a5b7d90a1b2c3d4e5f60718293a
        '400':
          description: 无效负载(`invalid_payload`、`invalid_signature`、`verification_failed`)。
        '404':
          description: 挑战 nonce 未知或不属于该账户(`not_found`)。
        '409':
          description: 挑战已被使用或证明无法持久化(`challenge_consumed`、`proof_not_signable`)。
        '410':
          description: 挑战已过期(`challenge_expired`)。
        '422':
          description: 签名与挑战地址不匹配(`signature_mismatch`)。
components:
  schemas:
    WalletLink:
      type: object
      description: >-
        通过签署 nonce 挑战关联到账户的外部钱包（custody=client）。挑战在签发后 10
        分钟过期；一旦钱包完成关联，链接将保持有效，直到被撤销。
      properties:
        link_id:
          type: string
          format: uuid
        account_id:
          type: string
          format: uuid
        chain:
          type: string
          enum:
            - eth
            - tron
        address:
          type: string
        status:
          type: string
          enum:
            - pending
            - linked
            - revoked
            - expired
        expires_at:
          type: string
          format: date-time
          description: 挑战过期时间（创建后 10 分钟）。
        proof_id:
          type: string
          format: uuid
          description: 验证时创建的签名证明（关联后存在）。
        verified_at:
          type: string
          format: date-time
        revoked_at:
          type: string
          format: date-time
        created_at:
          type: string
          format: date-time
    SignatureProof:
      type: object
      description: >-
        钱包对结构化 CBPay 消息(EIP-191 ETH/EVM、TIP-191 TRON)签名的加密证明。可通过 verify_url
        公开验证。
      properties:
        proof_id:
          type: string
          format: uuid
        wallet_id:
          type: string
          format: uuid
        account_id:
          type: string
          format: uuid
        chain:
          type: string
          enum:
            - eth
            - tron
        address:
          type: string
          description: 产生签名的链上地址。
        purpose:
          type: string
          enum:
            - ownership
            - statement
            - attestation
        envelope:
          type: string
          example: CBPay Signature Proof
        nonce:
          type: string
        proof_code:
          type: string
          description: 简短的公开验证码(以 G 开头)。
          example: G7F3A9C1E2B4
        status:
          type: string
          enum:
            - pending
            - signed
            - rejected
            - expired
            - revoked
        signature:
          type: string
        message_hash:
          type: string
        issued_at:
          type: string
          format: date-time
        expires_at:
          type: string
          format: date-time
        signed_at:
          type: string
          format: date-time
        revoked_at:
          type: string
          format: date-time
        created_at:
          type: string
          format: date-time
        verify_url:
          type: string
          example: >-
            https://api.qbank.cl/platform/v1/public/signature-proofs/Gc41d2a887f3e4b219c6d2e8f1a5b7d90a1b2c3d4e5f60718293a
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: |
        会话 JWT(来自注册/登录)或 API key(`pk_...`)。
        也接受 `X-API-Key: <token>` 作为替代请求头。

````