NAV
cURL

Introduction

You can use the Chainalysis Address Screening API to register an address and then immediately retrieve a risk assessment for a registered address. You can use the assessment to help you determine whether to allow your business or dApp to interact with an address based on its risk.

What's new

See below for Address Screening API releases, updates, and changes.

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.


Click here to expand or collapse previous entries


August 2022

Exposure information

We’re set to add exposure to Address Screening! 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:

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 Address Screening API and an Address Screening 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 Address Screening user interface lets you view your risk assessments for each Entity category. Additionally, you can generate API keys. To learn more about Address Screening and its user interface, check out our Address Screening knowledge base.

Note: If you already are an Address Screening 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:

  1. Sign in to Address Screening.
  2. Hover over the Gear icon Organization Settings drop-down, then click Developers > API Keys.
  3. If an API Key is present, copy it. Alternatively, click Generate API Key and copy it. Use the API Key to authenticate the Address screening endpoints and learn more about workflows in Workflows.

Authentication

The Address Screening 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 Address Screening instance to test initial API integration and validation. Once you have finished testing and completed the integration, you can move to a second, "clean" Address Screening instance with a new API key. This second instance will be your primary, ongoing Address Screening instance.

Please contact your CSM to help you create your Address Screening instances and obtain their credentials.

Environment URLs:

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 Address Screening API.

Get risk for an address

  1. End-user connects their private wallet to your application.
  2. You register their wallet address with the POST endpoint.
  3. You screen the registered address to determine its risk with the GET endpoint.
  4. Using the risk assessment returned via API, decide whether to allow the address to interact with your application.

Rescreen an address for changes in risk

  1. Choose a cadence to rescreen addresses based on your compliance needs (e.g., monthly).
  2. You rescreen the registered address to see if there are changes in risk using the GET endpoint.
  3. 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

  1. You register a wallet address with the POST endpoint.
  2. You screen the registered address to determine its risk (both exposure and category) with the GET endpoint, and store the result of the screen.
  3. You rescreen any addresses as needed for an updated report.
  4. 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. Address Screening provides two vectors to determine an address's score:

Each category has a starter risk assessment and starter exposure threshold (e.g., 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 assigned rating is the greater of these two values, the address 0x123abc will have a Severe rating.

To learn more about how Chainalysis defines exposure and categorizes entities, see:

Viewing and customizing risk

You can view your organization’s list of risk settings on Address Screening’s Risk Settings page.

You can customize the risk settings for category and exposure by contacting Customer Support. For example, instead of the defaults, you may want addresses categorized as Gambling to return Low. You may also want addresses with exposure to Mixing in the range of 0%-25% to return Medium, 25-90% to return High, and 90%-100% to return Severe.

For exposure thresholds, the lower bound is always exclusive and the upper bound is always inclusive (i.e., 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:

Each address above is on the SDN List and will by default return a Severe value for the risk property.

API reference

Address screening

These endpoints allow you to register an address and retrieve a risk assessment for a registered address:

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": "> 49% Exposure To High Risk Jurisdiction",
    "cluster": null,
    "addressIdentifications": [],
    "exposures": [
        {
            "category": "exchange",
            "value": 18886754.22849
        },
        {
            "category": "high risk jurisdiction",
            "value": 28863189.79402
        },
        {
            "category": "scam",
            "value": 774.35881
        },
        {
            ...
        }
    ],
    "triggers": [
        {
            "category": "high risk jurisdiction",
            "percentage": 49.463885,
            "message": "> 49% exposure to high risk jurisdiction",
            "ruleTriggered": {
                "risk": "Severe",
                "minThreshold": 0.0,
                "maxThreshold": 1.0
            }
        },
        {
            "category": "scam",
            "percentage": 0.001327,
            "message": "> 0% exposure to scam",
            "ruleTriggered": {
                "risk": "Medium",
                "minThreshold": 0.0,
                "maxThreshold": 0.1
            }
        }
    ],
    "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 Sanctions",
    "cluster": {
        "name": "OFAC SDN Lazarus Group 2022-04-22",
        "category": "sanctions"
    },
    "addressIdentifications": [
        {
            "name": "SANCTIONS: OFAC SDN Lazarus Group 2022-04-22 53b6936513e738f44fb50d2b9476730c0ab3bfc1",
            "category": "sanctions",
            "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"
        }
    ],
    "exposures": [
        {
            "category": "fee",
            "value": 35.95915
        },
        {
            "category": "sanctions",
            "value": 152638682.86834
        }
    ],
    "triggers": [
        {
            "category": "sanctions",
            "percentage": 51.537210,
            "message": "> 51% exposure to sanctions",
            "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 (1Je3RohZT6mH1AofjcjMJXgbVgKrJNVohD):

{
    "address": "1Je3RohZT6mH1AofjcjMJXgbVgKrJNVohD",
    "risk": "Severe",
    "riskReason": "> 0% Exposure To High Risk Jurisdiction",
    "cluster": {
        "name": "Coinbase.com",
        "category": "exchange"
    },
    "addressIdentifications": [],
    "exposures": [
        {
            "category": "atm",
            "value": 711515651.48923
        },
        {
            "category": "child abuse material",
            "value": 529236.68061
        },
        {
            "category": "high risk jurisdiction",
            "value": 8716319.92238
        },
        {
            ...
        }
    ],
    "triggers": [
        {
            "category": "child abuse material",
            "percentage": 0.000033,
            "message": "> 0% exposure to child abuse material",
            "ruleTriggered": {
                "risk": "Severe",
                "minThreshold": 0.0,
                "maxThreshold": 1.0
            }
        },
        {
            "category": "high risk jurisdiction",
            "percentage": 0.000545,
            "message": "> 0% exposure to high risk jurisdiction",
            "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": "Severe",
    "riskReason": "> 0% Exposure To High Risk Jurisdiction",
    "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": [
        {
            "category": "atm",
            "value": 711515651.48923
        },
        {
            "category": "child abuse material",
            "value": 529236.68061
        },
        {
            "category": "high risk jurisdiction",
            "value": 8716319.92238
        },
        {
            ...
        }
    ],
    "triggers": [
        {
            "category": "child abuse material",
            "percentage": 0.000033,
            "message": "> 0% exposure to child abuse material",
            "ruleTriggered": {
                "risk": "Severe",
                "minThreshold": 0.0,
                "maxThreshold": 1.0
            }
        },
        {
            "category": "high risk jurisdiction",
            "percentage": 0.000545,
            "message": "> 0% exposure to high risk jurisdiction",
            "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 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.
exposure Array or null An array that contains the address's current direct exposures.
exposure.category String The entity category the address has exposure to.
exposure.value Number The address’s aggregate exposure to the corresponding category, denominated in USD.
triggers Array or null An array that contains information about any of your organization’s exposure rules the address has 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 that contains information about the exposure risk settings that were triggered.
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%.
status String A string that indicates the exposure check's current status. Possible values are PENDING, IN_PROGRESS, or COMPLETE. PENDING means the check hasn't finished, whereas IN_PROGRESS means the check is currently processing. An IN_PROGRESS status usually lasts milliseconds.

Error handling

Address Screening 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.

Address Screening 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.