> ## 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에서 위젯 세션을 생성해 고객이 메시지 서명, Satoshi test, 스크린샷 또는 자기 선언으로 암호화폐 지갑 통제권을 증명하도록 합니다.



Mint 지갑 소유권 위젯 세션 API 프롬프트
        프롬프트를 클립보드에 복사



      
      

\<pre>

\`Mint a hosted wallet-ownership widget session so a customer can prove control of a crypto wallet - to advance a Travel Rule transfer out of UNCONFIRMED_OWNERSHIP, or to pre-verify a wallet before any transfer exists.

Endpoint:
POST https://verification.didit.me/v3/travel-rule/widget-session/

Authentication:
Use the x-api-key header with my Didit API key.

You rarely need this call: with auto_wallet_verification on (the default), Didit auto-mints a widget session at transaction creation whenever a transfer needs end-user proof, and returns it in the transaction's action_required block. Mint manually for pre-verification or when auto_wallet_verification is off.

Request body (application/json):
\{
"wallet_address": "0x8ba1f109551bD432803012645Ac136ddd64DBA72",   // the wallet to verify
"chain": "ETH",                               // chain identifier (ETH, BTC, SOL, TRX, ...); use the same token your transfers carry
"holder_name": "Ana Diaz",                    // used for the beneficiary name match
"vendor_data": "user-042",                    // your internal id, carried onto the address-book entry
"transaction_id": "<didit-transaction-uuid>", // optional: transfer to advance when the proof verifies
"satoshi_deposit_address": "",                // optional: a deposit address you control - enables the SATOSHI_TEST method
"callback_url": "https://yourapp.example/wallet-verified",  // optional: where the widget returns the customer
"expires_in_minutes": 60                      // optional; auto-extended to cover the Satoshi test window
}

When the customer starts a proof, Didit saves the wallet to your address book with this chain (or reuses the entry with the same address and chain).
Address-book matching is chain-scoped and does not translate names ("ethereum" does not match "ETH"), so pass the same chain token your transfers carry.

What to read from the response:
\- url - send your customer there, verbatim (never construct it yourself). Open it in a real browser or the SDK modal - NEVER an embedded mobile webview (wallet deep links cannot escape a webview).
\- widget_session_id, token, expires_at.

Proof methods offered (depending on settings and mint parameters):
\- MESSAGE_SIGNING - when chain is an EVM, Solana, Bitcoin or Tron chain.
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.
\- SATOSHI_TEST - a micro-deposit, offered when you pass satoshi_deposit_address and chain is an EVM, Solana or Bitcoin chain.
\- SCREENSHOT - if allow_screenshot_proof.
\- SELF_DECLARATION - if allow_self_declaration.

Detect completion:
\- Poll GET /v3/travel-rule/widget/{token}/ (completed_at becomes non-null), or
\- Subscribe to travel_rule.status.updated webhooks when the session is linked to a transfer.

Failure modes:
\- 400 - callback_url is not an absolute http(s) URL ({"callback_url": ["callback_url must be an absolute http(s) URL."]}), expires_in_minutes is outside 5 to 10080, transaction_id is not a UUID, or a field is longer than its limit.
\- 404 - transaction_id does not name a Travel Rule transfer in this application.
\- Minting does not check wallet_address against the linked transfer, but every proof on a linked session must use the transfer's counterparty wallet, otherwise starting the proof returns 400.

Full guide: /transaction-monitoring/wallet-ownership-widget.`

\</pre>



      
      

붙여넣을 곳



## OpenAPI

