API Documentation

Comprehensive guide to integrating Anchain.ai AML API

Navigation

Authentication

API Endpoints

• Crypto Screening • Crypto Auto Trace • Sanctions Screening • IP Screening • Smart Contract Agent

Supported Chains Error Handling

Authentication

Secure your API requests with authentication tokens

All API requests require authentication using your API key. Include your key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

API Endpoints

Available endpoints for AML screening and risk analysis

GET

/api/crypto_screening

🔒 Auth Required

Screen cryptocurrency addresses for risk factors and sanctions compliance

Parameters

Required

protocol(string)

The blockchain protocol code (e.g., btc, eth, sol)

Required

address(string)

Cryptocurrency address to screen

Optional

action(string)

Analysis type (default: 'score'). Options: 'score' (basic risk assessment), 'activity' (detailed suspicious activity analysis), 'attribution' (transaction flow attribution - pro plans only)

Response Fields

string

data.action

The analysis type that was performed

string

data.protocol

The blockchain protocol that was screened

string

data.address

The cryptocurrency address that was screened

number

data.risk_score

Calculated risk score (0-100)

string

data.risk_level

Risk level (Low/Guarded/High/Severe)

array

data.risk_factors

List of risk factors with category and optional name

string

data.entity_type

Comma-separated entity types if available

array

data.risk_activity

Detailed suspicious activity analysis (action=activity only)

object

data.attribution

Transaction flow attribution with counterparty analysis (action=attribution only)

Examples

Basic Usage (action=score)

curl -X GET \
  "https://staging-aml.anchainai.com/api/crypto_screening?protocol=btc&address=bc1qm34lsc65zpw79lxes69zkqmk6ee3ewf0j77s3h&action=score" \
  -H "Authorization: Bearer $APIKEY"

Activity Analysis (action=activity)

curl -X GET \
  "https://staging-aml.anchainai.com/api/crypto_screening?protocol=btc&address=bc1qm34lsc65zpw79lxes69zkqmk6ee3ewf0j77s3h&action=activity" \
  -H "Authorization: Bearer $APIKEY"

Attribution Analysis (action=attribution, Premium Plans Only)

curl -X GET \
  "https://staging-aml.anchainai.com/api/crypto_screening?protocol=btc&address=bc1qm34lsc65zpw79lxes69zkqmk6ee3ewf0j77s3h&action=attribution" \
  -H "Authorization: Bearer $APIKEY"

POST

/api/crypto_auto_trace

🔒 Auth Required

Crypto auto-trace transaction flows for investigation and analysis

Parameters

Required

proto(string)

Blockchain protocol. Supported: btc (Bitcoin), eth (Ethereum), xrp (Ripple), egld (MultiversX), trx (Tron)

Optional

address(string)

Wallet address to auto-trace from (required if txnhash not provided)

Optional

txnhash(string)

Transaction hash to auto-trace from (required if address not provided)

Optional

direct(string)

Auto-trace direction: 'in' for incoming, 'out' for outgoing (default: 'in')

Optional

time_from(number)

Start timestamp (Unix epoch)

Optional

time_to(number)

End timestamp (Unix epoch)

Optional

time_window(number)

Number of past days to include around transaction time (default: 365)

Optional

max_hop(number)

Maximum auto-tracing depth, range [1-10] (default: 10)

Optional

max_node(number)

Maximum number of nodes to auto-trace per hop, range [1-100] (default: 20)

Optional

min_amount(number)

Minimum transaction amount per hop (default: 0)

Optional

max_amount(number)

Maximum transaction amount per hop

Optional

token(string)

Token address filter

Optional

token_id(string)

NFT token ID filter

Optional

amt_cap(number)

Cap each hop by total transaction value (0: no cap, 1: cap applied)

Optional

sort_keys(string)

Priority for selecting nodes: 'time,amount' or 'amount,time'

Optional

has_report(number)

Generate xlsx report (0: no, 1: yes)

Response Fields

string

data.proto

The blockchain protocol that was traced (btc/eth/xrp/egld/trx)

string

data.direct

The auto-trace direction that was used

number

