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

## Chainalysis Sanction을 이용한 위험 평가

<mark style="color:green;">`POST`</mark> `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의 지갑 주소에 대한 위험도를 평가할 수 있습니다. 이를 통해 거래를 요청하는 쪽의 지갑 주소에 대한 위험 요소를 사전에 파악할 수 있으며, 필요한 조치를 취할 수 있습니다.

{% hint style="info" %}
**Chainalysis Sanction API 란**

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

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

* [Chainalysis Public Sanction API Sign up](https://go.chainalysis.com/crypto-sanctions-screening.html)

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

* [Chainalysis Public Sanction API Reference](https://public.chainalysis.com/docs/index.html)
  {% endhint %}

{% hint style="warning" %}
**사전 준비 사항**

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

1. Enclave 환경 변수 설정
   * VEGA\_CHAINALYSIS\_SANCTION\_API\_KEY : [Chainalysis Public Sanction API Sign up](https://go.chainalysis.com/crypto-sanctions-screening.html) 을 통해 발급한 API Key를 입력합니다.
2. Enclave 데이터베이스 테이블 생성
   * Chainalysis Sanction API 호출 이력이 enclave 데이터베이스에 저장됩니다. 따라서 API 호출 이력의 저장을 위한 데이터베이스 테이블을 따로 생성해야 합니다.
   * 테이블 정의는 [Chainalysis Sanction Results 테이블](https://docs-kr.verifyvasp.com/getting-started/database#chainalysis-sanction-results)을 참고하시기 바랍니다.
     {% endhint %}

## Request Body

<details>

<summary>Request Body Examples</summary>

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

</details>

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

## Response Body

### 성공 케이스

<details>

<summary>Response Body Examples</summary>

* 200 OK

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

</details>

| 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     | 위험 평가가 요청된 시간                                                                      |

* <mark style="color:blue;">**chainalysisSanction.status**</mark> 필드에는 다음과 같은 값이 들어갈 수 있습니다.
  * "NOHIT" : 제재되지 않은 주소일 경우
  * "SANCTION" : 제재된 주소일 경우

### 실패 케이스

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

<details>

<summary>Response Body Examples</summary>

* 400 Bad Request

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

</details>

#### API Key가 올바르지 않을 경우

<details>

<summary>Response Body Examples</summary>

* 401 Unauthorized

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

</details>

#### 존재하지 않는 verificationUuid인 경우

<details>

<summary>Response Body Examples</summary>

* 400 Bad Request

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

</details>

#### 기타 잘못된 요청인 경우

<details>

<summary>Response Body Examples</summary>

* 400 Bad Request

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

</details>