KYT Provider Migration: How to Switch Without Losing Your AML History

Nobody migrates a KYT provider because the old one works perfectly. The decision usually follows months of frustration — coverage gaps on chains the business now supports, slow API responses during peak volume, risk categories that do not match how the compliance team actually thinks about risk, alert logic that cannot be configured to the business's risk appetite, pricing changes that no longer fit the operating budget, or a provider that has simply been outgrown. By the time the replacement is selected, the team is eager to move.

Then reality arrives. The old system holds three years of screening results. Hundreds of completed alert cases with analyst notes, escalation records, and documented disposition decisions. Threshold logic that was calibrated over months of operational experience. Customer-wallet mappings that connect internal account IDs to blockchain addresses and provider-specific analysis references. Procedures and training built around the old provider's terminology. And an audit trail that regulators, banking partners, and internal reviewers expect to remain intact.

The new provider uses different risk categories. Different scoring methodology. Different entity attribution. Different API fields. Different alert semantics. And the compliance team discovers that replacing the API endpoint is the smallest part of the project. A KYT provider can be replaced. The AML logic and historical decisions built around it cannot simply be replaced with the API. A KYT migration is not just a software replacement — the business also has to migrate the meaning it has attached to risk data over years of AML decisions.

This article covers what to preserve before migration begins, how to translate risk categories and thresholds instead of copying them, how to test the new system against real compliance decisions, how to protect historical alert records, and how to validate the cutover — so that the switch strengthens the compliance program rather than creating a gap in it.

Preserve the Old KYT Logic Before You Migrate

Before connecting the new system, document not just the data in the old one, but how the old system's signals were translated into AML decisions. The goal is to capture the full chain: provider signal → internal rule → alert → review or restriction or escalation. Without this chain, the migration team is trying to recreate a system it never fully documented.

1. Risk Taxonomy and Internal Mapping. Record the current provider's risk categories — every one of them, not just the ones that generate the most alerts. For each category, document how it maps to the internal risk framework, whether it triggers an automated action (hold, restrict, block), whether it triggers manual review, whether it is informational only, and what the compliance team's standard response has been. A category name like "High Risk" means nothing without recording what the compliance team actually did when it appeared. Two different categories may both be labeled "High Risk" but receive different treatment — one may trigger an immediate hold while another generates a review within 24 hours.
2. Thresholds and Alert Rules. Document every threshold, alert trigger, and automated restriction — including the exact numerical values, the risk categories they reference, the exposure depth they consider, whether they apply to inbound transactions, outbound transactions, or both, and the specific internal response each one produces. Recording "High Risk = 70+" is not enough. Record what score 70 caused the team to do: hold the transaction, escalate to senior compliance, request source of funds, restrict the account, or simply log and monitor. Also document any compound rules — thresholds that combine a risk score with a transaction amount, a customer risk level, or a geographic factor. These are the rules that are most likely to break during migration because they reference multiple provider-specific fields simultaneously.
3. Customer and Wallet Mappings. Export the relationships between internal customer IDs, account IDs, wallet addresses, and provider-specific analysis IDs. These mappings are what connect compliance decisions to the people and transactions they relate to. If the new provider uses different internal IDs — different reference formats, different analysis objects, different webhook structures — the business must preserve the link between old and new references so that a historical case from 2024 can still be connected to the same customer and the same wallet in 2027. Losing this link does not just create inconvenience — it breaks the ability to show an auditor which customer was involved in a specific historical alert.
4. Historical Screening Results, Alerts, and Cases. Export or archive every material screening result, every open and closed alert, every analyst decision, every escalation record, and every case file — with the original provider name, the timestamp, the exact result returned, the evidence reviewed, the analyst's reasoning, and the final disposition. These records should not be modified during migration. They document what information was available when the decision was made — not what the new provider would show today for the same address. The distinction matters because an auditor evaluating a 2024 decision will ask what the compliance team knew in 2024, not what a different provider's system shows in 2026.
5. Procedures, Training Materials, and Team Knowledge. Document which provider-specific terminology the team currently uses, which internal procedures reference provider category names or score ranges, which training materials describe how to interpret results, and which support scripts or customer communications reference specific risk labels.

These are the artifacts that create operational continuity — and they are the ones most often forgotten during a technically focused migration. For more on what an AML API needs to preserve beyond the risk score, see our API Requirements Guide.

Translate the Risk Model Instead of Copying It

The central principle of KYT migration: old KYT ≠ new KYT. The two providers may use the same words — "mixer," "scam," "high-risk exchange" — and mean different things. Translation and calibration are required, not copy-paste.

1. Map Risk Categories. Create a formal crosswalk: Old Provider Category → Internal AML Category → New Provider Category → Internal Treatment. Work through every category the old provider offers, not just the high-frequency ones. Some mappings will be one-to-one — the old "Sanctions" category maps cleanly to the new "Sanctions" category. Others will split one old category into several new ones — the old "Illicit" may become "Scam," "Stolen Funds," and "Darknet" in the new system. Others will merge several old categories into one — three old subcategories may collapse into a single new label. Some will provide only an approximate equivalent. And some will have no equivalent at all — the old provider tracked a category the new one does not, or vice versa.