````yaml ko/openapi-25.json POST /v3/travel-rule/widget-session/
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-session/:
    post:
      tags:
        - Travel Rule
      summary: 지갑 소유권 위젯 세션 발급
      description: >-
        호스팅 지갑 소유권 위젯 URL/토큰을 생성합니다. 지갑 제어 권한을 증명(메시지 서명, 사토시 테스트, 스크린샷 또는 자체
        선언)할 수 있도록 고객을 반환된 url로 안내하십시오. 이 릴리스에서 위젯은 웹 전용입니다. 모바일 SDK 웹뷰 내부가 아닌
        시스템 브라우저 또는 커스텀 탭에서 url을 열어야 합니다.
      operationId: createTravelRuleWidgetSession
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TravelRuleWidgetSessionCreate'
            example:
              wallet_address: '0xd3b62acb76fb27a7f8961ec40fa11746b113aca9'
              chain: ETH
              holder_name: Jane Doe
              vendor_data: user-042
              transaction_id: 99999999-aaaa-bbbb-cccc-dddddddddddd
              expires_in_minutes: 60
      responses:
        '201':
          description: 발급된 위젯 세션입니다.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TravelRuleWidgetSessionResponse'
        '400':
          description: >-
            유효하지 않은 본문: `callback_url`이 절대 http(s) URL이 아니거나,
            `expires_in_minutes`가 5~10080 범위를 벗어났거나, `transaction_id`가 UUID가
            아니거나, 필드가 제한 길이를 초과했습니다.
          content:
            application/json:
              examples:
                Invalid callback_url:
                  value:
                    callback_url:
                      - callback_url must be an absolute http(s) URL.
        '404':
          description: '`transaction_id`가 이 애플리케이션의 Travel Rule 전송을 지정하지 않습니다.'
      security:
        - ApiKeyAuth: []
      x-codeSamples:
        - lang: curl
          label: curl
          source: >-
            curl -X POST
            https://verification.didit.me/v3/travel-rule/widget-session/ \
              -H 'x-api-key: YOUR_API_KEY' -H 'Content-Type: application/json' \
              -d '{"wallet_address":"0xd3b62acb76fb27a7f8961ec40fa11746b113aca9","chain":"ETH","holder_name":"Jane Doe","transaction_id":"99999999-aaaa-bbbb-cccc-dddddddddddd"}'
        - lang: python
          label: Python
          source: |-
            from didit import Didit

            # Reads DIDIT_API_KEY.
            client = Didit()

            result = client.travel_rule.create_widget_session(
                wallet_address="0xd3b62acb76fb27a7f8961ec40fa11746b113aca9",
                chain="ETH",
                holder_name="Jane Doe",
                vendor_data="user-042",
                transaction_id="99999999-aaaa-bbbb-cccc-dddddddddddd",
                expires_in_minutes=60,
            )
            print(result)
        - lang: javascript
          label: Node.js
          source: |-
            import Didit from "@didit-protocol/sdk-node";

            // Reads DIDIT_API_KEY.
            const didit = new Didit();

            const result = await didit.travelRule.createWidgetSession({
              wallet_address: "0xd3b62acb76fb27a7f8961ec40fa11746b113aca9",
              chain: "ETH",
              holder_name: "Jane Doe",
              vendor_data: "user-042",
              transaction_id: "99999999-aaaa-bbbb-cccc-dddddddddddd",
              expires_in_minutes: 60,
            });
            console.log(result);
        - lang: go
          label: Go
          source: "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.TravelRule.CreateWidgetSession(ctx, didit.TravelRuleWidgetSessionCreate{\n\tWalletAddress:    didit.String(\"0xd3b62acb76fb27a7f8961ec40fa11746b113aca9\"),\n\tChain:            didit.String(\"ETH\"),\n\tHolderName:       didit.String(\"Jane Doe\"),\n\tVendorData:       didit.String(\"user-042\"),\n\tTransactionID:    didit.String(\"99999999-aaaa-bbbb-cccc-dddddddddddd\"),\n\tExpiresInMinutes: didit.Int(60),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)"
        - lang: java
          label: Java
          source: >-
            import me.didit.Didit;

            import me.didit.types.TravelRuleWidgetSessionCreate;


            // Reads DIDIT_API_KEY.

            Didit client = new Didit();


            var result =
            client.travelRule().createWidgetSession(TravelRuleWidgetSessionCreate.builder()
                    .walletAddress("0xd3b62acb76fb27a7f8961ec40fa11746b113aca9")
                    .chain("ETH")
                    .holderName("Jane Doe")
                    .vendorData("user-042")
                    .transactionId("99999999-aaaa-bbbb-cccc-dddddddddddd")
                    .expiresInMinutes(60L)
                    .build());
            System.out.println(result);
        - lang: php
          label: PHP
          source: |-
            <?php

            require 'vendor/autoload.php';

            use Didit\DiditClient;

            // Reads DIDIT_API_KEY.
            $didit = new DiditClient();

            $result = $didit->travelRule->createWidgetSession([
                'wallet_address' => '0xd3b62acb76fb27a7f8961ec40fa11746b113aca9',
                'chain' => 'ETH',
                'holder_name' => 'Jane Doe',
                'vendor_data' => 'user-042',
                'transaction_id' => '99999999-aaaa-bbbb-cccc-dddddddddddd',
                'expires_in_minutes' => 60,
            ]);
            print_r($result->toArray());
        - lang: ruby
          label: Ruby
          source: |-
            require "didit"

            # Reads DIDIT_API_KEY.
            didit = Didit::Client.new

            result = didit.travel_rule.create_widget_session(
              wallet_address: "0xd3b62acb76fb27a7f8961ec40fa11746b113aca9",
              chain: "ETH",
              holder_name: "Jane Doe",
              vendor_data: "user-042",
              transaction_id: "99999999-aaaa-bbbb-cccc-dddddddddddd",
              expires_in_minutes: 60
            )
            puts result.to_h
        - lang: csharp
          label: .NET
          source: >-
            using System;

            using System.Text.Json;

            using Didit;


            // Reads DIDIT_API_KEY.

            using var client = new DiditClient();


            var result = await client.TravelRule.CreateWidgetSessionAsync(new
            TravelRuleWidgetSessionCreate

            {
                WalletAddress = "0xd3b62acb76fb27a7f8961ec40fa11746b113aca9",
                Chain = "ETH",
                HolderName = "Jane Doe",
                VendorData = "user-042",
                TransactionId = "99999999-aaaa-bbbb-cccc-dddddddddddd",
                ExpiresInMinutes = 60,
            });

            Console.WriteLine(JsonSerializer.Serialize(result));
