NAV
shell

KYT Introduction

Chainalysis Know Your Transaction (KYT) is an automated, real-time cryptocurrency transaction monitoring and compliance solution. At the core of KYT is a REST-based API that provides you with real-time transaction risk monitoring, alerts on risky transfers, and comprehensive user risk profiles, among other features. The API allows your internal business systems and Chainalysis's technology to communicate with each other.

Getting Started

Registering transfers is required to get the full value of KYT: real-time transaction screening, generating alerts, and building user and transaction risk profiles, among other features.

You can submit transfers via the API and KYT will provide real-time insights on the transfer and counterparty involved. KYT will automatically monitor each transaction posted for changes in exposure and counterparty risk. All alerts, user risk scores, and transfer profile updates will be reflected in both the KYT Dashboard and API responses.

See the KYT Integration Guide below for information on integrating with the API including, various implementations and example compliance workflows.

About the KYT API

KYT’s API is a REST-based web service that has uniform resource endpoints (/alerts, /transfers/sent), accepts a request body (your data), uses standard HTTP response codes (200, 404, 503), and returns responses in JSON.

After integrating your data into KYT, the API returns additional information on transfers, alerts, and user risk than the KYT interface alone, showing you a more comprehensive picture of risky activity.

Sorting and filtering is available on many endpoints to help facilitate workflows. For example, you can query for all alerts created between certain dates, see exposure details on a specific user, or pre-screen for counterparty risk within your withdrawal workflow.

All times are in UTC.

What's New

See below for KYT API releases, updates, and changes.

March 31, 2021

We've recently added Algorand as a supported asset.

For your transfers, KYT includes staking rewards where present. Algorand block explorers display staking rewards separately from the main payment transfer(s). Therefore, block explorers may introduce a discrepancy in the output index, e.g. a block explorer presents a counterparty at position 0, yet our representation shows the same counterparty at position 2. For this reason, you should include the output address, rather than output index, in transfer references for your KYT API requests.

View all the assets that Chainalysis supports here.

October 28, 2020

We’ve recently added support for another 16 ERC-20 tokens. These include DeFi tokens, one of the most exciting and talked about areas of crypto, and a tranche of stable coins. Chainalysis now supports over 100 cryptocurrency assets. See the complete list of assets that KYT suppports here.

June 8, 2020

Chainalysis has launched support for two notable cryptocurrencies: Dash and Zcash. As two of the most popular so-called “privacy coins” — cryptocurrencies with privacy enhancing features encoded into their protocols — they account for over $1.5 billion of reported daily trading volume.

Our latest blog post explains how these two privacy coins allow investigators and compliance professionals to investigate and monitor illicit activity using our products.

See all cryptocurrencies that Chainalysis supports here.

May 26, 2020

KYT has introduced a new user risk score calculation that's easier to understand, customize, and control.


March 12, 2020

Chainalysis has added 43 new tokens, more than doubling the number of ERC-20 tokens we support. KYT can now help you understand what’s happening with 97% of the total value in ERC-20s and over $1 billion of ERC-20 transfers every day. See a complete list of assets that KYT suppports here.


February 11, 2020


December 10, 2019


December 5, 2019


October 16, 2019


September 25, 2019


August 6, 2019


July 23, 2019

API Configuration

API Request Header & Authentication

Example Request Header:

curl -X GET "https://test.chainalysis.com/api/kyt/v1/assets" \
  --header "Token: <API_KEY>" \
  --header "Accept: application/json"

Note: Make sure to replace <API_KEY> with your API key.

KYT Environments

Example Test Server Request:

curl -X POST 'https://test.chainalysis.com/api/kyt/v1/users/user_547/transfers/sent' \
  --header 'Token: <API_KEY>' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '[{"asset": "BTC", "transferReference": "9aaaea1ce7d863e18d82f7ea331f9521a2c4fb7cbddd784001cd32ac28952cb5:0"}]'

We recommend using the Test Environment for initial API integration and validation. Once this is done, you can replace the API Key and URL to switch your integration to the KYT Production environment.

Security: All KYT API access is secured using HTTPS with TLS (v1.2) being supported.

Test Environment URLs

Production Environment URLs

Generating API Keys

API keys are created through the Settings option in the Account menu in KYT.

You can also obtain an API key in the Settings menu in Chainalysis Reactor.

API Response Pagination

In the following example the query parameters of "limit": 25 and "offset": 3 would display items 3-28 in the result set of 100 total items.

Note that the "data" array would typically display the data queried for these objects but has been truncated for this example.

The KYT API supports pagination for endpoints that return long lists of objects. Pagination allows you to retrieve a limited set (or subset) of results and to offset those results. Responses are displayed using total, limit, and offset. To see a different page, append the parameters limit and/or offset to the GET request.

{
  "total": 100,
  "limit": 25,
  "offset": 3,
  "data": [
    ...
  ]
}

Optional Pagination Parameters

Parameter Name Type Description
limit Int A limit on the number of objects returned.
offset Int The position of the first object returned in the response. The default is 0, which starts the page at the first result.

If there is no data to be returned, the data array will be empty.

KYT Integration Guide

You must complete an API integration to populate your data for risk reporting and case management in the KYT dashboard. The integration is first performed on our test environment, then once completed, the data is moved to our production environment. See KYT Environments above for more information about the test and production environments.

Get in touch with Customer Success for help uploading transactions via CSV.

Tips

Suggested integration workflow

  1. Access the test environment
    Log in with your test credentials (obtained via email) and generate your API key for the test environment (links above).

  2. Make successful requests on test server
    Ensure successful requests have been made on the test server (transfers/sent, transfers/received, etc).

  3. Set up compliance workflows and verify that requests are aligned in the test environment
    See our suggested compliance workflows here.

  4. Move from the test environment to the production environment
    Log in with your production credentials (obtained via email) and generate your API key for the production environment (URLs provided above).

You will need to regularly post new transfers to the KYT API. Each transfer needs to be posted to the API only once, and KYT will continuously monitor counterparties and transaction flows. If transfers are accidentally posted more than once, this will not have an effect.

Implementations

Suggested implementations of the Chainalysis KYT API are detailed below, increasing in complexity and the amount of functionality you will receive. You can choose to work entirely in the KYT user interface (UI), or build a response within your own internal systems based on feedback and analysis from Chainalysis.

Building the analysis and data from the KYT API into your internal system provides robust functionality and gives you a more comprehensive picture of your risk. We suggest reviewing example compliance workflows to help assess which implementation best meets your needs.

At minimum, the two major endpoints required for integration are: /transfers/sent and /transfers/received. For basic functionality, you must execute at least those two requests.

Overview

The following graphic serves as a preview and comparison for the various KYT implementations. The implementations are described in detail in the sections below, including benefits and drawbacks as well as required endpoints for each.

Implementations overview

To help you visualize a compliance workflow using data from the KYT API, here is a basic KYT implementation.

Customer lifecycle

Prepare for Launch 1

KYT UI only

This is the minimum implementation and keeps all data and functionality entirely within Chainalysis’s environment. It does not pull data into your internal systems.

You will receive the full functionality of the KYT UI, but you will not have the ability to automate actions on transfers within your internal systems based on the information from KYT.

Prepare for Launch 1

This implementation requires registering /transfers/sent and /transfers/received. /depositaddresses is optional.

POST /users/{userId}/transfers/received

POST /users/{userId}/transfers/sent

POST /users/{userId}/depositaddresses

Transactions must be associated with a User ID for user risk score calculation.

Prepare for Launch 2

Internal systems only

While you can work entirely in the Chainalysis environment (see above), this implementation pulls Chainalysis’s data into your own system where you can incorporate KYT into your automated payments workflow.

Integrating Chainalysis’s data into your internal system helps you to get a more comprehensive picture of your risk activity and automate actions on transfers based on Chainalysis data. However, you will be missing out on functionality and convenience by not working within the KYT UI.

Prepare for Launch 2

This implementation requires registering /transfers/sent and /transfers/received (described above), as well as /withdrawaladdresses.

For example, if you want to stop the withdrawal of funds to a sanction or terrorist financing entity, you would use this request.

POST /users/{userId}/withdrawaladdresses

Lift Off

KYT UI & Internal systems

This setup is more robust than the previous implementations, as it encompasses both the KYT UI and your internal systems. You will be able to take action on transfers within your system and also have the full functionality of the UI, helping to provide continuity in the data you review between systems.

However, it does not take advantage of all the KYT features, such as alerts.

Lift off implementation

This implementation requires registering /transfers/sent, /transfers/received, and /withdrawaladdresses (described above).

With this implementation you can:

Cruising Altitude

KYT UI & Internal systems

This implementation pulls Chainalysis data into both the KYT UI and your internal systems with an additional API endpoint, /alerts.

Cruising Altitude brings the most powerful data that KYT offers - alerts - into your internal system. You can perform the actions mentioned above (setting flags, pulling the risk score into payments queues, etc) with the benefit that the data you are using is the most robust. This implementation can also help you match the alerts workflows that your compliance team is likely doing in the UI.

Cruising altitude implementation

This implementation requires registering /transfers/sent, /transfers/received, /withdrawaladdresses (described above), as well as /alerts.

GET /alerts

To the Moon

KYT UI & Internal systems

