Skip to main content
POST
/
v1
/
w3s
/
compliance
/
screening
/
addresses
Screen a blockchain address
curl --request POST \
  --url https://api.circle.com/v1/w3s/compliance/screening/addresses \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "idempotencyKey": "a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a11",
  "address": "0x1bf9ad0cc2ad298c69a2995aa806ee832788218c",
  "chain": "MATIC-AMOY"
}'
{
  "result": "APPROVED",
  "decision": {
    "ruleName": "Low Gambling Risk (Owner)",
    "actions": [
      "REVIEW"
    ],
    "screeningDate": "2023-01-01T12:04:05Z",
    "reasons": [
      {
        "source": "ADDRESS",
        "sourceValue": "0x1bf9ad0cc2ad298c69a2995aa806ee832788218c",
        "riskScore": "LOW",
        "riskCategories": [
          "GAMBLING"
        ],
        "type": "OWNERSHIP",
        "signalSource": {
          "rowId": "c4d1da72-111e-4d52-bdbf-2e74a2d803d5",
          "pointer": "/addressRiskIndicator/0"
        }
      }
    ]
  },
  "id": "a77f408e-b0ca-46d0-bc13-987d0f021731",
  "address": "0x1bf9ad0cc2ad298c69a2995aa806ee832788218c",
  "chain": "MATIC-AMOY",
  "details": [
    {
      "id": "c4d1da72-111e-4d52-bdbf-2e74a2d803d5",
      "vendor": "VENDOR",
      "response": {},
      "createDate": "2023-01-01T12:04:05Z"
    }
  ],
  "alertId": "b372810b-aac5-4425-a40e-4d9c8cf3a08e"
}

Authorizations

​
Authorization
string
header
required

Circle's API Keys are formatted in the following structure "PREFIX:ID:SECRET". All three parts are requred to make a successful request.

Body

application/json
​
idempotencyKey
string<uuid>
required

Universally unique identifier (UUID v4) idempotency key. This key is utilized to ensure exactly-once execution of mutating requests. To create a UUIDv4 go to uuidgenerator.net. If the same key is reused, it will be treated as the same request and the original response will be returned.

Example:

"a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a11"

​
address
string
required

Blockchain address of the blockchain network.

Example:

"0x1bf9ad0cc2ad298c69a2995aa806ee832788218c"

​
chain
enum<string>
required

Blockchain network.

Available options:
ETH,
ETH-SEPOLIA,
AVAX,
AVAX-FUJI,
MATIC,
MATIC-AMOY,
ALGO,
ATOM,
ARB,
ARB-SEPOLIA,
HBAR,
SOL,
SOL-DEVNET,
UNI,
UNI-SEPOLIA,
TRX,
XLM,
BCH,
BTC,
BSV,
ETC,
LTC,
XMR,
XRP,
ZRX,
OP,
DOT
Example:

"MATIC-AMOY"

Response

OK.

​
result
enum<string>
required

Summary result of the screening evaluation.

Available options:
APPROVED,
DENIED
Example:

"APPROVED"

​
decision
object
required

Address decision detail about matched rule, actions to take, and all related risk signals. Screening decision detail about matched rule, actions to take, and all related risk signals.

​
id
string<uuid>
required

Universally unique identifier (UUID v4) that matches the idempotencyKey passed in from the request. System-generated unique identifier of the resource.

Example:

"c4d1da72-111e-4d52-bdbf-2e74a2d803d5"

​
address
string
required

Blockchain address which is screened.

Example:

"0x1bf9ad0cc2ad298c69a2995aa806ee832788218c"

​
chain
enum<string>
required

Blockchain network.

Available options:
ETH,
ETH-SEPOLIA,
AVAX,
AVAX-FUJI,
MATIC,
MATIC-AMOY,
ALGO,
ATOM,
ARB,
ARB-SEPOLIA,
HBAR,
SOL,
SOL-DEVNET,
UNI,
UNI-SEPOLIA,
TRX,
XLM,
BCH,
BTC,
BSV,
ETC,
LTC,
XMR,
XRP,
ZRX,
OP,
DOT
Example:

"MATIC-AMOY"

​
details
object[]
required

List of more details of the screening from vendor response.

​
alertId
string<uuid>

System-generated unique identifier of the alert generated from address screening. System-generated unique identifier of the resource.

Example:

"c4d1da72-111e-4d52-bdbf-2e74a2d803d5"