didit-transaction-monitoring

Didit Transaction Monitoring & Travel Rule API

概要

ルールエンジン（条件、速度ウィンドウ、ブロックリスト）に照らしてすべてのトランザクションをリアルタイムでスコアリングし、ブロックチェーン分析を用いて暗号資産ウォレットとトランザクションハッシュをスクリーニングし、FATF / EU TFR Travel Ruleに基づく取引先VASPとの情報交換を実行します。

主な情報：

• POST /v3/transactions/は同期処理です。スクリーニング、Travel Ruleのルーティング、ルールの適用はすべて呼び出しの中で実行されるため、201レスポンスにはすでに判定結果が含まれています。トランザクションはAPPROVEDとして作成され、ルールによってIN_REVIEW、DECLINED、またはAWAITING_USERに変更される場合があります。
• transaction_idはアプリケーションごとに一意です。再利用すると拒否されます（400と{"transaction_id": "A transaction with this transaction_id already exists."}、または2つのリクエストが競合した場合は409）。既存のトランザクションが返されることはありません。タイムアウト後にこの400が返された場合は「すでに作成済み」として扱い、再送信するのではなく、GET /v3/transactions/でレコードを検索してください。
• GET /v3/transactions/{uuid}/には、作成レスポンスに含まれるDiditのuuidを指定します。自分で指定したtransaction_idではありません。
• Sandboxアプリケーションではトランザクションが保存されますが、ルール、暗号資産のスクリーニング、Webhook、課金は実行されません（ステータスはAPPROVEDのままです）。
• ログイン、ゲームプレイ、ボーナス、チャージバックなどの金銭を伴わないアクティビティには、イベントAPIを使用してください。didit-event-monitoringスキルを参照してください。

料金： 1トランザクションあたり$0.02（Transaction Screening）。Travel Ruleによる送金は、スクリーニング料金との二重請求ではなく、送金ごとに別項目で$0.02が課金されます。Wallet Verification & Screeningは、トランザクション連動またはオンデマンドで、Didit管理の分析を利用する場合は$0.15から、自社のプロバイダーキーを利用する場合は$0.02です。Travel Ruleの属性付与で同じ照会が必要な場合でも、課金は1回のみです。Sandboxは課金対象外です。これらは2026年11月1日までのリスト価格です。同日以降はDiditの料金が変更され、毎月500件の無料チェックは月額$10分の無料クレジットに変更されます。最新の料金はdidit.me/pricingをご確認ください。

APIリファレンス： https://docs.didit.me/management-api/transactions/create 機能ガイド： https://docs.didit.me/transaction-monitoring/overview | https://docs.didit.me/transaction-monitoring/rules-api | https://docs.didit.me/transaction-monitoring/travel-rule | https://docs.didit.me/transaction-monitoring/wallet-screening

---

認証

すべてのリクエストにx-api-keyヘッダーが必要です。Didit Business ConsoleのDevelopers > API keysからアプリケーションのAPIキーを使用するか、アカウントとキーをプログラムで作成してください（「はじめに」を参照）。アクセス権をカスタマイズした名前付きキーには、Transactionsアクセス権が必要です（GETには読み取り、POST、PUT、PATCH、DELETEには書き込み）。一部のワークフローまたは承認済みセッションのみに制限されたキーには、Transactionsアクセス権を付与できません。

例外が2つあります。GET /v3/travel-rule/widget/{token}/にはキーは不要です（トークンが認証情報です）。デバイスのエンドポイント/v1/transactions/はX-Transaction-Tokenで認証します（SDKのトランザクショントークンを参照）。

はじめに（アカウントをお持ちでない場合）

Didit APIキーをお持ちでない場合は、API呼び出しを2回行って作成できます。

1. 登録： POST https://apx.didit.me/auth/v2/programmatic/register/に{"email": "[email protected]", "password": "MyStr0ng!Pass"}を指定します。
2. メールを確認し、6文字の認証コードを取得します。
3. 認証： POST https://apx.didit.me/auth/v2/programmatic/verify-email/に{"email": "[email protected]", "code": "A3K9F2"}を指定します。レスポンスのapplication.api_keyにキーが含まれています。

クレジットの追加： GET /v3/billing/balance/で残高を確認し、POST /v3/billing/top-up/に{"amount_in_dollars": 50}を指定してStripeのチェックアウトリンクを取得します。

プラットフォーム管理全般（ワークフロー、セッション、ユーザー、課金）については、didit-verification-managementスキルを参照してください。

---

エンドポイント

ベース URL：https://verification.didit.me

