> ## 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の暗号資産スクリーニングAPIは、ウォレットと取引ハッシュを自動でスクリーニングし、リスクスコア、エクスポージャー分析、ネットワークグラフを提供します。ウォレットスクリーニングは1件あたり$0.15から。

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

> [!TIP]
>
> 取引**なしで**アドレスをスクリーニングしたい場合は、[オンデマンドのウォレットスクリーニング](https://docs.didit.me/ja/transaction-monitoring/wallet-screening.md)エンドポイント（`POST /v3/wallet-screening/`）を使用してください。1回のAPI呼び出しで、単一のウォレットについて同じリスク結果を取得できます。

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

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

1. 取引の取引詳細に`currency_kind: "crypto"`が含まれている
2. [アプリケーション設定](https://docs.didit.me/ja/transaction-monitoring/settings.md)でトランザクションモニタリングが有効になっている

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

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

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

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

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

```json theme={null}
{
  "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は送付先ウォレットをスクリーニングします。

```json theme={null}
{
  "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はお客様の入金アドレスを対象としてトランザクションハッシュをスクリーニングし、利用可能な場合は取引の概要情報をレスポンスに追加します。

```json theme={null}
{
  "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](https://business.didit.me)の**Transactions** > **Settings** > **Provider Preferences**で設定するか、コンソールの**Marketplace**(Crypto monitoringカテゴリー)から独自のプロバイダーキーを接続してください。

`LIGHTNING`は、接続キーを使用するChainalysisおよびEllipticの構成でのみサポートされます。

> [!TIP]
>
> **接続キー料金**では、既存のプロバイダーの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](https://docs.didit.me/ja/transaction-monitoring/console.md)でインタラクティブな可視化として利用できます。

## ルールとの連携

スクリーニング結果は[ルールエンジン](https://docs.didit.me/ja/transaction-monitoring/rules.md)に直接反映されます。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をトリガーします。

## 次のステップ

> [card] [取引の送信](https://docs.didit.me/ja/transaction-monitoring/transactions.md)
>
> 暗号資産ウォレットの詳細を含めて取引を送信する方法。

> [card] [ルールとスコアリング](https://docs.didit.me/ja/transaction-monitoring/rules.md)
>
> スクリーニング結果がルールエンジンにどのように反映されるか。

> [card] [コンソールガイド](https://docs.didit.me/ja/transaction-monitoring/console.md)
>
> コンソールで暗号資産スクリーニングの分析、資金源、ネットワークグラフを確認する方法。


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