We refreshed our doc site!

Bookmarked links may have changed

Read release notes

Web3 Services

Testing Guide

This guide walks you through testing Circle's Transaction Screening service using the Web3 Services API on testnet. The service is a real time tool that checks blockchain transactions and addresses against predefined rules outlined in your Console.

This guide allows you to trigger hits against each of these rules.

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 9999 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. Check the Testnet Faucets guide for more information.

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

  • Circle’s Sanctions Blocklist: 9999
  • Frozen User Wallet: 8888
  • Your blocklist: 7777
  • Severe Sanctions Risk (Owner): 8999
  • Severe Terrorist Financing (Owner): 8899
  • Severe CSAM Risk (Owner): 8889
  • Severe Illicit Behavior (Owner): 7779
  • High Illicit Behavior Risk (Owner): 7666
  • High Gambling Risk (Owner): 7766

These addresses will return the appropriate test responses, allowing you to verify the functionality of the screening system.

Test Cases Example Responses

1. Circle’s Sanctions Blocklist

  • Magic Value: Address ending in 9999.
  • 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 8888.
  • 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 7777.
  • Result:
{
  "transactionScreeningEvaluation": {
    "ruleName": "Your blocklist",
    "actions": [
      "REVIEW"
    ],
    "reasons": [
      {
        "source": "address",
        "sourceValue": "0xd89e56cba08ee44a9ca9f6c5f2f0e608227b7777",
        "riskScore": "blocklist",
        "riskCategories": [
          "UNSUPPORTED"
        ],
        "type": "OWNERSHIP"
      }
    ],
    "screeningDate": "<timestamp>"
  }
}

4. Severe Sanctions Risk (Owner)

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

5. Severe Terrorist Financing Risk (Owner)

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

6. Severe CSAM Risk (Owner)

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

7. Severe Illicit Behavior Risk (Owner)

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

8. High Illicit Behavior Risk (Owner)

  • Magic Value: Send funds to an address ending in 7666.
  • 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 7766.
  • Result:
{
  "transactionScreeningEvaluation": {
    "ruleName": "High Gambling Risk (Owner)",
    "actions": [
      "REVIEW"
    ],
    "reasons": [
      {
        "source": "address",
        "sourceValue": "0x2d6d4a938e7b69f9b67d815cd0c2737ebf897766",
        "riskScore": "high",
        "riskCategories": [
          "GAMBLING"
        ],
        "type": "OWNERSHIP"
      }
    ],
    "screeningDate": "<timestamp>"
  }
}
Did this page help you?
© 2023-2024 Circle Technology Services, LLC. All rights reserved.