メソッド	パス	用途
POST	/v3/transactions/	トランザクションを送信します（同期判定）
GET	/v3/transactions/	トランザクションを新しい順に一覧表示します（limit、デフォルトは 50、offset）
GET	/v3/transactions/{uuid}/	トランザクションの詳細全体
POST	/v3/transactions/sdk-token/	/v1/transactions/ 用のデバイストークンを発行します
GET, POST	/v3/transactions/rules/	ルールの一覧表示／作成
GET, PATCH, DELETE	/v3/transactions/rules/{rule_uuid}/	ルールの読み取り／更新／削除
POST	/v3/transactions/rules/backtest/	過去のデータに対して仮想のルールを評価します
GET	/v3/transactions/rules/library/	is_installed を含むプリセットライブラリ
POST, DELETE	/v3/transactions/rules/install/	プリセットのインストール／アンインストール
POST	/v3/wallet-screening/	トランザクションを伴わず、1 つのウォレットをスクリーニングします
POST	/v3/wallet-screening/pdf/	スクリーニング結果を PDF として出力します
GET, PUT	/v3/travel-rule/settings/	トラベルルールの設定（PUT は部分更新）
PATCH	/v3/transactions/{uuid}/travel-rule/	送金を完了、キャンセル、または再送します
POST	/v3/transactions/{uuid}/travel-rule/ownership/	ウォレットの所有権を確認または否認します
GET, POST	/v3/travel-rule/wallet-addresses/	ウォレットアドレス帳
PATCH, DELETE	/v3/travel-rule/wallet-addresses/{entry_uuid}/	アドレスエントリーの更新／削除
GET	/v3/travel-rule/vasps/?search=	VASP ディレクトリ
POST	/v3/travel-rule/inbound/	すでに決済済みの入金を登録します（サンライズ）
POST	/v3/travel-rule/widget-session/	ウォレット所有権確認ウィジェットのリンクを発行します
GET	/v3/travel-rule/widget/{token}/	ウィジェットの進行状況（API キー不要）

---

トランザクションの作成

POST https://verification.didit.me/v3/transactions/

Body（JSON）

フィールド	型	必須	備考
transaction_id	文字列	はい	お客様の ID です。最大 128 文字で、アプリケーションごとに一意である必要があります。エイリアスは txnId です。
transaction_category	文字列	はい	finance、kyc、travel_rule、user_event、audit_trail_event、gambling_bet、gambling_limit_change、gambling_bonus_change。camelCase も使用できます：travelRule、userPlatformEvent、auditTrailEvent、gamblingBet、gamblingLimitChange、gamblingBonusChange。エイリアスキーは type です。複数語の値は、transaction_type で camelCase として返されます。
transaction_details.direction	文字列	はい	inbound ／ outbound（in ／ out も可。大文字と小文字は区別されません）。INBOUND ／ OUTBOUND として返されます。
transaction_details.amount	数値または小数文字列	はい	小数点以下最大 18 桁です。正確な精度が必要な場合は文字列を送信してください。
transaction_details.currency	文字列	はい	ISO 4217 コードまたは暗号資産のシンボルです。
transaction_details.currency_kind	文字列	いいえ	fiat または crypto。crypto を指定すると暗号資産スクリーニングが有効になります。
transaction_details.action_type	文字列	いいえ	例：deposit、withdrawal、transfer。デフォルトはカテゴリです。
transaction_details.payment_reference_id	文字列	いいえ	外部参照情報です。暗号資産の場合はオンチェーンハッシュを指定します（ハッシュスクリーニングに切り替わります）。
transaction_details.crypto_params.crypto_chain	文字列	いいえ	スクリーニングに使用するネットワーク（BTC、ETH、LTC、XRP、BCH、DOGE、TRX、SOL、MATIC、BNB、BASE、OP、ARB。LIGHTNING は Elliptic または Chainalysis のキーが接続されている場合のみ使用できます）。
transaction_details.amount_in_default_currency、default_currency、payment_details		いいえ	事前換算した金額とその通貨、自由記述のメモです。
subject.vendor_data	文字列	はい	最大 255 文字です。お客様のユーザー ID です。取引を、KYC セッションで使用するものと同じユーザープロフィールに関連付けます（取引頻度、ステップアップ認証用の保存済み顔情報）。
subject.full_name	文字列	はい
subject.entity_type	文字列	いいえ	individual（デフォルト）または company。
subject.*		いいえ	first_name、last_name、date_of_birth（YYYY-MM-DD）、address（country は ISO alpha-3、town、state、street、post_code）、institution_details、device_context、payment_method。
subject.payment_method ／ counterparty.payment_method	オブジェクト	いいえ	method_type（bank_card、bank_account、crypto_wallet、ewallet、unhosted_wallet、other）、account_id（IBAN、ウォレットアドレス）、issuing_country。
counterparty	オブジェクト	いいえ	subject と同じ形式です。必須項目はありません。
custom_properties	オブジェクト	いいえ	任意のキーと値を指定できます。ルールでは custom_values.<key> として参照できます。エイリアスは props です。
travel_rule_details	オブジェクト	いいえ	エイリアスは travelRule です。指定する場合、status は必須です（欠落時は 400）。Travel Rule を参照してください。
include_crypto_screening	ブール値	いいえ	アプリケーションのデフォルト設定を呼び出しごとに上書きします（null ／省略時はデフォルト）。
transaction_at、time_zone	文字列	いいえ	ISO タイムスタンプ（デフォルトは現在時刻）と IANA ゾーンです。エイリアスは txnDate、zoneId です。

