Risk Assessment with Chainalysis KYT API

Risk Assessment with Chainalysis KYT API

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

Chainalysis KYT (Know Your Transaction) API is used to assess the risk level of virtual asset wallet address or transaction, based on underlying Chainalysis service. It is necessary to complete user verification (POST /verifications) before calling KYT API. The Chainalysis KYT API works differently depending on before or after Transaction Result(Txhash) Report

1. Before Transaction Result(Txhash) Report:

   • Originating VASP : Assess the risk level of the Beneficiary’s wallet address.

   • Beneficiary VASP : Unable to call KYT API and returns UNSUPPORTED-RISK-ASSESSMENT error when KYT API is called. Therefore, the Beneficiary VASP cannot use this API before Transaction Result Report.

2. After Transaction Result(Txhash) Report:

   • Originating VASP : Assess the risk level of withdrawal transaction.

   • Beneficiary VASP : Assess the risk level of deposit transaction.

Chainalysis KYT API

The Chainalysis KYT API is a paid API that provides 2 types of functionalities:

1. Withdrawal Attempt Type: Allows VASPs to assess the risk level of the Beneficiary’s deposit address before initiating a withdrawal.

2. Transfer Type: Allows VASPs to assess the risk level of actual transactions.

The Chainalysis KYT API provides more accurate risk assessment than the Chainalysis Sanction API.

In order to use Chainalysis KYT API, VASPs need to sign up on Chainalysis and purchase a license. Please refer to the following link to request KYT API subscription. Alternatively please approach your point of contact within VerifyVASP for an introduction with Chainalysis team.

• Chainalysis KYT

After acquiring the Chainalysis KYT API license, VASP can access to KYT API key by signing in KYT Console. After signing in, click the ‘Help’ icon and refer to the ‘Developers’, ‘API Keys’ menu. (Please go to ‘Help’ > ‘Developers’ > ‘API Keys’ after signing in).

• Chainalysis KYT Console Site

The Chainalysis KYT API operates asynchronously. VASP Registers the subject(withdrawal attempt or transfer) for risk assessment with Chainalysis and receives the results for the registered request via Inquiry API. Please refer to the following link for more information on Chainalysis KYT API.

• Chainalysis KYT API Reference

• Chainalysis KYT Developer Guide

Prerequisites

Following 2 items need to be prepared in advance to use KYT API:

1. Setting up Enclave Environment Variable

   • VEGA_CHAINALYSIS_KYT_API_KEY : Enter the API key issued from Chainalysis KYT Console Site.

2. Creating Enclave Database Table

   • The history of Chainalysis KYT API calls and the resulting KYT alerts are stored in the enclave database. Therefore, it is necessary to create a separate database table.

   • For more information on the requirements of the database, please refer to the Chainalysis KYT Results Table and Chainalysis KYT Alerts Table.

Request Body

Request Body Examples

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

Field Name	Data Type	Required	Description
verificationUuid	string	true	Verification UUID for Travel Rule verification which will be subject to risk assessment
network	string	false	Input to specify network(transfer of virtual asset) for the Travel Rule verification previously performed

• Virtual assets like USDT can exist on several blockchain networks such as Ethereum, Tron, and EOS, making it difficult to proceed risk assessment without specifying which network the transfer was made.

• Therefore, in cases where the network for virtual asset varies like USDT, the network property can be used to specify the exact network on which the transaction occurred.

• For Network type, please refer to Supported networks and assets.

Response Body

Success Cases

Response Body Examples

• 200 OK

{
  "requestId": "f7231c6f-f1e7-4ae7-b143-2c87cd38abe9"
}

Field Name	Data Type	Required	Description
requestId	string	true	An identifier to distinguish risk assessment requests. It is different from the verificationUuid and is issued for each risk assessment.

The Chainalysis KYT operates asynchronously. Therefore, the results are not returned immediately upon calling the API. The results of the risk assessment using the Chainalysis KYT are delivered through the Callback VASP API. The risk assessment results delivered through Callback VASP API has the following format.

Request Body Example for CHAINALYSIS_KYT_RESULT callbackType

{
  "callbackType": "CHAINALYSIS_KYT_RESULT",
  "data": {
    "verificationUuid": "69a310e6-810f-4a31-83d1-bcdafccf5304",
    "riskAssessment": {
      "chainalysisKYT": {
        "requestId": "f7231c6f-f1e7-4ae7-b143-2c87cd38abe9",
        "counterpartyVaspId": "15952089931162059995",
        "apiType": "ATTEMPT",
        "userId": "15952089931162059995",
        "direction": "OUTGOING",
        "network": "ETHEREUM",
        "asset": "ETH",
        "amount": "1",
        "usdPrice": "1820.17",
        "outputAddress": "bb3fd383d1c5540e52ef0a7bcb9433375793aeaf",
        "timestamp": "2023-05-18T12:39:44.000Z",
        "externalId": "79382ac9-c7be-3fab-ad56-8c61c654e2fc",
        "status": "PROCESSED",
        "alertCount": 1,
        "createdAt": "2023-05-18T12:39:46.000Z",
        "assessedAt": "2023-05-18T12:39:45.263Z"
      },
      "chainalysisKYTAlerts": [
        {
          "counterpartyVaspId": "15952089931162059995",
          "externalId": "79382ac9-c7be-3fab-ad56-8c61c654e2fc",
          "direction": "OUTGOING",
          "alertId": "118b8cc8-f579-11ed-b86d-a3210c6ca9b8",
          "alertLevel": "MEDIUM",
          "entityCategory": "high risk exchange",
          "serviceName": "HIGH RISK EXCHANGE: SimpleSwap.io bb3fd383d1c5540e52ef0a7bcb9433375793aeaf",
          "exposureType": "DIRECT",
          "alertAmount": "1820.17",
          "createdAt": "2023-05-18T12:39:52.461Z"
        }
      ]
    }
  }
}

