Skip to main content
This guide walks you through testing Circle’s Transaction Screening service using the Developer Services API on testnet. The service is a real time tool that checks blockchain transactions and addresses against predefined rules outlined in your Console. For testnet, nine (9) default rules are already in place. Therefore, you will not need to set up rules using this guide. Note that if you remove rules in testnet, the testing flows below will no longer work. This guide allows you to trigger hits against each of these rules.
Compliance Engine on both testnet and mainnet is only available for eligible customers. Contact Circle through the Compliance Engine request form to get access.

​
Setting Up Your Testing Environment with Magic Values

  1. Use Magic Values for Testing:
    • You can test different rules by sending transactions between Programmable Wallets and blockchain addresses ending with specific suffixes (referred to as “Magic Values”).
    • For example, sending funds to an address ending in 999999999999 triggers the Sanctioned Address rule.
  2. Address Generation:
    • Use a vanity address generator like vanity-eth.tk to create an Ethereum address with the required suffix.
    • Import the generated address into your ETH wallet (e.g. MetaMask) using the private key.
  3. Funding the Address:
    • Add testnet tokens to your generated address using the Circle Faucet.

​
Summary of Test Cases

You can test the rules using both existing flows to trigger a screening evaluation against the magic value address generated in the previous steps:
  1. By initiating transactions as usual using the Wallets APIs
  2. By invoking the address screening endpoint via the Compliance Engine API
You can trigger specific responses and actions using addresses with certain suffixes:
SuffixRule nameRisk levelScreening result
999999999999Circle’s Sanctions BlocklistBlocklistDENIED
999999998888Frozen User WalletBlocklistDENIED
999999997777Your blocklistBlocklistDENIED
999999998999Severe Sanctions Risk (Owner)SevereDENIED
999999998899Severe Terrorist Financing Risk (Owner)SevereDENIED
999999998889Severe CSAM Risk (Owner)SevereDENIED
999999997779Severe Illicit Behavior Risk (Owner)SevereDENIED
999999997666High Illicit Behavior Risk (Owner)HighAPPROVED
999999997766High Gambling Risk (Owner)HighAPPROVED
These addresses will return the appropriate test responses, allowing you to verify the functionality of the screening system.
NoteThis guide helps you test Circle’s transaction screening service thoroughly and ensures your applications comply with Circle’s rules for real-time transaction risk screening.

​
Test Cases Example Responses

​
1. Circle’s Sanctions Blocklist

  • Magic Value: Address ending in 999999999999.
  • Result:
{
  "transactionScreeningEvaluation": {
    "ruleName": "Circle's Sanctions Blocklist",
    "actions": ["REVIEW", "FREEZE_WALLET"],
    "reasons": [
      {
        "source": "address",
        "sourceValue": "addressValue",
        "riskScore": "blocklist",
        "riskCategories": ["Sanctions"],
        "type": "OWNERSHIP"
      }
    ],
    "screeningDate": "<timestamp>"
  }
}

​
2. Frozen User Wallet

  • Magic Value: Address ending in 999999998888.
  • Result:
{
  "transactionScreeningEvaluation": {
    "ruleName": "Frozen User Wallet",
    "actions": ["REVIEW"],
    "reasons": [
      {
        "source": "address",
        "sourceValue": "addressValue",
        "riskScore": "blocklist",
        "riskCategories": ["FROZEN"],
        "type": "OWNERSHIP"
      }
    ],
    "screeningDate": "<timestamp>"
  }
}

​
3. Your blocklist

  • Magic Value: Address ending in 999999997777.
  • Result:
{
  "transactionScreeningEvaluation": {
    "ruleName": "Your blocklist",
    "actions": ["REVIEW"],
    "reasons": [
      {
        "source": "address",
        "sourceValue": "0xd89e56cba08ee44a9ca9f6c5f2f0999999997777",
        "riskScore": "blocklist",
        "riskCategories": ["UNSUPPORTED"],
        "type": "OWNERSHIP"
      }
    ],
    "screeningDate": "<timestamp>"
  }
}

