NAV

What's new in Transaction Monitoring API

See below for Transaction Monitoring API releases, updates, and changes.

2024

August 2024

MATIC migrates to POL

On September 4, Polygon Labs will migrate the MATIC token to the POL token. For more details, see the Polygon Labs blog post.

Starting September 4, Transaction Monitoring will accept POL as a value for the asset property when registering transfers and withdrawal attempts. Support for MATIC will end on December 2, 2024.

Between September 4 and December 2, 2024, we will provide backward compatibility with both POL and MATIC , allowing you to test and upgrade your integrations. We recommended using this period to ensure your integrations fully support POL.

This change affects both the V1 and V2 endpoints:

For any assistance, please contact Customer Support.

Action required by October 1, 2024

We’re upgrading the Transaction Monitoring API to improve your integrations. To avoid API interruptions, complete the following tasks before October 1, 2024:

The categoryId property helps you avoid string matching entity category names. We sometimes change entity category names to reflect best practices and real-world scenarios. With the property, you can reference categories with a numeric ID so that you can avoid updating your code whenever a name change occurs. To learn more, see the Category IDs Knowledge Base article.

The formatType query parameter allows you to specify the address and hash format in your JSON responses. You can choose either normalized or display formats. To learn more, see Address and hash formats.

May 2024

New endpoint to retrieve internal users

We’ve released a new endpoint to retrieve a list of internal users:

This endpoint returns a list of users and other information such as their name, email address, last activity, permissions and licenses, and account status. To use this endpoint, the user or API key making a request needs the ORGADMIN permission. For detailed information about the response properties or how to make requests, see Retrieve internal users.

February 2024

New asset ID property

We’ve released the assetId property for the V2 registration endpoints:

This lets you use a smart contract address or (or other unique address ID) to identify tokens when registering transfers and withdrawal attempts. To learn more, see the following resources:

Category ID support for additional v1 endpoint

The POST /v1/users/{userId}/transfers/received has been updated to support the categoryId property.

As a reminder, this property identifies categories by their unique numerical identifier (for example, 6) instead of their name (for example, stolen funds). For a complete mapping of category names to category IDs, see the knowledge base article Category IDs.

High risk exchange renamed to No KYC exchange

We’ve renamed the High risk exchange entity category to No KYC exchange and updated the definition.

Note that no entities were added or removed from this category as a result of this update. API integrations will only return high risk exchange until October 2024, which is when the category and categoryName properties will be deprecated and replaced with categoryId. You must transition to the categoryId property before October 2024 to maintain seamless functionality of your systems. Learn more in this update.

Additionally, your existing high risk exchange risk settings carry over to your no kyc exchange risk settings.

To see all current entity categories and their definitions, see Chainalysis entity categories.

2023

December 2023

Backend enhancements and the withdrawal attempt workflow

We've introduced backend enhancements that may affect your withdrawal attempts workflow. When registering a withdrawal attempt, updatedAt will now consistently return null in the response of the POST request. This means KYT will not yet have processed the withdrawal and generated alerts. You will need to poll the summary endpoint while updatedAt is null to ensure KYT processed your withdrawal. Typically, KYT processes withdrawals within seconds. The withdrawal workflow is as follows:

  1. Call POST /v2/users/{userId}/withdrawal-attempts.
  2. Poll GET /v2/withdrawal-attempts/{externalId} while updatedAt is null.
  3. Call GET /v2/withdrawal-attempts/{externalId}/alerts (or other subsequent endpoints).

Previously, step two was not crucial as KYT would process and generate alerts instantaneously upon registration. Skipping step two now, however, may mean you miss withdrawal attempt alerts. Please update your integration by January 10, 2024 to avoid missing alerts.

For more information about withdrawal attempt workflows and polling times, see the following resources:

October 2023

Custom groups

We are excited to announce the release of a new feature, custom groups, designed to enhance customization and personalization in your risk management process. To learn more about custom groups or how to create them, see the Custom groups and Manage custom groups knowledge base articles.

Additional API response property

To accommodate custom groups, we’ve added a response property to the GET /v1/alerts/ endpoint:

This property returns the alert ID when the alert is for a custom group. If the new response property is null, the alert is for a regular entity category.

August 2023

New format type query parameter

We’ve recently released a new formatType query parameter for the following endpoints:

This query parameter allows you to specify the address and transaction hash format you receive in the returning JSON, either in the display or normalized formats. To learn more about supported formats, see Address and hash formats, or for example usage, see the endpoint schemas (linked above).

Historically, mature networks and assets returned data in a normalized format, while emerging networks and assets returned data in the display format.

An exception will be made for BNB Smart Chain’s (Binance_Smart_Chain when registering transfers) upcoming graduation to the mature tier, and it will still return addresses and hashes in the display format until June 2024. After that date, it will default to the normalized format if you have not specified a type with the formatType query parameter.

July 2023

Renamed entity categories now live

We’ve renamed several entity categories to better reflect the real-world service of blockchain entities. This includes:

Note that only the above entity category names and definitions were updated. At this time, entities in each category will remain the same and won’t be reclassified.

