Quickstart

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.

Before you begin, make sure you have the following:

• A Circle Developer Account
• An API key with appropriate access to Compliance Engine (all testnet keys have this access by default)
• Node.js installed, or an API tool like Postman or cURL
• Axios installed, if using Node.js

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)
  })

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:

• Block the wallet from transaction activity (based on the DENY recommendation)
• Flag the wallet for manual review (based on the REVIEW recommendation)
• Freeze the wallet (based on the FREEZE_WALLET recommendation)

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:

• Create custom rules using the Rule Management Guide.
• Monitor and manage alerts via the Alert Management Guide.
• Validate your full transaction flow using the Testing Guide.