ユーザーまたは事業者のブロックリストに登録された vendor_data を持つ subject または counterparty を指定すると、400 が返されます（何も作成されません）。ブロックリストに登録されたウォレット、銀行口座、IP、またはデバイスフィンガープリントは作成されますが、ルールが実行される前に decision_reason_code: "blocklisted" として即座に DECLINED になります。

例

curl -X POST https://verification.didit.me/v3/transactions/ \
  -H "x-api-key: $DIDIT_API_KEY" -H "Content-Type: application/json" \
  -d '{
    "transaction_id": "tx-0001",
    "transaction_category": "finance",
    "transaction_details": {"direction": "outbound", "amount": "1500.50", "currency": "EUR", "action_type": "withdrawal"},
    "subject": {"entity_type": "individual", "vendor_data": "user-42", "full_name": "John Doe"},
    "counterparty": {"entity_type": "company", "full_name": "Acme Energy"},
    "custom_properties": {"order_id": "ORD-7891"}
  }'

import os, requests

r = requests.post(
    "https://verification.didit.me/v3/transactions/",
    headers={"x-api-key": os.environ["DIDIT_API_KEY"]},
    json={
        "transaction_id": "tx-0001",
        "transaction_category": "finance",
        "transaction_details": {"direction": "outbound", "amount": "1500.50", "currency": "EUR"},
        "subject": {"vendor_data": "user-42", "full_name": "John Doe"},
    },
    timeout=60,
)
tx = r.json()
print(r.status_code, tx.get("uuid"), tx.get("status"), tx.get("score"))

レスポンス（201）

取引の詳細全体（GET /v3/transactions/{uuid}/ と同じ形式）：

フィールド	備考
uuid	Didit の ID。以降のすべてのパスで使用します
txn_id	お客様の transaction_id
transaction_type、action_type、direction	保存された値
status	APPROVED、IN_REVIEW、DECLINED、AWAITING_USER
score、severity	ルールスコア（通常は 0～100）。severity は UNKNOWN／LOW／MEDIUM／HIGH／CRITICAL または null
decision_reason_code、decision_reason_label	ステータスの理由
amount、currency、currency_type、preferred_currency_amount、preferred_currency_code、payment_txn_id	金額は小数を含む文字列
rule_runs[]、alerts[]、provider_results[]、tags[]、parties[]、payment_methods[]	評価の詳細。スクリーニング結果は provider_results に含まれます
travel_rule	短い送金オブジェクト（uuid、status、protocol、required、obligations_count、originator_data、beneficiary_data、metadata）、または null
action_required	エンドユーザーに必要な対応、または null（以下を参照）
cost_breakdown	total_price と items[]
environment	live または sandbox

action_required

type	条件	フィールド	対応
wallet_ownership	取引のトラベルルール送金に、保留中（完了も期限切れもしていない）のウォレット所有権ウィジェットセッションがある場合。取引のステータスは問いません	url、widget_session_id、expires_at	url を実際のブラウザーまたはカスタムタブで開きます。モバイルの WebView は使用しないでください
verification_session	取引が AWAITING_USER で、ルールによって修正セッションが作成された場合のみ	url、session_id、session_token、status	ユーザーを url に誘導するか、Didit SDK で session_token を使用してセッションを開始します

両方に該当する場合は、wallet_ownership が優先されます。解決されると、action_required は null に戻ります。修正セッションではルールは再実行されません。セッションの判定によって取引のステータスが直接設定され（Approved -> APPROVED、Declined -> DECLINED、In Review -> IN_REVIEW。decision_reason_code は user_action_approved／user_action_declined／user_action_in_review）、transaction.status.updated が発火します。セッションが期限切れまたは放棄された場合、取引は AWAITING_USER のままになります。

暗号資産スクリーニング（取引連動）