data.max_hop

Maximum auto-tracing depth used

number

data.max_node

Maximum number of nodes traced per hop

string

data.address

The wallet address that was traced (if provided)

string

data.txnhash

The transaction hash that was traced (if provided)

array

data.path_info

Auto-trace path information with transaction details

object

data.labels_mapping

Address labels mapping for entity identification

object

data.tokens_mapping

Token information and metadata

object

data.cluster_mapping

Cluster analysis data

Examples

Basic Usage

curl -X POST \
  "https://staging-aml.anchainai.com/api/crypto_auto_trace" \
  -H "Authorization: Bearer $APIKEY" \
  -H "Content-Type: application/json" \
  -d '{
    "proto": "btc",
    "address": "13fhnkmpBBWXUQucJd6efWvXdEj78DKavk",
    "direct": "out",
    "max_hop": 5,
    "max_node": 20,
    "time_from": 1659283200,
    "time_to": 1753977600,
    "min_amount": 0.0001
  }'

POST

/api/sanctions_screening

🔒 Auth Required

Perform sanctions screening against global watchlists from OFAC, EU, UN, and other global regulators

Parameters

Optional

schema(string)

Entity type to screen (e.g. 'person', 'organization')

Optional

scope(string)

Search scope (basic/full). Default: basic. Full scope requires paid plan

Optional

properties.name(array of strings)

List of names/aliases (max 10, e.g. ["John Doe"])

Optional

properties.nationality(array of strings)

List of ISO 3166-1 alpha-2 country codes (e.g. ["us", "cn"])

Optional

properties.idNumber(array of strings)

List of identification numbers (passport, national ID, etc.)

Optional

properties.birthYear(array of strings)

List of birth years in YYYY format (e.g. ["1977"])

Response Fields

number

data.risk_score

Overall risk score (0 for no matches, 100 for matches found)

string

data.risk_level

Risk level based on score (Low/Guarded/High/Severe)

number

data.sanctions.{dataset}[]._score

Match relevance score for individual entity

string

data.sanctions.{dataset}[].id

Unique entity identifier

string

data.sanctions.{dataset}[].dataset

Source dataset name (e.g. 'us_ofac')

string

data.sanctions.{dataset}[].schema

Entity type (Person/Company/etc.)

string

data.sanctions.{dataset}[].caption

Display name of matched entity

object

data.sanctions.{dataset}[].properties

Additional entity properties (varies by entity)

Examples

Basic Usage

curl -X POST \
  "https://staging-aml.anchainai.com/api/sanctions_screening" \
  -H "Authorization: Bearer $APIKEY" \
  -H "Content-Type: application/json" \
  -d '{
    "schema": "person",
    "properties": {
      "name": ["Wei Zhang"],
      "nationality": ["cn"],
      "birthYear": ["1977"]
    }
  }'

GET

/api/ip_screening

🔒 Auth Required

Check IP address against global sanctions lists to determine if it originates from a sanctioned country

Parameters

Required

ip_address(string)

IP address to check (e.g. '8.8.8.8')

Response Fields

number

data.risk_score

Risk score (0 for non-sanctioned, 100 for sanctioned countries)

string

data.risk_level

Risk level based on score (Low/Guarded/High/Severe)

string

data.ip_address

The IP address that was checked

string

data.country

Country name where IP is located

string

data.country_code

2-letter country code (ISO 3166-1)

string

data.subdivsion

State/province subdivision if available, Requires Pro Plan

string

data.city

City name if available, Requires Pro Plan

boolean

data.is_sanctioned

Whether IP is from a sanctioned country

array

data.matched_sanction_list

List of sanction lists that matched this country

string

data.reason

Explanation of sanction status

Examples

Basic Usage

curl -X GET \
  "https://staging-aml.anchainai.com/api/ip_screening?ip_address=1.2.3.4" \
  -H "Authorization: Bearer $APIKEY"

GET

/api/smart_contract_agent

🔒 Auth Required

Transaction analysis service for blockchain data retrieval

Parameters

Required

protocol(string)

Blockchain protocol (e.g., 'eth', 'bnb')

Required

