暗号資産・ウォレットスクリーニングAPI

暗号資産取引では、Diditは取引の作成時に、Merkle Science、Crystal、Chainalysis、Elliptic、TRM Labsなどのブロックチェーン分析プロバイダーを用いて、ウォレットアドレスと取引ハッシュをスクリーニングできます。スクリーニングはサーバー側で実行されるため、お客様側で追加のAPI呼び出しを行う必要はありません。

取引なしでアドレスをスクリーニングしたい場合は、オンデマンドのウォレットスクリーニングエンドポイント（POST /v3/wallet-screening/）を使用してください。1回のAPI呼び出しで、単一のウォレットについて同じリスク結果を取得できます。

スクリーニングが実行される条件

暗号資産のスクリーニングは、次の両方の条件を満たすと自動的に実行されます。

取引の取引詳細にcurrency_kind: "crypto"が含まれている
アプリケーション設定でトランザクションモニタリングが有効になっている

取引作成ペイロードのinclude_crypto_screeningを使うと、このデフォルトを取引ごとに上書きできます。

値	動作
`true`	アプリケーションレベルのデフォルトが無効になっていても、暗号資産のスクリーニングを実行する
`false`	アプリケーションレベルのデフォルトが有効になっていても、暗号資産のスクリーニングをスキップする
省略または`null`	Consoleで設定したアプリケーションレベルのデフォルトを使用する

アプリケーションレベルのデフォルトは、Business ConsoleのTransactions > Settingsにあります。include_crypto_screeningは、作成する1件の取引に対してのみ、そのデフォルトを上書きします。

アセットとネットワークの選択

アセットとネットワークは別々のフィールドです。 transaction_details.currencyにトークンのシンボルを、transaction_details.currency_kindにcryptoを、transaction_details.crypto_params.crypto_chainにネットワークを設定します。たとえば、次のフラグメントはBase上のカスタムトークンを記録します。

{
  "transaction_details": {
    "currency": "TOKEN",
    "currency_kind": "crypto",
    "crypto_params": {"crypto_chain": "BASE"}
  }
}

マネージドスクリーニングでは、BTC、ETH、LTC、XRP、BCH、DOGE、TRX、SOL、MATIC、BNB、BASE、OP、ARB、AVAX、ADA、XLM、HBARを指定できます。 BASEはBase、OPはOptimism、ARBはArbitrum One、AVAXはAvalanche C-Chain、ADAはCardano、XLMはStellar、HBARはHederaを表します。一般的なネットワーク名も使用できます。たとえば、MATICにはPOLYGONまたはPOL、BNBにはBSC、TRXにはTRONを指定できます。 Celo、Mode、Plumeはマネージド連携の対象外で、接続済みのTRM Labsアカウントを通じてスクリーニングされます（CELO、MODE、PLUME）。接続済みのプロバイダーには、それぞれ独自の対応範囲があります。Lightningには、以下に示す追加の要件があります。トークンには、USDTやUSDCも含め、常にcrypto_chainを指定してください。指定しない場合は通貨がネットワークとして使われ、USDTとUSDCについては取引ハッシュから、ハッシュがない場合はウォレットアドレスからネットワークが判定されます。 TronまたはSolanaのハッシュであれば、TronまたはSolanaが選択されます。 0xハッシュはどのEVMネットワークでも同じ形式になるため、USDT、USDC、ETHについては、DiditがEthereum、BNB Chain、Polygon、Base、Arbitrum、Optimismでハッシュを検索し、見つかったネットワーク上で取引をスクリーニングします。 ETHが対象に含まれるのは、ETHがEthereum、Base、Arbitrum、Optimismのネイティブアセットであり、BNB Chain上でもブリッジされたBEP-20トークンとして送金されるためです。いずれのネットワークにもハッシュが存在しない場合、またはその時点でネットワークを確認できない場合、取引はスクリーニングされず、スクリーニングの料金も請求されません。このとき、custom_values.aml_screening_statusはFAILEDとなり、custom_values.aml_screening_errorにその理由が示され、承認済みの取引はレビューに移行します。ハッシュのないUSDTまたはUSDCの取引ではウォレットがスクリーニングされ、ウォレットアドレスによってネットワークが選択されます。 TronアドレスはTron上で、SolanaアドレスはSolana上でスクリーニングされます。 0xアドレスは、Ethereum、BNB Chain、Polygon、Base、Arbitrum、Optimismのうち、そのアドレスが取引を送信したことがある、またはそのトークンを保有している最初のネットワーク上でスクリーニングされます。いずれのネットワークでもアクティビティがない0xアドレス、またはその時点でネットワークを確認できないアドレスは、Ethereum上でスクリーニングされます。 crypto_chainを送信すれば、この検索は行われません。実際のネットワークの代わりにETHを指定することは決してしないでください。カスタムトークンのシンボルを記録しても、その送金が取引ハッシュのスクリーニング向けにインデックスされることは保証されません。トークンの対応状況は、トークンコントラクトとネットワークを使って確認する必要があります。取引が作成されたことは、スクリーニングが成功したことの証明にはなりません。スクリーニング済みとして扱う前に、スクリーニングのステータスとプロバイダーの結果を確認してください。