​
4. Severe Sanctions Risk (Owner)

  • Magic Value: Address ending in 999999998999.
  • Result:
{
  "transactionScreeningEvaluation": {
    "ruleName": "Severe Sanctions Risk (Owner)",
    "actions": ["REVIEW", "FREEZE_WALLET"],
    "reasons": [
      {
        "source": "address",
        "sourceValue": "0x21e936783ed3ced968ab083010eb999999998999",
        "riskScore": "severe",
        "riskCategories": ["SANCTIONS"],
        "type": "OWNERSHIP"
      }
    ],
    "screeningDate": "<timestamp>"
  }
}

​
5. Severe Terrorist Financing Risk (Owner)

  • Magic Values: Address ending in 999999998899.
  • Result:
{
  "transactionScreeningEvaluation": {
    "ruleName": "Severe Terrorist Financing Risk (Owner)",
    "actions": ["REVIEW", "FREEZE_WALLET"],
    "reasons": [
      {
        "source": "address",
        "sourceValue": "0x01f43824a066cebe734f3d949e48999999998899",
        "riskScore": "severe",
        "riskCategories": ["TERRORIST_FINANCING"],
        "type": "OWNERSHIP"
      }
    ],
    "screeningDate": "<timestamp>"
  }
}

​
6. Severe CSAM Risk (Owner)

  • Magic Value: Address ending in 999999998889.
  • Result:
{
  "transactionScreeningEvaluation": {
    "ruleName": "Severe CSAM Risk (Owner)",
    "actions": [
      "REVIEW",
      "FREEZE_WALLET"
    ],
    "reasons": [
      {
        "source": "address",
        "sourceValue": "0x068f626eacfbf669a0f4995b4de7999999998889",
        "riskScore": "severe",
        "riskCategories": [
          "CSAM"
        ],
        "type": "OWNERSHIP"
      }
    ],
    "screeningDate": “<timestamp>”
  }
}

​
7. Severe Illicit Behavior Risk (Owner)

  • Magic Value: Address ending in 999999997779.
  • Result:
{
  "transactionScreeningEvaluation": {
    "ruleName": "Severe Illicit Behavior Risk (Owner)",
    "actions": ["REVIEW", "FREEZE_WALLET"],
    "reasons": [
      {
        "source": "address",
        "sourceValue": "0xd5d268603413c563a9739a4ca692999999997779",
        "riskScore": "severe",
        "riskCategories": ["ILLICIT_BEHAVIOR"],
        "type": "OWNERSHIP"
      }
    ],
    "screeningDate": "<timestamp>"
  }
}

​
8. High Illicit Behavior Risk (Owner)

  • Magic Value: Send funds to an address ending in 999999997666.
  • Result:
{
  "transactionScreeningEvaluation": {
    "ruleName": "High Illicit Behavior Risk (Owner)",
    "actions": ["REVIEW"],
    "reasons": [
      {
        "source": "address",
        "sourceValue": "address",
        "riskScore": "high",
        "riskCategories": ["ILLICIT_BEHAVIOR"],
        "type": "OWNERSHIP"
      }
    ],
    "screeningDate": "<timestamp>"
  }
}

​
9. High Gambling Risk (Owner)

  • Magic Value: Address ending in 999999997766.
  • Result:
{
  "transactionScreeningEvaluation": {
    "ruleName": "High Gambling Risk (Owner)",
    "actions": ["REVIEW"],
    "reasons": [
      {
        "source": "address",
        "sourceValue": "0x2d6d4a938e7b69f9b67d815cd0c2999999997766",
        "riskScore": "high",
        "riskCategories": ["GAMBLING"],
        "type": "OWNERSHIP"
      }
    ],
    "screeningDate": "<timestamp>"
  }
}