If the old provider and the new provider use the same category name — "Scam," "Mixer," "High-Risk Exchange" — do not automatically assume the methodology behind it is identical. The same label from two providers can encompass different address sets, different clustering boundaries, different attribution sources, and different exposure calculations. A "Mixer" category that includes privacy protocols, CoinJoin transactions, and Tornado Cash in one provider may include only dedicated mixing services in another. The crosswalk should be reviewed and approved by the compliance officer — not only by the engineering team performing the integration. The engineering team can confirm that fields are mapped correctly in the API. The compliance officer must confirm that the mapping preserves the intended AML treatment.

2. Recalibrate Scores and Thresholds. Do not map old score 70 to new score 70. Do not convert 70/100 to 7/10. Providers use different scoring scales, different category weights, different exposure depth calculations, different direct-versus-indirect treatment, and different aggregation logic. A score of 70 from one provider and a score of 70 from another do not represent the same risk assessment — they represent the outputs of two different analytical systems that happened to produce the same number.

The target is not score equivalence. It is equivalent compliance treatment under the company's risk policy. What matters is that the same real-world risk reaches the same internal compliance response.

For example: old provider score 72 triggered manual review. New provider score 48 combined with a relevant risk signal may also warrant manual review. This can be a correct migration outcome even though the scores are numerically different. Conversely, if the new provider's score 72 triggers manual review but it fires on a completely different population of transactions — many more false positives, or missing genuine risks that the old system caught — the threshold is wrong even though the number looks the same.

Calibration means testing: take a representative set of historical transactions, run them through the new provider, and verify that the internal compliance response would have been appropriate. Adjust thresholds based on the results, not based on numerical similarity.

3. Map Entity Attribution and API Meaning. Provider A may attribute an address to Exchange X. Provider B may show the same address as Unknown. This is not necessarily an error by either provider — it reflects different intelligence databases, different clustering heuristics, and different attribution timelines. But it changes alerts, exposure calculations, counterparty context, and analyst interpretation. An alert that fires because the old provider identified a counterparty as a "High-Risk Exchange" may not fire under the new provider if the new provider does not attribute that address at all — creating a silent gap. For more on how wallet clustering and entity attribution work as analytical intelligence layers, see our entity identification guide.

Beyond entity attribution, the API field mapping must cover wallet versus transaction screening objects, inbound versus outbound direction handling, risk categories and subcategories, entity labels and confidence indicators, exposure depth and percentage, sanctions results and match types, customer IDs and account references, provider analysis IDs and report references, alert states and lifecycle, timestamps and timezone handling, webhooks and callback formats, error codes and retry behavior, and unsupported chains or assets.

Important: define what happens when the new provider returns Unknown, no attribution, an incomplete result, an unsupported chain, or an API error. These edge cases determine whether real compliance gaps open silently during migration. If the old provider covered a chain that the new one does not, transactions on that chain will return no risk data — and without explicit handling, they may be auto-approved by systems that interpret "no result" as "no risk."

Test the New Provider Against Real Compliance Decisions

A parallel run — operating both the old and new KYT systems simultaneously on the same transaction flow — is the most reliable way to understand how migration changes actual compliance outcomes before full cutover.

The purpose of a parallel run is not to determine which provider is "objectively correct." Neither the old nor the new provider is automatically ground truth. The purpose is to answer one operational question: how will our AML decisions change after migration?

The test sample should be representative of the business's actual risk landscape. It should include ordinary low-risk transactions that should pass without alerts, exchange-related flows that involve known services, sanctions-sensitive cases where any gap would be critical, scam and stolen-fund exposure where detection matters, mixer interactions, DeFi activity including DEX swaps and liquidity interactions, bridge transfers where cross-chain attribution may differ, P2P transactions, both inbound and outbound flows, historical false positives to verify whether the new system generates the same noise, historical escalations to verify whether the new system would have caught the same risks, and different customer types across the business's risk tiers.

For each case in the sample, compare: risk categories assigned, entity attribution, exposure type and depth, score or risk level, whether an alert was generated, whether the alert would trigger manual review under the business's rules, whether an automated action (hold, restrict, block) would fire, and the final compliance outcome — would the transaction follow the correct internal path?

Separately evaluate the aggregate operational picture: overall alert volume, high-risk alert volume, sanctions alert volume, manual-review volume, false-positive rate, and material risk categories that appear in one system but not the other. A sudden doubling of alerts may indicate that the new threshold is too sensitive. A sudden halving may indicate that genuine risks are being missed. Neither identical volume nor directional change is inherently correct — what matters is whether the alerts route material risks into the right compliance workflow. Do not try to achieve identical alert volume. If the old threshold was 70, do not copy 70 automatically. The new threshold should correspond to the existing risk policy, calibrated through testing against real transaction outcomes.

Keep Historical AML Decisions Intact

This is where migrations most often damage the audit trail — and where the damage is hardest to repair after the fact.