transaction_details.currency_kind が crypto で、アプリケーションのモニタリングが有効な場合（または include_crypto_screening: true の場合）に実行されます。false にするとスキップされます。スクリーニング対象のウォレットは、方向とオンチェーンハッシュを payment_reference_id に指定するかどうかによって異なります。

方向	送金前（ハッシュなし）	送金後（payment_reference_id にハッシュを指定）
入金	counterparty.payment_method.account_id の送信者ウォレット	お客様の入金アドレスに紐付けられたハッシュを subject.payment_method.account_id に指定（未指定の場合は 400）
出金	counterparty.payment_method.account_id の送金先ウォレット	counterparty.payment_method.account_id に紐付けられたハッシュ（未指定の場合は 400）

ネットワーク：transaction_details.crypto_params.crypto_chain を指定します。指定しない場合、通貨がチェーンとして使用されます。USDT／USDC は、ハッシュから Tron または Solana と特定されない限り、デフォルトで Ethereum になります。トークンでは必ず指定し、別の EVM チェーンで ETH を送信しないでください。接続済みの Elliptic または Chainalysis キーがない場合、LIGHTNING はスクリーニングや課金の前に 400 を返します。取引が作成されたことは、スクリーニングが実行された証拠にはなりません。provider_results を確認してください。

ウォレットスクリーニング（オンデマンド）

POST https://verification.didit.me/v3/wallet-screening/：トランザクションを作成せずに、1つのアドレスをスクリーニングします。設定済みのプロバイダー（Transactions > Settings > Provider Preferences）が必要です。設定されていない場合は 409 が返されます。

フィールド	必須	備考
wallet_address	はい	チェーンに対応した形式である必要があります（例：EVMでは 0x + 40桁の16進数）。別名は address です。
blockchain	はい	BTC、LIGHTNING、ETH、LTC、XRP、BCH、DOGE、TRX、SOL、MATIC、BNB、BASE、OP、ARB、USDT、USDC。USDT／USDC は Ethereum の旧式の別名であり、複数のチェーンを検索するものではありません。LIGHTNING には Elliptic または Chainalysis のキーが接続されている必要があります（それ以外の場合は 400）。別名は currency です。
direction	いいえ	inbound、outbound、deposit、withdrawal。コンテキストのみを示し、スコアは変わりません。

レスポンス 200：provider、screening_type（WALLET_SCREENING）、risk_score（0～100）、severity（0-9 は UNKNOWN、10-39 は LOW、40-69 は MEDIUM、70-89 は HIGH、90-100 は CRITICAL。UNKNOWN は区分の1つであり、合格を意味するものではありません）、status（SCREENED、PENDING、ERROR。完了した判定は SCREENED のみです。スコアが 0 の PENDING 結果はクリーンではありません）、summary、wallet_address、blockchain、sanctions_hit、pep_counterparty（null は PEP の該当情報がないことを示します）、dominant_risk_category、risk_factors[]（主な要因上位5件：source、category、label、entity_name、direction、exposure_type、amount_usd、percentage、is_high_risk、description）、source_of_funds[]、destination_of_funds[]、counterparty_connections[]、raw_response、report_signature。エラー：400 は入力検証エラー、409 はプロバイダー未設定、502 はプロバイダーの失敗（後で再試行してください）。スクリーニングが成功した場合に1回分の料金が請求されます。

PDF： POST /v3/wallet-screening/pdf/ にスクリーニングで返された JSON をそのまま（report_signature を含めて）送信すると、application/pdf のバイトデータが返されます。プロバイダーへの呼び出しも、請求も、データの保存もありません。署名がない場合、またはフィールドが編集されている場合は 400 が返されます。

RESULT=$(curl -s -X POST https://verification.didit.me/v3/wallet-screening/ \
  -H "x-api-key: $DIDIT_API_KEY" -H "Content-Type: application/json" \
  -d '{"wallet_address": "0x94f1b9b64e2932f6a2db338f616844400cd58e8a", "blockchain": "ETH"}')
curl -X POST https://verification.didit.me/v3/wallet-screening/pdf/ \
  -H "x-api-key: $DIDIT_API_KEY" -H "Content-Type: application/json" \
  -d "$RESULT" -o wallet_screening_report.pdf

トラベルルール（FATF／EU TFR）

設定

GET / PUT /v3/travel-rule/settings/（PUT は部分更新です）。is_enabled を有効にするには、空白以外の legal_name が必要です（保存済み、または同じリクエスト内に指定）。指定がない場合は 400 が返されます。

