메인 콘텐츠로 건너뛰기
POST
curl

왜 무상태인가

독립형 지갑 스크리닝은 거래 테이블에 아무것도 기록하지 않으므로, 이 endpoint가 렌더링할 저장된 기록이 없습니다. 대신 POST /v3/wallet-screening/이 이미 반환한 JSON 본문을 그대로 다시 전송하면, Didit이 공급자를 다시 호출하지 않고 해당 페이로드를 PDF로 렌더링합니다.

report_signature 필드

POST /v3/wallet-screening/ 응답에는 이제 report_signature 필드가 포함됩니다. 이는 애플리케이션 범위로 한정된 불투명 서명입니다. 이 endpoint는 렌더링 전에 이 서명을 검증하므로, 호출자가 risk_score, severity, sanctions_hit 또는 다른 필드를 수정해서 Didit이 생성하지 않은 결과에 대해 정상처럼 보이는 Didit 브랜드 PDF를 얻을 수는 없습니다. 항상 report_signature를 포함한 전체 응답 본문을 수정하지 않고 다시 전송하십시오. 키 순서를 바꾸는 것은 괜찮지만, 서명된 값을 변경하는 것은 허용되지 않습니다.

결제

공급자 호출이 이루어지지 않으며 결제되지 않습니다. 이 endpoint는 POST /v3/wallet-screening/을 호출할 때 이미 결제한 결과를 다시 렌더링할 뿐입니다.

오류

다음 단계

지갑 스크리닝

기반이 되는 온디맨드 지갑 스크리닝을 실행하고, 여기에 다시 전송할 JSON 결과를 가져옵니다.

온디맨드 지갑 스크리닝

독립형 지갑 스크리닝 endpoint와 결과 모델의 개요입니다.

인증

x-api-key
string
header
필수

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 를 참고하십시오.

본문

application/json

report_signature를 포함하여 POST /v3/wallet-screening/에서 반환된 수정되지 않은 JSON 객체입니다.

POST /v3/wallet-screening/ 응답과 동일한 형태입니다. report_signature를 포함하여 해당 응답 본문을 그대로 다시 전달하십시오.

provider
string
필수

스크리닝을 수행한 제공자입니다(예: merklescience, crystal).

screening_type
enum<string>
필수

이 endpoint의 경우 항상 WALLET_SCREENING입니다.

사용 가능한 옵션:
WALLET_SCREENING
risk_score
integer
필수

정규화된 0-100 위험 점수입니다. 높을수록 위험한 엔티티에 대한 노출도가 높음을 의미합니다. Merkle Science는 주소를 0-5로 등급을 매기며, 이는 0, 15, 35, 55, 75 또는 95에 매핑됩니다.

severity
enum<string>
필수

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을 긍정적인 저위험 또는 무결격 등급으로 간주하지 마십시오. 통과로 표시해서는 안 됩니다.

사용 가능한 옵션:
UNKNOWN,
LOW,
MEDIUM,
HIGH,
CRITICAL
status
enum<string>
필수

스크리닝 결과 상태입니다.

사용 가능한 옵션:
SCREENED,
PENDING,
ERROR
summary
string
필수

스크리닝 결과에 대해 사람이 읽을 수 있는 요약입니다.

wallet_address
string
필수

스크리닝된 주소로, 그대로 반환됩니다.

blockchain
string
필수

스크리닝된 블록체인입니다.

source_of_funds
object[]
필수

주소가 자금을 수취한 출처이며, 엔티티별로 귀속됩니다. 각 항목은 익스포저 세부 내역입니다.

destination_of_funds
object[]
필수

주소가 자금을 전송한 대상이며, 엔티티별로 귀속됩니다. exposure_direction = outgoing인 source_of_funds와 동일한 항목 형태를 갖습니다.

counterparty_connections
object[]
필수

제공업체가 스크리닝된 주소의 소유로 귀속시킨 엔티티입니다. Merkle Science의 경우 주소 자체의 소유자 및 사용자 태그에서 가져오므로 동일한 엔티티가 두 번 나타날 수 있으며 자금 흐름을 포함하지 않습니다(received_usd, sent_usd, received_hops, sent_hops는 null이고 percentage는 0). 여기서는 risk_level이나 is_direct를 기준으로 라우팅하지 마세요. 판정에는 sanctions_hit, dominant_risk_category, risk_factors[].is_high_risk를 사용하고, 직접성 여부에는 source_of_funds/destination_of_funds의 exposure_type을 사용하세요.

