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

# Set Up AML Compliance Screening on Finrock

> Enable automated AML screening for deposits and withdrawals using Chainalysis, Cipertrace, or AMLBot. Block high-risk addresses before funds move.

Finrock integrates with leading blockchain forensics providers — including Chainalysis, Cipertrace, and AMLBot — to give you automated anti-money laundering (AML) screening on every deposit and withdrawal. When AML is enabled, Finrock checks each transaction counterparty against the provider's database of hundreds of millions of addresses — spanning exchanges, mixing services, darknet markets, scam operations, and other real-world entities — before allowing funds to move. This guide explains how to enable AML screening, interpret risk levels, understand how blocked transactions are handled, and manage frozen addresses.

## Why AML Screening Matters

The digital asset market is a high-growth space, but it also attracts illicit activity. Blockchain forensics providers such as Chainalysis, Cipertrace, and AMLBot maintain continuously updated maps that link on-chain addresses to real-world entities. By connecting your workspace to one of these providers, you gain:

* Automated pre-transaction screening for every deposit and withdrawal
* Risk-level categorisation that lets you define your own tolerance threshold
* A defensible compliance audit trail linking each transaction to a screened address
* The ability to block or hold high-risk transactions before funds ever move on-chain

<Note>
  Finrock supports **Chainalysis**, **Cipertrace**, and **AMLBot** as AML providers. Risk levels available for all providers are: `SEVERE`, `HIGH`, `MEDIUM`, and `LOW`.
</Note>

## Supported Providers and Risk Levels

| Provider    | Risk Levels                    |
| ----------- | ------------------------------ |
| Chainalysis | `SEVERE` `HIGH` `MEDIUM` `LOW` |
| Cipertrace  | `SEVERE` `HIGH` `MEDIUM` `LOW` |
| AMLBot      | `SEVERE` `HIGH` `MEDIUM` `LOW` |

## Enabling AML Screening

Call `POST https://api.finrock.io/dac/v1/aml` with your AML provider API key and your desired configuration. You can enable screening for deposits, withdrawals, or both independently.

```bash theme={null}
curl --request POST \
     --url https://api.finrock.io/dac/v1/aml \
     --header 'Authorization: Token {JWT}' \
     --header 'x-api-key: YOUR_API_KEY' \
     --header 'content-type: application/json' \
     --header 'accept: application/json' \
     --data '{
       "provider": "Chainalysis",
       "aml_token": "your-chainalysis-api-key",
       "aml_risk_levels": "SEVERE, HIGH",
       "aml_deposit": true,
       "aml_withdrawal": true
     }'
```

### Configuration Parameters

| Parameter         | Type    | Required | Description                                                                                    |
| ----------------- | ------- | -------- | ---------------------------------------------------------------------------------------------- |
| `provider`        | string  | Yes      | AML provider to use: `Chainalysis`, `Cipertrace`, or `AMLBot`.                                 |
| `aml_token`       | string  | Yes      | Your API key from the chosen AML provider                                                      |
| `aml_risk_levels` | string  | Yes      | Comma-separated list of risk levels that will trigger a block or hold. Default: `SEVERE, HIGH` |
| `aml_deposit`     | boolean | Yes      | Enable AML screening on incoming deposits                                                      |
| `aml_withdrawal`  | boolean | Yes      | Enable AML screening on outbound withdrawals                                                   |

<Tip>
  Start with `aml_risk_levels: "SEVERE, HIGH"` to block clearly high-risk counterparties without generating false positives from lower-risk commercial services. You can add `MEDIUM` or `LOW` later as your compliance requirements evolve.
</Tip>

## Checking AML Status

Retrieve your current AML configuration at any time with a simple `GET` request:

```bash theme={null}
curl --request GET \
     --url https://api.finrock.io/dac/v1/aml \
     --header 'Authorization: Token {JWT}' \
     --header 'x-api-key: YOUR_API_KEY' \
     --header 'accept: application/json'
```

The response confirms which provider is active, which risk levels are configured, and whether deposit and withdrawal screening are enabled.

## How AML Affects Transactions

When AML screening is enabled, Finrock evaluates the counterparty address against your configured AML provider before executing the transaction. The outcome depends on the risk score returned:

<CardGroup cols={2}>
  <Card title="AML_Blocked" icon="ban">
    The counterparty address matches a risk level in your configured `aml_risk_levels` list. The transaction is blocked immediately and does not proceed. Funds are not moved.
  </Card>

  <Card title="AML_Pending" icon="clock">
    The address is under review. The transaction is held until screening completes or a compliance officer takes action.
  </Card>
</CardGroup>

<Warning>
  Transactions with an `AML_Blocked` status **cannot be processed** until the address is unfrozen by an authorised user. Review the address in your AML provider's dashboard before deciding to unfreeze.
</Warning>

## Linking Customer IDs with `aml_cid`

When creating a transaction, pass the `aml_cid` field with your internal customer identifier. Finrock forwards this value to your configured AML provider so the screening result is tied to the correct customer record in your compliance system:

```json theme={null}
{
  "asset": "USDT_TRX",
  "amount": 1000,
  "source_type": "INTERNAL",
  "destination_type": "EXTERNAL",
  "destination_id": "TRecipientAddressHere",
  "aml_cid": "customer-uuid-abc123"
}
```

This field is required if your compliance policy mandates subject-level AML record-keeping.

## Managing Frozen Addresses

When Finrock blocks a transaction due to AML, it automatically freezes the flagged counterparty address to prevent further interactions. You can view and manage frozen addresses through the API.

### List Frozen Addresses

Retrieve all currently frozen addresses in your workspace:

```bash theme={null}
curl --request GET \
     --url https://api.finrock.io/dac/v1/frozen-addresses \
     --header 'Authorization: Token {JWT}' \
     --header 'x-api-key: YOUR_API_KEY' \
     --header 'accept: application/json'
```

### Unfreeze an Address

After your compliance team reviews a flagged address and determines it is safe to interact with, unfreeze it using `POST /dac/v1/unfreeze-address`:

```bash theme={null}
curl --request POST \
     --url https://api.finrock.io/dac/v1/unfreeze-address \
     --header 'Authorization: Token {JWT}' \
     --header 'x-api-key: YOUR_API_KEY' \
     --header 'content-type: application/json' \
     --header 'accept: application/json' \
     --data '{
       "asset": "USDT_TRX",
       "address": "TFlaggedAddressHere",
       "address_tag": ""
     }'
```

| Parameter     | Type   | Required | Description                                               |
| ------------- | ------ | -------- | --------------------------------------------------------- |
| `asset`       | string | Yes      | Blockchain asset ticker                                   |
| `address`     | string | Yes      | The frozen address to unfreeze                            |
| `address_tag` | string | No       | Destination tag or memo if applicable (e.g. for XRP, XLM) |

<Warning>
  Unfreeze addresses only after a thorough compliance review. Unfreezing an address re-enables transactions to and from it — any subsequent transaction will bypass the frozen state but will still be screened against your AML provider at the configured risk levels.
</Warning>