フィールド	デフォルト	備考
is_enabled	false	travelRule トランザクションで管理対象となる取引所
legal_name、lei、compliance_email	""	お客様の VASP プロファイル
jurisdiction	"EU"	最大8文字。custom_values.travel_rule_regime を設定します
threshold_amount	"0.00"	この金額未満の送金は NOT_APPLICABLE になります（EU TFR に最低金額はありません）
name_matching_strictness	DEFAULT	NONE、STRICT、DEFAULT、FUZZY
confirmation_timeout_hours	48	最小値は1です。期限後は AWAITING_COUNTERPARTY から EXPIRED に移行します
timeout_outcome	HOLD	期限切れ時の処理：HOLD（確認）、REJECT（拒否）、PROCEED（変更なし）
inbound_auto_accept	true	名前が一致する、アドレス帳に登録済みの確認済みアドレスへの入金を自動承認します
auto_wallet_verification	true	所有権確認ウィジェットを action_required に自動発行します
allow_screenshot_proof、allow_self_declaration	true	ウィジェットで提供する証明方法
vasp_attribution_enabled	true	レールで解決できない場合に、ブロックチェーン分析による帰属判定を行います
disabled_networks	[]	Didit のプラットフォームメンバーシップを経由しないネットワーク：GTR、TRUST、VERIFYVASP、SYGNA
is_discoverable	true	VASP ディレクトリに掲載され、INTERNAL レールからアクセス可能になります
networks、travel_address		読み取り専用：ネットワークごとの {rail, mode, platform_available, connected}（mode は own／didit／off／unavailable）と、お客様独自のトラベルアドレス

送金の送信

transaction_category: "travelRule"（または travel_rule）と travel_rule_details を指定してトランザクションを作成します。

• status はすべてのリクエストで必須です。Travel Rule が有効な場合は無視され、Didit がやり取りを処理します。"AWAITING_COUNTERPARTY" を送信してください。Travel Rule が無効な場合、travel_rule_details は送信した status（現行またはレガシー値）とともに受動的に保存され、レールは実行されません。
• beneficiary_data：wallet_address、name、および任意のルーティングフィールド travel_address、counterparty_vasp_lei、counterparty_vasp_name、counterparty_vasp_email、counterparty_gtr_vasp_code、counterparty_trust_membership_id、counterparty_verifyvasp_id、counterparty_sygna_vasp_code。originator_data は任意です（IVMS 101 スタイル、ラテン文字）。
• 相手方の payment_method.method_type: "unhosted_wallet" はセルフホスト型ウォレットを示します。この場合、レールは実行されず、送金は UNCONFIRMED_OWNERSHIP で開始されます。また、auto_wallet_verification が有効な場合、ウィジェットのリンクは action_required に遷移します。
• それ以外の場合、レールは INTERNAL -> TRP -> GTR -> TRUST -> VERIFYVASP -> SYGNA -> EMAIL の優先順で実行され、その後、ブロックチェーン分析による帰属判定でレールがもう一度実行されます。

curl -X POST https://verification.didit.me/v3/transactions/ \
  -H "x-api-key: $DIDIT_API_KEY" -H "Content-Type: application/json" \
  -d '{
    "transaction_id": "trv-0001",
    "transaction_category": "travelRule",
    "transaction_details": {"direction": "outbound", "amount": "0.25", "currency": "ETH", "currency_kind": "crypto"},
    "subject": {"vendor_data": "user-42", "full_name": "Jane Doe"},
    "counterparty": {"full_name": "Ana Diaz", "payment_method": {"method_type": "crypto_wallet", "account_id": "0xBeneficiaryWallet01"}},
    "travel_rule_details": {
      "status": "AWAITING_COUNTERPARTY",
      "beneficiary_data": {"wallet_address": "0xBeneficiaryWallet01", "name": "Ana Diaz"}
    }
  }'

送金ステータスの値（travel_rule.status）

ステータス	意味／アクション
AWAITING_COUNTERPARTY	送信済みです。相手方の VASP からの応答を待っています。決済しないでください。
UNCONFIRMED_OWNERSHIP	ウォレットの管理権限を証明する手段（ウィジェットまたは .../ownership/）を待っています。再送信できません。
ON_HOLD	手動対応のため保留中です（例：入金時に一致するアドレス帳のエントリーがない場合）。トランザクションには AWAITING_USER と表示されます。
COMPLETED	データが一致しました。今すぐオンチェーンでブロードキャストしても安全です。
FINISHED	終端状態です。オンチェーンハッシュを報告した場合（送信時）、またはサンライズ入金が決済された場合です。
CANCELLED	終端状態です。action: "cancel" でキャンセルされました。
EXPIRED	終端状態です。confirmation_timeout_hours が経過し、timeout_outcome がトランザクションに適用されました。
COUNTERPARTY_MISMATCHED_DATA	受取人名が name_matching_strictness の条件を満たしませんでした。
COUNTERPARTY_VASP_GENERAL_DECLINE	相手方が拒否したか、管理権限が否認されました。
COUNTERPARTY_VASP_NOT_FOUND	どのレールでも、帰属判定でも VASP を特定できませんでした。再送信できます。
COUNTERPARTY_VASP_NOT_REACHABLE	VASP は特定されましたが、その TRP エンドポイントでエラーが発生しました。再送信できます。
NOT_ENOUGH_COUNTERPARTY_DATA	相手方からの回答に十分なデータがありませんでした。再送信できます。
NOT_APPLICABLE	金額が threshold_amount 未満であるか、受動的なレコードに送信した値です。