This implementation pulls Chainalysis data into both the KYT UI and your internal systems. It builds on the implementations above with an additional endpoint, /users. GET /users provides you with a user risk score for each of your users.

Alerts and user risk score are two powerful analytic metrics that are provided by the KYT API for assessing your risk activity. User risk scores allow you to perform user-level automated review in your internal system on top of the transfer-level review from above.

To the Moon implementation

This implementation requires registering /transfers/sent, /transfers/received, /withdrawaladdresses, /alerts (described above), as well as /users.

GET /users

Workflows

Below are example compliance workflows using KYT’s most powerful risk assessment features to help you formulate policies and procedures based on the information provided by the KYT and Reactor UIs, and the KYT API.

The workflows below focus on three KYT features that help you prioritize risk activity: alerts, user risk score, and counterparty screen:

We suggest using alerts as a notification and starting point for review and interacting with user risk profiles. The KYT Dashboard in the UI gives you a high-level overview of your risk for managerial and organizational reporting/monitoring, while alerts is where an analyst will spend most of their time.

Deposit workflow

This is a suggested workflow for funds that are received by a user at your organization. Note that in most cases, you cannot stop an incoming transfer from occurring. However, KYT helps you to detect the risk associated with the transfer and take appropriate compliance action. For example, if a user receives funds directly from a cluster categorized as child abuse material, you can decide how you want to react (e.g. freeze funds, investigate, and likely file a SAR).

Integration graphic

1. Register the transfer
When funds arrive at a user address, POST the received transfer.

2. Check alerts and/or user risk score

You can check alerts:

We suggest checking alerts first to assess risky transfer activity and then moving to review all alerts at the user level by clicking the unique URL for the user. You can also check the user’s risk score to see if the user is high risk.

You can check user risk score:

3. Take action

Take action on the received funds. For example, you can hold the transfer and submit it to be manually reviewed, immediately freeze the user’s funds, or deem the transfer non-risky.

Chainalysis continually monitors for risk on each registered transfer.

Withdrawal workflow

This is a suggested workflow for funds that are being sent by a user at your organization. Unlike deposits, you can stop a risky withdrawal from occurring if at the time of the withdrawal, the withdrawal address has been identified as risky. For example, if a user requests a withdrawal towards a sanctioned address, you can decide to block this request.

Integration graphic

1. Check Withdrawal Address

The withdrawal prescreen is used in real-time to pre-screen for counterparty risk. When a user requests a withdrawal, register the withdrawal address by making a POST request to the /withdrawaladdresses endpoint. For known counterparties, a risk rating of high risk or low risk will be provided, as well as the counterparty’s name.

Note that it is common to withdraw to a previously unknown address, so the majority of addresses you check may have an unknown rating.

2. Take action

After performing the withdrawal address counterparty screen, take action on the pending transfer. You may choose to block a transfer that is high risk, or flag it for further review.

3. Register the transfer

Always be sure to register an approved withdrawal as a sent transfer upon completion so that your team can access it in the compliance dashboard and KYT can monitor the transfer. Note that KYT updates risk for transfers on an ongoing basis, but does not update withdrawal addresses. The latter will always return the rating when the address was first screened.

As with deposits, Chainalysis monitors sent transfers for you over time.

4. Check alerts

Look at the user information page in the UI for the user's associated withdrawal addresses and alerts. Alerts that have a sent direction mean that the withdrawal was approved.

Example compliance actions

Here are some examples of compliance actions taken by our customers when following the workflows above:

“If we notice a withdrawal request towards terrorism financing, we will show the user the withdrawal request is processing and call our Financial Intelligence Unit hotline to ask if they want us to block the transaction (and likely tip off the user) or allow it to occur (for ongoing monitoring).”

“If we detect a direct deposit from a darknet market, we will silently freeze the account. Typically we will file a SAR report, offboard the user, and allow the user to withdraw their funds via a fiat conversion to their bank account.”

“If we detect a pattern of risky (in)direct darknet market transactions, we will freeze the account. Typically we will file a SAR report, offboard the user, and allow the user to withdraw their cryptocurrency.”

“Transfers to mixing services are prohibited on our platform. If we see a withdrawal request to a mixer, we flag the transfer for review and ask the user to explain the purpose of the withdrawal.”

Internal systems

Note that instead of performing these checks manually, you can automate the process by building a response within your own internal systems. See the suggested implementations above for more information. The benefits of automating compliance include:

Received Transfer Management

Transfers Received Endpoint

users/{userId}/transfers/received

https://test.chainalysis.com/api/kyt/v1/users/{User_ID}/transfers/received

transfers/received API Call

A list of assets that are currently supported by KYT appears below.

Note that you can send data for more assets in addition to this list through the transfers/received endpoint. As soon as KYT fully supports the coin, the system will automatically backfill any data you've sent. Therefore, you only have to upload this data once. See a list of all the assets you can send to KYT below.

POST: transfers/received

An example BTC received transfer for user 005 using output address in the transferReference.

curl -X POST 'https://test.chainalysis.com/api/kyt/v1/users/005/transfers/received' \
  --header 'Token: <API_KEY>' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '[{"asset": "BTC", "transferReference": "2d9bfc3a47c2c9cfd0170198782979ed327442e5ed1c8a752bced24d490347d4:1H7aVb2RZiBmdbnzazQgVj2hWR3eEZPg6v"}]'

An example BTC received transfer for user 005 using output index in the transferReference.

curl -X POST 'https://test.chainalysis.com/api/kyt/v1/users/005/transfers/received' \
  --header 'Token: <API_KEY>' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '[{"asset": "BTC", "transferReference": "2d9bfc3a47c2c9cfd0170198782979ed327442e5ed1c8a752bced24d490347d4:0"}]'

The above commands return JSON structured like this:

[
  {
    "transferReference": "2d9bfc3a47c2c9cfd0170198782979ed327442e5ed1c8a752bced24d490347d4:1H7aVb2RZiBmdbnzazQgVj2hWR3eEZPg6v",
    "asset": "BTC",
    "cluster": {
      "name": "Coinbase.com",
      "category": "exchange"
    },
    "rating": "lowRisk"
  }
]

Required Parameters

Property Type Description
userId String The userId to associate with the received transfer.
asset String The asset used during the transfer.
transferReference String The transaction output to associate with the userId. Read more about the transfer reference here.

Optional Parameters

Property Type Description
bulkImport String Either true or false. If set to true, no real-time response is returned and the request executes faster. We suggest using this parameter if you do not require the real-time response. There is a limit of 100 transfers when bulkImport is false and 1000 transfers when bulkImport is true.

If using bulkImport, it should be passed in as a parameter in the URL, not sent in the request body:

https://test.chainalysis.com/api/kyt/v1/users/005/transfers/received?bulkImport=true

If you are sending data for additional assets that are not currently supported by KYT (see list of supported assets), you can use the following optional parameters.

Property Type Description
transferTimestamp ISO-8601 Date String The timestamp of the transfer.
assetAmount Float The amount of the asset transferred as a Float.

Request Body

Define the asset used in the transfer.

"asset": "BTC"

The transaction hash followed by a ":" and the output address or output index.

"transferReference": "2d9bfc3a47c2c9cfd0170198782979ed327442e5ed1c8a752bced24d490347d4:1H7aVb2RZiBmdbnzazQgVj2hWR3eEZPg6v"

Note that the output address is the destination address for funds within the transaction; i.e. where funds are being sent (for a sent transfer) or where funds are being received (in a received transfer). The output for received transactions will be an address you control.

Response

A successful request will return the following JSON response and properties for a given userId, asset, and transferReference.

Property Name Type Description
transferReference String The Transaction hash:index combination associated to the Transaction.
asset String The asset associated with the Transaction associated with the user.
cluster Object The identification of a group of addresses estimated by Chainalysis to be controlled by a single entity.
cluster.name String The name of a named Cluster.
cluster.category String The category the named Cluster belongs to, ie. Exchange.
rating String The risk rating of the Transfer Received as highRisk, lowRisk, or unknown.

GET: transfers/received

An example request retrieving all received transfers for user BTC_01

curl -X GET 'https://test.chainalysis.com/api/kyt/v1/users/BTC_01/transfers/received' \
  --header 'Token: <API_KEY>' \
  --header 'Accept: application/json'

The above command returns JSON structured like this:

{
  "limit": 100,
  "offset": 0,
  "total": 1,
  "data": [
    {
      "asset": "BTC",
      "transferReference": "2d9bfc3a47c2c9cfd0170198782979ed327442e5ed1c8a752bced24d490347d4:1H7aVb2RZiBmdbnzazQgVj2hWR3eEZPg6v",
      "amount": "4",
      "amountUSD": "561.64",
      "rating": "lowRisk",
      "cluster": {
        "name": "Coinbase.com",
        "category": "exchange"
    }
  ]
}

The Response Body will be a list with the same length as the number of transfers in the request.

Required Parameters

Property Type Description
userId String The userId to list registered Received Transfers for.

Optional Pagination Parameters

Property Type Description
limit Int A limit on the number of objects returned.
offset Int The position of the first object returned in the response. The default is 0, which starts the page at the first result.

Request Body

This call has no accompanying Request Body.

Response Body

A successful request will return the following JSON response and properties for a given userId.

Property Name Type Description
asset String The asset associated with the Transaction associated with the user.
transferReference String The Transaction hash:index combination associated to the Transaction.
amount Float The amount of the asset transferred in the Transaction as a Float.
amountUSD Float The amount of the asset transferred in the Transaction converted to US Dollars at the time of the transaction as a Float.
rating String The risk rating of the Transfer Received as highRisk, lowRisk, or unknown.
cluster Object The identification of a group of addresses estimated by Chainalysis to be controlled by a single entity.
cluster.name String The name of a named Cluster.
cluster.category String The category the named Cluster belongs to, ie. Exchange.

Sent Transfer Management

Transfers Sent Endpoint

users/{userId}/transfers/sent

https://test.chainalysis.com/api/kyt/v1/users/{User_ID}/transfers/sent

transfers/sent API Call

A list of assets that are currently supported by KYT appears below.

Note that you can send data for more assets in addition to this list through the transfers/sent endpoint. As soon as KYT fully supports the coin, the system will automatically backfill any data you've sent. Therefore, you only have to upload this data once. See a list of all the assets you can send to KYT below.

POST: transfers/sent

An example BTC sent transfer for the user 005 using output address in the transferReference.

curl -X POST 'https://test.chainalysis.com/api/kyt/v1/users/005/transfers/sent' \
  --header 'Token: <API_KEY>' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data
  '[{
    "asset": "BTC",
    "transferReference": "7c2238d4de91472061d66f918bda68541f33bd84ce994bcf191cd1315fa41118:16HgQB937BRDk3PyS9nSUuHE2P6CbjNuAe"
  }]'

An example BTC sent transfer for the user 005 using output index in the transferReference.

curl -X POST 'https://test.chainalysis.com/api/kyt/v1/users/005/transfers/sent' \
  --header 'Token: <API_KEY>' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data
  '[{
    "asset": "BTC",
    "transferReference": "7c2238d4de91472061d66f918bda68541f33bd84ce994bcf191cd1315fa41118:0"
  }]'

The above commands return an empty JSON response.

Required Parameters

Property Type Description
userId String The userId to associate with the sent transfer.
asset String The asset used during the sent transfer.
transferReference String The transaction output to be associated with the userId. Read more about the transfer reference here.

Optional Parameters

If you are sending data for additional assets that are not currently supported by KYT (see list of supported assets), you can use the following optional parameters.

Property Type Description
transferTimestamp ISO-8601 Date String The timestamp of the transfer.
assetAmount Float The amount of the asset transferred as a Float.

Request Body

Define the asset used in the transfer.

"asset": "BTC"

The transaction hash followed by a ":" and the output address or transaction index.

"transferReference": "7c2238d4de91472061d66f918bda68541f33bd84ce994bcf191cd1315fa41118:0"

Response

The response will be an empty zero byte response, indicated by a response header Content-Length: 0.

GET: transfers/sent

An example request for retrieving all sent transfers for user BTC_01.

curl -X GET 'https://test.chainalysis.com/api/kyt/v1/users/BTC_01/transfers/sent' \
  --header 'Token: <API_KEY>' \
  --header 'Accept: application/json'

The above command returns JSON structured like this:

{
  "limit": 100,
  "offset": 0,
  "total": 1,
  "data": [
    {
      "asset": "BTC",
      "transferReference": "7c2238d4de91472061d66f918bda68541f33bd84ce994bcf191cd1315fa41118:0",
      "amount": "3",
      "amountUSD": "35001.39",
      "cluster": {
        "name": "Exmo.com",
        "category": "exchange"
    }
  ]  
}

The Response Body will be a list with the same length as the number of transfers in the request.

Required Parameters

Property Type Description
userId String The userId associated with the sent transfers you want to retrieve.

Optional Pagination Parameters

Property Type Description
limit Int A limit on the number of objects returned.
offset Int The position of the first object returned in the response. The default is 0, which starts the page at the first result.

Request Body

This call has no accompanying Request Body.

Response Body

A successful request will return the following properties in JSON format for a given userId.

Property Type Description
asset String The asset associated with the Transaction associated with the user.
transferReference String The Transaction hash:index combination associated to the Transaction.
amount Float The amount of the asset transferred in the Transaction as a Float.
amountUSD Float The amount of the asset transferred in the Transaction converted to US Dollars at the time of the transaction as a Float.
cluster Object The identification of a group of addresses estimated by Chainalysis to be controlled by a single entity.
cluster.name String The name of a named Cluster.
cluster.category String The category the named Cluster belongs to, ie. Exchange.

Transfer Format Reference

UTXO Based Cryptocurrencies

UTXO Based Transfer Example

Transfer is a sent transfer with hash 9022c2d59d1bed792b6449e956b2fe26b44b1043bbc1662d92ecd29526d7f34e and user output address 18SuMh4AFgTSQRvwFzdYGieHtgKDveHtc. The output address is in the 5th place in the transaction.

Select either output address method or output index method.

1. Output Address Method:

"asset": "BTC",
"transferReference":"2d9bfc3a47c2c9cfd0170198782979ed327442e5ed1c8a752bced24d490347d4:1H7aVb2RZiBmdbnzazQgVj2hWR3eEZPg6v"

2. Output Index Method:

"asset": "BTC",
"transferReference":"2d9bfc3a47c2c9cfd0170198782979ed327442e5ed1c8a752bced24d490347d4:0"

UTXO based cryptocurrencies, such as Bitcoin, must reference a transaction hash and a corresponding output address or transaction hash index.

Note that the output address is the destination address for funds within the transaction; i.e. where funds are being sent (for a sent transfer) or where funds are being received (in a received transfer). The output for received transactions will be an address you control.

When an output address is used to specify a transfer, the index of the first matching output is used regardless of value.

Account Based Cryptocurrencies

Account Based Transfer Example

Basic Ether Transfer:

"asset": "ETH",
"transferReference":"0xe823c9b7895f9c47985c80e4611272f8194403e885c9cc603422cd609d738098:0x3d21a92285bf17cbdde5f77531b8b58ac400288a"

User is sending funds to a smart contract (note that the output address is the smart contract):

"asset": "USDC",
"transferReference":"0xeb8cff0b134a93da1c8e3ee263ff7a60ed836489a57e38a56c77bd0d0ab8995d:0x39aa39c021dfbae8fac545936693ac917d5e7563”

User is receiving funds from a smart contract (note that the output address belongs to the user):

"asset": "ETH",
"transferReference":"0xce5c4a31b2b6265f2373b5abf319d092ed8d659fa5ba41edf62d9ad61db570d4:0xE1DaC2E83a7Fc3B1C21a6F740eCd8e28cB965F14"

Account based cryptocurrencies, such as Ethereum or ERC-20 tokens, require a valid transaction hash and output address (see note above about output addresses).

In the case of a smart contract, this format still holds. The output address can possibly be the smart contract itself if it is receiving funds from a user, or a customer if the smart contract is sending funds out.

Assets

See a list of all assets KYT supports here. Note that you can send data for more assets in addition to this list through the transfers/sent and transfers/received endpoints. As soon as KYT fully supports the coin, the system will automatically backfill any data you've sent and you only have to upload this data once. See a list of all the assets you can send to KYT below.

Withdrawal Pre-Screening

Withdrawal Address Endpoint

users/{userId}/withdrawaladdresses

https://test.chainalysis.com/api/kyt/v1/users/{userId}/withdrawaladdresses

withdrawaladdresses API Call

Note that KYT updates risk for transfers on an ongoing basis, but does not update withdrawal addresses. The withdrawaladdresses endpoint returns the cluster information that was available when the API was called. For ongoing monitoring, you should register the transfer with the transfers/sent endpoint.

The list of assets that KYT supports appears below. Note that this endpoint only accepts the assets from this list. To send data on additional assets (including assets that KYT may support in the future), use the transfers/sent and transfers/received endpoints.

POST: withdrawaladdresses

An example request for registering a Bitcoin Withdrawal Address of 1MCPcGbnrv4Uv9HcrjoQwzJaEFGrwzE6Pk for user BTC_01 would look like the following.

curl -X POST 'https://test.chainalysis.com/api/kyt/v1/users/BTC_01/withdrawaladdresses' \
  --header 'Token: <API_KEY>' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '[{"asset": "BTC", "address": "1MCPcGbnrv4Uv9HcrjoQwzJaEFGrwzE6Pk"}]'

The above command returns JSON structured like this:

{
  "asset": "BTC",
  "address": "1MCPcGbnrv4Uv9HcrjoQwzJaEFGrwzE6Pk",
  "cluster": {
    "name": "Coinbase",
    "category": "Exchange"
  },
  "rating": "lowRisk",
  "customAddress": null,
  "chainalysisIdentification": null
}

Example response body for an unknown recipient

{
  "asset": "BTC",
  "address": "1MCPcGbnrv4Uv9HcrjoQwzJaEFGrwzE6Pk",
  "cluster": null,
  "rating": "unknown",
  "customAddress": null,
  "chainalysisIdentification": null
}

Example response body for a Custom Address

{
   "asset": "BTC",
   "address": "1LRtBLSGLnhnhXiWenZWYkWZJnxZo282Ug",
   "cluster": null,
   "rating": "highRisk",
   "customAddress": {
       "addressName": "Fraud",
       "description": "Address used to deposit funds from ICO scam",
       "categoryName": "scam"
   },
   "chainalysisIdentification": null
}

Example response body for a Chainalysis Identification

{
  "asset": "LTC",
  "address": "LaizKtS5DUhPuP1nTQcc83MS7HwK6vk85z",
  "cluster": {
      "name": "Gatecoin.com",
      "category": "exchange"
  },
  "rating": "highRisk",
  "customAddress": null,
  "chainalysisIdentification": {
      "addressName": "OFAC SDN Guanghua Zheng",
      "description": "ZHENG, Guanghua (Chinese Traditional: 鄭广華; Chinese Simplified: 郑广华); DOB 04 Nov 1955; POB Shanghai, China; nationality China; citizen China; Email Address zhenguanghua1955@outlook.com; alt. Email Address zhenguanghua1955@gmail.com; Gender Male; Passport E51809923 (China) issued 25 May 2015 expires 24 May 2025; Identification Number 310108195511041616 (China); Chinese Commercial Code 6774 1639 5478 (individual) [SDNTK]. https://www.treasury.gov/resource-center/sanctions/OFAC-Enforcement/Pages/20190821.aspx",
      "categoryName": "sanctions"
  }
}

Required Parameters

Parameter Name Type Description
userId String The userId to associate with the withdrawal address.
asset String The asset type being pre-screened.
address String The address used to determine counterparty risk.

Optional Parameters

Parameter Name Type Description
bulkImport String Either true or false. If set to true, no real-time response is returned and the request executes faster. We suggest using this parameter if you do not require the real-time response. There is a limit of 100 items when bulkImport is false and 1000 items when bulkImport is true.

If using bulkImport, it should be passed in as a parameter in the URL, not sent in the request body:

https://test.chainalysis.com/api/kyt/v1/users/BTC_01/withdrawaladdresses?bulkImport=true

Request Body

Specify the asset of the address to be screened.

"asset": "BTC"

Include the address to be screened.

"address": "1MCPcGbnrv4Uv9HcrjoQwzJaEFGrwzE6Pk"

Response Body

A successful request will return the following JSON response for known recipients.

Property Name Type Description
asset String The asset associated with the withdrawal address.
address String The asset withdrawal address.
cluster Object The identification of a group of addresses estimated by Chainalysis to be controlled by a single entity. null if the cluster has not yet been identified.
cluster.name String The name of the named cluster.
cluster.category String The category of the named cluster.
rating String The risk rating of the known recipient address.
customAddress Object An address you've uploaded through the KYT UI that allows you to receive alerts on activity. null if not applicable.
customAddress.addressName String The name you've given to the Custom Address in the CSV file.
customAddress.description String The description you've provided for the Custom Address in the CSV file.
customAddress.categoryName String The category name you provided for the Custom Address in the CSV file.
chainalysisIdentification Object A Chainalysis Identified Address, representing an address-level identification that is part of a larger cluster. null if not applicable.
chainalysisIdentification.addressName String The name designated to the Chainalysis Identification.
chainalysisIdentification.description String The OSINT from the Chainalysis Identification.
chainalysisIdentification.categoryName String The category of the Chainalysis Identification.

Note that the responses are not mutually exclusive. For example, you can have a known or unknown recipient and a Custom Address and/or a Chainalysis Identification.

GET: withdrawaladdresses

Retrieves all withdrawal addresses and risk ratings for a single User ID.

An example request for listing all Withdrawal Addresses for user BTC_01.

curl -X GET 'https://test.chainalysis.com/api/kyt/v1/users/BTC_01/withdrawaladdresses' \
  --header 'Token: <API_KEY>' \
  --header 'Accept: application/json'

The above command returns JSON structured like this:

{
  "total": 100,
  "limit": 25,
  "offset": 3,
  "data": [
    {
      "asset": "BTC",
      "address": "1MCPcGbnrv4Uv9HcrjoQwzJaEFGrwzE6Pk",
      "cluster": {
        "name": "Coinbase",
        "category": "Exchange"
      },
      "customAddress": null,
      "chainalysisIdentification": null,
      "rating": "lowRisk",
    },
    ...
  ]
}

Example response body for a Custom Address

{
    "limit": 100,
    "offset": 0,
    "total": 1,
    "data": [
        {
            "asset": "BTC",
            "address": "12gzta6sTonaMy5mozWhStMMSet1FxFA7L",
            "cluster": null,
            "customAddress": {
                "addressName": "Darknet",
                "description": "User is operating store on darknet market",
                "categoryName": "darknet market"
            },
            "chainalysisIdentification": null,
            "rating": "highRisk"
        }
    ]
}

Example response body for a Chainalysis Identification

{
    "limit": 100,
    "offset": 0,
    "total": 1,
    "data": [
        {
            "asset": "LTC",
            "address": "LaizKtS5DUhPuP1nTQcc83MS7HwK6vk85z",
            "cluster": {
                "name": "Gatecoin.com",
                "category": "exchange"
            },
            "customAddress": null,
            "chainalysisIdentification": {
                "addressName": "OFAC SDN Guanghua Zheng",
                "description": "ZHENG, Guanghua (Chinese Traditional: 鄭广華; Chinese Simplified: 郑广华); DOB 04 Nov 1955; POB Shanghai, China; nationality China; citizen China; Email Address zhenguanghua1955@outlook.com; alt. Email Address zhenguanghua1955@gmail.com; Gender Male; Passport E51809923 (China) issued 25 May 2015 expires 24 May 2025; Identification Number 310108195511041616 (China); Chinese Commercial Code 6774 1639 5478 (individual) [SDNTK]. https://www.treasury.gov/resource-center/sanctions/OFAC-Enforcement/Pages/20190821.aspx",
                "categoryName": "sanctions"
            },
            "rating": "highRisk"
        }
    ]
}

Required Parameters

Parameter Name Type Description
userId String The userId to retrieve withdraw addresses for.

Optional Pagination Parameters

Parameter Name Type Description
limit Int A limit on the number of objects returned.
offset Int The position of the first object returned in the response. The default is 0, which starts the page at the first result.

Request Body

This call has no accompanying Request Body.

Response Body

A successful request will return the following JSON response for a known recipient.

Property Name Type Description
asset String The asset associated with the withdraw address.
address String The asset withdraw address.
cluster Object The identification of a group of addresses estimated by Chainalysis to be controlled by a single entity. null if the cluster has not yet been identified.
cluster.name String The name of the named cluster.
cluster.category String The category of the named cluster, i.e., Exchange.
customAddress Object An address you've uploaded through the KYT UI that allows you to receive alerts on activity. null if not applicable.
customAddress.addressName String The name you've given to the Custom Address in the CSV file.
customAddress.description String The description you've provided for the Custom Address in the CSV file.
customAddress.categoryName String The category name you provided for the Custom Address in the CSV file.
chainalysisIdentification Object A Chainalysis Identified Address, representing an address-level identification that is part of a larger cluster. null if not applicable.
chainalysisIdentification.addressName String The name designated to the Chainalysis Identification.
chainalysisIdentification.description String The OSINT from the Chainalysis Identification.
chainalysisIdentification.categoryName String The category of the Chainalysis Identification.
rating String The risk rating of the known recipient address.
total Int The total number of results in the data set.
limit Int The limit of the data set.
offset Int The offset of the data set.

DELETE: withdrawaladdresses

This endpoint deletes a specific Withdrawal Address for a given user.

An example request for deleting a Bitcoin Withdrawal Address of 1MCPcGbnrv4Uv9HcrjoQwzJaEFGrwzE6Pk for user BTC_01.

curl -X DELETE 'https://test.chainalysis.com/api/kyt/v1/users/BTC_01/withdrawaladdresses/BTC/1MCPcGbnrv4Uv9HcrjoQwzJaEFGrwzE6Pk' \
  --header 'Token: <API_KEY>' \
  --header 'Accept: application/json'

The above command returns an empty JSON response body.

Required Parameters

Parameter Name Type Description
userId String The userId to retrieve withdraw addresses for.
asset String The asset type associated with the withdraw address.
address String The asset withdraw address associated with the userId requested.

Response Body

The call has an empty Response Body. ie. a zero byte response, indicated by a response header Content-Length: 0.

Deposit Addresses

Deposit Address Endpoint

users/{userId}/depositaddresses

https://test.chainalysis.com/api/kyt/v1/users/{userId}/depositaddresses

depositaddresses API Call

Note: In the future, KYT will be able to detect deposits (but not withdrawals) based on the deposit address. While this endpoint is not currently required for monitoring or integration, you can implement it now for use with this upcoming functionality.

The list of assets that KYT supports appears below. Note that this endpoint only accepts the assets from this list. To send data on additional assets (including assets that KYT may support in the future), use the transfers/sent and transfers/received endpoints.

POST: depositaddresses

An example request for registering a Bitcoin deposit address of 1MCPcGbnrv4Uv9HcrjoQwzJaEFGrwzE6Pk for user BTC_01 would look like the following.

curl -X POST 'https://test.chainalysis.com/api/kyt/v1/users/BTC_01/depositaddresses' \
  --header 'Token: <API_KEY>' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '[{"asset": "BTC", "address": "1MCPcGbnrv4Uv9HcrjoQwzJaEFGrwzE6Pk"}]'

The above command returns an empty JSON response.

Required Parameters

Parameter Name Type Description
userId String The userId to associate with the deposit address.
asset String The asset to associate with the deposit address.
address String The deposit address to be associated with the userId and asset.

Optional Parameters

This call has no optional parameters.

Request Body

Specify the asset of the deposit address.

"asset": "BTC"

Include the address.

"address": "1MCPcGbnrv4Uv9HcrjoQwzJaEFGrwzE6Pk"

Response Body

The response will be empty, ie. a zero byte response, indicated by a response header Content-Length: 0.

GET: depositaddresses

Retrieves all deposit addresses for a single User ID.

An example request for listing all deposit addresses for user BTC_01 would look like the following.

curl -X GET 'https://test.chainalysis.com/api/kyt/v1/users/BTC_01/depositaddresses' \
  --header 'Token: <API_KEY>' \
  --header 'Accept: application/json'

The above command returns JSON structured like this:

{
  "total": 1000,
  "limit": 0,
  "offset": 0,
  "data": [
    {
      "asset": "BTC",
      "address": "1MCPcGbnrv4Uv9HcrjoQwzJaEFGrwzE6Pk"
    },
    ...
  ]
}

Required Parameters

Parameter Name Type Description
userId String The userId from which you wish to retrieve the deposit addresses.

Optional Parameters

Parameter Name Type Description
limit Int A limit on the number of objects returned.
offset Int The position of the first object returned in the response. The default is 0, which starts the page at the first result.

Request Body

This call has no accompanying Request Body.

Response Body

A successful request will return the following JSON response and properties for a given userId.

Property Name Type Description
asset String The asset associated with the deposit address for the user.
address String The deposit address associated with the user.
total Int The total number of results in the data set.
limit Int The limit of the data set.
offset Int The offset of the data set.

DELETE: depositaddresses

An example request for deleting an associated Bitcoin deposit address of 1MCPcGbnrv4Uv9HcrjoQwzJaEFGrwzE6Pk for user BTC_01 using curl would look like the following.

curl -X DELETE 'https://test.chainalysis.com/api/kyt/v1/users/BTC_01/depositaddresses/BTC/1MCPcGbnrv4Uv9HcrjoQwzJaEFGrwzE6Pk' \
--header 'Token: <API_KEY>' \
--header 'Accept: application/json'

Deletes the associated deposit address for a single User ID.

Required Parameters

Parameter Name Type Description
userId String The userId associated with the deposit address.
asset String The asset associated with the deposit address.
address String The deposit address to be deleted.

Optional Parameters

This call has no optional parameters.

Request Body

This call has no accompanying Request Body.

Response Body

The response will be empty, ie. a zero byte response, indicated by a response header Content-Length: 0.

Users

Users are aggregations of transfers, tagged by User ID. Users in KYT should map 1:1 to users on your platform. Analyzing risk at a user level allows you to compare all the historical transfers made by a user to their current transfer.

The Users endpoint generates risk score reports for all users submitted to Chainalysis KYT. The endpoint supports both a summary format of all users and detailed reporting on specific users when passed a corresponding user ID. You are also able to rename User IDs via the API.

In determining User IDs, it is important to keep the following information in mind:

GET: users

An example request for listing all User IDs in the KYT system using curl would look like the following.

curl -X GET 'https://test.chainalysis.com/api/kyt/v1/users/' \
  --header 'Token: <API_KEY>' \
  --header 'Accept: application/json'

The above command returns JSON structured like this:

{
  "total": 1000,
  "limit": 0,
  "offset": 0,
  "data": [
    {
      "userId": "BTC_01",
      "score": "green",
      "lastActivity": "2008-09-15T15:53:00+05:00",
      "scoreUpdatedDate": "2008-09-15T15:53:00+05:00",
      "riskScore": "LOW"
    },
    ...
  ]
}

HTTP Request

GET https://test.chainalysis.com/api/kyt/v1/users/

Optional Pagination Parameters

Parameter Name Type Description
limit Int A limit on the number of objects returned.
offset Int The position of the first object returned in the response. The default is 0, which starts the page at the first result.

Response Body

The Response Body will be a brief summary of the list of User IDs in the Chainalysis KYT system.

score is based on the legacy user risk model, while riskScore reflects the current model that was implemented in late May 2020. We recommend using the riskScore property going forward. Find more information about the user risk model here (login required).

A successful request will return the following JSON response and properties for all users.

Property Name Type Description
userId String The User ID of the user.
score String The score of the User ID as green, amber, or red. Based on the legacy user risk model.
lastActivity ISO-8601 Date String The date of the User ID's last tracked activity.
scoreUpdatedDate ISO-8601 Date String The date the score was last calculated. This field will update whenever activity occurs that could affect the user risk score, including: a new transfer is registered, a new alert is generated, or an alert status is changed.
riskScore String The overall score of the User ID as LOW, MEDIUM, HIGH, or SEVERE. Based on the new user risk model. We recommend using this property going forward.

GET: users/{userId}

An example request for listing a single User ID, BTC_01, in the KYT system using curl would look like the following.

curl -X GET 'https://test.chainalysis.com/api/kyt/v1/users/BTC_01' \
  --header 'Token: <API_KEY>' \
  --header 'Accept: application/json'

The above command returns JSON structured like this:

{
  "userId": "BTC_01",
  "score": "green",
  "lastActivity": "2008-09-15T15:53:00+05:00",
  "scoreUpdatedDate": "2008-09-15T15:53:00+05:00",
  "riskScore": "LOW",
  "creationDate": "2008-09-15T15:53:00+05:00",
  "exposureDetails": [
    {
      "cluster": {
        "name": "Coinbase.com",
        "category": "exchange"
      },
      "sentIndirectExposure": 25,
      "sentDirectExposure": 0,
      "receivedIndirectExposure": 25,
      "receivedDirectExposure": 0
    }
  ]
}

Retrieve detailed information on a single user in the Chainalysis KYT system.

HTTP Request

GET https://test.chainalysis.com/api/kyt/v1/users/{userId}

Required Parameters

Parameter Name Type Description
userId String The userId to query.

Response Body

A successful request will return the following JSON response and properties for all users.

Property Name Type Description
userId String The User ID of the user.
score String The score of the User ID as green, amber, or red. Based on the legacy user risk model.
lastActivity ISO-8601 Date String The date of the user's last tracked activity.
scoreUpdatedDate ISO-8601 Date String The date the score was last calculated. This field will update whenever activity occurs that could affect the user risk score, including: a new transfer is registered, a new alert is generated, or an alert status is changed.
riskScore String The overall score of the User ID as LOW, MEDIUM, HIGH, or SEVERE. Based on the new user risk model. We recommend using this property going forward.
creationDate ISO-8601 Date String The date the user was created in the KYT system.
exposureDetails Array An array of details about the user's exposure to risk.
cluster Object The identification of a group of addresses estimated by Chainalysis to be controlled by a single entity.
cluster.name String The name of the named cluster.
cluster.category String The category the named cluster belongs to.
sentIndirectExposure Int Total Sent Indirect Exposure for the user in USD.
sentDirectExposure Int Total Sent Direct Exposure for the user in USD.
receivedIndirectExposure Int Total Received Indirect Exposure for the user in USD.
receivedIndirectExposure Int Total Sent Indirect Exposure for the user in USD.

score is based on the legacy user risk model, while riskScore reflects the current model that was implemented in late May 2020. We recommend using the riskScore property going forward. Find more information about the user risk model here (login required).

POST: users/rename

Rename a userId in the KYT system.

An example request for renaming a User ID from test_1 to user_1 in the KYT system using curl would look like the following.

curl -X POST 'https://test.chainalysis.com/api/kyt/v1/users/rename' \
  --header 'Token: <API_KEY>' \
  --header 'Accept: application/json'
  --header 'Content-Type: application/json' \
  --data '[{"from":"test_1", "to":"user_1"},{"from":"test_1", "to":"user_1"}]'

The above command returns an empty JSON response.

Request Body

From is the userId that you would like to rename.
"from": "test_1"

To is the new userId.
It must be a new userId and not currently exist in the KYT system. Using an existing userId will result in a 400 error.
"to": "user_1"

The request body needs to be in the form of an array: [{"from":"test_1", "to":"user_1"}]. The request supports up to 1000 renames at a time.

Response Body

The endpoint returns an empty JSON response.

Alerts

Alerts in KYT are raised for risky transfers on your platform. A single transfer can trigger multiple alerts. Alert levels include Severe, High, Medium, and Low, and are based on factors such as category, service, direct versus indirect exposure, direction, and amount.

The Alerts endpoint retrieves information on all alerts that have been raised within your organization.

GET: alerts

An example request for listing all alerts in the KYT system using curl would look like the following.

curl -X GET 'https://test.chainalysis.com/api/kyt/v1/alerts/' \
  --header 'Token: <API_KEY>' \
  --header 'Accept: application/json'

The above command returns JSON structured like this:

{
  "total": 1000,
  "limit": 0,
  "offset": 0,
  "data": [
    {
      "alertAmountUsd": 132.50,
      "transactionHash": "b765440e872ab6e2521694d10465415bda4adf8ed7fc2fdafb6d39bd17c5fddf",
      "level": "HIGH",
      "exposureType": "DIRECT",
      "alertStatus": "Flagged",
      "transferReportedAt": "2017-01-05T14:23:00.397Z",
      "alertIdentifier": "a6a5d0f8-9753-11e9-a517-ebce3e967522",
      "service": "Silk Road Marketplace",
      "alertStatusCreatedAt": "2020-01-14T13:57:58.713226Z",
      "transferReference": "b765440e872ab6e2521694d10465415bda4adf8ed7fc2fdafb6d39bd17c5fddf:1",
      "userId": "mtgox_ghosts",
      "alertStatusCreatedBy": null,
      "createdAt": "2019-06-17T17:39:41.550575Z",
      "transferOutputAddress": "1DP38CC2kf6ewUDaaVd9nBfuAD8SP15g2T",
      "category": "darknet market",
      "transactionIndex": 1,
      "asset": "BTC",
      "direction": "SENT",
      "timestamp": "2011-06-18T08:22:21Z",
      "rule": ">$100 sent directly to darknet market",
      "minThreshold": 100,
      "maxThreshold": null
    },
    ...
  ]
}

HTTP Request

GET https://test.chainalysis.com/api/kyt/v1/alerts/

Optional Parameters

Parameter Name Type Description
asset String Return all alerts for a specific asset.
createdAt_gte ISO-8601 Date String Return all alerts created greater than or equal to a specific date and time.
createdAt_lte ISO-8601 Date String Return all alerts created less than or equal to a specific date and time.
level String Filters alerts by alert level as SEVERE, HIGH, MEDIUM, and LOW (values must be in caps).
transferReference String Return all alerts associated with a specific transfer reference. See Transfer Reference Formats for formatting requirements.
sort String Alerts can be sorted by timestamp, createdAt, level, and alertAmountUsd. For example, createdAt sorts alerts by the date the alert was created. See below for more information about the sort parameter.
userId String Return all alerts for a specific user.


Using the createdAt_gte and createdAt_lte parameters
You can use createdAt_gte and createdAt_lte to specify a date range. You can also keep track of your newest alerts by querying for all alerts after a given time (createdAt_gte), store the time you made the query, then query it again later for all alerts since the initial query.

Using the sort parameter
The sort parameter determines the order that the alerts are returned. timestamp, createdAt, level, and alertAmountUsd are supported. For example, returning all alerts sorted by amount from highest to lowest value (descending) looks like: ?sort=alertAmountUsd%20desc.

Get all alerts from a single transfer
To return all alerts on a single transfer, it is recommended to use the userId, asset, and transferReference parameters all at once. In rare circumstances, the same transferReference can exist for multiple assets or multiple users.

Optional Pagination Parameters

Parameter Name Type Description
limit Int A limit on the number of objects returned.
offset Int The position of the first object returned in the response. The default is 0, which starts the page at the first result.

Response Body

The response is sorted by alertStatusCreatedAt by default. Note that when an alert is created, the alertStatus is set to Unreviewed and the alertStatusCreatedAt is set to the time the alert was created.

A successful request will return the following JSON response and properties for all alerts:

Property Name Type Description
alertAmountUsd Int The amount of the transfer that triggered the alert in USD.
transactionHash String The transaction hash of the transfer that triggered the alert.
level String The level of the alert as SEVERE, HIGH, MEDIUM, or LOW.
exposureType String The type of exposure of the transfer that triggered the alert as DIRECT or INDIRECT.
alertStatus String The status of the alert as Unreviewed, In Review, Flagged, or Dismissed.
transferReportedAt ISO-8601 Date String The date the transfer was registered in KYT.
alertIdentifier String The alert ID.
service String The name of the counterparty in the transfer that triggered the alert. Note that the service will be null for indirect exposure alerts, as you can have multiple indirect counterparties contributing to one alert.
alertStatusCreatedAt ISO-8601 Date String The date the alert status was last changed.
transferReference String The transaction hash and index or output address of the transfer that triggered the alert.
userId String The User ID of the user.
alertStatusCreatedBy String The username of the person in your organization that changed the alert status.
createdAt ISO-8601 Date String The date the alert was created.
transferOutputAddress String The address to which the asset was sent.
category String The alert category.
transactionIndex String The 0-indexed number of the transfer in the transaction that caused the alert.
asset String The asset used in the transfer.
direction String The direction of the transfer that triggered the alert as SENT or RECEIVED.
timestamp ISO-8601 Date String The date of the transfer on the blockchain that caused the alert.
rule String An explanation of why the transfer caused an alert.
minThreshold Int The minimum amount in USD of the alert rule.
maxThreshold Int The maximum amount in USD of the alert rule.

Error Handling

All successful requests to the KYT API will return a 200 response code.

The KYT API uses the following error codes to identify a bad request:

Error Code Meaning Description
400 Bad Request May refer to using testnet data, or data in an illegal format - for example non-valid JSON or an object instead of a list.
403 Forbidden May indicate that your API Key is expired or not being sent properly as the value of the Token HTTP header.
404 Not Found Indicates that you have attempted to reach a page which does not exist - for example either a nonexistent endpoint or a user that does not exist.
406 Not Acceptable Means you are requesting a response format that the API cannot produce. We currently only support JSON output.
409 Conflict Indicates that there is a conflict of association with another user, such as overlapping addresses.
500 Internal Server Error Indicates an error with the server. For POST /transfers/sent and /transfers/received, you should try the request again to ensure the transaction has been screened by Chainalysis. Contact support@chainalysis.com with questions.
503 Service Unavailable Error Indicates that the server may be unavailable or not ready to handle the request. For POST /transfers/sent and /transfers/received, you should try the request again later to ensure the transaction has been screened by Chainalysis. Contact support@chainalysis.com with questions.

Glossary

The Chainalysis KYT API uses the following terms for all Asset types tracked:

Address

An Address is a cryptographic hash of a Public and Private key pair that holds value for a given cryptocurrency or token Asset. Bitcoin and other cryptocurrencies that use UTXO based transactions use what is called an "Address". Ethereum and other currencies that use Account based transactions use what is known as an "Account".

Asset

An Asset in KYT is the cryptocurrency or token being tracked (Bitcoin, Tether, etc).

A current list of supported assets by the KYT API can retrieved using the assets endpoint. You can also send data for additional assets and as soon as KYT fully supports the coin, the system will automatically backfill any data you've sent. A list of all assets you can send appears below.

Transfer

A Transfer is the part of a transaction that transfers value from one address to another address. For some asset types like Ethereum each transaction is one transfer, but for asset types like Bitcoin a transaction can contain multiple transfers.

Deposit Address

Deposit addresses are addresses that you manage on behalf of your users, where they can deposit value to your service. A deposit address is always associated with exactly one user, and should never be reused for another user, but a user can have multiple deposit addresses. Deposit addresses can be registered even before they have received value.

Withdrawal Address

Withdrawal addresses are foreign Bitcoin addresses outside your service, to which the user intends to send value. Multiple users might send value to the same withdrawal addresses.

Withdrawal addresses should be registered as early as possible for best results, for instance right when the address is pasted into a withdrawal form. When registering a withdrawal address a real-time rating of the address as a recipient of value is returned. This allows you to take action on suspicious behavior immediately.

Sent Transfer

Sent transfers are the value that your service sends on behalf of a user when the user makes a withdrawal from your service. Regardless of asset type, the transfer will be part of a transaction. A transfer can be registered as soon as its transaction has been created, and even before it has been broadcast to a blockchain. Once a transfer has been registered, KYT will track it.

For some asset types, the transfer will have to “settle” before it is processed by KYT; in Bitcoin we will wait until the transaction is 5 blocks deep to make sure the risk score reflects stable data. Registered transfers that remain unsettled for too long will automatically discard the registered transfer after a timeout of several days.

Received Transfer

Received transfers are the value transfers that your service receives on behalf of a user into their deposit address. Received transfers are registered and processed according to the same rules as sent transfers.

User IDs

All user activity is recorded in the KYT API under a user ID. The API allows you to use any unique user ID within the following constraints:

KYT

KYT is the abbreviation for Know Your Transaction.

Cluster

A cluster is a collection of cryptocurrency addresses that Chainalysis has identified to be controlled by one entity

UTXO

UTXO is the abbreviation for Unspent Transaction Output. UTXO is the method that some cryptocurrencies use to keep track of transactions in their transaction ledger in the Blockchain. UTXO is the amount of unspent cryptocurrency that can be spent in new transactions.

Examples of UXTO transaction based cryptocurrencies include:

Account

An Account, sometimes known as a Balance, is the method that some cryptocurrencies and tokens use to keep track of transactions in their transaction ledger in the Blockchain. The Account transaction method keeps track of the total currency in the Account in a global state. This transaction method allows for Smart Contracts to be created that keep track of different states to perform different tasks based on the state.

Examples of Account transaction based cryptocurrencies include:

Assets

HTTP Request

An example request for listing all assets.

curl -X GET 'https://test.chainalysis.com/api/kyt/v1/assets' \
  --header 'Token: <API_KEY>' \
  --header 'Accept: application/json'

The above command returns JSON structured as below. Note that the "data" array would typically display the data for all assets but has been truncated for this example.

[
    {
        "symbol": "AUDX",
        "name": "Etoro AUD"
    },
    {
        "symbol": "BCH",
        "name": "Bitcoin Cash"
    },
    {
        "symbol": "BNB",
        "name": "Binance Coin"
    },
    {
        "symbol": "BTC",
        "name": "Bitcoin"
    }
    ...
]

GET https://test.chainalysis.com/api/kyt/v1/assets

Returns a list of cryptocurrencies supported in the KYT API and the corresponding symbol.

For each asset, we return the asset’s symbol in canonical form, ie. BTC, not btc or btx, and the name of the asset, ie. Bitcoin. See a list of all supported assets below.

Supported Assets

The following assets are fully supported in KYT. Read more about transfer formats here.

Symbol Asset ERC-20? Transfer format reference
ALGO Algorand "transaction hash:output address"
AMPL Ampleforth "transaction hash:output address"
AUDX Etoro AUD "transaction hash:output address"
BAT Basic Attention Token "transaction hash:output address"
BCH Bitcoin Cash Output address format
"transaction hash:output address"

Or

Output index format
"transaction hash:output index"
BNB Binance Coin "transaction hash:output address"
BNT Bancor "transaction hash:output address"
BTC Bitcoin Output address format
"transaction hash:output address"

Or

Output index format
"transaction hash:output index"
BUSD Binance USD "transaction hash:output address"
CADX Etoro CAD "transaction hash:output address"
cBAT Compound Basic Attention Token "transaction hash:output address"
cDAI Compound Dai "transaction hash:output address"
CEL Celsius "transaction hash:output address"
CELR Celer Network "transaction hash:output address"
cETH Compound Ethereum "transaction hash:output address"
CGT CACHE Gold "transaction hash:output address"
CHFX Etoro CHF "transaction hash:output address"
CHZ chiliZ "transaction hash:output address"
COMP Compound "transaction hash:output address"
CNYX Etoro CNY "transaction hash:output address"
cREP Compound Augur "transaction hash:output address"
CRO Crypto.com (CRO) "transaction hash:output address"
CRPT Crypterium "transaction hash:output address"
cSAI Compound Sai "transaction hash:output address"
cUSDC Compound USD Coin "transaction hash:output address"
CVC Civic "transaction hash:output address"
cWBTC Compound Wrapped BTC "transaction hash:output address"
cZRX Compound ZRX "transaction hash:output address"
DAI Dai "transaction hash:output address"
DASH Dash Output address format
"transaction hash:output address"

Or

Output index format
"transaction hash:output index"
DRGN Dragonchain "transaction hash:output address"
ELF aelf "transaction hash:output address"
ENG Enigma "transaction hash:output address"
ENJ Enjin Coin "transaction hash:output address"
EOS EOS Output address format
"transaction hash:output address"

Or

Output index format
"transaction hash:output index"
ETH Ethereum "transaction hash:output address"
ETHLend Aave "transaction hash:output address"
EURS Stasis Euro "transaction hash:output address"
EURX Etoro EUR "transaction hash:output address"
FTT FTX Token "transaction hash:output address"
GBPX Etoro GBP "transaction hash:output address"
GLDX Etoro GLD "transaction hash:output address"
GNO Gnosis "transaction hash:output address"
GNT Golem "transaction hash:output address"
GUSD Gemini Dollar "transaction hash:output address"
GYEN GMO Yen "transaction hash:output address"
HOT Holo Token "transaction hash:output address"
HT Huobi Token "transaction hash:output address"
HUSD Hot USD "transaction hash:output address"
IDRT Rupiah Token "transaction hash:output address"
JPYX Etoro YEN "transaction hash:output address"
KCS Kucoin Shares "transaction hash:output address"
KNC Kyber Network "transaction hash:output address"
LEO UNUS SED LEO "transaction hash:output address"
LINK Chainlink "transaction hash:output address"
LOOM Loom Network "transaction hash:output address"
LRC LoopringCoin "transaction hash:output address"
LTC Litecoin Output address format
"transaction hash:output address"

Or

Output index format
"transaction hash:output index"
MANA Decentraland "transaction hash:output address"
MATIC Matic Network "transaction hash:output address"
MCO Crypto.com (MCO) "transaction hash:output address"
MKR Maker "transaction hash:output address"
MLN Melon "transaction hash:output address"
MTL Metal "transaction hash:output address"
NEXO Nexo "transaction hash:output address"
NMR Numeraire "transaction hash:output address"
NPXS Pundi X "transaction hash:output address"
NZDX Etoro NZD "transaction hash:output address"
OKB Okex Exchange Token "transaction hash:output address"
OMG OmiseGO "transaction hash:output address"
OXT Orchid "transaction hash:output address"
PAX Paxos Standard "transaction hash:output address"
PAXG Paxos Gold "transaction hash:output address"
PAY TenX "transaction hash:output address"
POWR PowerLedger "transaction hash:output address"
QNT Quant "transaction hash:output address"
RCN Ripio Credit Network "transaction hash:output address"
REN Republic "transaction hash:output address"
RLC iExec Token "transaction hash:output address"
RUBX Etoro RUB "transaction hash:output address"
SAI Single Collateral DAI "transaction hash:output address"
SALT SALT "transaction hash:output address"
SENT Sentinel "transaction hash:output address"
SLVX Etoro SLV "transaction hash:output address"
SNT Status "transaction hash:output address"
STORJ Storj "transaction hash:output address"
sUSD SynthetixUSD "transaction hash:output address"
TGBP TrueGBP "transaction hash:output address"
TUSD TrueUSD "transaction hash:output address"
USDC USD Coin "transaction hash:output address"
USDEX Etoro USD "transaction hash:output address"
USDT USD Tether Omni "transaction hash"
USDT_ETH USD Tether Ether "transaction hash:output address"
VGX Voyager Token "transaction hash:output address"
WBTC Wrapped Bitcoin "transaction hash:output address"
WETH Wrapped Ether "transaction hash:output address"
WTC Waltonchain "transaction hash:output address"
XAUT Tether Gold "transaction hash:output address"
XCHF CryptoFranc "transaction hash:output address"
XRP XRP "transaction hash"

Or

“transaction hash:output address”

The output address is required when there is more than one receiving party, otherwise KYT records the receiving party as the 0 index (the first listed).
ZEC Zcash Output address format
"transaction hash:output address"

Or

Output index format
"transaction hash:output index"
ZRX 0x "transaction hash:output address"
ZUSD Z.com USD "transaction hash:output address"

Historic assets

Historic assets are assets that we have supported until a certain date due to factors such as coin migration, paused ingestion, or coin deprecation. For the assets listed below, KYT provides only the historical transaction values up to their specified date and does not yield new transfers.


Symbol Asset Date Notes ERC-20? Transfer format reference
ETC Ethereum Classic 2020-08-06 Paused ingestion following 51% attack. "transaction hash:output address"
FET Fetch.ai 2020-10-14 Migrated smart contract. "transaction hash:output address"
ICN Iconomi 2019-12-31 Coin deprecation. "transaction hash:output address"
REP Augur 2020-07-29 Migrated smart contract. "transaction hash:output address"
ZIL Zilliqa 2020-02-26 Migrated to native chain. "transaction hash:output address"

Sending Additional Assets

You can send data for additional assets that are not yet fully supported through the transfers/sent and transfers/received endpoints. As soon as KYT supports the coin, the system will automatically backfill any data you've sent and you only have to upload this data once. A list of all assets you can send appears below.

Some ERC-20 tokens may require additional input, which are specified below. All ERC-20 tokens must have a valid transaction hash. UTXO based cryptocurrencies must reference a transaction hash and a corresponding output address or transaction hash index. Read more about transfer formats here.

Note that the response when sending additional assets via the API is an empty JSON object. The KYT API does not validate addresses for coins we do not yet support.

Symbol Asset ERC-20? Transfer format reference
1ST Firstblood "transaction hash:output address"
ABT ArcBlock "transaction hash:output address"
ABYSS Abyss "transaction hash:output address"
ADA Cardano "transaction hash:output address"
ADD ADD "transaction hash:output address"
ADT adToken "transaction hash:output address"
ADX AdEx "transaction hash:output address"
AERGO Aergo "transaction hash:output address"
AGI SingularityNET "transaction hash:output address"
AIDf AidCoin "transaction hash:output address"
AION AION "transaction hash:output address"
AKRO Akropolis "transaction hash:output address"
ANKR Ankr "transaction hash:output address"
ANT Aragon "transaction hash:output address"
ART Maecenas "transaction hash:output address"
AST AirSwap "transaction hash:output address"
ATD Atidium "transaction hash:output address"
ATM Atonomi "transaction hash:output address"
ATOM Cosmos "transaction hash"
AUC Auctus "transaction hash"
AVT AVT "transaction hash"
BBN BBN "transaction hash:output address"
BCI Bitcoin Interest "transaction hash:output address"
BCPT BlockMason Credit Protocol "transaction hash:output address"
BFT BnkToTheFuture "transaction hash:output address"
BKX Bankex "transaction hash:output address"
BLOC Blockcloud "transaction hash:output address"
BLT Bloom "transaction hash:output address"
BNB_ETH Binance Coin ETH "transaction hash:output address"
BORA BORA "transaction hash:output address"
BOX ContentBox Token "transaction hash:output address"
BOXX Blockparty "transaction hash:output address"
BRZ BRZ Token "transaction hash:output address"
BSV Bitcoin SV "transaction hash:output address"
BTG Bitcoin Gold "transaction hash:output address"
BTT BitTorrent "transaction hash:output address"
BTU BTU Protocol "transaction hash:output address"
BWX Blue Whale eXchange "transaction hash:output address"
CBC CashBet "transaction hash:output address"
CBT CommerceBlock "transaction hash:output address"
CFI Cofoundit "transaction hash:output address"
CHR Chromia "transaction hash:output address"
CLO Callisto "transaction hash:output address"
CMCT Crowd Machine "transaction hash:output address"
CND Cindicator "transaction hash:output address"
CNHT Tether CNH "transaction hash:output address"
CNN CNN Token "transaction hash:output address"
CPT Contents Protocol "transaction hash:output address"
CS Credits "transaction hash:output address"
CTXC Cortex "transaction hash:output address"
DADI DADI "transaction hash:output address"
DATA Steamr DATAcoin "transaction hash:output address"
DENT Dent "transaction hash:output address"
DGB DIGIBYTE "transaction hash:output address"
DGD DigixDAO "transaction hash:output address"
DGX Digix Gold Token "transaction hash:output address"
DMT DMarket "transaction hash:output address"
DNT district0x "transaction hash:output address"
DT Dragon Token "transaction hash:output address"
DTA Data "transaction hash:output address"
DTH Dether "transaction hash:output address"
DUSK Dusk Network "transaction hash:output address"
EDG Edgeless "transaction hash:output address"
EDO Eidoo "transaction hash:output address"
EDR Endor "transaction hash:output address"
EOX EOX "transaction hash"
EPIQ Everipedia "transaction hash:output address"
ESS Essentia "transaction hash"
ETP Ethereum Platinum "transaction hash"
EURT Tether EUR "transaction hash"
EVT Ethfinex Voting Token "transaction hash"
FOA Foam Token "transaction hash:output address"
FSN Fusion "transaction hash:output address"
FTM Fantom "transaction hash:output address"
FTT FTX Com "transaction hash:output address"
FUN FunFair "transaction hash:output address"
FX Function X "transaction hash:output address"
FXC Flexacoin "transaction hash:output address"
GAM Gambit "transaction hash:output address"
GEN DAOStack "transaction hash:output address"
GEO GeoCoin "transaction hash:output address"
GOT GOToken "transaction hash:output address"
GTO Gifto "transaction hash:output address"
GTX Gate IO "transaction hash:output address"
GUP Guppy "transaction hash:output address"
HEDG HedgeTrade "transaction hash:output address"
HINT Hintchain "transaction hash:output address"
HMQ Humaniq "transaction hash:output address"
HOLD Hold "transaction hash:output address"
HST Decision Token "transaction hash:output address"
HXRO Hxro "transaction hash:output address"
HYDRO Hydro "transaction hash:output address"
IHT I-House Token "transaction hash:output address"
IMP Ether Kingdoms Token "transaction hash:output address"
INT Internet Node Token "transaction hash:output address"
IOTA IOTA "transaction hash:output address"
IOTX IoTeX "transaction hash:output address"
ITM Intimate "transaction hash:output address"
JNT Jibrel "transaction hash:output address"
KAN Kan "transaction hash:output address"
LAMB Lambda "transaction hash:output address"
LBA Cred "transaction hash:output address"
LBTC Liquid BTC "transaction hash:output address"
LEO-ERC20 UNUS SED LEO ERC20 "transaction hash:output address"
LUN Lunyr "transaction hash:output address"
LYM Lympo tokens "transaction hash:output address"
MAN Matrix AI Network "transaction hash:output address"
MEDX MediBloc "transaction hash:output address"
MET Metronome "transaction hash:output address"
MFT Mainframe "transaction hash:output address"
MITH Mithril Token "transaction hash:output address"
MOC Mossland "transaction hash:output address"
MORE More "transaction hash:output address"
MTN MedicalChainToken "transaction hash:output address"
MGO MobileGo "transaction hash:output address"
MOC Mossland "transaction hash:output address"
MTO Meetone "transaction hash:output address"
NANO NANO "transaction hash:output address"
NCASH Nucleus Vision "transaction hash:output address"
NEC Ethfinex Nectar Token "transaction hash:output address"
NEO NEO "transaction hash:output address"
NGC Naga "transaction hash:output address"
NIOX Autonio "transaction hash:output address"
NKN NKN "transaction hash:output address"
NXC Nexium "transaction hash:output address"
OCEAN Ocean Protocol "transaction hash:output address"
OCN Odyssey "transaction hash:output address"
ODE ODEM Token "transaction hash:output address"
OGO Origo "transaction hash:output address"
ONL On.Live "transaction hash:output address"
OMNI OMNI "transaction hash:output address"
ORBS Orbs "transaction hash:output address"
ORS ORS Token "transaction hash:output address"
OST Simple Token "transaction hash:output address"
PAI PAI Project "transaction hash:output address"
PASS Blockpass "transaction hash:output address"
PI PCHAIN "transaction hash:output address"
PLA PlayChip "transaction hash:output address"
PMA PumaPay "transaction hash:output address"
PNK Kleros Token "transaction hash:output address"
POLY Polymath "transaction hash:output address"
POA POA Network "transaction hash:output address"
PRO Propy "transaction hash:output address"
PROM Prometeus "transaction hash:output address"
PTON Foresting "transaction hash:output address"
PTOY Patientory "transaction hash:output address"
PXL Pixel "transaction hash:output address"
QASH QASH "transaction hash:output address"
QTUM Qtum "transaction hash:output address"
QWARK Qwark "transaction hash:output address"
RBTC RBTC "transaction hash:output address"
RDN Raiden "transaction hash:output address"
REQ Request Network "transaction hash:output address"
RFR Refereum "transaction hash:output address"
RIF RIF "transaction hash:output address"
RRB RenrenBit Token "transaction hash:output address"
RRT Recovery Rights Token "transaction hash:output address"
RTE Rate3 "transaction hash:output address"
SAN SANtiment Network Token "transaction hash:output address"
SEE SEER "transaction hash:output address"
SEN ConsenusAI "transaction hash:output address"
SERV Serve "transaction hash:output address"
SNGLS SingularDTV "transaction hash:output address"
SNX Synthetix "transaction hash:output address"
SOLVE Solve.Care "transaction hash:output address"
SPANK Spank "transaction hash:output address"
SPC SpaceChain "transaction hash:output address"
SPHR Sphere "transaction hash:output address"
SPIN SPIN Protocol "transaction hash:output address"
SPND Spendcoin "transaction hash:output address"
SRN Sirin Token "transaction hash:output address"
STEEM Steem "transaction hash:output address"
STORM Storm "transaction hash:output address"
STPT Standard Tokenization Protocol "transaction hash:output address"
SWT Swarm City Token "transaction hash:output address"
TEMCO TEMCO "transaction hash:output address"
TIX Blocktix "transaction hash:output address"
TKN TokenCard "transaction hash:output address"
TNB Time New Bank "transaction hash:output address"
TRAC OriginTrail "transaction hash:output address"
TRIO Tripio "transaction hash:output address"
TRST Trustcoin "transaction hash:output address"
TRX TRON "transaction hash:output address"
TSHP 12Ships "transaction hash:output address"
TUDA Tutor's Diary "transaction hash:output address"
UFR Upfiring "transaction hash:output address"
UKG UnikoinGold "transaction hash:output address"
UOS Ultra "transaction hash:output address"
UP UpToken "transaction hash:output address"
UPP Sentinel Protocol "transaction hash:output address"
URAC Uranus "transaction hash:output address"
USDK USDK "transaction hash:output address"
USDS StableUSD "transaction hash:output address"
UTK UTRUST "transaction hash:output address"
UTNP Universa "transaction hash:output address"
VDX Vodi X "transaction hash:output address"
VEE BLOCKv "transaction hash:output address"
VEN VeChain "transaction hash:output address"
VET VeChain "transaction hash:output address"
VIB Viberate "transaction hash:output address"
VITE Vite "transaction hash:output address"
VTI Vetri "transaction hash:output address"
VSYS v.systems "transaction hash:output address"
WAVES WAVES "transaction hash"
WAX Worldwide Asset Exchange "transaction hash:output address"
WIB Wibson "transaction hash:output address"
WINGS Wings DAO "transaction hash:output address"
WLO Wollo "transaction hash:output address"
WPR WePower "transaction hash:output address"
XD Data Transaction Token "transaction hash:output address"
XDG Dogecoin "transaction hash:output address"
XLM Stellar Lumens "transaction hash"
XMR Monero Deposits - "transaction hash:tx index:receiving address:payment ID"

Withdrawals - "transaction hash:tx index:withdrawal address:payment ID"

The asset amount must be included as another field in the JSON
XNK Ink Protocol "transaction hash:output address"
XRA MasterXriba "transaction hash:output address"
XTZ Tezos "transaction hash:output address"
XVG Verge "transaction hash:output address"
XYO XYO "transaction hash:output address"
YEED YGGDRASH "transaction hash:output address"
YOYOW YOYOW "transaction hash:output address"
ZBT ZBToken "transaction hash:output address"
ZCN 0Chain "transaction hash:output address"