Skip to content

KYW response reference

Interpret custody classification, confidence, attribution, risk, and entity fields.

A fresh KYW check returns a classification and independent agentic signals. Risk and entity information depend on the available source data. Use the integration guide for a minimal request and routing decisions.

Response Model

FieldTypeDescription
idstringAML Check search history record ID.
addressstringWallet address that was classified.
blockchainstringBlockchain used for the classification.
walletTypestringCUSTODIAL, NON_CUSTODIAL, or UNKNOWN.
confidenceScorenumberNumeric confidence from 0 to 100.
confidencestringLOW, MEDIUM, or HIGH, derived from confidenceScore.
isVerifiedbooleanWhether the associated entity or wallet signal is verified.
attributionReasonstring or nullHuman-readable explanation for the classification.
attributionReasonCodestring or nullMachine-readable reason code.
riskScorenumber, object, or nullRisk score from the matched verification, directory entity, or analytics source when available.
auditLogIdstringAudit ledger ID. This is the same AML history record ID as id.
entityInfoobject or nullEntity details when KYW resolves the wallet to a known entity.
agenticBehaviourobjectIndependent agentic attribution result. It does not change walletType.

agenticBehaviour fields:

FieldTypeDescription
detectedbooleanWhether the available evidence crossed the agentic-detection threshold.
confidenceScorenumberAgentic confidence from 0 to 100. A score of 100 is reserved for deterministic attribution.
confidencestringLOW, MEDIUM, or HIGH.
isVerifiedbooleantrue only for deterministic attribution, currently an exact ERC-8004 match. Behavioral heuristics never set this to true.
attributionReasonstring or nullHuman-readable explanation of the agentic result.
attributionReasonCodestring or nullDETECTED_VIA_ERC8004, DETECTED_VIA_BEHAVIORAL_ANALYSIS, or null.

walletType values:

ValueMeaning
CUSTODIALThe wallet is likely controlled by a VASP, exchange, payment provider, bank, mining pool, ATM, or another custodial service.
NON_CUSTODIALThe wallet is likely controlled by an individual user, self-hosted wallet app, DeFi service, wallet verification record, or another non-custodial source.
UNKNOWNCryptoSwift could not classify the wallet with enough signal. Use your internal policy to decide whether to ask for more information, run wallet verification, or escalate.

confidenceScore maps to confidence as follows:

ScoreConfidence
0-33LOW
34-66MEDIUM
67-100HIGH

Common attributionReasonCode values:

CodeMeaning
VERIFIED_SELF_HOSTED_WALLETThe wallet has a completed self-hosted wallet verification.
REGISTERED_PLATFORM_TENANT_WALLETThe wallet matches a wallet registered by a CryptoSwift platform tenant.
REGISTERED_PLATFORM_TENANT_WALLET_WITH_ASSET_HINTThe wallet matches a tenant wallet without blockchain metadata, and asset metadata suggests the requested blockchain.
DETECTED_VIA_PARTNER_NETWORKThe wallet owner was identified through partner-network data.
DETECTED_VIA_BLOCKCHAIN_ANALYTICSBlockchain analytics identified an owner or entity type.
KNOWN_SELF_HOSTED_WALLET_APPThe resolved entity is a known self-hosted wallet app.
HEURISTIC_WEB3_AND_GENESIS_SIGNATURESBehavioral heuristics indicate private-key ownership through Web3 activity or genesis funding patterns.
HEURISTIC_AUTOMATED_PATTERNSBehavioral heuristics indicate automated custodial wallet patterns.
INCONCLUSIVE_BEHAVIORAL_HEURISTICSBehavioral heuristics were inconclusive.

These codes describe the root wallet classification. The nested agenticBehaviour.attributionReasonCode uses a separate namespace:

CodeMeaning
DETECTED_VIA_ERC8004The wallet exactly matches an ERC-8004 registered agent on the requested network.
DETECTED_VIA_BEHAVIORAL_ANALYSISThe wallet crossed the behavioral automation threshold. This result is not verified agent ownership.

Entity Info

When KYW resolves the wallet to a known entity, entityInfo can include:

FieldDescription
entityIdPublic entity ID from the CryptoSwift entity directory.
name / legalNameEntity display name and legal name.
typeEntity type, such as exchange, wallet, bank, payment provider, DeFi service, or other directory type.
isVerifiedWhether CryptoSwift has verified the entity record.
inNetworkWhether the entity is in the CryptoSwift network.
isRiskAssessedWhether a risk assessment is available.
isMicaCompliantWhether the entity is marked as MiCA compliant.
belongsToWarningListWhether the entity belongs to a warning list.
countriesCountries associated with the entity.
riskAssessmentRisk assessment details when available.
url, email, logo, noticePublic entity profile information when available.

Next steps