COMPLETED になる前にブロードキャストしないでください。 その後、PATCH /v3/transactions/{uuid}/travel-rule/ を実行します。

• {"payment_txn_id": "0xhash"} -> FINISHED（送信時かつ COMPLETED の場合のみ。それ以外は 409）
• {"action": "resend"} -> ルーティングを再実行します（送信時に、再送信可能な 3 つの状態のいずれかから実行する場合のみ。それ以外は 409）。先に相手方のデータを改善してください。
• {"action": "cancel"} -> 終端状態でない送金をキャンセルします（終端状態の場合は 409）

トランザクション自体の status（許可／保留／拒否）は別のものです。travel_rule_eu_tfr プリセットバンドルは、不一致、未検証のセルフホスト型ウォレット（デフォルト通貨で 1000 以上）、および期限切れの場合に、トランザクションをレビュー状態に移行させます。

受取とウォレットの所有権

• アドレス帳： POST /v3/travel-rule/wallet-addresses/ に address、chain、holder_name、holder_vendor_data、entity_type、travel_address、self_declared（true にすると、検証済みの状態で作成されます）を指定します。address と chain が重複している場合は 400 です。PATCH .../{entry_uuid}/ では holder_name、holder_vendor_data、entity_type、travel_address を指定できます。DELETE でエントリーを削除します（204）。照合はアドレスのみで行われます。
• 所有権の確認： 受取人側で POST /v3/transactions/{uuid}/travel-rule/ownership/ に {"confirmed": true|false} を指定します。UNCONFIRMED_OWNERSHIP の場合のみ有効で、それ以外は 409 です。true にするとエントリーを検証し、名前の照合を実行します。false の場合は COUNTERPARTY_VASP_GENERAL_DECLINE になります。入金の originator_data／beneficiary_data は、所有権が確認されるまで非表示です。
• ウィジェット： POST /v3/travel-rule/widget-session/ に wallet_address、chain、任意の holder_name、vendor_data、transaction_id（次に進めるDiditトランザクションのUUID）、satoshi_deposit_address（Satoshiテストを有効にします）、callback_url、expires_in_minutes（デフォルトは60、5～10080）を指定すると、{widget_session_id, token, url, expires_at} が返されます。ブラウザーで url をそのまま開きます。APIキーなしで GET /v3/travel-rule/widget/{token}/ をポーリングします（検証が完了すると completed_at はnull以外になります。不明なトークンは 404、期限切れは 410）。または travel_rule.status.updated を待ちます。
• Sunrise（すでに決済済みの入金）： POST /v3/travel-rule/inbound/ に必須の chain、txid、wallet_address、amount（10進数文字列）、currency と、任意の originator_data、beneficiary_data、originating_vasp（{name, lei, travel_address}）を指定します。txid と wallet_address で重複を判定します。新しい入金トランザクションの場合は created: true とともに 201、再利用の場合は created: false とともに 200 が返されます。状態は ON_HOLD（エントリーなし）、UNCONFIRMED_OWNERSHIP、COUNTERPARTY_MISMATCHED_DATA、または COMPLETED になり、その後 FINISHED になります。
• ディレクトリ： GET /v3/travel-rule/vasps/?search=<name>（limit のデフォルトは50、offset）で、name、lei、jurisdiction、dd_status、dd_score、dd_score_breakdown、reachable_rails、is_didit_customer を取得します。

SDKトランザクショントークン（クライアント側からの送信）

バックエンドで発行します。POST /v3/transactions/sdk-token/ に必須の vendor_data、ttl_seconds（デフォルトは900、60～86400）、max_uses（1以上。省略または null にすると、有効期限内は無制限）を指定すると、201 {"sdk_token", "expires_at"} が返されます。 デバイスは X-Transaction-Token ヘッダーを付けて POST https://verification.didit.me/v1/transactions/ および GET /v1/transactions/{uuid}/ を呼び出します。対象者はトークンの vendor_data に固定され、サーバーがIPアドレスとユーザーエージェントを追加します。また、読み取りではその vendor_data のトランザクションのみが返されます。トークンが拒否された場合（未指定、不明、期限切れ、max_uses 超過）は 401 です。Didit Web、iOS、Android、React Native、Flutterの各SDKでは、これを submitTransaction としてラップし、wallet_ownership アクションを自動的に起動します（didit-sdk-integration スキルを参照）。アプリにAPIキーを含めないでください。

