NAV
cURL

API Technical Integration Guide

Requirements and other resources

API keys

You can create API keys from the Settings option in the UI's Account menu.

To create an API key:

  1. Log into the Transaction Monitoring (either sandbox or primary) for which you want to create an API key.
  2. From the Help icon drop-down menu, click Developers > API Keys.
  3. Click the Generate API Key button. Your API key appears below.

You can also obtain an API key from the Help icon drop-down menu in Reactor. Click Developers > API Keys.

API documentation

This document is focused on providing workflow and integration examples. Supplemental technical documentation can also be found here.

Integration resources

Developer - This document is focused on providing your Development team technical information needed to successfully integrate.

Compliance - This document covers high-level concepts of alerting and alert testing using our default alert thresholds. Specific alerting thresholds should be defined by your compliance team in accordance with your risk and compliance policy. See section Alerting and Testing at the end of this guide for more information on how to test alerts.

Transaction Monitoring implementation features

The matrix below defines four standard workflow options based on features offered. Each subsequent workflow contains the features from the previous workflow.

Integration workflow descriptions

Workflow 1

Overview

Integrating with the UI

Advantages

Limitations

API endpoints

Registering a mature asset

Endpoint: POST /v2/users/{userId}/transfers

Notes

Example call

curl -X POST 'https://api.chainalysis.com/api/kyt/v2/users/user_example/transfers' \
    --header 'token: {API KEY}' \
    --header 'Content-Type: application/json' \
    --header 'Accept: application/json' \
    --data '{
        "network": "Bitcoin",
        "asset": "BTC",
        "transferReference": "0f6d4e6b9bddbe3dacb043012ffa029d706867e4749600f1d048aae9d1a66011:3A62vpSwwLM88DAjE8VwnX9gfqSpitUxg7", 
        "direction": "received" 
    }

Response

{
    "updatedAt": null,
    "asset": "BTC",
    "network": "BITCOIN",
    "transferReference": "0f6d4e6b9bddbe3dacb043012ffa029d706867e4749600f1d048aae9d1a66011:3A62vpSwwLM88DAjE8VwnX9gfqSpitUxg7",
    "tx": null,
    "idx": null,
    "usdAmount": null,
    "assetAmount": null,
    "timestamp": null,
    "outputAddress": null,
    "externalId": "53844b3c-510d-3a30-bb69-9566bcc0a5a6"
}

Registering a pre-growth asset

Endpoint: POST /v2/users/{userId}/transfers

Notes

Example call

curl -X POST 'https://api.chainalysis.com/api/kyt/v2/users/user_example/transfers' \
    --header 'token: {API KEY}' \
    --header 'Content-Type: application/json' \
    --header 'Accept: application/json' \
    --data '{ 
        "network": "Chia", 
        "asset": "XCH", 
        "transferReference": "0x3419e2be63a8404826a49ab250b007f27447333019079d083c2b322c4cbe3cd4:xch19ukfhgdjx9w5zw5jkhcrf7sr9qkvhgtk0lv6u7c5m9ptj60dt4tscqkmna", 
        "direction":"sent", 
        "transferTimestamp": "2022-03-10T20:37:32+00:00", 
        "assetAmount": "1.75", 
        "outputAddress": "xch19ukfhgdjx9w5zw5jkhcrf7sr9qkvhgtk0lv6u7c5m9ptj60dt4tscqkmna", 
        "inputAddresses": ["xch1vjgqx900fwejxgn8667h6pykn544fkxwwqtszv0dmd7ngar52eyq8gr9zd"], 
        "assetPrice": "69.09", 
        "assetDenomination": "USD" 
    }'

Response

{
    "updatedAt": null,
    "asset": "XCH",
    "network": "",
    "transferReference": "0x3419e2be63a8404826a49ab250b007f27447333019079d083c2b322c4cbe3cd4:xch19ukfhgdjx9w5zw5jkhcrf7sr9qkvhgtk0lv6u7c5m9ptj60dt4tscqkmna",
    "tx": null,
    "idx": null,
    "usdAmount": null,
    "assetAmount": null,
    "timestamp": null,
    "outputAddress": null,
    "externalId": "dc0ef9d7-fa72-3a8c-be24-37fa34409b92"
}

Workflow 2

Overview

Integrating withdrawal-attempts before sending funds out

Advantages

Limitations

API endpoints

Note: Review API examples in workflow 1 for posting transfers.

Posting a withdrawal attempt

Endpoint: POST /v2/users/{userId}/withdrawal-attempts

Notes

Example call

