Crystal Intelligence
The Crystal Intelligence adapter is implemented for address screening with Crystal Risk Check.
Implementation
Section titled “Implementation”| Field | Value |
|---|---|
| Integration name | crystal |
| Display name | Crystal Intelligence |
| Type | blockchain_analytics |
| Required credentials | apiKey |
| Optional settings | entityList |
| Base URL | https://apiexpert.crystalblockchain.com |
| Endpoint path | /risk-check |
| Connection test path | /monitor/currency/list |
| Timeout | 10 seconds |
| Retries | None |
Screening
Section titled “Screening”The adapter supports:
- Address screening through Crystal Risk Check (
type: address) - Each address on the transfer, the originator's and the beneficiary's, in its own request
- The connected-entities setting, sent as
entity_list - Network mapping before requests: a network Crystal does not map fails the check with
UNSUPPORTED_NETWORK
A request sends only type, address, blockchain and entity_list: no customer reference, amount or token ID. Crystal is called at a rule checkpoint (precheck or postcheck) only when a compliance rule that applies there reads its response.
Transaction hashes are not screened: a transaction check fails with UNSUPPORTED_OPERATION, since Crystal's transfer screening takes a direction, an address and a token ID.
Network Mapping
Section titled “Network Mapping”| Network | Crystal blockchain |
|---|---|
bitcoin |
btc |
bitcoin-cash |
bch |
litecoin |
ltc |
ethereum |
eth |
ethereum-classic |
etc |
arbitrum, arbitrum-one |
arb |
optimism |
op |
base |
base |
polygon |
matic |
bsc |
bsc |
tron |
trx |
solana |
sol |
ripple |
xrp |
stellar |
xlm |
cardano |
ada |
xinfin |
xdc |
adi |
adi |
Case is ignored, and Covalent's network aliases (such as btc, eth, matic or binance_smart_chain) and Crystal's own identifiers are accepted. Any other network fails the check with UNSUPPORTED_NETWORK, including avalanche, fantom, dogecoin, algorand, cosmos, near and polkadot.
Credential Behavior
Section titled “Credential Behavior”The adapter sends the API key saved for the transfer's environment in the X-Auth-Apikey header. Test and live transfers both call Crystal's API at the same base URL, each with its own environment's key. Save it with PUT /api/v2/integrations/crystal; see Providers and Integrations.
Without a key for the transfer's environment, the check fails before any request is sent. There is no sandbox fallback: save a test API key to screen test transfers.
entityList (Include connected entities) is saved for each environment, like the key, as text: "true" sends entity_list: true, and "false" or no value sends false. Any other value fails every check and connection test until it is corrected.
Connection Test
Section titled “Connection Test”The connection test sends a read-only GET /monitor/currency/list with the environment's API key, and screens no address. It passes, with the message Connected to Crystal Intelligence API, when Crystal answers with its currency list and a meta.error_code of 0; any other answer fails the test. Without saved credentials for the environment, the test is 409 NOT_CONFIGURED.
Response Mapping
Section titled “Response Mapping”An address's screening succeeds when Crystal's response has a meta.error_code of 0, names exactly one network in data.blockchains, the requested one, and has a risk score from 0 to 1 in data.counterparty.riskscore. When the response names an address in data.counterparty.address, it must be the screened address: compared ignoring case for eth, etc, arb, op, base, bsc, matic, xdc and adi, and exactly for the others. Crystal's complete response is stored, and the score keeps Crystal's 0 to 1 scale.
A response for another network or address fails with SUBJECT_MISMATCH, and any other response with INVALID_RESPONSE. The check succeeds only when every screened address does. For a role with pii:view, the check's response.screenings holds each address's party, status, Crystal's response and any error.
In a rule, the JSON response query data.counterparty.riskscore reads the score of each screened address. When the check fails, a rule that reads Crystal's response requires review.
Error Mapping
Section titled “Error Mapping”The adapter fails a screening with these error codes. The check stores the failure's message, never Crystal's response body.
| Error Code | When |
|---|---|
UNSUPPORTED_NETWORK |
The transfer's network has no Crystal identifier |
BAD_REQUEST |
The address is blank |
HTTP_<status> |
Crystal answers with a 4xx or 5xx status, such as HTTP_401 |
CRYSTAL_<code> |
Crystal's meta.error_code is not 0 |
INVALID_RESPONSE |
The response is not JSON, or not in the shape above |
SUBJECT_MISMATCH |
The response is for another network or address |
TIMEOUT |
The request takes longer than 10 seconds |
RESPONSE_TOO_LARGE |
The response is larger than 2 MiB |
NETWORK_ERROR |
Any other request failure, a redirect included |