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

# 发起钱包所有权证明 API - Travel Rule 组件

> 通过组件会话 token 发起钱包所有权证明：支持消息签名、Satoshi 测试、截图或自我声明。Didit 支持再次选择方法以恢复该证明流程。

启动 Widget Proof API 提示词
将提示词复制到剪贴板

<pre>
  \`Start a wallet-ownership proof for a widget session. This is the call the hosted widget makes when the end user picks a proof method; use it only if I build my own widget UI.

  Endpoint:
  POST [https://verification.didit.me/v3/travel-rule/widget/\{token}/proofs/](https://verification.didit.me/v3/travel-rule/widget/\{token}/proofs/)

  Authentication:
  None - the widget token in the URL path is the credential. Treat the token as a secret.

  Body:

  * method - one of the context's allowed\_methods: MESSAGE\_SIGNING, SATOSHI\_TEST, SCREENSHOT or SELF\_DECLARATION.
  * wallet\_address, chain - optional, default to the session's.

  Behavior:

  * 201 with a new PENDING proof. MESSAGE\_SIGNING returns the challenge to sign; SATOSHI\_TEST returns deposit\_address, expected\_amount and expires\_at; SELF\_DECLARATION is verified at once.
  * 200 with the proof already open when the same method is picked again (same challenge or amount): resume it, do not treat it as an error.
  * Picking another method closes the unfinished proof as METHOD\_SWITCHED, except a submitted screenshot or a test deposit still being checked.
  * After a REJECTED proof, picking a method starts a new one (201). A session takes a limited number of rejected proofs: the context reports max\_attempts, attempts\_used and attempts\_remaining.
  * Message signing works on EVM chains (Ethereum, BNB Chain, Polygon, Arbitrum, Base, Optimism, Avalanche, Linea and others), Bitcoin (BIP-137 and BIP-322 simple), Solana and Tron.

  Failure modes (errors carry a code to translate):

  * 400 - code CHAIN\_UNSUPPORTED when the method is not available on the chain; also an invalid body or a wallet that does not match the transfer.
  * 403 - SELF\_DECLARATION not allowed for the application.
  * 409 - code OWNERSHIP\_CHANGED: mint a new session for the current holder.
  * 409 - no attempts left (no code; the body carries attempts\_remaining 0): mint a new session.
  * 404 - unknown token. 410 - the session expired.

  Full guide: /transaction-monitoring/wallet-ownership-widget#what-it-proves.\`
</pre>

粘贴到


## OpenAPI

````yaml zh/openapi-25.json POST /v3/travel-rule/widget/{token}/proofs/
openapi: 3.0.0
info:
  version: 3.0.0
  title: Didit Verification API
  description: 身份证件验证 API。使用 x-api-key 请求头进行身份验证。
servers:
  - url: https://verification.didit.me
security: []
tags: []
paths:
  /v3/travel-rule/widget/{token}/proofs/:
    post:
      tags:
        - Travel Rule
      summary: 发起钱包所有权证明
      description: >-
        基于小部件会话 token 的公开 endpoint，无需 API
        密钥：当终端用户选择证明方法时，托管小部件会调用此接口。证明仅在发生此调用后才会存在并计入您的证明转化漏斗。再次选择相同方法将返回已开启的证明（200，相同的
        challenge 或充值金额），而不会发起第二个证明；选择其他方法则会将未完成的证明关闭为
        METHOD_SWITCHED（已提交的屏幕截图或仍在检查中的测试充值除外）。MESSAGE_SIGNING 返回待签名的
        challenge；SATOSHI_TEST 返回充值地址、精确金额和时间窗口；SELF_DECLARATION 则立即可通过验证（状态为
        VERIFIED）。各链族验证的签名格式：EVM 链采用十六进制编码的 personal_sign (EIP-191) 签名；比特币采用
        Base64 编码的 BIP-137 signmessage 签名（P2PKH、P2SH-P2WPKH 和 P2WPKH 地址）或
        BIP-322 simple 签名（P2WPKH 和 P2TR 地址）；Solana 采用对 challenge 进行签名且以 Base58
        编码的 Ed25519 签名；Tron 采用十六进制编码的 signMessageV2 (TIP-191) 签名。BIP-322 full
        签名、资金证明签名或多签地址将因 SIGNATURE_UNSUPPORTED_SCHEME 而失败。
      operationId: createTravelRuleWidgetProof
      parameters:
        - name: token
          in: path
          required: true
          description: 生成 widget 会话时返回的不透明会话 token。
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TravelRuleWidgetProofCreate'
      responses:
        '200':
          description: 已恢复此前为此方式打开的证明。
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TravelRuleWidgetProofSummary'
        '201':
          description: 新的 PENDING 证明（SELF_DECLARATION 为 VERIFIED）。
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TravelRuleWidgetProofSummary'
        '400':
          description: >-
            无效的请求体、钱包与转账不匹配、不允许 SCREENSHOT，或者当该方法在对应链上不可用时返回代码
            CHAIN_UNSUPPORTED。
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TravelRuleWidgetProofError'
        '403':
          description: 此应用不允许 SELF_DECLARATION。
        '404':
          description: 未知的 token。
        '409':
          description: >-
            代码 OWNERSHIP_CHANGED：生成会话后钱包的持有者发生变更，或钱包已被删除；请为当前持有者生成新会话。当会话缺少
            satoshi_deposit_address 时针对 SATOSHI_TEST
            也会返回此代码；当会话没有剩余尝试次数时也会返回此响应（不含代码；响应体包含 max_attempts、attempts_used
            以及值为 0 的 attempts_remaining）：请生成新会话。
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TravelRuleWidgetProofError'
        '410':
          description: 会话已过期。
      security:
        - {}
      x-codeSamples:
        - lang: curl
          label: curl
          source: >-
            curl -X POST
            https://verification.didit.me/v3/travel-rule/widget/{token}/proofs/
            \
              -H 'Content-Type: application/json' \
              -d '{"method": "MESSAGE_SIGNING"}'
components:
  schemas:
    TravelRuleWidgetProofCreate:
      type: object
      required:
        - method
      properties:
        method:
          type: string
          enum:
            - MESSAGE_SIGNING
            - SATOSHI_TEST
            - SCREENSHOT
            - SELF_DECLARATION
          description: 终端用户选择的证明方式。必须是上下文 allowed_methods 中的一种。
        wallet_address:
          type: string
          maxLength: 128
          description: 默认为会话的 wallet_address。当会话关联到转账时，必须与转账的钱包匹配。
        chain:
          type: string
          maxLength: 32
          description: 默认为会话所属的链。
    TravelRuleWidgetProofSummary:
      type: object
      properties:
        proof_id:
          type: string
          format: uuid
        method:
          type: string
          enum:
            - MESSAGE_SIGNING
            - SATOSHI_TEST
            - SCREENSHOT
            - SELF_DECLARATION
        status:
          type: string
          enum:
            - PENDING
            - VERIFIED
            - REJECTED
            - EXPIRED
          description: >-
            PENDING：终端用户选择了此方式，证明尚未作出决策。签名失败或测试充值尚无法读取或确认会使证明保持 PENDING 状态并附带
            failure_reason，以便终端用户重试；提交的 SATOSHI_TEST 充值会在其窗口关闭前自动重新检查，提交的
            SCREENSHOT
            等待您的审核。VERIFIED：所有权已证明。REJECTED：测试充值确实有误（发送方不符、转入充值地址的金额不符、早于挑战，或该交易已用于证明另一个钱包）或您的审核员拒绝了屏幕截图；failure_reason
            会说明具体原因。被拒绝的证明为最终状态，并会消耗会话的一次尝试次数。EXPIRED：证明无法再作出决策（其窗口已关闭、终端用户切换了验证方式、小部件会话已失效，或钱包持有者已更改）；failure_reason
            会说明具体原因。
        wallet_address:
          type: string
        chain:
          type: string
          description: 该证明所属地址簿条目的规范链标识符，例如 ETH、BTC、SOL、TRX。
        deposit_address:
          type: string
          nullable: true
          description: 客户必须向其发送 Satoshi 测试金额的充值地址。仅存在于 SATOSHI_TEST 证明中。
        expected_amount:
          type: string
          nullable: true
          description: Satoshi 测试充值必须匹配的链上确切金额，以充值的原生货币计。仅在 SATOSHI_TEST 证明中存在。
        expires_at:
          type: string
          format: date-time
          nullable: true
          description: >-
            该证明自身的聪测试（Satoshi test）窗口截止时间。仅在 SATOSHI_TEST 证明上提供；当提供 SATOSHI_TEST
            时，挂件会话自身的 expires_at 会被延长以涵盖该窗口。
        challenge:
          type: string
          nullable: true
          description: Didit 签发并由客户使用其钱包签名的消息。仅存在于 MESSAGE_SIGNING 证明中。
        rejection_reason:
          type: string
          description: >-
            证明被拒绝的原因，作为面向终端用户的英文句子。仅当 `status` 为 REJECTED
            时存在；当您的审核员拒绝屏幕截图时为空（您的备注保留在您方）。
        created_at:
          type: string
          format: date-time
        attempts:
          type: integer
          description: 为此证明提交凭据的次数（签名、交易 ID、上传文件）。
        failure_reason:
          allOf:
            - $ref: '#/components/schemas/TravelRuleWalletProofFailureReason'
          description: 上次尝试未达标的原因，或证明关闭的原因。未发生失败时为空。
    TravelRuleWidgetProofError:
      type: object
      properties:
        detail:
          type: string
          description: 便于人类阅读的英文消息。
        code:
          allOf:
            - $ref: '#/components/schemas/TravelRuleWalletProofFailureReason'
          description: 机器可读的原因，以便客户端展示其自有的翻译消息。
        status:
          type: string
          enum:
            - PENDING
            - VERIFIED
            - REJECTED
            - EXPIRED
          description: >-
            在证明已关闭时存在：因刚提交的充值而变为 REJECTED（400），或在向已关闭的证明发送证据时为 REJECTED 或
            EXPIRED（409）。
        proof_id:
          type: string
          format: uuid
          description: 与状态一起提供：已关闭的证明。
        method:
          type: string
          enum:
            - MESSAGE_SIGNING
            - SATOSHI_TEST
            - SCREENSHOT
            - SELF_DECLARATION
          description: 与状态一起提供：已关闭证明的方式。
        max_attempts:
          type: integer
          description: 随状态存在：该会话允许的被拒绝钱包证明。
        attempts_used:
          type: integer
          description: 与状态一起提供：截至目前被拒绝的证明。
        attempts_remaining:
          type: integer
          description: 与状态一起提供：当其值为 0 时，启动另一个证明将返回 409，您需要生成新的小部件会话。
    TravelRuleWalletProofFailureReason:
      type: string
      enum:
        - ''
        - SIGNATURE_INVALID
        - SIGNATURE_UNSUPPORTED_SCHEME
        - DEPOSIT_NOT_FOUND
        - DEPOSIT_UNCONFIRMED
        - DEPOSIT_LOOKUP_FAILED
        - DEPOSIT_MISMATCH
        - DEPOSIT_STALE
        - TXID_REUSED
        - CHAIN_UNSUPPORTED
        - WINDOW_EXPIRED
        - OWNERSHIP_CHANGED
        - METHOD_SWITCHED
        - REVIEW_REJECTED
        - ABANDONED
      description: >-
        钱包所有权证明（或其最近一次尝试）未能达到 VERIFIED 的原因。未出现失败时为空。处于 PENDING
        状态的证明可能会包含此项：最近一次尝试失败，终端用户可以重试。DEPOSIT_MISMATCH、DEPOSIT_STALE、TXID_REUSED
        和 REVIEW_REJECTED 会将证明关闭为
        REJECTED。SIGNATURE_INVALID：签名与钱包和挑战值不匹配。SIGNATURE_UNSUPPORTED_SCHEME：钱包签名的格式
        Didit
        无法验证。DEPOSIT_NOT_FOUND、DEPOSIT_UNCONFIRMED、DEPOSIT_LOOKUP_FAILED：测试存款不可读取或尚未确认；Didit
        会持续检查，直至测试窗口关闭。DEPOSIT_MISMATCH：交易未从该钱包向存款地址发送预期金额。DEPOSIT_STALE：交易早于挑战值发生。TXID_REUSED：该交易已用于证明另一个钱包。CHAIN_UNSUPPORTED：该方法在此链上不可用。WINDOW_EXPIRED：测试窗口已关闭。OWNERSHIP_CHANGED：在小组件会话生成后，钱包持有者发生变更，或钱包已从您的地址簿中删除。METHOD_SWITCHED：终端用户在完成该方法之前选择了另一种方法。REVIEW_REJECTED：您的审核员拒绝了该截图。ABANDONED：小组件会话在终端用户完成之前已失效。

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.