Note: This guide applies specifically to the standalone screening mode, where blockchain addresses are screened independently of transaction flows.
Circle's Transaction Screening allows you to programmatically assess the risk of wallet addresses when sending digital assets using Circle Wallets. This guide walks you through setup, integration, and testing using Circle's Compliance Engine.
Note: This guide applies specifically to the standalone screening mode, where blockchain addresses are screened independently of transaction flows.
Before you begin, make sure you have the following:
Follow the steps below to screen an address:
To simulate a real screening scenario, visit
vanity-eth.tk to generate a test Ethereum wallet
address ending in 9999
:
For example:
0x7fb49965753A9eC3646fd5d004ee5AeD6Cc89999
The 9999
suffix triggers Circle's Sanctions Blocklist in the screening
API.
Submit a POST
request to the screening API using Node.js:
import axios from 'axios'
const options = {
method: 'POST',
url: 'https://api.circle.com/v1/w3s/compliance/screening/addresses',
headers: {
Authorization: 'Bearer <API_KEY>',
'Content-Type': 'application/json',
},
data: {
idempotencyKey: '44bd2d89-9461-4502-84ba-550c9e278db7', // unique-idempotency-key
address: '0x7fb49965753A9eC3646fd5d004ee5AeD6Cc89999',
chain: 'ETH-SEPOLIA',
},
}
axios
.request(options)
.then(function (response) {
console.log(response.data)
})
.catch(function (error) {
console.error(error)
})
Note: You must replace the <API_KEY>
above with your actual Circle API
key.
If the address is flagged, the response returns a DENIED
result with some
actionable compliance recommendations:
{
"result": "DENIED",
"decision": {
"ruleName": "Circle's Sanctions Blocklist",
"actions": ["FREEZE_WALLET", "DENY", "REVIEW"],
"reasons": [
{
"source": "ADDRESS",
"sourceValue": "0x7fb49965753A9eC3646fd5d004ee5AeD6Cc89999",
"riskScore": "BLOCKLIST",
"riskCategories": ["SANCTIONS"],
"type": "OWNERSHIP"
}
],
"screeningDate": "2025-03-29T01:59:02Z"
},
"address": "0x7fb49965753A9eC3646fd5d004ee5AeD6Cc89999",
"chain": "ETH-SEPOLIA"
}
If the screening result is DENIED
, you can take the following actions based on
the recommendations provided:
DENY
recommendation)REVIEW
recommendation)FREEZE_WALLET
recommendation)You can block or freeze the wallet from the Compliance Engine > Alerts page in the Developer Console. For more details, see the Alerts Management documentation.
You can integrate actions and alerts into the transaction logic of your application:
if (response.data.result === 'DENIED') {
const ruleName = response.data.decision.ruleName
const actions = response.data.decision.actions
console.log('Screening result: DENIED by Rule: ' + ruleName)
if (actions.includes('DENY')) {
console.log('Recommended action: DENY — block transactions on wallet')
}
if (actions.includes('REVIEW')) {
console.log('Recommended action: REVIEW — flag wallet for manual review')
}
if (actions.includes('FREEZE_WALLET')) {
console.log('Recommended action: FREEZE_WALLET — freeze wallet activity')
}
}
You can also query additional fields such as riskCategories
, ruleName
, and
type
to make compliance decisions tailored to your business needs. For more
information about these fields, refer to their descriptions in the response
object of the
Screen a blockchain address API
endpoint.
You can use specific suffixes in test addresses to simulate different risk scenarios:
Suffix | Simulated Rule Triggered |
---|---|
9999 | Circle's Sanctions Blocklist |
8888 | Frozen User Wallet |
7777 | Custom Blocklist Rule |
8999 | Severe Sanctions Risk (Owner) |
8899 | Severe Terrorist Financing (Owner) |
8889 | Severe CSAM Risk (Owner) |
7779 | Severe Illicit Behavior (Owner) |
7666 | High Illicit Behavior Risk (Owner) |
7766 | High Gambling Risk (Owner) |
Test suffixes are useful in pre-production environments for validation of custom rule enforcement and behavior.