Consider a practical example. In 2025, Provider A returned score 35, category "Exchange," and the analyst reviewed and accepted the transaction. In 2026, after migration, Provider B returns "High Risk" with "Scam Exposure" for the same wallet address. The new result does not invalidate the old decision. In 2025, the analyst made a decision based on the information available at that time, from the provider in use at that time. That decision was appropriate given the data that existed. The correct response is not to overwrite the 2025 record — it is to preserve it as a historical fact and, if the wallet needs reassessment, create a new screening event under the new provider with a new date.

Every completed case should retain the provider that generated the original result, the timestamp of the screening, the exact risk result returned (score, categories, exposure), the evidence the analyst reviewed, the analyst's decision and reasoning, and the final disposition. These elements should remain unchanged by the migration. The historical record is not just a score — it is the full chain: risk signal → review → evidence → decision → reason. Breaking any link in that chain means the decision can no longer be explained to an auditor.

Do not rename old risk categories using the new provider's terminology. Do not recalculate old scores using the new provider's methodology. Do not merge old cases into new case management without preserving the original provider context. Do not delete old screening results because the new system "supersedes" them. For more on how high-risk crypto alerts should be reviewed and documented, see our alert workflow guide.

Not every historical wallet needs to be rescreened after migration. Universal rescreening of every address ever checked is operationally impractical and analytically unnecessary. Reasonable candidates for rescreening include active customers with ongoing transaction activity, wallets currently under enhanced monitoring, open cases awaiting resolution, elevated-risk relationships, recent counterparties within a defined lookback period, sanctions-sensitive cases where any provider gap would be critical, and cases where parallel testing revealed material differences between old and new provider results.

Do not define a universal rescreening frequency based on the migration event alone. Do not backfill historical records with new provider data as if that data existed at the time of the original decision. Use a clear distinction in every record: original screening (Provider A, date, result) versus later rescreening or enrichment (Provider B, date, result). These are separate compliance events, not corrections of the same event.

Cut Over Only After the New KYT Workflow Is Understood

Before cutover, the migration team should confirm that every operational element is ready — not just that the API returns successful responses.

1. Pre-cutover checklist. Taxonomy mapping has been reviewed and approved by compliance. Thresholds have been calibrated through parallel testing, not copied from the old system. Alert routing has been tested — alerts reach the correct queue, the correct team, and the correct priority level. Sanctions logic has been verified specifically, because sanctions gaps carry the highest regulatory and legal risk. Internal customer IDs are preserved in the new system and correctly linked to provider references. Legacy cases remain accessible — either in the old system, in an archive, or migrated with full context. Unsupported chains and assets are documented, with explicit handling rules. API failure behavior is defined — what happens when the provider is unreachable, returns an error, or returns an incomplete result. Analysts understand the new terminology, the new category meanings, and the differences from the old system. Operating procedures have been updated to reference the new provider's outputs. Training has been completed and documented.
2. Document the cutover boundary. Record the exact cutover date and time, the old provider name and version, the new provider name and version, the old threshold configuration, the new threshold configuration, the approved category crosswalk, the known limitations of the new system compared to the old, and any chains, assets, or features that are temporarily unsupported. This creates a clean historical boundary: everything before the cutover date uses legacy KYT context; everything after uses new KYT context. An auditor reviewing a case from before the cutover should see the old provider's data. A case from after should show the new provider's data. Cases that span the boundary should reference both.

Do not delete legacy context just because the old API is disconnected. Historical reports, screening results, alert cases, and analyst decisions may be needed for years — for audits, customer disputes, investigations, regulatory reviews, or internal case reopening. For more on how to document AML control changes after a system migration, see our change management guide.

Post-cutover monitoring. After the switch, monitor actual production behavior for a defined stabilization period. Watch for unexpected alert spikes or drops that indicate threshold miscalibration, missing risk categories that appeared in the old system but are absent in the new one, new false-positive patterns the team has not seen before, API failures or timeout behavior under real load, unsupported transactions that return no risk data, sanctions alerts to confirm they still fire correctly, manual-review volume to verify operational sustainability, customer and account mapping integrity, and analyst overrides that may indicate confusion about the new system's outputs. Migration is not complete when the new API returns successful responses. It is complete when the compliance team understands how the new KYT system behaves in production — and when the operational evidence confirms that material risks are reaching the correct compliance workflow.

KYT Providers Can Change; AML Decisions Must Stay Explainable

A successful migration preserves three things.

1. Data Continuity. Can the business still find the historical transaction, screening result, alert, and case? Can it retrieve the original provider's output for a specific address on a specific date? Can it connect that output to the customer, the wallet, and the compliance decision that followed?
2. Decision Continuity. Can the business explain what information existed at the time and why the analyst made that decision? Can it show that the decision was reasonable given the data available from the provider in use at that moment — even though a different provider might show a different result today?
3. Control Continuity. Does the new KYT provider still route material risks into the correct internal compliance workflow? Do sanctions hits still trigger immediate holds? Do high-risk signals still reach the right team? Do thresholds still reflect the business's risk policy — not the old provider's numbers in a new system?

The goal is not to make the new KYT provider reproduce the old one. The goal is to preserve the company's AML logic while changing the system that supplies the risk intelligence. KYT providers can change. Historical AML decisions still need to remain understandable before, during, and after the switch.

FAQ