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

> Didit 提供的接口，通过 token 读取钱包所有权小组件会话的公开上下文信息，包括允许的证明方式、证明进度和完成状态。

获取 Widget 上下文 API 提示词
将提示词复制到剪贴板

<pre>
  \`Read the public context of a wallet-ownership widget session - the same endpoint the hosted widget page itself is driven by. Poll it to track proof progress from your backend.

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

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

  What to read from the response:

  * completed\_at - non-null once a proof has been verified. This is the completion signal.
  * allowed\_methods - which proof methods this session offers (MESSAGE\_SIGNING, SATOSHI\_TEST, SCREENSHOT, SELF\_DECLARATION).
    MESSAGE\_SIGNING works with wallets installed in the customer's browser, discovered in the page (EIP-6963 / Wallet Standard).
    Pairing a mobile wallet app (for example by scanning a QR code) is not available in production today.
  * transfer\_status - the linked Travel Rule transfer's status, when the session was minted with a transaction\_id.
  * proofs\[] - per-proof progress. A SATOSHI\_TEST proof carries deposit\_address, expected\_amount, and its own expires\_at; a MESSAGE\_SIGNING proof carries the challenge string. A SATOSHI\_TEST proof can sit at status PENDING while its deposit is seen on-chain but unconfirmed - a background job completes it automatically once it confirms. Each proof also carries attempts and failure\_reason (why the last attempt fell short, or why the proof closed; empty when nothing failed). A REJECTED proof carries rejection\_reason, an English sentence for the end user.
  * max\_attempts, attempts\_used, attempts\_remaining - how many rejected proofs this session allows, has had and has left. When attempts\_remaining is 0, starting another proof answers 409: mint a new session.
  * chain\_family - EVM, BTC, SOL or TRON: the key family behind chain, so a client picks the right wallet. One EVM key holds the same address on every EVM chain.
  * wallet\_address, chain (as minted, for example "ETH"), holder\_name, vasp\_name, callback\_url, expires\_at.

  Failure modes:

  * 404 - unknown token.
  * 410 - the session expired without completing.

  Prefer travel\_rule.status.updated webhooks over polling when the session is linked to a transfer.

  Full guide: /transaction-monitoring/wallet-ownership-widget#detect-completion.\`
</pre>

粘贴到


## OpenAPI

````yaml zh/openapi-25.json GET /v3/travel-rule/widget/{token}/
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}/:
    get:
      tags:
        - Travel Rule
      summary: 获取钱包所有权小组件上下文
      description: >-
        基于小部件会话 token 的公开读取 endpoint，无需 API
        密钥。返回小部件上下文以及每项证明的状态，以便您通过轮询来检测完成情况；证明通过验证后，completed_at
        将变为非空值。当在链上检测到充值但尚未确认时，SATOSHI_TEST 证明可能处于 PENDING
        状态：后台任务会自动重新检查，并在充值确认后将其完成，因此在等待期间无需客户端执行任何操作。每项证明都包含其方法所需的字段：SATOSHI_TEST
        包含 deposit_address、expected_amount 及其自身的 expires_at；MESSAGE_SIGNING 包含
        challenge。当会话关联至转账时，建议优先使用 travel_rule.status.updated Webhook 而非轮询。
      operationId: getTravelRuleWidgetContext
      parameters:
        - name: token
          in: path
          required: true
          description: 生成 widget 会话时返回的不透明会话 token。
          schema:
            type: string
      responses:
        '200':
          description: 小组件上下文和证明状态。
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TravelRuleWidgetContext'
        '404':
          description: 未知的 token。
        '410':
          description: 会话已过期且未完成。
      security:
        - {}
      x-codeSamples:
        - lang: curl
          label: curl
          source: curl https://verification.didit.me/v3/travel-rule/widget/{token}/
components:
  schemas:
    TravelRuleWidgetContext:
      type: object
      properties:
        vasp_name:
          type: string
          description: 来自您 VASP 资料的法定名称，会在小部件中向客户展示。不存在资料时为空。
        wallet_address:
          type: string
        chain:
          type: string
          description: 铸造会话所用的链，与您发送的一致。
        chain_family:
          type: string
          nullable: true
          enum:
            - EVM
            - BTC
            - SOL
            - TRON
            - null
          description: >-
            链背后的密钥族：EVM（Ethereum、BNB
            Chain、Polygon、Arbitrum、Base、Optimism、Avalanche、Linea 及其他 EVM
            链）、BTC、SOL 或 TRON。一个 EVM 密钥控制每条 EVM 链上的同一地址。当无法在链上验证签名时为 Null。
        holder_name:
          type: string
        allowed_methods:
          type: array
          items:
            type: string
            enum:
              - MESSAGE_SIGNING
              - SCREENSHOT
              - SATOSHI_TEST
              - SELF_DECLARATION
          description: >-
            此会话可用的证明方式。MESSAGE_SIGNING 需要包含 chain_family 的链，SATOSHI_TEST 需要会话上存在
            satoshi_deposit_address 且链的充值记录 Didit 可回读，SCREENSHOT 需要开启
            allow_screenshot_proof 设置，SELF_DECLARATION 需要开启
            allow_self_declaration 设置。
        transfer_status:
          type: string
          nullable: true
          description: 关联的 Travel Rule 转账的状态。会话创建时未包含 transaction_id 则为 Null。
        callback_url:
          type: string
          description: 组件完成后将客户返回到的位置。未设置时为空。
        expires_at:
          type: string
          format: date-time
        completed_at:
          type: string
          format: date-time
          nullable: true
          description: 证明核验后为非空。
        proofs:
          type: array
          items:
            $ref: '#/components/schemas/TravelRuleWidgetProofSummary'
        max_attempts:
          type: integer
          description: 本次会话允许的已拒绝钱包证明。
        attempts_used:
          type: integer
          description: 截至目前已拒绝的证明。
        attempts_remaining:
          type: integer
          description: 为 0 时，启动另一个验证会返回 409，您需要生成一个新的小部件会话。
        customization:
          type: object
          nullable: true
          description: 启用白标时该应用的白标定制信息（颜色、Logo、字体系列），组件将以与验证工作流相同的品牌标识进行渲染。否则为 null。
    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: 上次尝试未达标的原因，或证明关闭的原因。未发生失败时为空。
    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.