> ## Documentation Index
> Fetch the complete documentation index at: https://docs.corsa.finance/llms.txt
> Use this file to discover all available pages before exploring further.

# Chainalysis KYT Integration

> Connect your Chainalysis KYT account to Corsa for automatic two-way syncing of alerts, users, transfers, and case management.

The Chainalysis integration connects your Chainalysis KYT account directly to Corsa. It automatically syncs **users, transfers, blockchain wallets, and alerts** from Chainalysis into your Corsa workspace — and pushes **status and assignee changes** back to Chainalysis in real time.

Your compliance team always works with the most up-to-date information in both platforms.

## How It Works

1. **Secure Connection** — Link your Chainalysis KYT account to Corsa once. All credentials are encrypted and securely stored.
2. **Full Data Sync** — On each sync cycle, Corsa pulls users, their transfers (deposits and withdrawals), blockchain wallet data, and KYT alerts from Chainalysis.
3. **Automatic Entity Linking** — Each alert is automatically linked to the relevant client profile and transaction in Corsa using Chainalysis identifiers (`chainalysisUserId`, `chainalysisTransactionId`).
4. **Smart Mapping** — A rules engine maps each alert's severity, category, and status to Corsa's alert model. Flagged alerts are automatically escalated to cases.
5. **Bi-Directional Sync** — Status changes, resolutions, and assignee updates made in Corsa are pushed back to Chainalysis. No duplicates, no manual sync.

## What Gets Synced

### Users → Clients

Chainalysis KYT users are synced as **Individual** or **Corporate** clients in Corsa (configurable per integration). Each synced client includes:

* `chainalysisUserId` set on the client's integrations, enabling automatic matching.
* Chainalysis risk data stored as **custom fields**: `chainalysisRiskScore`, `chainalysisScoreUpdatedDate`, `chainalysisLastActivity`, `chainalysisExposureDetails`.
* Country information (citizenship for individuals, country of incorporation for corporates).
* A `chainalysis-imported` tag for easy filtering.

<Note>Chainalysis risk scores are stored as custom fields — they do not overwrite the client's native Corsa risk level.</Note>

### Transfers → Deposits & Withdrawals

Chainalysis transfers are mapped to Corsa operations based on direction:

| Chainalysis Direction | Corsa Operation |
| --------------------- | --------------- |
| `RECEIVED`            | Deposit         |
| `SENT`                | Withdrawal      |

Each synced transaction includes:

* Amount in the original asset and converted USD value.
* Transaction hash and blockchain network.
* `chainalysisTransactionId` set on the transaction's integrations.
* Source/destination wallet addresses with client associations.

### Blockchain Wallets

Wallet addresses from transfers are created as blockchain wallet entities in Corsa with:

* Chainalysis cluster information (name, category ID) stored as custom fields.
* Risk ratings from Chainalysis (for received transfers) mapped to Corsa risk levels: `highRisk` → HIGH, `lowRisk` → LOW.

### Alerts

KYT alerts are synced with:

* Auto-generated descriptions including severity, rule name, asset, amount, direction, and exposure type.
* Full Chainalysis alert payload preserved in vendor metadata.
* Direct link to the alert in Chainalysis KYT.
* Automatic associations to the relevant client and transaction.

## Prerequisites

1. A Chainalysis KYT account with permission to generate API credentials.
2. Owner access to the Corsa application.

## Setting Up the Integration

