Introduction
You can use the Entities API to register address-based entities, such as personal wallets or contract addresses, and retrieve their risk assessments. Once you have the risk assessments, you can use them to help determine whether to interact with the address. If you have a dApp, you can control the address's access to your application. Or, if you're a liquidity provider, you can better understand the risks of contributing to a liquidity pool.
What's new
See below for Entities API releases, updates, and changes.
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 Entities API.
For instructions about how to edit your indirect exposure risk settings, see Adjust risk settings.
Click here to expand or collapse previous entries
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 theexposures
array andtriggers.ruleTriggered
object.- For customers with indirect exposure, this returns either
indirect
ordirect
. - For customers without indirect exposure, this returns
direct
.
- For customers with indirect exposure, this returns either
direction
in theexposures
array andtriggers.ruleTriggered
object.- Independent of whether you have indirect exposure, this always returns
both_directions
.
- Independent of whether you have indirect exposure, this always returns
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 theexposures
array and thetriggers.ruleTriggered
object.- The values are either
direct
orindirect
.
- The values are either
direction
in theexposures
array andtriggers.ruleTriggered
object.- The value is
both_directions
.
- The value is
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.
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.
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.
Getting started
Creating an API key
To create an API key:
- Sign in to the Risk UI.
- Click the Help icon, select the Developers drop-down, then select API Keys.
- If an API Key is present, copy it. Alternatively, click Generate API Key and copy it. Use the API Key to authenticate the Entities endpoints and learn more about workflows in Workflows.
Authentication
The Entities API uses a unique API token to authorize calls. You pass this unique token in the header:
curl -X GET {API URL} \
--header "Token: {YOUR_API_TOKEN}" \
--header "Accept: application/json"
Environments
We recommend using a sandbox entities instance to test initial API integration and validation. Once you have finished testing and completed the integration, you can move to a second, "clean" instance with a new API key. This second instance will be your primary, ongoing entities instance.
Please contact your CSM to help you create your entities instances and obtain their credentials.
Environment URLs:
- Chainalysis Risking UI kyt.chainalysis.com
- Chainalysis Entities API base URL api.chainalysis.com/api/risk
Security: All API access is secured using HTTPS with TLS (v1.2) being supported.
Base URL
The base URL of the API is: api.chainalysis.com/api/risk
.
Workflows
Below are example workflows that can be used with the Entities API.
Get risk for a private address
- End-user connects their private wallet to your application.
- You register their wallet address with the POST endpoint.
- You retrieve the wallet address's risk assessment with the GET endpoint.
- Using the risk assessment returned via API, decide whether to allow the address to interact with your application.
Get risk for a contract address
- You identify a liquidity pool you're interested in providing liquidity for.
- You register the liquidity pool's contract address with the POST endpoint.
- You retrieve the liquidity pool's risk assessment with the GET endpoint.
- Using the risk assessment returned via API, decide whether to contribute liquidity to the pool.
Rescreen an address for changes in risk
- Choose a cadence to rescreen addresses based on your compliance needs (e.g., monthly).
- You rescreen the registered address to see if there are changes in risk using the GET endpoint.
- You decide whether to take an action based on any updated source of funds information.
Get an audit trail of the risk of screened addresses
- You register a wallet address with the POST endpoint.
- You screen the registered address to determine its risk (both exposure and category) with the GET endpoint, and store the result of the screen.
- You rescreen any addresses as needed for an updated report.
- You aggregate all responses and report on them as needed.
Risk
How risk is determined
Risk assessments come as either Severe, High, Medium, or Low scores. Entity risking provides two vectors to determine an address's score:
- The address's entity category.
- The address's exposure to a given entity category.
Each category has a starter risk assessment and starter exposure threshold (a percentage of total exposure) to a given category. If an address meets two or more criteria, whichever score is greater is assigned to the address.
For example, address 0x123abc may have an entity category of Darknet Market (constituting a score of High) and have 20% direct exposure to a sanctioned entity (constituting a risk score of Severe). Since the exposure score is the greater of the two, the address 0x123abc will have a Severe score. We calculate exposure values using both directions (sent and received).
To learn more about how Chainalysis defines exposure and categorizes entities, see:
- Exposure
- Clustering and identification
- Chainalysis entity categories
- Viewing and customizing risk settings
Viewing and customizing risk settings
Entity risking’s starter rules should be tailored to meet your compliance needs. Today, we only provide starter rules for direct exposure and don’t provide starter rules for indirect exposure. You can view your organization’s risk settings by clicking Tools > Risk settings, then navigating to the Entities tab.
Since indirect exposure does not come with starter rules, you must configure them. Until you do, the risk
value will remain unaffected by indirect exposure, even though indirect exposure values return in the exposures
array.
Example
As an example, if you’re in a jurisdiction where gambling is legal, you might want to set addresses categorized as Gambling to Low to help reduce false positives. If set to Low, these addresses will only return a Low score unless they also meet a specific exposure percentage threshold.
As a second step, you can adjust the exposure percentage thresholds. For example, you can set 1%-25% exposure to Mixing to return Medium, 25%-90% to return High, and 90%-100% to return Severe. Setup like this, a Gambling address will always score Low unless it has Mixing exposure:
- 1%-25% would return Medium.
- 25-90% would return High.
- 90%-100% would return Severe.
For exposure thresholds, the lower bound is always exclusive and the upper bound is always inclusive (10%-20% means greater than 10% and less than or equal to 20%).
Addresses to test
The following are some addresses that you can test the API with:
- 0x8589427373D6D84E98730D7795D8f6f8731FDA16
- 0x8d3a28A74435A6562Ac41bAcCC0547eA5a161040
- 0x8576acc5c05d6ce88f4e49bf65bdf0c62f91353c
- 0x53b6936513e738f44FB50d2b9476730C0Ab3Bfc1
- 0x72a5843cc08275C8171E582972Aa4fDa8C397B2A
- 0x6f1ca141a28907f78ebaa64fb83a9088b02a8352
Each address above is on the SDN List and will by default return a Severe
value for the risk
property.
API reference
Entity risking
These endpoints allow you to register an address and retrieve a risk assessment for a registered address:
- POST
/v2/entities
(Register) - GET
/v2/entities/{address}
(Retrieve)
Register address
ENDPOINT
POST
/v2/entities
This endpoint registers an address and allows you to retrieve the risk assessment for the address.
Note: An address needs to be registered once using the POST endpoint before its risk assessment can be retrieved using the GET endpoint.
The following is an example cURL request to register the address
0x0038AC785dfB6C82b2c9A7B3B6854e08a10cb9f1
:
curl -X POST 'https://api.chainalysis.com/api/risk/v2/entities' \
--header 'Token: {YOUR_API_TOKEN}' \
--header 'Content-Type: application/json' \
--data-raw '{
"address": "0x0038AC785dfB6C82b2c9A7B3B6854e08a10cb9f1"
}'
Request body schema
Property | Type | Required | Description |
---|---|---|---|
address |
String | Yes | The address that you want to register. |
Response schema
The following is an example JSON response body for a successful registration of an address:
{
"address": "0x0038AC785dfB6C82b2c9A7B3B6854e08a10cb9f1"
}
A successful request will return the following JSON response.
Property | Type | Description |
---|---|---|
address |
String | An echoback of the address you registered. |
Retrieve risk assessment for a registered address
ENDPOINT
GET
/v2/entities/{address}
This endpoint retrieves the risk assessment for a registered address. If the address has not been registered, the response will return a message
property with the value Entity not found. Please be sure to register the Entity
.
The following is an example cURL request to view the risk assessment for the address
0x0038AC785dfB6C82b2c9A7B3B6854e08a10cb9f1
:
curl -X GET 'https://api.chainalysis.com/api/risk/v2/entities/0x0038AC785dfB6C82b2c9A7B3B6854e08a10cb9f1' \
--header 'Token: {YOUR_API_TOKEN}' \
--header 'Content-Type: application/json' \
Path parameters
Parameter | Type | Required | Description |
---|---|---|---|
address |
String | Yes | The address that you want to retrieve a risk assessment for. |
Response schema
The following is an example JSON response body when retrieving the risk assessment of a clean private wallet (0x0038AC785dfB6C82b2c9A7B3B6854e08a10cb9f1):
{
"address": "0x0038AC785dfB6C82b2c9A7B3B6854e08a10cb9f1",
"risk": "Low",
"riskReason": null,
"cluster": null,
"addressIdentifications": [],
"exposures": [
{
"category": "exchange",
"value": 424895.68594
},
{
"category": "fee",
"value": 1108.16272
},
{
"category": "unnamed service",
"value": 3612152.81483
}
],
"triggers": [],
"status": "COMPLETE"
}
The following is an example JSON response body when retrieving the risk assessment of a risky private wallet (0x2337bBCD5766Bf2A9462D493E9A459b60b41B7f2):
{
"address": "0x2337bBCD5766Bf2A9462D493E9A459b60b41B7f2",
"risk": "Severe",
"riskReason": "> 50% Exposure To Sanctioned Jurisdiction",
"cluster": null,
"addressIdentifications": [],
"exposures": [
{
"category": "exchange",
"value": 18912691.08382
},
{
"category": "fee",
"value": 74901.03290
},
{
"category": "no kyc exchange",
"value": 37457.26330
},
{
"category": "other",
"value": 72.82114
},
{
"category": "sanctioned jurisdiction",
"value": 29927285.77654
},
{
"category": "scam",
"value": 774.35881
}
],
"triggers": [
{
"category": "sanctioned jurisdiction",
"percentage": 50.641326,
"message": "> 50% exposure to sanctioned jurisdiction",
"ruleTriggered": {
"risk": "Severe",
"minThreshold": 0.0,
"maxThreshold": 1.0
}
},
{
"category": "scam",
"percentage": 0.001310,
"message": "> 0% exposure to scam",
"ruleTriggered": {
"risk": "High",
"minThreshold": 0.0,
"maxThreshold": 1.0
}
}
],
"status": "COMPLETE"
}
The following is an example JSON response body when retrieving the risk assessment for an address with an OFAC sanctions designation (0x53b6936513e738f44FB50d2b9476730C0Ab3Bfc1):
{
"address": "0x53b6936513e738f44FB50d2b9476730C0Ab3Bfc1",
"risk": "Severe",
"riskReason": "Identified as Sanctioned Entity",
"cluster": {
"name": "OFAC SDN Lazarus Group 2022-04-22",
"category": "sanctioned entity"
},
"addressIdentifications": [
{
"name": "SANCTIONED ENTITY: MOFA JP Lazarus Group 2022-12-12 53b6936513e738f44fb50d2b9476730c0ab3bfc1",
"category": "sanctioned entity",
"description": "This specific address 0x53b6936513e738f44FB50d2b9476730C0Ab3Bfc1 within the cluster has been identified as belonging to MOFA JP Lazarus Group 2022-12-12. \n\nLazarus Group\na.k.a. Hidden Cobra; Office 91; Guardians of Peace; The New Romantic Cyber Army Team; Whois Hacking Team; Red Dot; Temp.Hermit; Group 77; Zinc; APT-C-26; Appleworm)\n所在地:北朝鮮平壌特別市普通江区域\n暗号資産アドレス:\n0xa0e1c89Ef1a489c9C7dE96311eD5Ce5D32c20E4B;\n0x098B716B8Aaf21512996dC57EB0615e2383E2f96;\n0x3Cffd56B47B7b41c56258D9C7731ABaDc360E073;\n0x53b6936513e738f44FB50d2b9476730C0Ab3Bfc1;\n0x35fB6f6DB4fb05e6A4cE86f2C93691425626d4b1;\n0xF7B31119c2682c88d88D455dBb9d5932c65Cf1bE;\n0x3e37627dEAA754090fBFbb8bd226c1CE66D255e9;\n0x08723392Ed15743cc38513C4925f5e6be5c17243\n\nhttps://www.mofa.go.jp/mofaj/files/100429313.pdf"
},
{
"name": "SANCTIONED ENTITY: OFAC SDN Lazarus Group 2022-04-22 53b6936513e738f44fb50d2b9476730c0ab3bfc1",
"category": "sanctioned entity",
"description": "This specific address 0x53b6936513e738f44FB50d2b9476730C0Ab3Bfc1 has been identified as belonging to Lazarus Group.\n\nLAZARUS GROUP (a.k.a. \"APPLEWORM\"; a.k.a. \"APT-C-26\"; a.k.a. \"GROUP 77\"; a.k.a. \"GUARDIANS OF PEACE\"; a.k.a. \"HIDDEN COBRA\"; a.k.a. \"OFFICE 91\"; a.k.a. \"RED DOT\"; a.k.a. \"TEMP.HERMIT\"; a.k.a. \"THE NEW ROMANTIC CYBER ARMY TEAM\"; a.k.a. \"WHOIS HACKING TEAM\"; a.k.a. \"ZINC\"), Potonggang District, Pyongyang, Korea, North; Digital Currency Address - ETH 0x098B716B8Aaf21512996dC57EB0615e2383E2f96; Secondary sanctions risk: North Korea Sanctions Regulations, sections 510.201 and 510.210; Transactions Prohibited For Persons Owned or Controlled By U.S. Financial Institutions: North Korea Sanctions Regulations section 510.214 [DPRK3]. -to- LAZARUS GROUP (a.k.a. \"APPLEWORM\"; a.k.a. \"APT-C-26\"; a.k.a. \"GROUP 77\"; a.k.a. \"GUARDIANS OF PEACE\"; a.k.a. \"HIDDEN COBRA\"; a.k.a. \"OFFICE 91\"; a.k.a. \"RED DOT\"; a.k.a. \"TEMP.HERMIT\"; a.k.a. \"THE NEW ROMANTIC CYBER ARMY TEAM\"; a.k.a. \"WHOIS HACKING TEAM\"; a.k.a. \"ZINC\"), Potonggang District, Pyongyang, Korea, North; Digital Currency Address - ETH 0x098B716B8Aaf21512996dC57EB0615e2383E2f96; alt. Digital Currency Address - ETH 0xa0e1c89Ef1a489c9C7dE96311eD5Ce5D32c20E4B; alt. Digital Currency Address - ETH 0x3Cffd56B47B7b41c56258D9C7731ABaDc360E073; alt. Digital Currency Address - ETH 0x53b6936513e738f44FB50d2b9476730C0Ab3Bfc1; Secondary sanctions risk: North Korea Sanctions Regulations, sections 510.201 and 510.210; Transactions Prohibited For Persons Owned or Controlled By U.S. Financial Institutions: North Korea Sanctions Regulations section 510.214 [DPRK3]. \n\nhttps://home.treasury.gov/policy-issues/financial-sanctions/recent-actions/202204222"
},
{
"name": "SANCTIONED ENTITY: MOFA FSC Lazarus Group 2023-02-10 53b6936513e738f44fb50d2b9476730c0ab3bfc1",
"category": "sanctioned entity",
"description": "This specific address 0x53b6936513e738f44FB50d2b9476730C0Ab3Bfc1 within the cluster has been identified as belonging to MOFA FSC Lazarus Group 2023-02-10.\n\nLAZARUS GROUP (a.k.a. \"APPLEWORM\"; a.k.a. \"APT-C-26\"; a.k.a. \"GROUP 77\"; a.k.a.\n\"GUARDIANS OF PEACE\"; a.k.a. \"HIDDEN COBRA\"; a.k.a. \"OFFICE 91\"; a.k.a. \"RED DOT\"; a.k.a. \"TEMP.HERMIT\"; a.k.a. \"THE NEW ROMANTIC CYBER ARMY TEAM\"; a.k.a. \"WHOIS HACKING TEAM\"; a.k.a. \"ZINC\"), Potonggang District, Pyongyang, Korea, North; Digital Currency\nAddress - ETH 0x098B716B8Aaf21512996dC57EB0615e2383E2f96; alt. Digital Currency Address -\nETH 0xa0e1c89Ef1a489c9C7dE96311eD5Ce5D32c20E4B; alt. Digital Currency Address - ETH\n0x3Cffd56B47B7b41c56258D9C7731ABaDc360E073; alt. Digital Currency Address - ETH\n0x53b6936513e738f44FB50d2b9476730C0Ab3Bfc1; alt. Digital Currency Address - ETH\n0x35fB6f6DB4fb05e6A4cE86f2C93691425626d4b1; alt. Digital Currency Address - ETH\n0xF7B31119c2682c88d88D455dBb9d5932c65Cf1bE; alt. Digital Currency Address - ETH\n0x3e37627dEAA754090fBFbb8bd226c1CE66D255e9; alt. Digital Currency Address - ETH\n0x08723392Ed15743cc38513C4925f5e6be5c17243 (2023. 2. 10 지정).\n\nhttps://www.fsc.go.kr/po040200/79415?srchCtgry=&curPage=&srchKey=&srchText=&srchBeginDt=&srchEndDt="
}
],
"exposures": [
{
"category": "fee",
"value": 35.95914
},
{
"category": "sanctioned entity",
"value": 152638682.86834
}
],
"triggers": [
{
"category": "sanctioned entity",
"percentage": 51.537210,
"message": "> 51% exposure to sanctioned entity",
"ruleTriggered": {
"risk": "Severe",
"minThreshold": 0.0,
"maxThreshold": 1.0
}
}
],
"status": "COMPLETE"
}
The following is an example JSON response body when retrieving the risk assessment of an address owned by an exchange that has an address-level identification of scam (32PUt3ijeewVN2jjoYJqP9ReDfjhqHW3EL):
{
"address": "32PUt3ijeewVN2jjoYJqP9ReDfjhqHW3EL",
"risk": "High",
"riskReason": "Identified as Scam",
"cluster": {
"name": "Coinbase.com",
"category": "exchange"
},
"addressIdentifications": [
{
"name": "SCAM: Alpha-Cash.com 32PUt3ijeewVN2jjoYJqP9ReDfjhqHW3EL",
"category": "scam",
"description": "This specific address 32PUt3ijeewVN2jjoYJqP9ReDfjhqHW3EL within the cluster has been identified as Alpha-Cash.com."
}
],
"exposures": [],
"triggers": [],
"status": "COMPLETE"
}
The following is an example JSON response body when retrieving the risk assessment of a liquidity pool (0x512011c2573e0EcBd66be051b9A1C0fd097F2092):
{
"address": "0x512011c2573e0EcBd66be051b9A1C0fd097F2092",
"risk": "Low",
"riskReason": null,
"cluster": {
"name": "Uniswap V3: WETH 0xc02aaa - CMB 0xc6db55 (0.3%)",
"category": "decentralized exchange"
},
"addressIdentifications": [],
"exposures": [
{
"category": "decentralized exchange",
"value": 8902121.21723
}
],
"triggers": [],
"status": "COMPLETE",
"poolMetadata": {
"fees": 0.3,
"tokens": [
"WETH",
"CMB"
]
}
}
The following is an example JSON response body when you have indirect exposure enabled:
{
"address": "0x2337bBCD5766Bf2A9462D493E9A459b60b41B7f2",
"risk": "Severe",
"riskReason": "> 50% Indirect Exposure To Sanctioned Jurisdiction",
"cluster": null,
"addressIdentifications": [],
"exposures": [
{
"category": "sanctioned jurisdiction",
"value": 3660.77658,
"exposureType": "direct",
"direction": "both_directions"
},
{
"category": "sanctioned jurisdiction",
"value": 5000.35881,
"exposureType": "indirect",
"direction": "both_directions"
}
],
"triggers": [
{
"category": "sanctioned jurisdiction",
"percentage": 50.641326,
"message": "> 50% indirect exposure to sanctioned jurisdiction",
"ruleTriggered": {
"risk": "Severe",
"minThreshold": 0.0,
"maxThreshold": 1.0,
"exposureType": "direct",
"direction": "both_directions"
}
}
],
"status": "COMPLETE"
}
The following is an example JSON response body when retrieving the risk assessment of an address that has not yet been registered:
{
"message": "Entity not found. Please be sure to register the Entity."
}
A successful request will return the following JSON response.
Property | Type | Description |
---|---|---|
address |
String | The address that you are assessing the risk of. |
risk |
String | The risk assessment of the address. Values can be Severe , High , Medium , or Low . The assessment is whichever is greater between the category or exposure assessments. |
riskReason |
String or null |
A human-readable string that provides the rationale for the returned risk assessment. |
cluster |
Object or null |
An object that contains any available cluster information for the provided address. If the object returns null , the address has not been clustered. |
cluster.name |
String | The name of the identified cluster. |
cluster.category |
String | The category of the identified cluster. |
addressIdentifications |
Array | An array that contains any available Chainalysis Address Identification information. These are used to identify individual addresses part of a larger cluster. If the array is empty, the address has no address-level identification. |
addressIdentifications.name |
String | The name designated to the Chainalysis Address Identification. |
addressIdentifications.category |
String | The category of the Chainalysis Address Identification. |
addressIdentifications.description |
String | The OSINT from the Chainalysis Address Identification. |
exposures |
Array or null |
An array that contains the address's current exposures. |
exposures.category |
String | The entity category the address has exposure to. |
exposures.value |
Number | Denotes the exposure to the corresponding category, denominated in USD. If indirect exposure is not enabled, it represents only direct exposure, and aggregates both sent and received directions. |
exposures.exposureType |
String | The exposure type, either direct or indirect . If you don’t have access to indirect exposure, this property will only return direct . This value aggregates sent and received directions (both directions). |
exposures.direction |
String | The exposure direction. The value will only be both_directions . |
triggers |
Array or null |
An array containing information about any exposure rules the address triggered. |
triggers.category |
String | The entity category of the triggered exposure rule. |
triggers.percentage |
Number | The percentage of exposure the address has to the corresponding category . |
triggers.message |
String | A short, human-readable description of the trigger. |
triggers.ruleTriggered |
Object or null |
An object containing details about the exposure rule the address triggered, such as thresholds of the triggered exposure rule, the riskiness assigned to the address when this rule is triggered, exposure direction, and exposure type. |
triggers.ruleTriggered.risk |
String | The riskiness assigned to the address when this rule is triggered. |
triggers.ruleTriggered.minThreshold |
Number | The lower bound of the triggered exposure rule. This threshold is always exclusive (e.g., >) and the number correlates to a percentage. For example, 10.0 means >10%. |
triggers.ruleTriggered.maxThreshold |
Number | The upper bound of the triggered exposure rule. This threshold is always inclusive (e.g., <=) and the number correlates to a percentage. For example, 20.0 means <=20%. |
triggers.ruleTriggered.exposureType |
String | The exposure type, either direct or indirect . If you don’t have access to indirect exposure, this property will only return direct . This value aggregates sent and received directions (both directions). |
triggers.ruleTriggered.direction |
String | The exposure direction. The value will only be both_directions . |
status |
String | A string that indicates the exposure check's status. Currently, the only possible value is COMPLETE . While there were previously other options (IN_PROGRESS and PENDING ), improvements have made these statuses obsolete, and you should now only ever see the COMPLETE status. |
poolMetadata |
Object | An object that contains metadata about the liquidity pool. Note: This property only returns if the screened address is a liquidity pool. |
poolMetadata.fees |
Number or null |
The fees associated with the pool. It is expressed in scientific notation, where 1.0E-4 is equivalent to 0.0001 . This value is typically a small number, representing a percentage of the transaction. |
poolMetadata.tokens |
Array | An array that contains the symbols of the tokens traded in the pool. Each string in the array is a token symbol. For example, WETH and NIOX are token symbols. |
Error handling
Entities Risking uses standard HTTP response codes to indicate the success or failure of an API request.
Response codes in the 2xx
range indicate success. Response codes in the 4xx
range indicate an error due to the information provided, such as a missing or incorrectly formatted parameter or request body property. Response codes in the 5xx
range indicate an internal server error within Chainalysis.
Entities API codes and meaning
Code | Meaning | Description |
---|---|---|
200 | Successful request | The request was successful. |
400 | Bad request | The request was unacceptable. This may refer to a missing or improperly formatted parameter or request body property, non-valid JSON, or the use of testnet blockchain data. |
403 | Forbidden | Your API key is invalid. This may be because your API Key is expired or not sent correctly as the value of the Token HTTP header. |
404 | Not found | This may be because you either requested a nonexistent endpoint or referenced a user that does not exist. |
406 | Not acceptable | You requested a response format that the API cannot produce. We currently only support JSON output. |
409 | Conflict | The request has a conflict. |
500 | Internal server error | (Rare.) This indicates an error with Chainalysis's server. |
503 | Service unavailable error | (Rare.) Chainalysis's server may be unavailable or not ready to handle the request. |
504 | Request timeout | (Rare.) This indicates that our API gateway did not get a response from our application servers within the expected time. |
Error response schema
The following is an example JSON response body from a
403
error:
{
"message": "Missing Authentication Token"
}
Property | Type | Description |
---|---|---|
message |
String | A human-readable string that provides further detail about the error. |