ルール API

コンソールの トランザクション > ルール と同じルールです。TEST で作成してバックテストを行い、その後 ACTIVE に切り替えます。サンドボックスアプリケーションではルールは実行されません。

フィールド	説明
title	必須。アプリケーションごとに一意です（重複すると 400）
category	必須。例：finance、aml_ctf、crypto_monitoring、travel_rule
mode	必須：ACTIVE、TEST（実行を記録しますが、スコア／ステータスは変更しません）、DISABLED
evaluation_mode	conditions に対して ALL（デフォルト）または ANY
scope	transaction_types、directions（INBOUND／OUTBOUND）、action_types、record_types（デフォルトは ["transaction"]、["event"]、または両方）、イベントルール用の event_categories
conditions[]	{field, operator, value}。演算子は eq、ne、gt、gte、lt、lte、in、not_in、contains、not_contains、contains_any、regex、fuzzy_match（score が必要）、exists、not_exists およびそのエイリアス。任意項目は value_type（list、field、relative_date）と group_index
aggregation[]	{metric, field?, operator, value, window, filters}。メトリクスは count、sum、avg、min、max、distinct_count。ウィンドウは <N>m／<N>h／<N>d。フィルター内の "__current__" は「このトランザクションと同じ値」を意味します
actions[]	add_score（value）、change_status（value は APPROVED／IN_REVIEW／DECLINED／AWAITING_USER。AWAITING_USER には workflow_id が必要）、add_tags、add_note、add_to_list（list_id）、open_case

• GET /v3/transactions/rules/ のフィルター：source（PRESET／CUSTOM）、category、mode、bundle、search、ordering、limit、offset。
• PATCH .../rules/{rule_uuid}/：カスタムルールはすべてのフィールドを受け付けます。プリセットで受け付けるのは mode のみです（その他のフィールドは 400）。
• DELETE .../rules/{rule_uuid}/：カスタムルールを削除します（204）。プリセットの場合は 400 を返します（代わりにアンインストールしてください）。
• POST .../rules/backtest/ に conditions、aggregation、evaluation_mode（デフォルトは ALL）、scope、period_days（デフォルトは 90）を指定すると、{evaluated, matched, affected_entities, period_days} を返します。有効化する予定の設定とまったく同じ内容でバックテストしてください。
• GET .../rules/library/（bundle、category、search）は、is_installed を含む 150 件以上のプリセットを一覧表示します。POST .../rules/install/ に {"library_keys": [...]} または {"bundle": "travel_rule_eu_tfr"} を指定すると {installed_library_keys, installed_count} を返します。DELETE に同じ本文を指定すると {uninstalled_count} を返します。どちらのキーも指定しない場合は 400 です。

curl -X POST https://verification.didit.me/v3/transactions/rules/ \
  -H "x-api-key: $DIDIT_API_KEY" -H "Content-Type: application/json" \
  -d '{
    "title": "High-value withdrawal step-up",
    "category": "finance",
    "mode": "TEST",
    "scope": {"directions": ["OUTBOUND"]},
    "conditions": [{"field": "preferred_currency_amount", "operator": "gte", "value": 5000}],
    "actions": [{"type": "change_status", "value": "AWAITING_USER", "workflow_id": "YOUR_BIOMETRIC_WORKFLOW_ID"}]
  }'

open_case によって作成されたケースは、didit-case-management スキルで扱います。

Webhook

POST /v3/webhook/destinations/ の subscribed_events で登録します。

• transaction.created および transaction.status.updated：transaction_id（Didit の UUID）、txn_id、status、score、severity、amount、currency、direction、action_required。理由を確認するには、完全なレコードを取得してください。
• travel_rule.status.updated：transaction_id、txn_id、travel_rule_status、rail、direction。

フラットなエンベロープには webhook_type、event_id（再試行時にも再利用される重複排除キー）、timestamp、created_at、application_id、environment が含まれます。X-Timestamp を使用して X-Signature-V2 を検証してください。サンドボックスアプリケーションではトランザクション Webhook は送信されません。イベントには Webhook がありません。

エラーレスポンス