受信と送信

transaction_details.directionは、送金のどちら側をスクリーニングすべきかをDiditに伝えるため、必須です。

方向	オンチェーン送金の前	オンチェーン送金の後
受信（入金）	`counterparty.payment_method.account_id`で指定した場合、取引相手の送信元ウォレットをスクリーニングする	`subject.payment_method.account_id`にある貴社サービスまたは顧客の入金アドレスに限定して、取引ハッシュをスクリーニングする
送信（出金）	資金を送る前に、`counterparty.payment_method.account_id`の送金先ウォレットをスクリーニングする	`counterparty.payment_method.account_id`にある同じ送金先ウォレットに限定して、取引ハッシュをスクリーニングする

送金前のスクリーニングでは、transaction_details.payment_reference_idを省略します。Diditは該当するウォレットアドレスに対してウォレットスクリーニングを実行します。送金後のスクリーニングでは、transaction_details.payment_reference_idにブロックチェーンの取引ハッシュを含めます。Diditは取引スクリーニングを実行し、オンチェーンのエンリッチメントが利用可能な場合は取引の概要データを保存します。

Lightning Network

Lightning Networkのスクリーニングを行うには、transaction_details.crypto_params.crypto_chainをLIGHTNINGに設定します。 Lightningのスクリーニングには、コンソールのMarketplaceで接続したEllipticまたはChainalysisのBYOKプロバイダーが必要です。マネージドのMerkle Science、Crystal、TRM LabsはLIGHTNINGを受け付けません。Diditはこれらのリクエストを、スクリーニングや請求の前に400で拒否します。 Ellipticの場合、DiditはEllipticのBTC Lightningウォレット分析を通じて、指定されたLightning識別子をスクリーニングします。 Chainalysisの場合、transaction_details.payment_reference_idが存在するときに、DiditはLightningの送金をKYTに送信します。

必須フィールド

暗号資産のスクリーニングリクエストでは、次を送信します。

transaction_details.direction：INBOUNDまたはOUTBOUND
transaction_details.currency_kind：crypto
transaction_details.currency：資産のシンボル(例：BTC、ETH、USDC、または独自トークン)
上記の方向ルールで選択される参加者のウォレットアドレス

送金がオンチェーンに記録された後にトランザクションハッシュでスクリーニングする場合は、さらに次を送信します。

transaction_details.payment_reference_id：ブロックチェーンのトランザクションハッシュ

暗号資産のスクリーニングが有効で、方向に応じて必要なウォレットアドレスが含まれていない場合、Create Transaction APIはリクエストを拒否します。

送金前の送信先スクリーニングの例

資金を送る前に、トランザクションハッシュを含めずに出金の暗号資産取引を作成します。Diditは送付先ウォレットをスクリーニングします。

{
  "transaction_id": "withdrawal-001",
  "transaction_category": "finance",
  "include_crypto_screening": true,
  "transaction_details": {
    "direction": "OUTBOUND",
    "amount": "0.25",
    "currency": "ETH",
    "currency_kind": "crypto",
    "action_type": "withdrawal"
  },
  "subject": {
    "entity_type": "individual",
    "vendor_data": "user-123",
    "full_name": "John Doe"
  },
  "counterparty": {
    "entity_type": "unhosted_wallet",
    "full_name": "John Doe",
    "payment_method": {
      "method_type": "crypto_wallet",
      "account_id": "0xRecipientWallet..."
    }
  }
}

受取後の入金スクリーニングの例