While the affected categories are backwards compatible and accept both values, we strongly recommend transitioning to the categoryId property before October 2024. This will help you maintain seamless functionality of your systems. To see all current entity categories and their definitions, see Chainalysis entity categories.

June 2023

Categories endpoint

We’ve recently released a new GET /v2/categories endpoint. This endpoint allows you to retrieve all available entity categories, along with their corresponding IDs. We recommend that you call this endpoint periodically to ensure that you have the most recent categories Chainalysis is using, keeping your KYT integrations up-to-date.

For detailed information about how to utilize the endpoint, please refer to the GET /v2/categories reference documentation.

Category IDs

We've updated the following endpoints with categoryId support:

Now, instead of using string matching for category names (for example, stolen funds), you can utilize their unique identifiers (for example, 6). For a complete mapping of category names to category IDs, see the knowledge base article Category IDs.

Looking ahead, we'll introduce an endpoint that will enable programmatic retrieval of categories and their corresponding IDs. You can call this endpoint periodically to ensure you have the most up-to-date information about the entity categories.

Update on renaming entity categories

In April, we announced upcoming changes to several entity categories and the impact it will have on you.

After further discussion, we are not renaming the Mining or Mining pool categories at this time. The other category renames we announced will occur on July 15, 2023.

To view the upcoming definitions, see the knowledge base's What's new entry.

April 2023

Upcoming entity categories

We‘re excited to introduce five new entity categories that provide a more nuanced way to classify blockchain entities:

Ensure that your KYT API integration is configured to handle these new entity categories.

For definitions, see Chainalysis entity categories.

Renaming existing entity categories

In early July, we are renaming the below entity categories to succinctly reflect the real-world service of blockchain entities. We will send an email at least 30 days prior with an exact date for these renames.

Additionally, to future proof KYT API integrations, a category ID property will be added to all existing endpoints that currently return entity categories.

2022

July 2022

We've recently released our Developer Portal! The Developer Portal can be accessed here and houses information such as:

With the addition of the Developer Portal, we've published two quickstarts (Register a transfer and Register a withdrawal attempt) and a tutorial (Retrieve alerts as Slack notifications). Watch this space as we continue to add more content!

Note that the API technical overview and reference documentation can still be found on this page. We’ve reorganized information to make the appropriate content easier to find and keep the endpoint reference cleaner.


February 2022

On March 10, 2022, we will be increasing our asset coverage extensively with the Emerging asset tier. To complement this change, we've added a new request body property (network) to identify the blockchain network a transfer occurs on. For all assets and networks that Chainalysis supported before February 15, 2022, you can effectively ignore the network property, and KYT is backward compatible for those assets. The network property will be required for all new assets and networks that Chainalysis begins to support going forward.

To help customers acclimate to this transition, we've published a new article, Asset tiers, and updated our lists of Mature and emerging networks and Pre-growth networks. We will update the rest of our KYT API reference documentation to account for the network property as we near the March 10th release date.

To learn more about KYT's functionality for each asset tier, see our knowledge base article, Asset coverage.

Additionally, on March 10th, 2022, we will be deprecating the KYT API /assets endpoint. This endpoint will not be updated with a current asset list after March 10th, 2022 and will be fully deprecated and unavailable on June 15th, 2022.

January 2022

We've added support to our GET /v1/alerts endpoint for behavioral alerts. You can now programmatically retrieve behavioral alerts with the query parameter alertType. Additionally, we've added the following JSON response properties for behavioral alerts:

To learn more about the new query parameter or response properties, check out the definitions and descriptions in the schema.

2021

August 2021

We've released a new endpoint to assign alerts. You can now make a POST request to programmatically assign alerts to users in your organization. To unassign an alert, use null in the request body.

Additionally, we've added the following response body fields to the GET /v1/alerts endpoint:

You can also sort and filter with these fields.

New optional requirement status

We've changed the requirement of certain request body fields for the POST /v2/users/{userId}/transfers endpoint. Now, transferTimestamp, assetAmount, outputAddress, inputAddress, assetPrice, and assetDenomination are optional for both CDN and fully-supported assets.

July 2021

We've recently released a new endpoint that retrieves an alert's status and comment history.

We've also added two new parameters to the get alerts endpoint:

Use these parameters to retrieve alerts with statuses and comments that were recently updated.

You can also use the sort parameter with alertStatusCreatedAt to sort your alerts by the time their status was created.

Restructure docs

We've updated our KYT API docs to restructure and reframe our endpoints. We believe the new structure brings more clarity to our API. It is important to note that both v1 and v2 endpoints are compatible. We've included a new API implementation that details how you might integrate with our API. We've renamed our old integration guide to Legacy implementation.

May 2021

We've recently released a new endpoint, POST: alert status and comment.

You can now make a POST request to change an alert's status and include a comment, giving you the ability to action historic alerts programmatically and ensure your case management syncs with KYT. View the endpoint here.

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

2020

October 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 supports here.

June 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 2020

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

March 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 supports here.

February 2020

2019

December 2019

Ethereum classic is supported

Filter alerts via API

October 2019

September 2019

August 2019

July 2019