# Crypto AML & Wallet Screener MCP — OFAC, EU, UN & AMLBot (`olican/crypto-aml-wallet-screener`) Actor

Extract real-time crypto wallet address sanctions status (OFAC, EU, UN) and enrich with AMLBot on-chain risk scoring in a single execution. MCP-native tool.

- **URL**: https://apify.com/olican/crypto-aml-wallet-screener.md
- **Developed by:** [Sergio Calvo](https://apify.com/olican) (community)
- **Categories:** Automation, Agents, Integrations
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $50.00 / 1,000 wallet aml analyses

This Actor is paid per event and usage. You are charged both the fixed price for specific events and for Apify platform usage.

Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-event

## What's an Apify Actor?

Actors are a software tools running on the Apify platform, for all kinds of web data extraction and automation use cases.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.
Actors are written with capital "A".

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.
The best way to integrate Actors is as follows.

In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js.md):

```bash
npm install apify-client
```

In Python projects, use official [Python client library](https://docs.apify.com/api/client/python.md):

```bash
pip install apify-client
```

In shell scripts, use [Apify CLI](https://docs.apify.com/cli/docs.md):

````bash
# MacOS / Linux
curl -fsSL https://apify.com/install-cli.sh | bash
# Windows
irm https://apify.com/install-cli.ps1 | iex
```bash

In AI frameworks, you might use the [Apify MCP server](https://docs.apify.com/platform/integrations/mcp.md).

If your project is in a different language, use the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).


# README

## Crypto AML & Wallet Screener MCP — OFAC, EU, UN & AMLBot

**The only MCP-native Apify Actor that combines real-time sanctions list screening (OFAC SDN, EU Consolidated, UN) with active on-chain risk scoring (via AMLBot API) in a single execution. Screen Bitcoin, Ethereum, Solana, BNB Chain, and Tron addresses instantly.**

This compliance bridge is designed to automate cryptocurrency wallet due diligence. It downloads, parses, and memory-caches the official global sanctions databases once per run, then queries the AMLBot REST API with intelligent pacing (5 reqs/sec) and exponential backoff. Results are flattened as columns for easy **Table View** and **Excel/CSV export** on the Apify Console.

---

### 🎯 Target Audience & 💡 Primary Use Cases

#### Casos de Uso / Valor Comercial (Commercial Value)
- **Onboarding Risk Check:** Screen new users' wallet addresses during registration or sign-up to block sanctioned individuals.
- **Transaction Validation:** Validate destination and origin wallet addresses before executing smart contract transfers or payments.
- **Periodic Auditing:** Re-check existing corporate asset portfolios and database records against daily updated lists.
- **DeFi & Web3 Compliance:** Automate MiCA/FinCEN compliance requirements without paying for expensive enterprise suites.

#### Público Objetivo (Target Audience)
- **Compliance & Legal Teams:** Audit and export transaction history with legal evidence of sanctions checks.
- **Exchanges & VASPs:** High-performance REST API to automate wallet verification pipelines.
- **Startups & DeFi Builders:** Simple integration via JSON webhooks or native Model Context Protocol (MCP).
- **AI Agents & LLMs:** Fetch risk profiles instantly from the chat using MCP tools without backend middleware.

---

### 🚀 Características Clave (Key Technical Capabilities)

- **Official Sanctions Parsing:** Automatically fetches and processes XML data directly from:
  - **OFAC SDN list** (U.S. Department of the Treasury)
  - **EU Consolidated Sanctions List** (European Commission FSF)
  - **UN Consolidated list** (United Nations Security Council)
- **On-Chain Risk Enrichment:** Integrates with AMLBot API to fetch the 0–100 transaction history risk percentage.
- **Multi-Chain Support:** Auto-detects formats and validates addresses for **Bitcoin (BTC)**, **Ethereum (ETH)**, **Solana (SOL)**, **BNB Chain (BSC)**, and **Tron (TRX)**.
- **Anti-Crash & Fallback Design:** Missing sanctions tokens or AMLBot timeouts will not crash your run; the Actor logs a warning, sets an `errorCode` (e.g., `API_TIMEOUT`, `UNSUPPORTED_CHAIN`), and saves the partial results.
- **Intelligent Rate-Limiting:** Built-in 200ms pacing and exponential retry (up to 3 attempts) on AMLBot API responses (429/503) to respect provider boundaries.
- **MCP-Ready Integration:** Ready to expose as a tool in Claude Desktop, Cursor, or VS Code using `mcp.apify.com`.

---

### ⚙️ Input Parameters

The Actor accepts the following input parameters in its configuration form (INPUT_SCHEMA):

| Field / Campo | Type | Default | Description |
|---|---|---|---|
| `walletAddresses` | Array[String] | *Required* | List of cryptocurrency wallet addresses to screen. |
| `chains` | Array[String] | `["BTC","ETH","SOL","BSC","TRX"]` | Supported blockchains. Allowed values: `BTC`, `ETH`, `SOL`, `BSC`, `TRX`. |
| `sanctionsLists` | Array[String] | `["ofac","eu","un","uk"]` | Sanctions lists to check against. |
| `riskScoring` | Boolean | `true` | Activates AMLBot on-chain risk check. Requires `AMLBOT_API_KEY` env var. |
| `webhookUrl` | String | `null` | Optional URL to send a POST request with the final summary. |

---

### 📊 Output Schema

To maximize usability, the output dataset is completely flattened so that it maps cleanly as columns in the Apify spreadsheet / Table view.

#### Flat Table View Columns (Root JSON level)
*   `wallet` (String): The wallet address analyzed.
*   `chain` (String): Detected blockchain network (e.g. `BTC`, `ETH`, `SOL`, `BSC`, `TRX`).
*   `sanctioned` (Boolean): `true` if the address matched a blacklist, `false` otherwise.
*   `matchedList` (String): The list name where the match occurred (`ofac`, `eu`, `un`, or `none`).
*   `matchedEntity` (String): Name of the sanctioned individual/entity (or `null`).
*   `riskScore` (Number): 0–100 numerical on-chain risk score from AMLBot (or `null`).
*   `riskLevel` (String): Normalized risk level: `LOW`, `MEDIUM`, `HIGH`, `CRITICAL`, or `UNKNOWN`.
*   `checkedAt` (String): ISO 8601 timestamp of the check.
*   `errorCode` (String): Error descriptor if a service failed (e.g., `UNSUPPORTED_CHAIN`, `API_TIMEOUT`, `INVALID_ADDRESS`, or `null`).

---

### 🧠 Risk Level Methodology

The Actor categorizes the numerical risk score returned by the AMLBot API into four clear levels:
- **`LOW` (0–25):** Safe wallet address. No suspicious connections detected.
- **`MEDIUM` (26–60):** Warning. Minor exposure to mixers, peer-to-peer exchanges, or secondary risk sources.
- **`HIGH` (61–85):** High risk. Direct exposure to gambling, darknet markets, or stolen funds.
- **`CRITICAL` (86–100):** Severe threat. Directly linked to sanctioned entities, hackers, or illicit services.

---

### 🔌 Automatización e Integraciones

- **Webhooks & No-Code:** Configure the `webhookUrl` input parameter to trigger automated email/Slack alerts or update Zapier, Make, or n8n workflows when `sanctioned: true` or `riskLevel: "CRITICAL"` is detected.
- **Schedules:** Run the Actor daily or weekly using Apify Console schedules to monitor active customer wallets.
- **Cloud Databases:** Sync Apify datasets directly to BigQuery, Snowflake, Amazon S3, or PostgreSQL for compliance record audits.

---

### 📋 Example Output (JSON)
```json
{
  "wallet": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
  "chain": "ETH",
  "sanctioned": false,
  "matchedList": "none",
  "matchedEntity": null,
  "riskScore": 12,
  "riskLevel": "LOW",
  "checkedAt": "2026-06-11T10:04:15.864Z",
  "errorCode": null
}
````

***

### 💳 Pricing & Monetization

This Actor is optimized for **Pay-Per-Event (PPE)** pricing on the Apify Store, providing predictable billing:

- **`run_start` event:** **$0.05 USD** per execution.
- **`wallet_screened` event:** **$0.10 USD** per wallet address checked.

***

### 🙋 Frequently Asked Questions

##### How do I configure my AMLBot API Key?

You must set up your AMLBot API Key as an environment variable in the Actor settings on Apify Console. Create a variable named `AMLBOT_API_KEY` and paste your token. If the variable is missing, the Actor will automatically skip the AMLBot checks and only perform sanctions list matches.

##### Why does the check return UNSUPPORTED\_CHAIN?

This error is returned if the wallet address format does not match any known blockchain regex, or if the detected chain is not in the allowed `chains` list configured in the input parameters.

##### Are the sanctions lists downloaded in real-time?

Yes. Every time the Actor runs, it fetches the latest official XML documents directly from the US Treasury (OFAC), the European Commission (EU), and the United Nations (UN). The lists are parsed and cached in memory once per execution to guarantee maximum efficiency and accurate up-to-date checks.

# Actor input Schema

## `walletAddresses` (type: `array`):

List of cryptocurrency wallet addresses to screen (one per row or list items).

## `chains` (type: `array`):

Blockchains to check. If empty or not specified, the Actor will auto-detect the chain based on format.

## `sanctionsLists` (type: `array`):

Official sanctions lists to cross-reference.

## `riskScoring` (type: `boolean`):

Activate AMLBot API risk scoring for transaction history (0-100 score). Requires AMLBOT\_API\_KEY environment variable.

## `webhookUrl` (type: `string`):

Optional HTTP POST URL to notify when the run finishes. It will send a summary payload.

## Actor input object example

```json
{
  "walletAddresses": [
    "1A1zP1eP5QGefi2DMPTfTL5SLmv7Divf3N",
    "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045"
  ],
  "chains": [
    "BTC",
    "ETH",
    "SOL",
    "BSC",
    "TRX"
  ],
  "sanctionsLists": [
    "ofac",
    "eu",
    "un",
    "uk"
  ],
  "riskScoring": true
}
```

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "walletAddresses": [
        "1A1zP1eP5QGefi2DMPTfTL5SLmv7Divf3N",
        "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("olican/crypto-aml-wallet-screener").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = { "walletAddresses": [
        "1A1zP1eP5QGefi2DMPTfTL5SLmv7Divf3N",
        "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
    ] }

# Run the Actor and wait for it to finish
run = client.actor("olican/crypto-aml-wallet-screener").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"])
for item in client.dataset(run["defaultDatasetId"]).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "walletAddresses": [
    "1A1zP1eP5QGefi2DMPTfTL5SLmv7Divf3N",
    "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045"
  ]
}' |
apify call olican/crypto-aml-wallet-screener --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "command": "npx",
            "args": [
                "mcp-remote",
                "https://mcp.apify.com/?tools=olican/crypto-aml-wallet-screener",
                "--header",
                "Authorization: Bearer <YOUR_API_TOKEN>"
            ]
        }
    }
}