資金を受け取った後は、トランザクションハッシュを含めます。Diditはお客様の入金アドレスを対象としてトランザクションハッシュをスクリーニングし、利用可能な場合は取引の概要情報をレスポンスに追加します。

{
  "transaction_id": "deposit-001",
  "transaction_category": "finance",
  "include_crypto_screening": true,
  "transaction_details": {
    "direction": "INBOUND",
    "amount": "0.25",
    "currency": "ETH",
    "currency_kind": "crypto",
    "action_type": "deposit",
    "payment_reference_id": "0xTransactionHash..."
  },
  "subject": {
    "entity_type": "individual",
    "vendor_data": "user-123",
    "full_name": "John Doe",
    "payment_method": {
      "method_type": "crypto_wallet",
      "account_id": "0xYourServiceDepositAddress..."
    }
  },
  "counterparty": {
    "entity_type": "unhosted_wallet",
    "full_name": "John Doe"
  }
}

対応プロバイダー

プロバイダー	ステータス	マネージド料金	接続キー料金
Merkle Science	利用可能	$0.15/スクリーニング	$0.02/スクリーニング
Crystal	Marketplaceでプロバイダーキーを接続	利用不可	$0.02/スクリーニング
Chainalysis	Marketplaceでプロバイダーキーを接続	利用不可	$0.02/スクリーニング
Elliptic	Marketplaceでプロバイダーキーを接続	利用不可	$0.02/スクリーニング
TRM Labs	Marketplaceでプロバイダーキーを接続	利用不可	$0.02/スクリーニング

使用するプロバイダーはBusiness ConsoleのTransactions > Settings > Provider Preferencesで設定するか、コンソールのMarketplace(Crypto monitoringカテゴリー)から独自のプロバイダーキーを接続してください。 LIGHTNINGは、接続キーを使用するChainalysisおよびEllipticの構成でのみサポートされます。

接続キー料金では、既存のプロバイダーのAPIキーを接続し、スクリーニングごとに記載のインフラ料金をお支払いいただきます。ブロックチェーン分析プロバイダーとすでに商業契約を結んでいる場合は、このオプションをご利用ください。

スクリーニング結果

どのプロバイダーを使用しても、各スクリーニングは標準化された結果を返します。

スクリーニングステータス

custom_values.aml_screening_statusは、取引がスクリーニングされたかどうかを示します。

値	意味
`COMPLETED`	スクリーニングが完了しました。結果は`provider_results`と、`custom_values`のその他のスクリーニングフィールドに格納されます。
`PENDING`	スクリーニングはまだ完了していません。プロバイダーが分析中であるか、Diditが後で取引ハッシュを再度スクリーニングします(後述)。
`ERROR`	プロバイダーは応答しましたが、プロバイダー自身の分析が失敗したと報告しました。
`FAILED`	取引はスクリーニングされませんでした。理由は`custom_values.aml_screening_error`に記載されます。Didit管理のスクリーニングでは料金は発生しません。接続済みのプロバイダーが応答したリクエストは、プロバイダーリクエストとしてカウントされます。

本来であれば承認される取引も、スクリーニングがCOMPLETED以外の状態である間はIN_REVIEWに移行します。

インデックス未登録の取引ハッシュ

ブロックチェーン分析プロバイダーは、マイニングされたばかりの送金をインデックスするまでに数分かかることがあり、それまではスクリーニングできません。プロバイダーが取引ハッシュをまだインデックスしていないと応答し、かつネットワーク自体がその取引の存在を確認している場合、Diditはスクリーニングを失敗とせず、バックグラウンドで再度スクリーニングします。

作成時のレスポンスで、すでにcustom_values.aml_screening_statusがPENDINGと表示され、理由がcustom_values.aml_screening_errorに記載されます。承認済みの取引は、decision_reason_codeがaml_screening_pendingの状態でIN_REVIEWに保留されます。
Diditは、取引の作成から約2分後、12分後、42分後に取引ハッシュを再度スクリーニングします。
再試行でスクリーニングできた場合、結果は他のスクリーニングと同様に保存され、スクリーニング料金は1回分のみ請求されます。スクリーニングデータに対してルールが再度実行され、保留が解除されます。ステータスが変わったかどうかにかかわらず、ルール適用後の取引ステータスを含むtransaction.status.updated Webhookを1件受信します。その間にレビュアーによって却下または解決された取引は、そのステータスを維持します。
最後の再試行後もプロバイダーが取引ハッシュをインデックスしていない場合、スクリーニングは作成時と同様にFAILEDで終了します。取引はdecision_reason_codeがaml_screening_failedの状態でIN_REVIEWに留まり、作成時の失敗と同様に課金されます。つまり、Didit管理のスクリーニングでは料金は発生せず、最後の試行が接続済みのプロバイダーに到達した場合は1件のプロバイダーリクエストとしてカウントされます。再試行の対象となったそれ以前の試行が課金されることはありません。
再試行の実行時に残高がスクリーニング料金を賄えなくなっている場合、スクリーニングはFAILEDで終了し、料金は請求されません。

