Sanctions Service

Manages sanctions screening for blockchain addresses and transactions.

---

Endpoints

---

Verify Address (Async)

POST /sanctions/verify-address

Starts an asynchronous address verification job. Results are delivered via webhook.

Request Body

Field	Type	Required	Description	Example
externalId	string	Yes	External job ID for tracking.	"ext-123e4567-e89b-12d3-a456-426614174000"
address	string	Yes	Blockchain address to verify.	"0x1da5821544e25c636c1417ba96ade4cf6d2f9b5a"
blockchain	string	Yes	Blockchain name (e.g., "ethereum", "solana").	"ethereum"
callbackHeaders	object	No	Optional headers to include in webhook callback.	{ "Authorization": "Bearer your-token" }

Example Request:

{
  "externalId": "ext-123e4567-e89b-12d3-a456-426614174000",
  "address": "0x1da5821544e25c636c1417ba96ade4cf6d2f9b5a",
  "blockchain": "ethereum",
  "callbackHeaders": {
    "Authorization": "Bearer your-token"
  }
}

Success Response

Returns job details.

{
  "jobId": "job-789e4567-e89b-12d3-a456-426614174000",
  "externalId": "ext-123e4567-e89b-12d3-a456-426614174000",
  "status": "pending"
}

Error Responses

• 400 Bad Request: Validation failed (missing or invalid fields)
• 409 Conflict: Duplicate externalId

---

Verify Address (Sync)

POST /sanctions/verify-address/sync

Performs synchronous address verification. Returns result immediately.

Request Body

Field	Type	Required	Description	Example
address	string	Yes	Blockchain address to verify.	"0x1da5821544e25c636c1417ba96ade4cf6d2f9b5a"
blockchain	string	Yes	Blockchain name.	"ethereum"

Example Request:

{
  "address": "0x1da5821544e25c636c1417ba96ade4cf6d2f9b5a",
  "blockchain": "ethereum"
}

Success Response

Returns verification result.

{
  "address": "0x1da5821544e25c636c1417ba96ade4cf6d2f9b5a",
  "blockchain": "ethereum",
  "sanctioned": false,
  "sources": [
    {
      "provider": "Chainalysis",
      "match": false,
      "details": {}
    }
  ],
  "checkedAt": "2025-11-20T12:34:56.789Z"
}

Error Responses

• 400 Bad Request: Validation failed

---

Verify Transaction (Async)

POST /sanctions/verify-transaction

Starts an asynchronous transaction verification job. Results are delivered via webhook.

Request Body

Field	Type	Required	Description	Example
externalId	string	Yes	External job ID for tracking.	"ext-123e4567-e89b-12d3-a456-426614174000"
transactionId	string	Yes	Blockchain transaction ID to verify.	"0xabc123..."
blockchain	string	Yes	Blockchain name.	"ethereum"
callbackHeaders	object	No	Optional headers for webhook callback.	{ "Authorization": "Bearer your-token" }

Example Request:

{
  "externalId": "ext-123e4567-e89b-12d3-a456-426614174000",
  "transactionId": "0xabc123...",
  "blockchain": "ethereum",
  "callbackHeaders": {
    "Authorization": "Bearer your-token"
  }
}

Success Response

Returns job details.

{
  "jobId": "job-789e4567-e89b-12d3-a456-426614174000",
  "externalId": "ext-123e4567-e89b-12d3-a456-426614174000",
  "status": "pending"
}

Error Responses

• 400 Bad Request: Validation failed (missing or invalid fields)
• 409 Conflict: Duplicate externalId

---

Verify Transaction (Sync)

POST /sanctions/verify-transaction/sync

Performs synchronous transaction verification. Returns result immediately.

Request Body

Field	Type	Required	Description	Example
transactionId	string	Yes	Blockchain transaction ID to verify.	"0xabc123..."
blockchain	string	Yes	Blockchain name.	"ethereum"

Example Request:

{
  "transactionId": "0xabc123...",
  "blockchain": "ethereum"
}

Success Response

Returns verification result.

{
  "transactionId": "0xabc123...",
  "blockchain": "ethereum",
  "sanctioned": false,
  "sources": [
    {
      "provider": "Chainalysis",
      "match": false,
      "details": {}
    }
  ],
  "checkedAt": "2025-11-20T12:34:56.789Z"
}

Error Responses

• 400 Bad Request: Validation failed

---

Error Format

All error responses follow this format:

{
  "statusCode": "ERROR_CODE",
  "error": ["Description of the error"],
  "requestId": "72e32108-6260-45e9-bb12-325fe3b61e42",
  "path": "endpoint path",
  "timestamp": "2025-11-19T16:32:57.915Z"
}

---

Field Descriptions

Field	Type	Description
jobId	string	Unique identifier for the verification job
externalId	string	External job ID provided by client
status	enum	Job status (pending, completed, failed)
address	string	Blockchain address being verified
transactionId	string	Blockchain transaction ID being verified
blockchain	string	Blockchain name (e.g., "ethereum", "solana")
sanctioned	boolean	Whether the address/transaction is sanctioned
sources	array	List of provider results for sanctions screening
checkedAt	string	ISO8601 timestamp of verification

---

For enum values, see SanctionsJobStatus and SanctionsResult definitions.