```

## OpenAPI specification

```json
{
    "openapi": "3.0.1",
    "info": {
        "title": "Crypto AML & Wallet Screener MCP — OFAC, EU, UN & AMLBot",
        "description": "Extract real-time crypto wallet address sanctions status (OFAC, EU, UN) and enrich with AMLBot on-chain risk scoring in a single execution. MCP-native tool.",
        "version": "1.0",
        "x-build-id": "LrPJeMALDulBDhVhp"
    },
    "servers": [
        {
            "url": "https://api.apify.com/v2"
        }
    ],
    "paths": {
        "/acts/olican~crypto-aml-wallet-screener/run-sync-get-dataset-items": {
            "post": {
                "operationId": "run-sync-get-dataset-items-olican-crypto-aml-wallet-screener",
                "x-openai-isConsequential": false,
                "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.",
                "tags": [
                    "Run Actor"
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/inputSchema"
                            }
                        }
                    }
                },
                "parameters": [
                    {
                        "name": "token",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Enter your Apify token here"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK"
                    }
                }
            }
        },
        "/acts/olican~crypto-aml-wallet-screener/runs": {
            "post": {
                "operationId": "runs-sync-olican-crypto-aml-wallet-screener",
                "x-openai-isConsequential": false,
                "summary": "Executes an Actor and returns information about the initiated run in response.",
                "tags": [
                    "Run Actor"
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/inputSchema"
                            }
                        }
                    }
                },
                "parameters": [
                    {
                        "name": "token",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Enter your Apify token here"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/runsResponseSchema"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/acts/olican~crypto-aml-wallet-screener/run-sync": {
            "post": {
                "operationId": "run-sync-olican-crypto-aml-wallet-screener",
                "x-openai-isConsequential": false,
                "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.",
                "tags": [
                    "Run Actor"
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/inputSchema"
                            }
                        }
                    }
                },
                "parameters": [
                    {
                        "name": "token",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Enter your Apify token here"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK"
                    }
                }
            }
        }
    },
    "components": {
        "schemas": {
            "inputSchema": {
                "type": "object",
                "required": [
                    "walletAddresses"
                ],
                "properties": {
                    "walletAddresses": {
                        "title": "Wallet Addresses",
                        "type": "array",
                        "description": "List of cryptocurrency wallet addresses to screen (one per row or list items).",
                        "items": {
                            "type": "string"
                        }
                    },
                    "chains": {
                        "title": "Blockchains",
                        "type": "array",
                        "description": "Blockchains to check. If empty or not specified, the Actor will auto-detect the chain based on format.",
                        "items": {
                            "type": "string",
                            "enum": [
                                "BTC",
                                "ETH",
                                "SOL",
                                "BSC",
                                "TRX"
                            ],
                            "enumTitles": [
                                "Bitcoin",
                                "Ethereum",
                                "Solana",
                                "BNB Chain",
                                "Tron"
                            ]
                        },
                        "default": [
                            "BTC",
                            "ETH",
                            "SOL",
                            "BSC",
                            "TRX"
                        ]
                    },
                    "sanctionsLists": {
                        "title": "Sanctions Lists",
                        "type": "array",
                        "description": "Official sanctions lists to cross-reference.",
                        "items": {
                            "type": "string",
                            "enum": [
                                "ofac",
                                "eu",
                                "un",
                                "uk"
                            ],
                            "enumTitles": [
                                "OFAC SDN (US)",
                                "EU Consolidated List",
                                "UN Consolidated List",
                                "HM Treasury (UK)"
                            ]
                        },
                        "default": [
                            "ofac",
                            "eu",
                            "un",
                            "uk"
                        ]
                    },
                    "riskScoring": {
                        "title": "On-Chain Risk Scoring",
                        "type": "boolean",
                        "description": "Activate AMLBot API risk scoring for transaction history (0-100 score). Requires AMLBOT_API_KEY environment variable.",
                        "default": true
                    },
                    "webhookUrl": {
                        "title": "Webhook URL",
                        "type": "string",
                        "description": "Optional HTTP POST URL to notify when the run finishes. It will send a summary payload."
                    }
                }
            },
            "runsResponseSchema": {
                "type": "object",
                "properties": {
                    "data": {
                        "type": "object",
                        "properties": {
                            "id": {
                                "type": "string"
                            },
                            "actId": {
                                "type": "string"
                            },
                            "userId": {
                                "type": "string"
                            },
                            "startedAt": {
                                "type": "string",
                                "format": "date-time",
                                "example": "2025-01-08T00:00:00.000Z"
                            },
                            "finishedAt": {
                                "type": "string",
                                "format": "date-time",
                                "example": "2025-01-08T00:00:00.000Z"
                            },
                            "status": {
                                "type": "string",
                                "example": "READY"
                            },
                            "meta": {
                                "type": "object",
                                "properties": {
                                    "origin": {
                                        "type": "string",
                                        "example": "API"
                                    },
                                    "userAgent": {
                                        "type": "string"
                                    }
                                }
                            },
                            "stats": {
                                "type": "object",
                                "properties": {
                                    "inputBodyLen": {
                                        "type": "integer",
                                        "example": 2000
                                    },
                                    "rebootCount": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "restartCount": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "resurrectCount": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "computeUnits": {
                                        "type": "integer",
                                        "example": 0
                                    }
                                }
                            },
                            "options": {
                                "type": "object",
                                "properties": {
                                    "build": {
                                        "type": "string",
                                        "example": "latest"
                                    },
                                    "timeoutSecs": {
                                        "type": "integer",
                                        "example": 300
                                    },
                                    "memoryMbytes": {
                                        "type": "integer",
                                        "example": 1024
                                    },
                                    "diskMbytes": {
                                        "type": "integer",
                                        "example": 2048
                                    }
                                }
                            },
                            "buildId": {
                                "type": "string"
                            },
                            "defaultKeyValueStoreId": {
                                "type": "string"
                            },
                            "defaultDatasetId": {
                                "type": "string"
                            },
                            "defaultRequestQueueId": {
                                "type": "string"
                            },
                            "buildNumber": {
                                "type": "string",
                                "example": "1.0.0"
                            },
                            "containerUrl": {
                                "type": "string"
                            },
                            "usage": {
                                "type": "object",
                                "properties": {
                                    "ACTOR_COMPUTE_UNITS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATASET_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATASET_WRITES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "KEY_VALUE_STORE_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "KEY_VALUE_STORE_WRITES": {
                                        "type": "integer",
                                        "example": 1
                                    },
                                    "KEY_VALUE_STORE_LISTS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "REQUEST_QUEUE_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "REQUEST_QUEUE_WRITES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATA_TRANSFER_INTERNAL_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATA_TRANSFER_EXTERNAL_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "PROXY_SERPS": {
                                        "type": "integer",
                                        "example": 0
                                    }
                                }
                            },
                            "usageTotalUsd": {
                                "type": "number",
                                "example": 0.00005
                            },
                            "usageUsd": {
                                "type": "object",
                                "properties": {
                                    "ACTOR_COMPUTE_UNITS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATASET_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATASET_WRITES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "KEY_VALUE_STORE_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "KEY_VALUE_STORE_WRITES": {
                                        "type": "number",
                                        "example": 0.00005
                                    },
                                    "KEY_VALUE_STORE_LISTS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "REQUEST_QUEUE_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "REQUEST_QUEUE_WRITES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATA_TRANSFER_INTERNAL_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATA_TRANSFER_EXTERNAL_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "PROXY_SERPS": {
                                        "type": "integer",
                                        "example": 0
                                    }
                                }
                            }
                        }
                    }
                }
            }
        }
    }
}
```