curl -X POST 'https://api.chainalysis.com/api/kyt/v2/users/withdrawal_attempt_test/withdrawal-attempts' \
    --header 'token: {API KEY}' \
    --header 'Content-Type: application/json' \
    --header 'Accept: application/json' \
    --data '{ 
        "network": "Bitcoin", 
        "asset": "BTC", 
        "address": "1MRcUDjinYQ3sMkN29ifMwY3oo7aZuuriH", 
        "attemptIdentifier": "attempt11234", 
        "assetAmount": 1.0, 
        "attemptTimestamp": "2022-6-07T17:25:40.008307" 
        }'

Response

{
    "network": "Bitcoin",
    "asset": "BTC",
    "address": "1MRcUDjinYQ3sMkN29ifMwY3oo7aZuuriH",
    "attemptIdentifier": "attempt11234",
    "assetAmount": 1.0,
    "usdAmount": 29877.50,
    "updatedAt": "2022-06-13T13:26:16.778+00:00",
    "externalId": "c54ae96b-eabe-3950-8cc7-5acdc950ed5b"
}

Getting a summary for a withdrawal attempt

Endpoint: GET /v2/withdrawal-attempts/{externalId}

Notes

Example call

curl -X GET 'https://api.chainalysis.com/api/kyt/v2/withdrawal-attempts/c54ae96b-eabe-3950-8cc7-5acdc950ed5b' \
    --header 'token: {API KEY}' \
    --header 'Content-Type: application/json' \
    --header 'Accept: application/json'

Response

{
    "network": "Bitcoin",
    "asset": "BTC",
    "address": "1MRcUDjinYQ3sMkN29ifMwY3oo7aZuuriH",
    "attemptIdentifier": "attempt11234",
    "assetAmount": 1.0,
    "usdAmount": 29877.50,
    "updatedAt": "2022-06-13T13:26:16.778+00:00",
    "externalId": "c54ae96b-eabe-3950-8cc7-5acdc950ed5b"
}

Getting alerts for a withdrawal attempt

Endpoint: GET /v2/withdrawal-attempts/{externalId}/alerts

Notes

Example call

curl -X GET 'https://api.chainalysis.com/api/kyt/v2/withdrawal-attempts/c54ae96b-eabe-3950-8cc7-5acdc950ed5b/alerts' \
    --header 'token: {API KEY}' \
    --header 'Content-Type: application/json' \
    --header 'Accept: application/json'

Response

 {
     "alerts": [
         {
             "alertLevel": "SEVERE",
             "category": "child abuse material",
             "service": "CHILD ABUSE MATERIAL: Child Abuse 1MRcUDjinYQ3sMkN29ifMwY3oo7aZuuriH",
             "externalId": "6760324c-eb1c-11ec-a780-8750e6bf7669",
             "alertAmount": 29877.50,
             "exposureType": "DIRECT",
             "categoryId": 1
         }
     ]
 }

Visit the withdrawal attempts section of the Transaction Monitoring API documentation for additional details and endpoints.

Workflow 3

Overview

Integrating real-time deposit screening before crediting funds to a user

Advantages

Limitations

API endpoints

Review API examples in workflow 1 and workflow 2 for posting transfers and registering withdrawal attempts.

Get summary of transfers

Endpoint: GET /v2/transfers/{externalId}

Notes

Example call

Note: This uses the externalId of the transfer from workflow 1.

 curl -X GET 'https://api.chainalysis.com/api/kyt/v2/transfers/53844b3c-510d-3a30-bb69-9566bcc0a5a6' \
     --header 'token: {API KEY}' \
     --header 'Content-Type: application/json' \
     --header 'Accept: application/json'

Response

{
     "updatedAt": "2022-06-08T19:26:12.690702",
     "asset": "BTC",
     "network": "BITCOIN",
     "transferReference": "0f6d4e6b9bddbe3dacb043012ffa029d706867e4749600f1d048aae9d1a66011:3A62vpSwwLM88DAjE8VwnX9gfqSpitUxg7",
     "tx":"0f6d4e6b9bddbe3dacb043012ffa029d706867e4749600f1d048aae9d1a66011",
     "idx": 0,
     "usdAmount": 3.09,
     "assetAmount": 0.0000867,
     "timestamp": "2021-01-12T06:11:30.000+00:00",
     "outputAddress": "3A62vpSwwLM88DAjE8VwnX9gfqSpitUxg7",
     "externalId": "53844b3c-510d-3a30-bb69-9566bcc0a5a6"
 }

Getting generated transfer alerts

Endpoint: GET /v2/transfers/{externalId}/alerts

Notes

Example call