ステータス	意味	対処方法
400	無効なリクエスト：フィールドの不足、transaction_id の再利用（{"transaction_id": "A transaction with this transaction_id already exists."}）、travel_rule_details.status の不足、ハッシュスクリーニング用ウォレットの不足、ブロックリスト登録された vendor_data、未対応のチェーン、編集済みの PDF ペイロード	レスポンス本文のフィールドエラーを確認してください
401	API キーの有効期限切れ、または /v1/transactions/ で X-Transaction-Token がない、無効、期限切れ、もしくは使用済み	キーをローテーションするか、新しい SDK トークンを発行してください
403	API キーがない、間違っている、または取り消されている、このエンドポイントへのアクセス権がないスコープ付きキー、キーの IP 許可リスト外からのリクエスト、またはクレジット不足（トランザクションとウォレットスクリーニングでは "code": "insufficient_credits" が返されます）	detail または error のメッセージを確認してください。x-api-key ヘッダーまたはキーのアクセス権を修正するか、クレジットを追加してください
404	不明なトランザクション、ルール、アドレスエントリ、またはウィジェットトークン（もしくは UUID ではない）	Didit の uuid を使用してください
409	同じ transaction_id を使った 2 つの作成リクエストが競合した、現在のステータスでは Travel Rule の操作が許可されていない、ウォレットスクリーニングのプロバイダーが設定されていない	再試行する前にレコードを読み直してください
410	ウィジェットセッションの期限切れ	新しいウィジェットセッションを発行してください
429	レート制限：キーごとに 1 分あたり POST/PATCH/DELETE リクエスト 300 件、GET リクエスト 600 件	Retry-After の秒数だけ待ってから、再試行してください
502	ウォレットスクリーニングのプロバイダーでエラーが発生しました	後でもう一度お試しください

よくあるワークフロー

Travel Rule に対応した暗号資産の出金（エンドツーエンド）

1. PUT /v3/travel-rule/settings/ を 1 回実行し、is_enabled: true と legal_name を設定します。
2. POST /v3/transactions/ を実行します。transaction_category: "travelRule"、暗号資産の transaction_details（crypto_params.crypto_chain を含む）、ユーザーを subject、送金先を相手方の payment_method（ユーザー自身のウォレットの場合は unhosted_wallet）に指定し、status と beneficiary_data を含む travel_rule_details を設定します。
3. action_required.type == "wallet_ownership" の場合は、ブラウザーでユーザーをその url に誘導します。
4. travel_rule.status == "COMPLETED"（travel_rule.status.updated Webhook または GET /v3/transactions/{uuid}/）と、拒否されていないトランザクションの status を待ちます。
5. オンチェーンで送信し、その後 payment_txn_id を指定して PATCH .../travel-rule/ を実行し、FINISHED にします。

高額トランザクションのステップアップ生体認証

1. Biometric Authentication の workflow_id を指定し、change_status アクションで AWAITING_USER に遷移させるルールを作成します（Rules API またはコンソールを使用）。バックテストを実行してから、PATCH {"mode": "ACTIVE"} を実行します。
2. ユーザーの KYC と同じ vendor_data を使って通常どおりトランザクションを送信します。ルールが適用されると、action_required.type == "verification_session" になります。
3. ユーザーを url に誘導します。オンボーディング時に認証された顔と、ライブセルフィー 1 枚を照合します。
4. セッションの判定により、トランザクションのステータスが APPROVED、DECLINED、または IN_REVIEW に設定され、transaction.status.updated が発火します。

決済後の入金スクリーニング

direction: "inbound"、currency_kind: "crypto"、payment_reference_id にハッシュ、subject.payment_method.account_id に入金先アドレス、crypto_params.crypto_chain にネットワークを指定します。その後、provider_results とトランザクションの status を確認します。

ユーティリティスクリプト

scripts/submit_transaction.py はトランザクションを 1 件送信し、JSON と要約（uuid、status、score、travel_rule.status、action_required.type）を出力します。

export DIDIT_API_KEY="your_api_key"

python scripts/submit_transaction.py --txn-id tx-0001 --amount 1500.50 --currency EUR \
    --vendor-data user-42 --subject-name "John Doe" --counterparty-name "Acme Energy" \
    --counterparty-entity-type company

# Outbound crypto withdrawal with wallet screening
python scripts/submit_transaction.py --txn-id wd-0001 --amount 0.25 --currency ETH --chain ETH \
    --vendor-data user-42 --subject-name "Jane Doe" --counterparty-name "Ana Diaz" \
    --wallet 0xBeneficiaryWallet01 --crypto

# Travel Rule transfer to the user's own self-hosted wallet
python scripts/submit_transaction.py --txn-id trv-0001 --amount 0.25 --currency ETH --chain ETH \
    --vendor-data user-42 --subject-name "Jane Doe" --counterparty-name "Jane Doe" \
    --wallet 0xJanesColdWallet01 --crypto --category travel_rule --unhosted