components:
  schemas:
    TravelRuleWidgetSessionCreate:
      type: object
      properties:
        wallet_address:
          type: string
          description: 검증할 지갑 주소입니다. 선택 사항이며, 비어 있는 경우 증명을 시작할 때 주소를 제공해야 합니다.
          maxLength: 128
        chain:
          type: string
          description: >-
            해당 주소의 체인 token(예: `ETH`, `BTC` 또는 `SOL`)입니다. 지갑 주소록에서 사용하는 것과 동일한
            token을 사용하십시오. 메시지 서명 및 사토시 테스트는 지원되는 체인에 대해서만 제공됩니다. 증명이 검증하는 주소록
            항목은 표준 식별자(ETH, BTC, SOL, TRX)로 이를 저장합니다.
          maxLength: 32
        holder_name:
          type: string
          description: 수취인 이름 대조에 사용되는 지갑 보유자 이름입니다.
          maxLength: 255
        vendor_data:
          type: string
          description: 보유자에 대한 귀하의 내부 식별자이며, 생성된 주소록 항목으로 전달됩니다.
          maxLength: 255
        transaction_id:
          type: string
          format: uuid
          description: 선택 사항입니다. 증명이 검증될 때 진행할 Travel Rule 전송의 Didit 거래 UUID입니다.
          nullable: true
        satoshi_deposit_address:
          type: string
          description: 선택 사항입니다. 귀하가 관리하는 입금 주소이며, 이를 제공하면 SATOSHI_TEST 증명 방법이 활성화됩니다.
          maxLength: 128
        callback_url:
          type: string
          description: 선택 사항입니다. 완료 후 위젯이 고객을 리디렉션할 절대 http(s) URL입니다.
          maxLength: 512
        expires_in_minutes:
          type: integer
          description: >-
            선택 사항입니다. 발급된 링크의 유효 기간(분 단위)입니다. SATOSHI_TEST가 제공되는 경우 사토시 테스트 기간을
            포함하도록 자동으로 연장됩니다.
          default: 60
          minimum: 5
          maximum: 10080
    TravelRuleWidgetSessionResponse:
      type: object
      properties:
        widget_session_id:
          type: string
          format: uuid
        token:
          type: string
          description: 위젯 URL에 포함된 불투명 세션 token입니다.
        url:
          type: string
          description: 호스팅 지갑 소유권 위젯 URL입니다. 시스템 브라우저에서 그대로 엽니다(모바일 SDK 웹뷰 내에서는 절대 열지 마세요).
        expires_at:
          type: string
          format: date-time
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: >-
        Business Console의 Developers -> API keys에서 발급받은 귀하 애플리케이션의 API 키입니다. 기본
        키는 전체 접근 권한을 갖습니다. 이름이 지정된 키는 리소스별 none, read, write 범위로 권한을 제한할 수 있으며
        특정 워크플로나 승인된 세션, IP 주소 목록, 만료일 등으로 제한할 수도 있습니다. 401은 키가 잘못되었거나 폐기되었거나
        만료되었음을 의미합니다. 403은 키가 전송되지 않았거나, 키에 해당 리소스나 작업에 대한 접근 권한이 없거나, 요청이 허용된
        IP 목록 외부 주소에서 발생했음을 의미합니다. 세션 경로에서의 404는 해당 세션이 키의 허용 워크플로 또는 상태 범위를
        벗어났음을 의미합니다. 미디어 접근 권한이 없는 키는 이미지, 비디오, PDF URL을 null로 수신하며, 세션 write
        권한이 없는 키는 세션 링크와 token을 null로 수신합니다.
        https://docs.didit.me/console/api-keys 를 참고하십시오.

````

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