transaction_hash(string)

Transaction hash to analyze

Response Fields

string

data.action

The analysis type that was performed

string

data.protocol

The blockchain protocol that was analyzed

string

data.transaction_hash

The transaction hash that was analyzed

object

data.transaction

Transaction analysis results

object

data.transaction.overview

Transaction overview with basic information

object

data.transaction.balance_table

Balance changes summary

object

data.transaction.transaction_graph

Transaction flow graph with vertices and edges

object

data.transaction.token_index

Token information and metadata mapping

object

data.transaction.data

Detailed transaction execution data including calls, gas usage, and trace information

Examples

Basic Usage

curl -X GET \
  "https://staging-aml.anchainai.com/api/smart_contract_agent?protocol=eth&transaction_hash=0xfd04466bb91ec4270172acffe187eea57145a906de9b488a0f410ade1569760e" \
  -H "Authorization: Bearer $APIKEY"

Supported Blockchain Networks

Comprehensive coverage across major blockchain ecosystems

Bitcoin (BTC)

Ethereum (ETH)

Binance Smart Chain (BNB)

Solana (SOL)

Ripple (XRP)

Avalanche (AVAX)

Tron (TRX)

Polygon (MATIC)

Litecoin (LTC)

Bitcoin Cash (BCH)

Stellar (XLM)

Bitcoin SV (BSV)

MultiversX (EGLD)

Algorand (ALGO)

Flow (FLOW)

Klaytn (KLAY)

Bitcoin Gold (BTG)

Zcash (ZEC)

Dash (DASH)

Harmony (ONE)

Verge Currency (XVG)

Provenance (HASH)

SUI (SUI)

EOS (EOS)

Dogecoin (DOGE)

Cardano (ADA)

Conflux (CFX)

Cosmos (ATOM)

Ethereum Classic (ETC)

Celo (CELO)

Fantom (FTM)

Moonbeam (GLMR)

Cronos (CRO)

Everscale (EVER)

Filecoin (FIL)

Hedera (HBAR)

Tezos (XTZ)

Coreum (COREUM)

COTI (COTI)

Need support for another chain?

Error Handling

HTTP status codes and error response formats

Response Format

All API responses follow a consistent structure with status, error message, and data fields:

{
  "status": <HTTP_STATUS_CODE>,
  "err_msg": "<ERROR_MESSAGE>",
  "data": <RESPONSE_DATA_OR_NULL>
}

HTTP Status Codes

200

Request successful

Example Response:

{
  "status": 200,
  "err_msg": "",
  "data": { ... }
}

400

Bad Request

Invalid request parameters or malformed JSON

Example Response:

{
  "status": 400,
  "err_msg": "Missing required field: name",
  "data": null
}

401

Unauthorized

Invalid or missing API key

Example Response:

{
  "status": 401,
  "err_msg": "Invalid API key",
  "data": null
}

403

Forbidden

API key does not have permission for this resource

Example Response:

{
  "status": 403,
  "err_msg": "Insufficient permissions",
  "data": null
}

404

Not Found

Endpoint does not exist

Example Response:

{
  "status": 404,
  "err_msg": "Endpoint not found",
  "data": null
}

429

Too Many Requests

Rate limit exceeded

Example Response:

{
  "status": 429,
  "err_msg": "Rate limit exceeded. Try again in 60 seconds",
  "data": null
}

500

Internal Server Error

Server encountered an unexpected condition

Example Response:

{
  "status": 500,
  "err_msg": "Internal server error",
  "data": null
}

502

Bad Gateway

Invalid response from upstream server

Example Response:

{
  "status": 502,
  "err_msg": "Bad gateway",
  "data": null
}

503

Service Unavailable

Service temporarily unavailable

Example Response:

{
  "status": 503,
  "err_msg": "Service unavailable. Please try again later",
  "data": null
}

Error Handling Best Practices

•Always check the status field before processing data

•Implement retry logic for 5xx server errors with exponential backoff

•Handle rate limiting (429) by respecting the retry-after header

•Log error messages for debugging and monitoring purposes

•Validate API keys and refresh tokens before making requests