AML Check Endpoints¶

This section covers API endpoints related to Anti-Money Laundering (AML) checks. AML checks are designed for verifying the risk profile and compliance status of cryptocurrency addresses or transactions through paid third-party analysis services. These checks help meet regulatory requirements and mitigate fraud risk by analyzing blockchain data.

To use AML check features, you need to request this feature to be enabled for your account by contacting support. Once enabled, you must also ensure that your API keys have the appropriate allow_aml_check permission. All API features require specific permissions which you can select when creating or updating API keys.

Get Available AML Plans¶

Returns the list of available AML check plans. Each plan record represents the price for a single AML check. Currently, only the "check" type is supported.

When a check is initiated, the plan price is deducted from the user's balance in the specified currency. Users can buy packs of checks at a lower price per check, which is why plans are priced individually.

GET /aml/plan

Required Permissions¶

• allow_aml_check

Rate Limit¶

600 requests per minute

Response¶

[
  {
    "code": "amlcheck",
    "name": "AML Check",
    "description": "Standard AML check using AMLCHECK token",
    "check_type": "check",
    "currency": "AMLCHECK",
    "price": "1.00"
  },
  {
    "code": "usdt",
    "name": "AML Check (USDT)",
    "description": "Standard AML check using USDT",
    "check_type": "check",
    "currency": "USDT",
    "price": "1.00"
  }
]

Response Fields¶

Get Available AML Tokens¶

Returns the list of available tokens (blockchain networks) for AML checks.

GET /aml/token

Required Permissions¶

• allow_aml_check

Rate Limit¶

120 requests per minute

Response¶

[
  {
    "id": 1,
    "symbol": "BTC",
    "name": "Bitcoin",
    "network": "bitcoin",
    "precision": 8
  },
  {
    "id": 2,
    "symbol": "ETH",
    "name": "Ethereum",
    "network": "ethereum",
    "precision": 18
  },
  {
    "id": 3,
    "symbol": "USDT",
    "name": "Tether USD ERC20",
    "network": "ethereum",
    "precision": 6
  }
]

Response Fields¶

Create AML Check¶

Initiates an AML check for an address or transaction.

POST /aml/check

Required Permissions¶

• allow_aml_check

Rate Limit¶

600 requests per minute

Request Parameters¶

Example Request for Address Check¶

{
  "direction": "withdrawal",
  "token": 1,
  "address": "bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh",
  "callback_url": "https://example.com/callbacks/aml",
  "custom_id": "my-aml-check-123"
}

Example Request for Transaction Check¶

{
  "direction": "deposit",
  "token": 1,
  "transaction": "7b5968e39e0d4c980a234931b8a2fd21e804eb7e9f7eb5af75b3d89e2972ad3d",
  "callback_url": "https://example.com/callbacks/aml",
  "custom_id": "my-aml-check-456"
}

Response¶

{
  "code": "AML123456",
  "custom_id": "my-aml-check-123",
  "callback_url": "https://example.com/callbacks/aml",
  "created_at": "2023-01-15T14:30:15Z",
  "updated_at": "2023-01-15T14:30:15Z",
  "plan": "amlcheck",
  "token": 1,
  "currency": "AMLCHECK",
  "price": "1.00",
  "status": "pending",
  "reason_code": null,
  "reason_message": null,
  "address": "bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh",
  "transaction": null,
  "direction": "deposit",
  "result": null,
  "refund_on_fail": true
}

Response Fields¶

List AML Checks¶

Returns a list of AML checks.

GET /aml/check

Required Permissions¶

• allow_aml_check

Rate Limit¶

600 requests per minute

Query Parameters¶

Response¶

[
  {
    "code": "AML123456",
    "custom_id": "my-aml-check-123",
    "callback_url": "https://example.com/callbacks/aml",
    "created_at": "2023-01-15T14:30:15Z",
    "updated_at": "2023-01-15T14:35:20Z",
    "plan": "amlcheck",
    "token": 1,
    "currency": "AMLCHECK",
    "price": "1.00",
    "status": "success",
    "reason_code": null,
    "reason_message": null,
    "address": "bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh",
    "transaction": null,
    "direction": "deposit",
    "result": {
      "direction": "deposit",
      "status": "ready",
      "alert_grade": "low",
      "riskscore": 0.1,
      "signals": {
        "exchanger": 0.1,
        "mixer": 0.0,
        "darknet": 0.0,
        "scam": 0.0,
        "gambling": 0.0
      },
      "address": "bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh",
      "currency": "BTC"
    },
    "refund_on_fail": true
  }
  // More checks...
]