When the risk assessment result is delivered, the riskAssessment property is provided, and among them, the risk assessment result using the KYT API is conveyed through the chainalysisKYT property under riskAssessment.

chainalysisKYT structure has the following attributes.

Field Name	Data Type	Required	Description
requestId	string	true	An identifier to distinguish each risk assessment request.
counterpartyVaspId	string	true	Counterparty VASP’s vaspId
apiType	string	true	The value that distinguishes which API type was used when calling the Chainalysis KYT API, assessing the risk of the counterparty's wallet address before withdrawal is 'ATTEMPT', and assessing the risk of a transaction is 'TRANSFER'.
userId	string	true	The userId provided when calling the Chainalysis KYT API, the counterparty VASP ID will be used.
direction	string	true	‘OUTGOING’ for withdrawal, ‘INCOMING’ for deposit
network	string	true	The name of the blockchain network where the transaction will take place
asset	string	true	The type of virtual asset being transferred, or that has been transferred, Ticker
amount	string	true	The quantity of the virtual asset being transferred, or that has been transferred
usdPrice	string	false	The USD equivalent value of the virtual asset being transferred, or that has been transferred
transferRef	string	false	In the case of apiType as 'TRANSFER', it’s the identifier of the transaction subject to risk assessment. The format varies with blockchain network, it generally takes the form of '<tx_hash>:<output_address>'.
outputAddress	string	true	The wallet address subject to the risk assessment.
timestamp	string	true	The time when the transaction subject to risk assessment occurred; if the apiType is 'ATTEMPT', it is the time when the KYT API was called.
externalId	string	false	ID issued by Chainalysis to distinguish each risk assessment request; not issued if the KYT API call is failed.
status	string	true	The status of the risk assessment request; 'REGISTERED' if the results have not yet been obtained, and 'PROCESSED' if the risk assessment results are available
alertCount	number	false	The number of KYT alerts for the result of risk assessment; ‘null’ if the status is not 'PROCESSED'. If the number of alerts is one or more, the KYT alerts are delivered in a separate array.
createdAt	string	true	The time when the risk assessment history was created.
assessedAt	string	false	The time when the risk assessment result was created from Chainalysis.

If the risk assessment result using the Chainalysis KYT yields an alertCount of one or more, the KYT alerts are delivered through the chainalysisKYTAlerts property under riskAssessment as mentioned above.

The chainalysisKYTAlerts property is an array and contains elements equal to the number of alertCount. Each element has the following attributes.

Field Name	Data Type	Required	Description
counterpartyVaspId	string	true	Counterparty VASP’s vaspId
externalId	string	true	ID issued by Chainalysis to distinguish each risk assessment request. It is used to identify which KYT request generate this alert.
direction	string	true	‘OUTGOING’ for withdrawal, ‘INCOMING’ for deposit
alertId	string	true	ID issued by Chainalysis to distinguish each KYT alert
alertLevel	string	true	The risk level of the KYT alert, which can have values of 'LOW', 'MEDIUM', 'HIGH', 'SEVERE', in ascending order of risk
entityCategory	string	false	The category of the entity being tracked by the Alert rule, please refer to the description below.
serviceName	string	false	The name of the counterparty’s service defined by Chainalysis; if the service name has not yet been identified or in the case of INDIRECT exposure, returns ‘null’.
exposureType	string	true	Defines the exposure type, 'DIRECT' or 'INDIRECT'
alertAmount	string	true	The scale of the funds subject to the KYT alert, in USD units
createdAt	string	true	The time when the KYT alert was created

entityCategory is a category defined by Chainalysis. List of Category can be found on following URL. Logging in to Chainalysis KYT dashboard is required.

List of Entity Category

Failed Cases

Missing mandatory parameter case

Response Body Examples

• 400 Bad Request

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

Incorrect API Key

Response Body Examples

• 403 Forbidden

{
  "code": "UNKNOWN-ERROR-CODE",
  "message": "AccessDenied"
}

Invalid verificationUuid

Response Body Examples

• 400 Bad Request

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

API called before Transaction Result Report arrived to the Beneficiary VASP

Response Body Examples

• 400 Bad Request

{
  "code": "UNSUPPORTED-RISK-ASSESSMENT",
  "message": "Chainalysis KYT API for received transfer should be called after txHash is reported"
}

Incorrect requests

Response Body Examples

• 400 Bad Request

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