curl -X GET 'https://api.chainalysis.com/api/kyt/v2/transfers/53844b3c-510d-3a30-bb69-9566bcc0a5a6/alerts' \
    --header 'token: {API KEY}' \
    --header 'Content-Type: application/json' \
    --header 'Accept: application/json'

Response

 {
 "alerts": [
        {
            "alertLevel": "SEVERE",
            "category": "sanctioned entity",
            "service": "OFAC SDN Fujing Zheng 2019-08-21",
            "externalId": "db805446-e760-11ec-b188-aff69c5a858c",
            "alertAmount": 3.09,
            "exposureType": "DIRECT",
            "categoryId": 3
        }
    ] 
 }

Visit the transfers section in the Transaction Monitoring API documentation for additional details and endpoints.

Workflow 4

Overview

All of the above workflows and continuous monitoring

Workflows 1-3

Continuous monitoring

Advantages

API endpoints

Note: Review API examples in workflow 1, workflow 2, and workflow 3 for transfer and withdrawal attempt workflows.

Get all alerts

Endpoint: GET /v1/alerts

Notes

Example call

Note: This gets all alerts for the user from workflow 1.

 curl -X GET 'https://api.chainalysis.com/api/kyt/v1/alerts?userId=user_example' \
    --header 'token: {API KEY}' \
    --header 'Content-Type: application/json' \
    --header 'Accept: application/json'

Response

 {
    "limit": 100,
    "offset": 0,
    "total": 1,
    "data": [
        {
            "alertAmountUsd": 3.09,
            "transactionHash": "0f6d4e6b9bddbe3dacb043012ffa029d706867e4749600f1d048aae9d1a66011",
            "exposureType": "DIRECT",
            "alertStatus": "Flagged",
            "transferReportedAt": "2022-06-03T20:20:40.051Z",
            "alertIdentifier": "a4bdcb94-e37a-11ec-b47d-e388868df12f",
            "transferReference": "0f6d4e6b9bddbe3dacb043012ffa029d706867e4749600f1d048aae9d1a66011:3A62vpSwwLM88DAjE8VwnX9gfqSpitUxg7",
            "alertStatusCreatedBy": "testuser@chainalysis.com",
            "valid": true,
            "transferCountWindow": null,
            "ruleAsset": null,
            "direction": "RECEIVED",
            "timestamp": "2021-01-12T06:11:30Z",
            "period": null,
            "windowSize": null,
            "transferredValuePercentage": 100.0,
            "level": "SEVERE",
            "service": "OFAC SDN Fujing Zheng 2019-08-21",
            "alertStatusCreatedAt": "2022-06-03T20:22:33.609501Z",
            "userId": "user_example",
            "transferCount": null,
            "createdAt": "2022-06-03T20:20:43.093931Z",
            "alertType": "TRANSFER",
            "transferOutputAddress": "3A62vpSwwLM88DAjE8VwnX9gfqSpitUxg7",
            "validity": "VALID",
            "category": "sanctioned entity",
            "transactionIndex": 0,
            "asset": "BTC",
            "rule": ">$0 received directly from sanctioned entity",
            "minThreshold": 0,
            "maxThreshold": null,
            "categoryId": 3                                                
        }
    ]
 }

Visit the alerts section of the Transaction Monitoring API documentation for more details.

Alerting and testing

How do I view and customize my alert rules?

Navigate to the Alerts tab in the UI. Click the Rules button at the top right to navigate to the list of alert rules that generate different severity alerts for transfers and withdrawal attempts. The rules are populated by default but please review them to make sure they align with your compliance and regulations. If you or additional users need permission to edit alert rules, please contact our Customer Support team.

What do the alert levels mean?

How can I test my alert rules?

Refer to this article, which goes over how to pull sample data from graphs and then send it to Transaction Monitoring to generate test alerts.

How are user risk scores calculated?

The user risk score is based on alerts, with the risk score equaling the highest severity alert that has not been dismissed. See here for more information about user risk scores.

Can I customize how risk scores are calculated in the risk profile?

You can customize a user's risk score in two ways:

  1. By turning on/off alerts or dismissing an alert.
    • See here for more information on customizing a user's risk score.
  2. You can also customize which categories or services are considered high risk. Please contact our Customer Support team to make these changes.

FAQs

How do I contact support?

The answers to many frequently asked questions can be found within the Knowledge Base. Use the search bar on the home page to find your issue. In case of further questions, you can contact Chainalysis Support by emailing support@chainalysis.com.

How should I determine User IDs?

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

Visit the FAQ section in the knowledge base for more FAQs.

cURL