> ## 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의 온디맨드 지갑 스크리닝으로 거래를 생성하지 않고도 단일 암호화폐 지갑 주소의 AML 위험을 점검하세요. 자금 출처, 제재 노출, 위험 점수를 필요할 때 바로 확인할 수 있습니다.

고객이 출금 주소를 추가하거나 컴플라이언스 팀이 특정 주소를 수시로 검토해야 하는 경우처럼, 기록할 거래가 생기기 **전에** 암호화폐 지갑의 AML 위험을 확인해야 할 때가 있습니다. 온디맨드 지갑 스크리닝 endpoint는 단일 주소를 스크리닝하고, 거래를 생성하지 않은 채 전체 위험 결과를 반환합니다.

이 endpoint는 [거래 제출](https://docs.didit.me/ko/transaction-monitoring/transactions.md) 중에 실행되는 [자동 암호화폐 스크리닝](https://docs.didit.me/ko/transaction-monitoring/aml-screening.md)의 독립형 버전입니다. 두 기능 모두 같은 블록체인 분석 제공업체를 사용하며 결과 형식도 같습니다.

## 사용 시기

| 사용 사례 | endpoint |
| - | - |
| 기록할 거래 없이 주소를 사전 확인 | **지갑 스크리닝**: `POST /v3/wallet-screening/` |
| 기록된 입금 또는 출금의 일부로 지갑 스크리닝 | `currency_kind: "crypto"`를 포함한 [거래 생성](https://docs.didit.me/ko/transaction-monitoring/transactions.md) |

지갑 스크리닝은 거래 테이블에 아무것도 기록하지 않습니다. 규칙, 알림, webhook과 함께 모니터링되는 거래에 스크리닝 결과를 연결해야 한다면 대신 거래를 제출하십시오.

## 사전 요구 사항

애플리케이션에 거래 모니터링이 구성되어 있어야 하며, 관리형 제공업체 또는 [기존 제공업체 키](https://docs.didit.me/ko/transaction-monitoring/aml-screening.md#지원되는-제공업체) 중 하나를 사용해야 합니다. [Business Console](https://business.didit.me)에서 **거래** > **설정** > **Provider Preferences** 순서로 구성하십시오. 제공업체가 구성되어 있지 않으면 endpoint는 `409 Conflict`를 반환합니다.

## 요청

`POST https://verification.didit.me/v3/wallet-screening/`

인증은 `x-api-key` 헤더로 합니다.

| 필드 | 유형 | 필수 | 설명 |
| - | - | - | - |
| `wallet_address` | string | 예 | 스크리닝할 주소 또는 네트워크 식별자입니다. 선택한 네트워크와 일치해야 합니다. 예를 들어 EVM 체인에서는 `0x` + 40자리 16진수 문자이고, Lightning 식별자는 제공업체가 허용하는 형식이어야 합니다. 별칭: `address`. |
| `blockchain` | string | 아니요 | 자산 또는 네트워크 식별자입니다. 생략하면 Didit이 주소 형식에서 네트워크를 읽습니다. `bc1`, `1`, `3` 주소는 Bitcoin(`BTC`), `T` 주소는 Tron(`TRX`), base58 공개 키는 Solana(`SOL`)로 처리합니다. `0x` 주소는 모든 EVM 네트워크에서 유효하므로 `candidate_chains`와 함께 `422`를 반환하며, 아무것도 스크리닝되거나 청구되지 않습니다. 네트워크를 지정하여 다시 요청하십시오. 그 밖의 형식은 `400`을 반환합니다. 허용되는 값: `BTC`, `LIGHTNING`, `ETH`, `LTC`, `XRP`, `BCH`, `DOGE`, `TRX`, `SOL`, `MATIC`, `BNB`, `BASE`, `OP`, `ARB`, `AVAX`, `ADA`, `XLM`, `HBAR`, `CELO`, `MODE`, `PLUME`, `USDT`, `USDC`. 일반적인 네트워크 이름도 허용됩니다. 예를 들어 `MATIC`에는 `POLYGON` 또는 `POL`, `BNB`에는 `BSC`, `TRX`에는 `TRON`을 사용할 수 있습니다. 별칭: `currency`. |
| `direction` | string | 아니요 | `inbound`, `outbound`, `deposit`, `withdrawal` 중 하나입니다. 제공업체를 위한 선택적 컨텍스트입니다. 전송 전 중립적인 스크리닝에는 생략하십시오. 반환되는 `risk_score`, `severity`, 자금 흐름 세부 내역은 이 값에 따라 달라지지 않습니다([응답](#response)의 참고 사항 참조). |

### 체인 지원 범위

관리형 스크리닝은 지갑과 거래 해시 스크리닝 모두에 대해 Base(`BASE`), Optimism(`OP`), Arbitrum One(`ARB`)을 지원합니다.
연결된 제공업체마다 지원 범위가 다를 수 있습니다. 체인은 선택한 제공업체와 계정에서도 지원되어야 합니다.
Celo(`CELO`), Mode(`MODE`), Plume(`PLUME`)은 연결된 TRM Labs 계정(Marketplace, 자체 키 사용)을 통해 스크리닝합니다. 관리형 스크리닝은 이들을 지원하지 않으며 `400`을 반환합니다.
같은 주소라도 체인마다 활동 내역과 위험도가 다를 수 있으므로, 다른 EVM 네트워크에 `ETH`를 제출하지 마십시오.

관리형 스크리닝에서 `USDT`와 `USDC`는 이전 버전과의 호환을 위한 Ethereum 별칭입니다. 이 토큰이 존재하는 모든 네트워크를 검색하지는 않습니다.
지갑이 실제로 사용하는 체인에 맞는 네트워크 식별자를 사용하십시오(`ETH`, `TRX`, `SOL`, `MATIC`, `BNB`, `BASE`, `OP`, `ARB`, `AVAX`, `ADA`, `XLM`, `HBAR`, 또는 TRM Labs 사용 시 `CELO`, `MODE`, `PLUME`).
기록된 거래의 토큰은 `transaction_details.currency`에 유지하고, 네트워크는 `transaction_details.crypto_params.crypto_chain`에 따로 지정하십시오.
자세한 내용은 [자산 및 네트워크 선택](https://docs.didit.me/ko/transaction-monitoring/aml-screening.md#자산-및-네트워크-선택)을 참조하십시오.

> [!WARNING]
>
> `LIGHTNING`은 애플리케이션에 콘솔 **Marketplace**의 연결된 Elliptic 또는 Chainalysis BYOK 제공업체가 있을 때만 사용할 수 있습니다.
> 관리형 Merkle Science, Crystal, TRM Labs에서는 사용할 수 없습니다.
> 지원되는 연결 제공업체가 없는 요청은 `400`을 반환하며, 스크리닝되거나 청구되지 않습니다.

```bash theme={null}
curl -X POST https://verification.didit.me/v3/wallet-screening/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "wallet_address": "0x94f1b9b64e2932f6a2db338f616844400cd58e8a",
    "blockchain": "ETH"
  }'
```

## Response

응답은 표준화된 스크리닝 결과이며, 거래 스크리닝에서 반환되는 `WALLET_SCREENING` 제공자 결과와 형태가 동일합니다.

| 필드 | 유형 | 설명 |
| - | - | - |
| `provider` | string | 주소를 스크리닝한 제공자(`merklescience`, `crystal`, `chainalysis`, `elliptic`, `trmlabs`). |
| `screening_type` | string | 항상 `WALLET_SCREENING`입니다. |
| `risk_score` | integer | 정규화된 0\~100 위험 점수입니다. Merkle Science는 주소를 `0-5`로 평가하며, 이는 `0`, `15`, `35`, `55`, `75` 또는 `95`에 매핑됩니다. |
| `severity` | string | `risk_score`에서 도출된 위험 구간(아래 참고): `UNKNOWN`, `LOW`, `MEDIUM`, `HIGH` 또는 `CRITICAL`. |
| `status` | string | `SCREENED`, `PENDING` 또는 `ERROR`. |
| `summary` | string | 사람이 읽을 수 있는 요약입니다. |
| `wallet_address` | string | 스크리닝된 주소입니다. |
| `blockchain` | string | 스크리닝된 체인입니다. |
| `sanctions_hit` | boolean | 스크리닝된 지갑이 제재 대상이거나, 거래 상대방의 자금 중 일부가 제재 대상 기관에서 왔을 때(노출) `true`입니다. 두 경우를 구분하지 않습니다. |
| `pep_counterparty` | boolean \| null | 정치적 주요 인물(PEP) 노출 여부입니다. 사용 가능한 PEP 결과가 없을 때 `null`이며, 현재는 제공자가 PEP 결과를 보고하지 않으므로 모든 결과가 해당합니다. `false`는 명시적인 음성 스크리닝 결과일 때만 반환됩니다. `null`을 PEP 점검이 완료되었다는 의미로 해석하지 마십시오. |
| `dominant_risk_category` | string \| null | 가장 높은 가중치를 받은 고위험 카테고리이며, 없으면 `null`입니다. |
| `risk_factors` | array | `risk_score`에 대한 순위별 설명으로, 이 판정이 어떻게 도출되었는지를 보여 줍니다. [위험 요인](#위험-요인)을 참고하십시오. |
| `source_of_funds` | array | 자금을 어디에서 받았는지 엔터티별로 나타냅니다. [노출 내역](#노출-내역)을 참고하십시오. |
| `destination_of_funds` | array | 자금을 어디로 보냈는지 엔터티별로 나타냅니다. 항목 형태는 `source_of_funds`와 같습니다. |
| `counterparty_connections` | array | 제공자가 해당 주소와 연결된다고 판단한 기관입니다. [거래 상대방 연결](#거래-상대방-연결)을 참고하십시오. |
| `network_nodes`, `network_edges` | array | 거래 스크리닝에서의 노출 그래프입니다. 지갑 스크리닝 결과에서는 비어 있습니다. |
| `transaction_hash`, `block_timestamp`, `total_value_usd`, `fee_usd`, `transaction_flows_status`, `transaction_flows_error` | null | 결과 형태를 거래 스크리닝과 공유하는 거래 스크리닝 필드입니다. 지갑 스크리닝 결과에서는 항상 `null`입니다. |
| `sender_rows`, `receiver_rows`, `transaction_flows` | array | 거래 스크리닝 필드입니다. 지갑 스크리닝 결과에서는 항상 비어 있습니다. |
| `raw_response` | object | 제공자의 원본 페이로드입니다. 형태는 제공자마다 다르며 예고 없이 바뀔 수 있으므로, 이를 파싱하지 말고 위의 정규화된 필드를 사용하십시오. |
| `report_signature` | string | 귀사의 애플리케이션 범위에 한정된, 이 결과에 대한 불투명 서명입니다. [PDF로 렌더링](#pdf-보고서)하려면 이 필드를 포함하여 응답을 수정하지 않고 그대로 다시 전송하십시오. |

> [!NOTE]
>
> **`severity`가 설정되는 방식.** `severity`는 정규화된 `risk_score`가 속한 구간입니다. `0-9` → `UNKNOWN`, `10-39` → `LOW`, `40-69` → `MEDIUM`, `70-89` → `HIGH`, `90-100` → `CRITICAL`입니다. `UNKNOWN`은 가장 낮은 구간이지, "데이터 없음" 상태를 뜻하지 않습니다. `risk_score: 0`(일반적인 깨끗한 주소의 경우)은 제공자가 부정적인 평가를 반환하지 않았다는 뜻이고, `1-9` 범위의 0이 아닌 점수는 실제 신호지만 `LOW` 미만의 수준입니다. 따라서 구간만 보지 말고 `risk_score` 자체를 확인하십시오. 어느 경우든 `UNKNOWN`을 "안전" 또는 "통과"로 표시하지 마십시오.
>
> **`direction`은 위험 모델을 바꾸지 않습니다.** 선택 사항인 `direction` 필드는 컨텍스트로만 제공자에게 전달됩니다. `risk_score`, `severity` 또는 반환되는 노출 내역 목록에는 영향을 주지 않습니다. `source_of_funds`와 `destination_of_funds`는 항상 모두 반환됩니다. 따라서 `direction`을 변경하거나 생략해도 이미 스크리닝된 주소를 다시 스크리닝할 필요는 없습니다.

### 위험 요인

`risk_factors`는 "이 주소의 점수가 왜 이렇게 매겨졌는가"에 대한 순위별 답변입니다. 제공자는 자체 모델로 주소를 평가하며 판정만 반환합니다. 예를 들어 Merkle Science는 정수 `0-5`를 반환하므로, `risk_score`만으로는 조치를 취할 수 없습니다. 각 항목은 하나의 요인을 나타내며, 고위험 항목이 먼저 오고 그다음에는 해당 요인을 통해 이동한 금액 순으로 정렬됩니다.

| 필드 | 유형 | 설명 |
| - | - | - |
| `source` | string | `attribution`(제공자가 해당 주소를 무엇이라고 보는지, 즉 제공자 자체의 태그 또는 클러스터) 또는 `exposure`(자금이 실제로 이동한 경로)입니다. |
| `category` | string | 정규화된 위험 카테고리이며, 노출 내역과 같은 용어 체계를 사용합니다. |
| `label` | string | 제공자 자체의 표현입니다(예: `Gambling / Crypto only`). UI에 이 값을 사용하십시오. 제공자 콘솔에서 보이는 내용과 일치합니다. |
| `entity_name` | string \| null | 귀속된 엔터티입니다(예: 도박 사이트 또는 거래소). 이 페이지의 예시는 `Example Gambling`과 같은 자리표시자를 사용합니다. |
| `direction` | string | `incoming`, `outgoing`, `connected`, `attribution`(주소 자체의 태그) 또는 제공자가 방향을 보고하지 않았을 때의 `unknown`입니다. |
| `exposure_type` | string | `direct`(1홉), `indirect`(다중 홉), `attribution`(주소 자체의 태그), 또는 제공자가 거래 상대방이 몇 홉 떨어져 있는지 밝히지 않았을 때의 `unknown`입니다. `unknown`은 분류되지 않은 것으로 취급하며, 절대 `direct`로 취급하지 마십시오. |
| `amount_usd` | number \| null | 이 요인에 귀속된 USD 금액입니다. |
| `percentage` | number | 양방향을 합산한 해당 주소의 **전체 스크리닝 거래량**에서 차지하는 비율입니다. 방향별로 정규화되는 `source_of_funds` / `destination_of_funds` 내부의 `percentage`와 다르며, 전체 목록에서 비교하고 합산할 수 있습니다. |
| `is_high_risk` | boolean | Didit이 고위험으로 취급하는 카테고리인지 여부입니다(`sanctioned`, `mixer`, `stolen_funds`, `ransomware`, `scam`, `darknet_market`, `terrorist_financing`, `child_exploitation`, `hacked_exchange`, `high_risk_exchange`, `seized_funds`). |
| `description` | string | 요인에 대한 한 줄 설명입니다(예: `9.01% indirect outgoing exposure to Gambling / Crypto only (Example Gambling)`). |

> [!NOTE]
>
> **고점수이지만 `is_high_risk` 요인이 없는 경우도 실제로 의미 있는 결과입니다.** 제공자가 제재, PEP 또는 귀속된 기관 일치 여부를 보고하지 않은 채 자체 노출 모델로 주소를 평가했다는 뜻입니다. 목록에 있는 요인은 점수의 근거가 된 자금 흐름입니다. `summary`에 이 점이 명시되므로, 이런 주소는 확인된 일치 결과가 아니라 "흐름을 검토할 대상"으로 취급하십시오. `risk_factors`는 가장 강한 다섯 가지 요인으로 제한되며, `source_of_funds`와 `destination_of_funds`에는 전체 내역이 항상 포함됩니다.
>
> **`risk_factors`는 최상위 필드이며 중첩된 필드가 아닙니다.** 이 필드가 도입되기 전에 스크리닝된 결과에는 키 자체가 없습니다. 이 경우 설명이 비어 있다고 가정하지 말고 빈 목록으로 읽으십시오.

### 노출 내역

`source_of_funds` / `destination_of_funds`의 각 항목은 주소가 자금을 주고받은 엔티티 하나를 나타냅니다.

| 필드 | 타입 | 설명 |
| - | - | - |
| `category` | string | 정규화된 위험 카테고리(`exchange_licensed`, `dex`, `defi`, `mixer`, `sanctioned`, `darknet_market`, `stolen_funds`, …)입니다. |
| `entity_name` | string \| null | 귀속된 엔티티입니다(예: 거래소, 믹서, 제재 대상 단체). 이 페이지의 예시는 자리표시자를 사용합니다. |
| `entity_type` | string \| null | 제공자의 엔티티 유형입니다(`Exchange`, `DeFi`, `Sanctions`). |
| `entity_subtype` | string \| null | 세부 하위 유형입니다(`Mandatory KYC and AML`, `OFAC`). |
| `description` | string \| null | `entity_type / entity_subtype` 형식이며, 제공자가 해당 엔티티에 붙인 라벨과 같습니다. |
| `exposure_direction` | string | `incoming`, `outgoing` 또는 `connected`입니다. |
| `exposure_type` | string | `direct`(1홉) 또는 `indirect`(다중 홉)입니다. |
| `is_direct` | boolean | `exposure_type`이 `direct`이면 `true`입니다. |
| `amount_usd` | number \| null | 엔티티에 귀속된 USD 금액입니다. |
| `percentage` | number | 해당 방향 전체 노출에서 차지하는 비율(0–100)입니다. |
| `hops` | integer \| null | 엔티티까지의 홉 수입니다(직접 거래 상대방이면 `1`). 제공자가 보고하는 경우에만 제공됩니다. Merkle Science는 노출이 직접인지 간접인지만 보고하므로 항상 `null`입니다. 이 경우 `exposure_type`을 사용하십시오. |
| `country` | string \| null | 엔티티의 주 ISO 3166-1 alpha-2 국가 코드입니다. 제공자가 알지 못하는 경우 비어 있거나 `null`입니다. |
| `provider_entity_id`, `provider_entity_type_id`, `provider_entity_subtype_id` | string \| null | 엔티티와 그 유형에 대한 제공자 고유 식별자입니다. |
| `raw_amount`, `raw_currency` | number \| null, string \| null | 제공자가 보고하는 경우 자산 고유 단위로 된 금액입니다. |

### 거래 상대방 연결

`counterparty_connections`에는 제공자가 스크리닝된 주소에 귀속시킨 엔티티가 나열됩니다. Merkle Science의 경우 이 값은 주소 자체의 소유자 태그와 사용자 태그에서 가져오므로 같은 엔티티가 두 번 나타날 수 있습니다. 또한 자금 흐름 정보가 없으므로 `received_usd`, `sent_usd`, `received_hops`, `sent_hops`는 `null`이고 `percentage`는 `0.0`입니다. 자금 흐름은 `source_of_funds`와 `destination_of_funds`에서 확인하십시오.

| 필드 | 타입 | 설명 |
| - | - | - |
| `entity_name` | string \| null | 귀속된 엔티티입니다. |
| `entity_type` | string \| null | 제공자의 엔티티 유형입니다. |
| `entity_subtype` | string \| null | 세부 하위 유형입니다. |
| `categories` | array | 엔티티의 정규화된 위험 카테고리입니다. |
| `risk_level` | string | 소문자이며 제공자에 따라 다릅니다. Merkle Science의 경우 주소 자체의 0–5 위험 등급(`no_risk`, `low`, `medium_low`, `medium`, `high`, `critical`)이며, 엔티티의 카테고리가 고위험인 경우 `high`로 상향됩니다. 엔티티 자체에 대한 별도 등급이 아닙니다. |
| `is_direct` | boolean | Merkle Science의 경우 항상 `true`입니다. 이 연결은 거래 상대방이 아니라 귀속이기 때문입니다. |
| `received_usd`, `sent_usd` | number \| null | 제공자가 보고하는 경우 엔티티로부터 받은 USD와 엔티티로 보낸 USD입니다. |
| `received_hops`, `sent_hops` | integer \| null | 제공자가 보고하는 경우 각 방향의 엔티티까지 홉 수입니다. |
| `percentage` | number | 제공자가 보고하는 경우 주소 노출에서 차지하는 비율이며, 그렇지 않으면 `0.0`입니다. |
| `country` | string \| null | 알려진 경우 엔티티의 국가입니다. |
| `provider_entity_id` | string \| null | 엔티티에 대한 제공자 고유 식별자입니다. |

> [!WARNING]
>
> `counterparty_connections[].risk_level`과 `counterparty_connections[].is_direct`를 분기 조건으로 사용하지 마십시오. Merkle Science의 경우 전자는 주소 자체의 등급을 반복하고(`risk_score`를 확인하십시오), 후자는 항상 `true`입니다. 판정에는 `sanctions_hit`, `dominant_risk_category`, `risk_factors[].is_high_risk`를 사용하고, 직접성 여부에는 `source_of_funds` / `destination_of_funds`의 `exposure_type`을 사용하십시오.

### 예시

Merkle Science로 OFAC 제재 목록에 있는 주소를 스크리닝한 실제 응답입니다. `raw_response`만 줄였고 `report_signature`는 대체했습니다.

```json theme={null}
{
  "provider": "merklescience",
  "screening_type": "WALLET_SCREENING",
  "risk_score": 95,
  "severity": "CRITICAL",
  "status": "SCREENED",
  "summary": "Merkle Science risk: Critical (5/5). SANCTIONS HIT. Dominant risk: sanctioned. Driven by: the address is attributed to Sanctions / OFAC (Example Sanctions)",
  "wallet_address": "0x94f1b9b64e2932f6a2db338f616844400cd58e8a",
  "transaction_hash": null,
  "blockchain": "ETH",
  "block_timestamp": null,
  "total_value_usd": null,
  "fee_usd": null,
  "sender_rows": [],
  "receiver_rows": [],
  "transaction_flows": [],
  "transaction_flows_status": null,
  "transaction_flows_error": null,
  "source_of_funds": [
    {
      "category": "sanctioned",
      "percentage": 100.0,
      "amount_usd": 9813695.0,
      "entity_name": "Example Sanctions",
      "entity_type": "Sanctions",
      "entity_subtype": "OFAC",
      "hops": null,
      "description": "Sanctions / OFAC",
      "is_direct": true,
      "exposure_direction": "incoming",
      "exposure_type": "direct",
      "provider_entity_id": "118885",
      "provider_entity_type_id": "30",
      "provider_entity_subtype_id": "125",
      "country": "",
      "raw_amount": null,
      "raw_currency": null
    }
  ],
  "destination_of_funds": [
    {
      "category": "defi",
      "percentage": 84.824453,
      "amount_usd": 7783414.38,
      "entity_name": "Example DeFi 7",
      "entity_type": "DeFi",
      "entity_subtype": "Bridges",
      "hops": null,
      "description": "DeFi / Bridges",
      "is_direct": false,
      "exposure_direction": "outgoing",
      "exposure_type": "indirect",
      "provider_entity_id": "118459",
      "provider_entity_type_id": "33",
      "provider_entity_subtype_id": "143",
      "country": "",
      "raw_amount": null,
      "raw_currency": null
    },
    {
      "category": "defi",
      "percentage": 15.175547,
      "amount_usd": 1392494.37,
      "entity_name": "Example DeFi 2",
      "entity_type": "DeFi",
      "entity_subtype": "Yield Aggregator",
      "hops": null,
      "description": "DeFi / Yield Aggregator",
      "is_direct": false,
      "exposure_direction": "outgoing",
      "exposure_type": "indirect",
      "provider_entity_id": "90192",
      "provider_entity_type_id": "33",
      "provider_entity_subtype_id": "142",
      "country": "",
      "raw_amount": null,
      "raw_currency": null
    }
  ],
  "counterparty_connections": [
    {
      "entity_name": "Example Sanctions",
      "entity_type": "Sanctions",
      "entity_subtype": "OFAC",
      "risk_level": "critical",
      "categories": [
        "sanctioned"
      ],
      "received_usd": null,
      "sent_usd": null,
      "received_hops": null,
      "sent_hops": null,
      "percentage": 0.0,
      "is_direct": true,
      "country": null,
      "provider_entity_id": null
    },
    {
      "entity_name": "Example Sanctions",
      "entity_type": "Sanctions",
      "entity_subtype": "OFAC",
      "risk_level": "critical",
      "categories": [
        "sanctioned"
      ],
      "received_usd": null,
      "sent_usd": null,
      "received_hops": null,
      "sent_hops": null,
      "percentage": 0.0,
      "is_direct": true,
      "country": null,
      "provider_entity_id": null
    }
  ],
  "network_nodes": [],
  "network_edges": [],
  "sanctions_hit": true,
  "pep_counterparty": null,
  "dominant_risk_category": "sanctioned",
  "risk_factors": [
    {
      "source": "attribution",
      "category": "sanctioned",
      "label": "Sanctions / OFAC",
      "entity_name": "Example Sanctions",
      "direction": "attribution",
      "exposure_type": "attribution",
      "amount_usd": null,
      "percentage": 0.0,
      "is_high_risk": true,
      "description": "the address is attributed to Sanctions / OFAC (Example Sanctions)"
    },
    {
      "source": "exposure",
      "category": "sanctioned",
      "label": "Sanctions / OFAC",
      "entity_name": "Example Sanctions",
      "direction": "incoming",
      "exposure_type": "direct",
      "amount_usd": 9813695.0,
      "percentage": 51.679304,
      "is_high_risk": true,
      "description": "51.6793% direct incoming exposure to Sanctions / OFAC (Example Sanctions)"
    },
    {
      "source": "exposure",
      "category": "defi",
      "label": "DeFi / Bridges",
      "entity_name": "Example DeFi 7",
      "direction": "outgoing",
      "exposure_type": "indirect",
      "amount_usd": 7783414.38,
      "percentage": 40.987766,
      "is_high_risk": false,
      "description": "40.9878% indirect outgoing exposure to DeFi / Bridges (Example DeFi 7)"
    },
    {
      "source": "exposure",
      "category": "defi",
      "label": "DeFi / Yield Aggregator",
      "entity_name": "Example DeFi 2",
      "direction": "outgoing",
      "exposure_type": "indirect",
      "amount_usd": 1392494.37,
      "percentage": 7.33293,
      "is_high_risk": false,
      "description": "7.33293% indirect outgoing exposure to DeFi / Yield Aggregator (Example DeFi 2)"
    }
  ],
  "raw_response": {
    "...": "provider-specific details"
  },
  "report_signature": "<hmac-sha256 over the result, scoped to your application>"
}
```

이 예시는 응답 구조를 보여 주기 위한 것이며, 실제 주소에 대한 판정을 보장하지 않습니다. 위험 점수와 제재 노출은 선택한 네트워크, 최신 인텔리전스 및 구성된 위험 정책에 따라 달라집니다. 거래소 귀속이 위험 점수 0을 의미하지는 않습니다. 거래소 지갑도 자금 흐름을 통해 제재 노출을 가질 수 있습니다.
`sanctions_hit: true`는 지갑 자체가 제재 대상임을 나타낼 수도 있고 자금에 제재 노출이 있음을 나타낼 수도 있습니다. 따라서 이 값만으로 스크리닝된 지갑 소유자가 제재 대상이라는 뜻은 아닙니다.
같은 스크리닝이 기록된 거래에 대해 실행되면 규칙은 `custom_values.wallet_sanctioned`를 읽을 수 있으며, 이 값은 제공자가 지갑 자체를 제재 대상 엔티티에 귀속시킨 경우에만 `true`입니다. 또한 `custom_values.aml_sanctions_exposure_pct`도 읽을 수 있습니다.
[규칙용 스크리닝 필드](https://docs.didit.me/ko/transaction-monitoring/aml-screening.md#규칙용-스크리닝-필드)를 참조하십시오.
귀속과 노출을 구분하려면 `risk_factors`, `source_of_funds`, `destination_of_funds`를 함께 읽으십시오.
단계별 설명은 [암호화폐 및 지갑 스크리닝](https://docs.didit.me/ko/transaction-monitoring/aml-screening.md#스크리닝-결과)을 참조하십시오.

## PDF 보고서

스크리닝 결과의 Didit 브랜드 PDF를 받으려면 `report_signature`를 포함한 응답 본문 전체를 그대로 `POST /v3/wallet-screening/pdf/`에 다시 전송하십시오. 이 요청은 상태를 저장하지 않습니다. 제공자 호출이 없고 추가 요금도 없으며 아무것도 저장되지 않습니다. 재전송 전에 서명된 필드(`risk_score`, `severity`, `sanctions_hit` 등)를 하나라도 수정하면 `400`으로 실패합니다.

```bash theme={null}
RESULT=$(curl -s -X POST https://verification.didit.me/v3/wallet-screening/ \
  -H "x-api-key: YOUR_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: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d "$RESULT" \
  -o wallet_screening_report.pdf
```

전체 요청/응답 스키마와 오류 형식은 [지갑 스크리닝 PDF](https://docs.didit.me/ko/management-api/transactions/screen-wallet-pdf.md)를 참조하십시오.

## Billing

AML 모니터링 사용량 1회는 성공한 스크리닝마다 과금되며, 요금은 거래 연동 암호화폐 스크리닝과 동일합니다. 관리형 및 연결된 키의 요금은 [요금](https://docs.didit.me/ko/transaction-monitoring/aml-screening.md#지원되는-제공업체)을 참조하세요. 샌드박스 애플리케이션은 과금되지 않습니다. 유효성 검사 오류(`400`)와 AML 제공자가 구성되지 않은 오류(`409`)는 절대 과금되지 않습니다.

## 오류

| 상태 | 의미 |
| - | - |
| `400` | 잘못된 형식의 주소, `wallet_address` 누락 또는 지원되지 않는 `blockchain`. |
| `401` | `x-api-key`가 없거나 유효하지 않음. |
| `409` | 애플리케이션에 AML 제공자가 구성되지 않음. 먼저 거래 모니터링을 구성하세요. |
| `409` | 연결한 API 키를 제공자가 거부함(`wallet_screening_provider_credentials_rejected`). Marketplace 연결에서 키를 업데이트하거나, 해당 키가 거래 모니터링 설정에서 구성된 경우 그곳에서 업데이트하세요. 같은 키로 재시도해도 도움이 되지 않습니다. |
| `409` | 구성된 AML 제공자가 아직 지갑 스크리닝을 지원하지 않음(`wallet_screening_provider_unavailable`). |
| `422` | `blockchain` 없이 `0x` 주소를 보냄(`wallet_screening_chain_undetermined`). 응답 본문에 `candidate_chains`가 나열되며, 그중 하나를 포함하여 다시 요청하세요. 스크리닝이 수행되지 않으며 과금되지도 않습니다. |
| `502` | 제공자가 스크리닝을 완료하지 못함. 나중에 다시 시도하세요. |

## 다음 단계

> [card] [API 레퍼런스](https://docs.didit.me/ko/management-api/transactions/screen-wallet.md)
>
> Screen Wallet endpoint의 전체 요청 및 응답 스키마.

> [card] [Screen Wallet PDF](https://docs.didit.me/ko/management-api/transactions/screen-wallet-pdf.md)
>
> 스크리닝 결과를 Didit 브랜드가 적용된 PDF로 렌더링합니다.

> [card] [암호화폐 및 지갑 스크리닝](https://docs.didit.me/ko/transaction-monitoring/aml-screening.md)
>
> 거래 생성 중 자동 스크리닝과 결과 모델.


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