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.

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).

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.

Prerequisites

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

  1. Setting up Enclave Environment Variable

  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": "......"
}
PreviousRisk Assessment with Chainalysis Sanction APINextRisk Assessment with Refinitiv WCO API

Last updated