Chainalysis Sanction 기능을 이용한 위험 평가 API

Chainalysis Sanction을 이용한 위험 평가

POST http://<enclave-endpoint>/v1/risk-assessment/chainalysis-sanction

Chainalysis Sanction API는 Chainalysis 서비스와 연계하여 가상 자산 지갑 주소의 위험도를 평가하는 데 사용하는 API입니다.

Sanction API를 호출하기 위해서는 반드시 먼저 사용자 검증(POST /verifications)을 완료해야 합니다.

Chainalysis Sanction API는 다양한 상황에서 활용될 수 있습니다. 예를 들어, 사용자가 출금 요청을 한 경우, 출금 요청을 하는 Originating VASP는 먼저 사용자 검증 API(POST /verifications)를 통해 사용자 검증을 완료해야 합니다. 그다음, Beneficiary의 지갑 주소에 대한 위험도를 평가하기 위해 Chainalysis Sanction API를 사용할 수 있습니다. 이를 통해 입금 받는 쪽의 지갑 주소가 어떤 위험 요소를 가지고 있는지 신속하게 평가할 수 있습니다.

또한, Beneficiary VASP에서도 Chainalysis Sanction API를 활용하여 Originator의 지갑 주소에 대한 위험도를 평가할 수 있습니다. 이를 통해 거래를 요청하는 쪽의 지갑 주소에 대한 위험 요소를 사전에 파악할 수 있으며, 필요한 조치를 취할 수 있습니다.

Chainalysis Sanction API 란

Chainalysis에서 제공하는 무료 API로, 특정 암호화폐 지갑 주소의 위험 정도를 판별해 주는 기능을 제공합니다. 이를 통해 송수신자의 암호화폐 지갑 주소가 얼마나 위험한지를 빠르게 확인할 수 있습니다.

Chainalysis Sanction API를 사용하기 위해서는 API 키를 발급받아야 합니다. API 키 발급을 위해서는 아래의 링크를 통해 등록 및 발급 절차를 진행할 수 있습니다. 등록과 발급 절차를 완료하면 Chainalysis sanction screening 기능을 통합하여 사용할 수 있습니다.

• Chainalysis Public Sanction API Sign up

Chainalysis Sanction API에 대한 자세한 내용은 아래의 링크를 통해 확인하실 수 있습니다. 해당 링크에서는 API의 사용 방법과 관련된 자세한 정보를 찾아볼 수 있습니다.

• Chainalysis Public Sanction API Reference

사전 준비 사항

Chainalysis Sanction API를 사용하기 위해서는 아래의 2가지 사항을 미리 준비해야 합니다.

1. Enclave 환경 변수 설정

   • VEGA_CHAINALYSIS_SANCTION_API_KEY : Chainalysis Public Sanction API Sign up 을 통해 발급한 API Key를 입력합니다.

2. Enclave 데이터베이스 테이블 생성

   • Chainalysis Sanction API 호출 이력이 enclave 데이터베이스에 저장됩니다. 따라서 API 호출 이력의 저장을 위한 데이터베이스 테이블을 따로 생성해야 합니다.

   • 테이블 정의는 Chainalysis Sanction Results 테이블을 참고하시기 바랍니다.

Request Body

Request Body Examples

{
  "verificationUuid": "d63398e3-c806-4300-bd99-170b54642080"
}

Field Name	Data Type	Required	Description
verificationUuid	string	true	위험 평가를 수행할 사전에 수행했던 트래블룰 검증 (verification)의 verificationUuid

Response Body

성공 케이스

Response Body Examples

• 200 OK

{
  "chainalysisSanction": {
    "requestId": "398ace46-6baf-4488-a9f2-ee43680b413e",
    "counterpartyVaspId": "15952089931162059995",
    "direction": "OUTGOING",
    "address": "0xBb3fd383d1C5540E52EF0A7bcb9433375793aEAF",
    "status": "NOHIT",
    "createdAt": "2023-05-26T13:34:23.053Z"
  }
}

Field Name	Data Type	Required	Description
chainalysisSanction	object	true	-
chainalysisSanction.requestId	string	true	위험 평가 요청을 구분하기 위한 식별자. verificationUuid 와는 다르며, 위험 평가를 요청할 때마다 새로 부여된다.
chainalysisSanction.counterpartyVaspId	string	true	거래 상대방 VASP의 vaspID
chainalysisSanction.direction	string	true	출금인 경우 OUTGOING, 입금인 경우 INCOMING
chainalysisSanction.address	string	true	위험 평가 대상이 되는 거래 상대방의 지갑 주소
chainalysisSanction.status	string	true	위험 평가 결과
chainalysisSanction.ofacName	string	false	status가 "SANCTION"일 경우, 제재된 주소와 연결된 OFAC name, 그 외의 경우에는 값이 전달되지 않음
chainalysisSanction.ofacDescription	string	false	status가 "SANCTION"일 경우, 제재된 주소에 대한 OFAC description, 그 외의 경우에는 값이 전달되지 않음
chainalysisSanction.ofacUrl	string	false	status가 "SANCTION"일 경우, 제제된 주소에 대한 자세한 정보를 확인할 수 있는 OFAC URL, 그 외의 경우에는 값이 전달되지 않음
chainalysisSanction.createdAt	string	true	위험 평가가 요청된 시간

• chainalysisSanction.status 필드에는 다음과 같은 값이 들어갈 수 있습니다.

  • "NOHIT" : 제재되지 않은 주소일 경우

  • "SANCTION" : 제재된 주소일 경우

실패 케이스

필수 파라미터를 입력하지 않은 경우

Response Body Examples

• 400 Bad Request

{
  "code": "MISSING-VERIFICATION-UUID",
  "message": "`verificationUuid` is required."
}

API Key가 올바르지 않을 경우

Response Body Examples

• 401 Unauthorized

{
  "code": "UNKNOWN-ERROR-CODE",
  "message": "Invalid API Key"
}

존재하지 않는 verificationUuid인 경우

Response Body Examples

• 400 Bad Request

{
  "code": "NOT-FOUND-VERIFICATION",
  "message": "Verification(8d729bf4-38db-471d-b052-896f8660916a) is not found"
}

기타 잘못된 요청인 경우

Response Body Examples

• 400 Bad Request

{
  "code": "BAD-REQUEST",
  "message": "......"
}