sanctions_hit
boolean
필수

주소가 직접 또는 간접적인 제재에 노출된 경우 true입니다.

dominant_risk_category
string | null
필수

가중치가 가장 높은 고위험 카테고리이거나, 지배적인 카테고리가 없는 경우 null입니다(예: sanctioned, mixer, stolen_funds).

report_signature
string
필수

애플리케이션으로 범위가 지정된, 이 정확한 결과에 대한 불투명한 HMAC-SHA256 서명입니다. 단독으로는 의미가 없으며, PDF로 렌더링하려면 이 필드를 포함하여 수정되지 않은 전체 응답 본문을 POST /v3/wallet-screening/pdf/로 다시 전송해야 합니다. report_signature가 누락되었거나 다시 전송하기 전에 서명된 필드(예: risk_score, severity, sanctions_hit)가 수정된 경우, PDF endpoint에서는 요청을 400으로 거부합니다.

transaction_hash
string | null

결과 형태와 공유되는 거래 스크리닝 필드입니다. 지갑 스크리닝 결과에서는 항상 null입니다.

block_timestamp
string | null

결과 형태와 공유되는 거래 스크리닝 필드입니다. 지갑 스크리닝 결과에서는 항상 null입니다.

total_value_usd
number | null

결과 형태와 공유되는 거래 스크리닝 필드입니다. 지갑 스크리닝 결과에서는 항상 null입니다.

fee_usd
number | null

결과 형태와 공유되는 거래 스크리닝 필드입니다. 지갑 스크리닝 결과에서는 항상 null입니다.

sender_rows
object[]

결과 형태와 공유되는 거래 스크리닝 필드입니다. 지갑 스크리닝 결과에서는 항상 비어 있습니다.

receiver_rows
object[]

결과 형태와 공유되는 거래 스크리닝 필드입니다. 지갑 스크리닝 결과에서는 항상 비어 있습니다.

transaction_flows
object[]

결과 형태와 공유되는 거래 스크리닝 필드입니다. 지갑 스크리닝 결과에서는 항상 비어 있습니다.

transaction_flows_status
string | null

결과 형태와 공유되는 거래 스크리닝 필드입니다. 지갑 스크리닝 결과에서는 항상 null입니다.

transaction_flows_error
string | null

결과 형태와 공유되는 거래 스크리닝 필드입니다. 지갑 스크리닝 결과에서는 항상 null입니다.

network_nodes
object[]

거래 스크리닝을 위한 익스포저 그래프 노드입니다. 지갑 스크리닝 결과에서는 비어 있습니다.

network_edges
object[]

거래 스크리닝을 위한 익스포저 그래프 에지입니다. 지갑 스크리닝 결과에서는 비어 있습니다.

pep_counterparty
boolean | null

정치적 주요 인물(PEP) 노출 여부입니다. PEP 결과가 없는 경우 null이며, 현재 어떤 제공업체도 이를 보고하지 않으므로 모든 결과가 이에 해당합니다. 명시적인 부정적 스크리닝 결과에 대해서만 false입니다. null을 완료된 PEP 확인으로 간주하지 마십시오.

risk_factors
object[]

risk_score에 대한 순위별 설명입니다. 이 판정이 도출된 원인을 나타냅니다. 제공자는 자체 모델을 기반으로 주소의 등급을 매기고 판정 결과만 반환하므로(Merkle Science는 0-5 사이의 정수 반환), 점수만으로는 조치를 취하기 어렵습니다. 고위험 항목이 먼저 정렬되고, 그 다음 각 요인을 통해 이동한 금액 순으로 정렬되며 상위 5개로 제한됩니다. source_of_funds 및 destination_of_funds에는 항상 전체 내역이 포함됩니다. is_high_risk 항목이 없는데 risk_score가 높다면 제공자가 제재 또는 주소에 귀속된 엔티티 일치를 보고하지 않았으며 순전히 자체 위험 노출 모델에 따라 주소 등급을 매겼음을 의미합니다. summary에 이 내용이 명시적으로 표시됩니다.

raw_response
object

공급자 자체 payload입니다. 형태는 공급자마다 다르며 사전 예고 없이 변경될 수 있으므로, 이를 직접 파싱하지 말고 정규화된 필드를 확인하십시오.

응답

렌더링된 PDF 문서로, 바이너리 application/pdf 형식으로 직접 반환됩니다. JSON 래퍼가 없습니다.

The response is of type file.

마지막 수정일 2026년 11월 7일