再試行は、Ethereum、BNB Chain、Polygon、Base、Arbitrum、Optimism、Tron上の取引ハッシュに適用されます。ネットワークが認識していないハッシュや、それ以外のネットワーク上のハッシュは再試行されず、スクリーニングは直ちに失敗します。

リスクスコアと重大度

スクリーニングされたすべてのウォレットまたは取引には、以下が付与されます。

リスクスコア(0〜100):スコアが高いほど、リスクの高いエンティティへのエクスポージャーが大きいことを示します
重大度レベル:スコアから導出され、LOW、MEDIUM、HIGH、CRITICALのいずれかになります

資金源分析

資金の出所をエンティティの種類別に分類した割合の内訳です。

カテゴリー	リスクレベル	説明
`SANCTIONED`	重大	国際的な制裁リスト(OFAC、EU、UN)に掲載されているエンティティ
`TERRORIST_FINANCING`	重大	テロ資金供与に関連するアドレス
`CHILD_EXPLOITATION`	重大	児童搾取コンテンツに関連するアドレス
`RANSOMWARE`	高	ランサムウェアの支払い先アドレス
`STOLEN_FUNDS`	高	既知の窃盗やハッキングに関連するアドレス
`DARKNET_MARKET`	高	ダークネットマーケットのアドレス
`MIXER`	高	資金の出所を隠すために使われるミキシングまたはタンブリングサービス
`SCAM`	高	既知の詐欺や不正に関連するアドレス
`HIGH_RISK_EXCHANGE`	中	KYC/AML管理が不十分な取引所
`HIGH_RISK_JURISDICTION`	中	FATFが指定する高リスク法域のエンティティ
`GAMBLING_UNLICENSED`	中	ライセンスを持たないギャンブルプラットフォーム
`P2P_EXCHANGE`	低	P2P取引サービス
`EXCHANGE`	低	規制下にある暗号資産取引所
`UNNAMED_SERVICE`	低	特定されていないサービス

内訳の各エンティティには、資金の割合、受取額と送付額、および接続が直接か間接かが含まれます。

エクスポージャーテーブル

送金元、送金先、取引相手のエンティティを示すエクスポージャーテーブルで、以下を含みます。

エンティティ名とカテゴリー
直接接続と間接接続(ホップ距離)
受取額と送付額
エンティティごとのリスクレベル

ネットワークグラフ

ウォレットの取引関係をノードとエッジで視覚的に表現したものです。

ノードは、ウォレット、取引所、サービス、その他のエンティティを表します
エッジは、ノード間の取引を金額と取引ハッシュとともに表します
指標には、中心性や深さなどのグラフ全体の統計が含まれます

ネットワークグラフは、Business Consoleでインタラクティブな可視化として利用できます。

ルールとの連携

スクリーニング結果はルールエンジンに直接反映されます。Diditには、スクリーニングデータに基づいて自動的に発動するプリセットルールが用意されています。

プリセットルール	アクション
Sanctions counterparty	即時却下。スクリーニング対象のウォレット自体が制裁対象の主体に帰属している（`custom_values.wallet_sanctioned`）
制裁へのエクスポージャー	スコアを加算し、レビュー対象としてフラグ付け。ウォレット自体は制裁対象ではないものの、制裁対象の主体との間で資金を移動している（`sanctions_hit`がtrueで、`wallet_sanctioned`がtrueではない）
Terrorist financing / child exploitation	即時却下
Darknet market exposure	スコアを加算し、レビュー対象としてフラグ付け
Mixer/obfuscation service exposure	スコアを加算し、レビュー対象としてフラグ付け
High-risk source of funds (>30%)	スコアを加算し、レビュー対象としてフラグ付け
Multiple risky counterparties	スコアを加算し、レビュー対象としてフラグ付け
Medium wallet risk score	スコアを加算し、レビュー対象としてフラグ付け
Screening pending	スクリーニングが完了するまで取引を保留

