Wallets

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:

Text
0x7fb49965753A9eC3646fd5d004ee5AeD6Cc89999

The 9999 suffix triggers Circle's Sanctions Blocklist in the screening API.

Submit a POST request to the screening API using Node.js:

JavaScript
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:

JSON
{
  "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:

JavaScript
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:

SuffixSimulated Rule Triggered
9999Circle's Sanctions Blocklist
8888Frozen User Wallet
7777Custom Blocklist Rule
8999Severe Sanctions Risk (Owner)
8899Severe Terrorist Financing (Owner)
8889Severe CSAM Risk (Owner)
7779Severe Illicit Behavior (Owner)
7666High Illicit Behavior Risk (Owner)
7766High Gambling Risk (Owner)
Did this page help you?
© 2023-2025 Circle Technology Services, LLC. All rights reserved.