1. Log in to Corsa.
2. Go to **Developers Hub → Integrations**.
3. Click **Configure** on the Chainalysis card.
4. Create an API Key in the [Chainalysis KYT API keys](https://kyt.chainalysis.com/developers/api-keys) page.
5. Enter the API key into Corsa.
6. Configure the **Polling Interval** — how frequently Corsa syncs with Chainalysis (default: 10 minutes).
7. Select the **Client Type** — whether Chainalysis users should be synced as `Individual` or `Corporate` clients.

If the configuration was successful, you should see the integration in an **enabled** status.

## Linking Entities

### Automatic Linking (via sync)

When the integration syncs, Corsa automatically:

1. **Creates clients** from Chainalysis users and sets `chainalysisUserId` on the client.
2. **Creates deposits/withdrawals** from Chainalysis transfers and sets `chainalysisTransactionId` on the transaction.
3. **Links alerts** to the matching client and transaction.

### How Alert-to-Client Matching Works

When a Chainalysis alert arrives, Corsa uses the alert's `userId` to find the matching client. The match is resolved using an OR strategy — a client matches if **any** of the following fields equal the Chainalysis `userId`:

| Corsa Client Field               | Description                                         |
| -------------------------------- | --------------------------------------------------- |
| `integrations.chainalysisUserId` | Set automatically during sync, or manually via API. |
| `referenceId`                    | The client's external reference ID in Corsa.        |
| `id`                             | The client's internal Corsa UUID.                   |

**To ensure matching**, set the Chainalysis KYT `userId` to the same value as your Corsa client's `referenceId` or `chainalysisUserId`. This way, when alerts sync, Corsa finds the right client automatically — whether the client was created by the integration or ingested via API.

### How Alert-to-Transaction Matching Works

Corsa uses the alert's `transferReference` (falling back to `transactionHash`) to find the matching transaction. The match is resolved using an OR strategy — a transaction matches if **any** of the following fields equal the Chainalysis identifier:

| Corsa Transaction Field                 | Description                                         |
| --------------------------------------- | --------------------------------------------------- |
| `integrations.chainalysisTransactionId` | Set automatically during sync, or manually via API. |
| `referenceId`                           | The transaction's external reference ID in Corsa.   |
| `txHash`                                | The on-chain transaction hash.                      |
| `id`                                    | The transaction's internal Corsa UUID.              |

**To ensure matching**, register transfers in Chainalysis KYT using the same `transferReference` or `transactionHash` that your Corsa transactions use as `referenceId` or `txHash`.

### Manual Linking (via API)

You can also pre-link entities before the integration syncs them:

* **Clients**: Include the `chainalysisUserId` field in the `integrations` object when creating a client via the Corsa API. Set it to the same `userId` used in Chainalysis KYT. See the [Ingesting Clients guide](/api/ingesting-clients).
* **Transactions**: Include the `chainalysisTransactionId` field in the `integrations` object when creating a transaction. Set it to the Chainalysis `transferReference`. See the [Ingesting Operations guide](/api/ingesting-operations).

When alerts sync, they will automatically link to these pre-existing entities using the matching strategy above.

## Alert Mapping

Corsa uses a configurable rules engine to map Chainalysis alert properties to Corsa's alert model. The defaults are described below, and can be customized per integration.

### Category Mapping

| Corsa Category           | Condition                         |
| ------------------------ | --------------------------------- |
| `TRANSACTION_MONITORING` | All Chainalysis alerts (default). |

<Note>Behavioral alerts (where `alertType` is `BEHAVIORAL`) are tagged internally for custom rule routing. You can configure custom category mapping rules to route behavioral alerts to a different category.</Note>

### Priority Mapping

| Corsa Priority | Chainalysis Alert Level              |
| -------------- | ------------------------------------ |
| `HIGH`         | `HIGH` or `SEVERE`                   |
| `MEDIUM`       | `MEDIUM` (also the default fallback) |
| `LOW`          | `LOW`                                |

### Status Mapping (Chainalysis → Corsa)

| Corsa Status                  | Chainalysis Status         |
| ----------------------------- | -------------------------- |
| `ESCALATED` (+ case creation) | `Flagged`                  |
| `IN_REVIEW`                   | `In Review`                |
| `RESOLVED`                    | `Dismissed` or `No Review` |
| `NEW`                         | All other statuses         |

### Status Mapping (Corsa → Chainalysis)

| Chainalysis Status | Corsa Status |
| ------------------ | ------------ |
| `Unreviewed`       | `NEW`        |
| `In Review`        | `IN_REVIEW`  |
| `Flagged`          | `ESCALATED`  |
| `Dismissed`        | `RESOLVED`   |

<Note>Status and assignee mapping is bi-directional. Changes in Corsa are pushed to Chainalysis with a comment indicating who made the change and why.</Note>

## Bi-Directional Sync Details

### Status Updates

When an analyst changes an alert status in Corsa, the integration:

1. Maps the Corsa status to the equivalent Chainalysis status.
2. Updates the alert in Chainalysis KYT via the API.
3. Adds a comment in Chainalysis with the analyst's email and resolution reason (if provided).

### Assignee Updates

When an alert is assigned or unassigned in Corsa:

1. The integration resolves the Corsa user ID to an email address.
2. Updates the alert assignment in Chainalysis KYT.

### Case Escalation

When a Chainalysis alert has status `Flagged`, Corsa automatically:

1. Creates the alert with status `ESCALATED`.
2. Creates a new case linked to the alert (if one doesn't already exist).

### Circular Update Protection

The integration detects when an update originated from its own sync process and skips re-syncing it. This prevents infinite update loops between Corsa and Chainalysis.

## Incremental Sync

After the initial full sync, subsequent sync cycles are incremental:

* **Users**: Only users with updated `lastActivity` or `scoreUpdatedDate` since the last sync are re-fetched.
* **Alerts**: Only alerts with status changes since the last sync are fetched (using `alertStatusCreatedAt` filter).
* **Transfers**: All transfers for updated users are re-synced.

This keeps API usage efficient and sync cycles fast.

***

Corsa offers native integrations with leading compliance, blockchain analytics, and custody providers. [See all integrations](/integrations) or [schedule a demo](https://calendly.com/michellelatzer/welcome-to-corsa) to see how Corsa fits into your stack.