ルール用のスクリーニングフィールド

暗号資産スクリーニングは、取引のcustom_valuesに以下のキーを書き込みます。そのため、ルールではcustom_values.<key>として利用できます。

フィールド	型	説明
`sanctions_hit`	boolean	ウォレット自体が制裁対象である場合、またはいずれかの取引相手の資金が制裁対象の主体から流入している場合（エクスポージャー）に`true`になります。大手取引所は、エクスポージャーのみで`true`になることがよくあります。
`wallet_sanctioned`	boolean	スクリーニングプロバイダーが、スクリーニング対象のウォレット自体を制裁対象の主体（OFAC、EU、UN、HMTによる指定）に帰属させている場合にのみ`true`になります。エクスポージャーだけでこの値が設定されることはありません。
`aml_sanctions_exposure_pct`	number (0-100)	ウォレットのスクリーニング対象取引量のうち、制裁対象の主体と関わった割合です。`aml_high_risk_exposure_pct`と同じ方法で算出され、対象は制裁に限定されます。

間接的なエクスポージャーしかない大手取引所への送金を却下せずに、制裁対象のウォレットへの送金をブロックするには、wallet_sanctionedを使用してください。エクスポージャーをレビューまたはスコアリングするには、sanctions_hitまたはaml_sanctions_exposure_pctを使用してください。プリセットルールSanctions counterpartyはwallet_sanctionedがtrueの場合に却下し、プリセットルール制裁へのエクスポージャーはエクスポージャーのみのウォレットをレビューに回します。この2つのルールが同じ取引に一致することはないため、制裁対象のウォレットは必ず却下されます。この変更より前にSanctions counterpartyをインストールしていた場合、Diditが自動的に同ルールの条件をwallet_sanctionedに変更し、同じモードで制裁へのエクスポージャーを追加しています。そのため、旧ルールがエクスポージャーのみを理由に却下していた送金は、今後は却下されずにレビューに回されます。スクリーニングが完了すると、Diditは拡充された取引データに対してすべてのルールを自動的に再評価し、該当するWebhookをトリガーします。

次のステップ

取引の送信

暗号資産ウォレットの詳細を含めて取引を送信する方法。

ルールとスコアリング

スクリーニング結果がルールエンジンにどのように反映されるか。

コンソールガイド

コンソールで暗号資産スクリーニングの分析、資金源、ネットワークグラフを確認する方法。

はじめに

機能

リファレンス

コンソール

暗号資産・ウォレットスクリーニングAPI

スクリーニングが実行される条件

アセットとネットワークの選択

受信と送信

Lightning Network

必須フィールド

送金前の送信先スクリーニングの例

受取後の入金スクリーニングの例

対応プロバイダー

スクリーニング結果

スクリーニングステータス

インデックス未登録の取引ハッシュ

リスクスコアと重大度

資金源分析

エクスポージャーテーブル

ネットワークグラフ

ルールとの連携

ルール用のスクリーニングフィールド

次のステップ

取引の送信

ルールとスコアリング

コンソールガイド

​スクリーニングが実行される条件

​アセットとネットワークの選択

​受信と送信

​Lightning Network

​必須フィールド

​送金前の送信先スクリーニングの例

​受取後の入金スクリーニングの例

​対応プロバイダー

​スクリーニング結果

​スクリーニングステータス

​インデックス未登録の取引ハッシュ

​リスクスコアと重大度

​資金源分析

​エクスポージャーテーブル

​ネットワークグラフ

​ルールとの連携

​ルール用のスクリーニングフィールド

​次のステップ

取引の送信

ルールとスコアリング

コンソールガイド

スクリーニングが実行される条件

アセットとネットワークの選択

受信と送信

Lightning Network

必須フィールド

送金前の送信先スクリーニングの例

受取後の入金スクリーニングの例

対応プロバイダー

スクリーニング結果

スクリーニングステータス

インデックス未登録の取引ハッシュ

リスクスコアと重大度

資金源分析

エクスポージャーテーブル

ネットワークグラフ

ルールとの連携

ルール用のスクリーニングフィールド

次のステップ