Response Fields¶

ÏSame as the create check response, with the addition of result object.

Pagination¶

The API uses simple offset-based pagination with limit and offset parameters. Offset is limited for maximum 10000, if you set more - error will be returned. The default limit is 100, and the maximum limit is 200. The response is a direct list of AML check objects without pagination metadata wrapper. If you need to fetch more than 200 checks, you should use the start_at and end_at parameters to fetch checks in smaller date ranges. List is sorted by creation date in descending order.

Result Object¶

The result field includes the complete report from the AML check provider:

Signals Object¶

Signals object represents detailed information about the risk factors of the address or transaction. Known signals is: atm, dark_market, dark_service, exchange_fraudulent, exchange_mlrisk_high, exchange_mlrisk_low, exchange_mlrisk_moderate, exchange_mlrisk_veryhigh, gambling, ransom, marketplace, miner, mixer, p2p_exchange_mlrisk_high, p2p_exchange_mlrisk_low, payment, scam, wallet, stolen_coins, illegal_service, terrorism_financing, child_exploitation, seized_assets, sanctions, liquidity_pools. Note that more signals may appear in the future.

Counterparty Object¶

This object represents known entity that is counterparty for address in transaction. All fields are optional and may not be present en reports.

Interpretation of Risk Score¶

The risk score is a value between 0 and 1, where 0 means no risk and 1 means high risk. The risk score is calculated by the AML provider based on various factors, including the presence of known risk signals, the amount of funds involved, and the counterparty's risk profile.

Your system can use the risk score to determine the appropriate action for the address or transaction. For example, you might decide to block a transaction with a high risk score or flag an account for manual review.

Get AML Check Details¶

Returns details of a specific AML check.

GET /aml/check/{code}

Required Permissions¶

• allow_aml_check

Rate Limit¶

600 requests per minute

Path Parameters¶

Response¶

Same as a single check object from the list endpoint.

AML Check Status Values¶

Callback Notifications¶

If a callback_url was provided when creating the check, the system will send POST requests to this URL when the check status changes.

Important Note: You may not receive callbacks for every intermediate status change or field update if changes occur very rapidly. When operations transition through multiple states quickly, intermediate callbacks may be skipped. However, you will always receive callbacks for the final states of operations. Design your callback handling to be idempotent and not dependent on receiving every single state transition.

Currently, callbacks are not signed. The signature mechanism for callbacks is planned for a future update. You should validate callback data by making an authenticated API request to verify the check status.

Callback Payload¶

The callback payload contains the same data as the check details response, with essential fields for status updates:

{
  "code": "AML123456",
  "custom_id": "my-aml-check-123",
  "created_at": "2023-01-15T14:30:15Z",
  "updated_at": "2023-01-15T14:35:20Z",
  "status": "success",
  "reason_code": null,
  "reason_message": null,
  "plan": "amlcheck",
  "token": 1,
  "currency": "AMLCHECK",
  "price": "1.00",
  "result": {
    "direction": "deposit",
    "status": "READY",
    "alert_grade": "low",
    "riskscore": 0.1,
    "signals": {
      "exchanger": 0.1,
      "mixer": 0.0,
      "darknet": 0.0,
      "scam": 0.0,
      "gambling": 0.0
    },
    "address": "bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh",
    "currency": "BTC"
  }
}

Securing Callbacks¶

Since callbacks are not currently signed, you should implement these security measures:

1. Whitelist IPs: Accept callbacks only from the service's IP addresses. Contact support to get the list of server IPs.
2. Verify Data: Always make an authenticated API request to /aml/check/{code} to verify the status and details of any check after receiving a callback.
3. Use HTTPS: Ensure your callback URL uses HTTPS to encrypt the data in transit.

Common Use Cases¶

• Customer verification: Check the risk level of customer source addresses
• Transaction monitoring: Assess the risk level of incoming and outgoing transactions
• Regulatory compliance: Comply with AML/CTF regulations
• Risk management: Identify and mitigate risks associated with cryptocurrency transactions