What's new in the Entity Risking API

See below for Entity Risking API releases, updates, and changes.

2025

January 2025

Optional changes to the Entity Risking API

We are excited to announce that starting December 4, 2024, you will no longer need to register an address via the POST endpoint to retrieve exposure and risk scores. Instead, you can use the GET endpoint to directly retrieve exposure and risk scores.

While we encourage you to migrate to only use the GET endpoint, the POST endpoint will remain functional, and your existing workflows will not be impacted.

2024

April 2024

Indirect exposure risk settings available in the user interface

Platinum and Gold customers who have opted in for indirect exposure can now configure their risk settings directly in the user interface, eliminating the need to submit a CSV file of risk settings to Customer Support. This comes as a follow up to providing indirect exposure data for entities screened programmatically with the Entity Risking API.

For instructions about how to edit your indirect exposure risk settings, see Adjust risk settings.

March 2024

New response properties

On May 8, 2024, we will introduce the exposureType and direction properties in the GET /v2/entities/{address} API response for all customers. Please update your integrations to accommodate these properties before May 8, 2024.

As a reminder, we recently released an early access version of indirect exposure to Platinum and Gold customers, and we’re now standardizing our system so that these properties return for all customers. This update provides clarity about the exposure type and direction you’re accessing:

• exposureType in the exposures array and triggers.ruleTriggered object.
  • For customers with indirect exposure, this returns either indirect or direct.
  • For customers without indirect exposure, this returns direct.
• direction in the exposures array and triggers.ruleTriggered object.
  • Independent of whether you have indirect exposure, this always returns both_directions.

To maintain the integrity of your integrations, please review your current handling of API responses to ensure your systems can accommodate the exposureType and direction properties. For detailed information about these responses, see the GET /v2/entities/{address} API reference documentation.

February 2024

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. If you've hard coded against high risk exchange in your API integration, you'll need to update that to allow for no kyc exchange. no kyc exchange can appear in the following endpoint:

• GET /v2/entities/{address}
  • addressIdentifications.category
  • cluster.category
  • exposures.category
  • riskReason
  • triggers.category
  • triggers.message

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.

Indirect exposure

We now offer indirect exposure via API for entity risking! This is available only to Platinum and Gold customers. If you’d like to upgrade your tier or enable access, please contact Customer Support.

With indirect exposure enabled, the GET /v2/entities/{address} endpoint now returns the following properties:

• exposureType in the exposures array and the triggers.ruleTriggered object.
  • The values are either direct or indirect.
• direction in the exposures array and triggers.ruleTriggered object.
  • The value is both_directions.

To learn more about these properties or to see JSON response examples, see Retrieve risk assessment for a registered address.

To set your indirect exposure risk settings, please contact Customer Support.

2023

May 2023

New response properties

We've added new JSON response properties that return when screening liquidity pools:

• poolsMetadata
• fees
• tokens

These properties return when retrieving the risk assessment of a liquidity pool address. Additionally, we've added an example JSON response for a liquidity pool. For definitions of the properties or to see the new example, see the endpoint reference. To learn more about screening liquidity pools in general, check out the knowledge base update.

March 2023

Updated property

Due to system optimizations, the status property in the GET /v2/entities/{address} response now only returns the value COMPLETE in practice. The previous options, IN_PROGRESS and PENDING, will no longer return.

2022

November 2022

New response property

We've added riskReason as a new response property for the GET /v2/entities/{address} endpoint. This property provides a brief rationale for an address's returned risk assessment. To learn more about the property or to view JSON examples, see Retrieve risk assessment for a registered address.

August 2022

Exposure information

We’re set to add exposure to entities risking. Exposure adds another vector to help determine an address’s risk.

The GET /v2/entities/{address} endpoint now returns the exposure and triggers arrays. The exposure array contains objects detailing an address’s complete exposure, and the triggers array returns objects where exposure meets your organization's exposure risk settings. To learn more about the new properties or how exposure affects a risk assessment, see the following resources:

• GET /v2/entities/{address} endpoint reference
• Risk

In addition to the API improvements, we’ve added exposure settings to the user interface. As well as viewing your risk settings for categories, you can now view your risk settings for various exposure thresholds. To learn more, check out View your risk settings. If you would like to customize these settings, please contact Customer Support.

June 2022

Dedicated endpoints and a user interface

We've recently released a dedicated Entities API and user interface.

The new endpoints provide you with an improved user experience. You no longer need to send or associate a userId with an address or identify a particular asset and network pair. Instead, you can register any address from any network and retrieve the address's risk assessment. The new endpoints have a new path and will require a separate integration. See the API reference and workflows to learn more.

The entities user interface lets you view your risk assessments for each Entity category. Additionally, you can generate API keys. To learn more about entities risking and its user interface, check out our entities risking knowledge base.

Note: If you already are customer integrated with the /withdrawaladdressesendpoints, you do not need to migrate to the new endpoints.