Public API Reference

The BlockchainAnalysis.io REST API provides programmatic access to wallet screening, transaction analysis, fund tracing, entity lookup, and real-time transaction monitoring. Integrate compliance workflows directly into your applications with a simple, credit-based pay-per-use model.

API access is available to all users. Generate an API key from the dashboard at BA | API > Overview & Keys, then purchase API credits to start screening.

Base URL

https://blockchainanalysis.io/api/v1

All API requests must be made over HTTPS.

Use blockchainanalysis.io (without www). The www subdomain redirects and drops the Authorization header.

Authentication

The API uses Bearer token authentication. Include your API key in the Authorization header of every request:

curl -H "Authorization: Bearer ba_live_..." \
  https://blockchainanalysis.io/api/v1/usage

API keys are generated in the dashboard under BA | API > Overview & Keys. Keys use the prefix ba_live_ and are shown only once at creation — store them securely.

Never expose your API key in client-side code, public repositories, or logs. If compromised, revoke it immediately from the dashboard and create a new one.

Endpoints

Health Check

GET /v1/health

Lightweight liveness probe. No authentication, no credits consumed, no rate limit. Use this for uptime monitoring and integration heartbeats — do not use resource endpoints like /v1/monitoring/wallets for that purpose.

Example Request

curl https://blockchainanalysis.io/api/v1/health

Response

{ "success": true, "status": "ok", "ts": "2026-05-13T10:00:00.000Z" }

Wallet Screening

POST /v1/screening

Screen a wallet address for risk score, entity identification, sanctions check, transaction flow analysis, and full compliance assessment. Costs 1 API credit per call.

Request Body

| Parameter | Type | Required | Description | |---|---|---|---| | address | string | Yes | The blockchain address to screen | | chain | string | Yes | Blockchain identifier (e.g., ETH, BTC, SOL, TRON) | | jurisdiction | string | No | ISO 3166-1 alpha-2 country code for legal interpretation (default: CH) |

Example Request

curl -X POST https://blockchainanalysis.io/api/v1/screening \
  -H "Authorization: Bearer ba_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "address": "0x28C6c06298d514Db089934071355E5743bf21d60",
    "chain": "ETH",
    "jurisdiction": "CH"
  }'

Response (abbreviated)

{
  "success": true,
  "data": {
    "address": "0x28C6c06298d514Db089934071355E5743bf21d60",
    "chain": "ETH",
    "riskScore": 15,
    "riskLevel": "LOW",
    "entity": {
      "name": "Binance 14",
      "category": "EXCHANGE",
      "threatLevel": "SAFE"
    },
    "sanctioned": false,
    "clusterAnalysis": { ... },
    "transactionFlow": { ... },
    "geographicRisk": { ... },
    "crossChainBalances": { ... },
    "bridgeActivity": { ... },
    "darknetExposure": { ... },
    "legalInterpretation": { ... },
    "scoreBreakdown": [ ... ]
  },
  "credits": { "remaining": 99 }
}

The full screening response includes 15+ analysis sections: entity labels, sanctions check, cluster analysis, transaction flow (inflows/outflows), geographic risk, cross-chain balances, bridge activity, darknet exposure, fund flow jurisdictions, historical services, address validation, legal interpretation, and risk score breakdown.

Entity Lookup

GET /v1/entity/{address}

Look up known entity labels for a wallet address. Returns entity name, category, threat level, and OFAC sanctions status. Free — no credits consumed. Rate-limited to 100 requests/minute.

Path Parameters

| Parameter | Type | Required | Description | |---|---|---|---| | address | string | Yes | The blockchain address to look up |

Query Parameters

| Parameter | Type | Required | Description | |---|---|---|---| | chain | string | No | Blockchain identifier (default: ETH) |

Example Request

curl https://blockchainanalysis.io/api/v1/entity/0x28C6c06298d514Db089934071355E5743bf21d60?chain=ETH \
  -H "Authorization: Bearer ba_live_..."

Response

{
  "success": true,
  "data": {
    "address": "0x28C6c06298d514Db089934071355E5743bf21d60",
    "chain": "ETH",
    "labels": [
      {
        "name": "Binance 14",
        "category": "EXCHANGE",
        "threatLevel": "SAFE",
        "source": "etherscan",
        "tags": ["binance"],
        "confidence": 1
      }
    ],
    "sanctioned": false,
    "sanctionsDetail": null
  }
}

Know Your Transaction (KYT)

POST /v1/kyt

Analyze a single address or a transaction pair (sender/receiver) for risk assessment, entity identification, and compliance flags. Costs 1 API credit per call. Rate-limited to 60 requests/minute.

Request Body

| Parameter | Type | Required | Description | |---|---|---|---| | address | string | Conditional | Single address to analyze (use this OR from/to) | | chain | string | Yes | Blockchain identifier | | from | string | Conditional | Sender address (use with to for transaction pair analysis) | | to | string | Conditional | Receiver address (use with from) |

ENS names (e.g., vitalik.eth) are automatically resolved to addresses.

Example Request — Single Address

curl -X POST https://blockchainanalysis.io/api/v1/kyt \
  -H "Authorization: Bearer ba_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "address": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
    "chain": "ETH"
  }'

Example Request — Transaction Pair

curl -X POST https://blockchainanalysis.io/api/v1/kyt \
  -H "Authorization: Bearer ba_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "from": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
    "to": "0x28C6c06298d514Db089934071355E5743bf21d60",
    "chain": "ETH"
  }'

Response (abbreviated)

{
  "success": true,
  "data": {
    "riskScore": 12,
    "riskLevel": "LOW",
    "from": {
      "address": "0xd8dA...",
      "entity": { "name": "vbuterin.eth", "category": "OTHER", "threatLevel": "LOW" },
      "sanctioned": false
    },
    "to": {
      "address": "0x28C6...",
      "entity": { "name": "Binance 14", "category": "EXCHANGE", "threatLevel": "SAFE" },
      "sanctioned": false
    },
    "flags": []
  },
  "credits": { "remaining": 98 }
}

Fund Trace

POST /v1/trace

Trace the flow of funds through multiple hops, generating a transaction graph. Supports path-finding between two addresses. Costs 5 credits per trace, 10 credits for path mode. Rate-limited to 5 requests/minute.

Request Body

| Parameter | Type | Required | Description | |---|---|---|---| | address | string | Yes | Starting address for the trace | | chain | string | Yes | Blockchain identifier | | direction | string | No | in, out, or both (default: both) | | hops | number | No | Number of hops to trace, 1-3 (default: 1) | | targetAddress | string | No | Enable path-finding mode — find paths between address and targetAddress | | maxDepth | number | No | Max depth for path search (default: 3) | | crossChain | boolean | No | Include cross-chain bridge activity (default: false) |

Example Request — Fund Trace

curl -X POST https://blockchainanalysis.io/api/v1/trace \
  -H "Authorization: Bearer ba_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "address": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
    "chain": "ETH",
    "direction": "out",
    "hops": 2
  }'

Example Request — Path Finder

curl -X POST https://blockchainanalysis.io/api/v1/trace \
  -H "Authorization: Bearer ba_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "address": "0xSourceAddress...",
    "targetAddress": "0xDestinationAddress...",
    "chain": "ETH",
    "maxDepth": 3
  }'

Response (abbreviated)

{
  "success": true,
  "data": {
    "nodes": [
      { "address": "0xd8dA...", "label": "vbuterin.eth", "category": "OTHER", "riskLevel": "LOW" },
      { "address": "0x28C6...", "label": "Binance 14", "category": "EXCHANGE", "riskLevel": "LOW" }
    ],
    "edges": [
      { "from": "0xd8dA...", "to": "0x28C6...", "value": "150.5", "txCount": 3, "firstSeen": "2024-01-15", "lastSeen": "2026-03-10" }
    ],
    "stats": { "totalNodes": 2, "totalEdges": 1, "maxDepthReached": 1 }
  },
  "credits": { "remaining": 93 }
}

Exchange Regulatory Status

GET /v1/exchange-status

Check the regulatory status of a cryptocurrency exchange across jurisdictions. Queries 44 regulatory registers worldwide. Free — no credits consumed. Rate-limited to 100 requests/minute. Requires entity permission.

Query Parameters

| Parameter | Type | Required | Description | |---|---|---|---| | name | string | Yes | Exchange name (e.g., Binance, Coinbase) | | jurisdiction | string | No | ISO country code to filter results (e.g., US, EU) |

Example Request

curl "https://blockchainanalysis.io/api/v1/exchange-status?name=Binance&jurisdiction=EU" \
  -H "Authorization: Bearer ba_live_..."

Response (abbreviated)

{
  "success": true,
  "data": {
    "exchange": "Binance",
    "registrations": [
      {
        "jurisdiction": "FR",
        "authority": "AMF",
        "status": "REGISTERED",
        "registrationId": "E2022-037",
        "registeredAs": "PSAN"
      }
    ],
    "restrictedJurisdictions": ["US", "UK"],
    "totalRegistrations": 15
  }
}

Transaction Monitoring

The Transaction Monitoring API provides real-time wallet monitoring with automated alerts. Add wallets to continuous monitoring, configure alert rules, and receive notifications via webhook, email, Slack, or Telegram when suspicious activity is detected.

Transaction Monitoring requires the monitoring permission on your API key. New API keys include this permission by default.

Add Wallet to Monitoring

POST /v1/monitoring/wallets

Register a wallet for real-time transaction monitoring. Sets up webhook listeners (Alchemy/Moralis) and runs an initial risk screening. Costs 1 API credit.

Request Body

| Parameter | Type | Required | Description | |---|---|---|---| | walletAddress | string | Yes | The blockchain address to monitor | | chain | string | Yes | Blockchain identifier. Supported for TM: ETH, BSC, POLYGON, ARBITRUM, OPTIMISM, BASE, AVALANCHE, FANTOM, CRONOS, GNOSIS | | label | string | No | Human-readable label for the wallet | | alertThreshold | string | No | Alert sensitivity: all, medium, high, critical (default: all) | | alertFrequency | string | No | realtime or daily (default: realtime) | | enabledRules | string[] | No | Alert rule IDs to enable (default: all rules) | | customWebhookUrl | string | No | URL to receive alert webhooks (POST) | | notes | string | No | Internal notes |

Available Alert Rules

| Rule ID | Description | |---|---| | SANCTIONS-001 | Transaction with sanctioned entity detected | | MIXING-001 | Interaction with mixing/tumbling service | | SCAM-001 | Interaction with known scam address | | HIGHRISK-001 | Transaction with high-risk entity | | DARKWEB-001 | Darknet marketplace interaction | | VELOCITY-001 | Unusual transaction velocity or volume spike |

Example Request
curl -X POST https://blockchainanalysis.io/api/v1/monitoring/wallets \
  -H "Authorization: Bearer ba_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "walletAddress": "0x28C6c06298d514Db089934071355E5743bf21d60",
    "chain": "ETH",
    "label": "Treasury Wallet",
    "customWebhookUrl": "https://your-app.com/webhook/alerts"
  }'
Response
{
  "success": true,
  "data": {
    "wallet": {
      "id": "cm...",
      "walletAddress": "0x28c6c06298d514db089934071355e5743bf21d60",
      "chain": "ETH",
      "label": "Treasury Wallet",
      "status": "ACTIVE",
      "riskScore": 15,
      "riskLevel": "LOW",
      "enabledRules": ["SANCTIONS-001", "MIXING-001", "SCAM-001", "HIGHRISK-001", "DARKWEB-001", "VELOCITY-001"],
      "customWebhookUrl": "https://your-app.com/webhook/alerts",
      "createdAt": "2026-04-14T09:00:00.000Z"
    }
  },
  "credits": { "remaining": 99 }
}

List Monitored Wallets

GET /v1/monitoring/wallets

Retrieve all wallets under monitoring. Free — no credits consumed.

Query Parameters

| Parameter | Type | Required | Description | |---|---|---|---| | includeDeleted | boolean | No | Include soft-deleted wallets (default: false) |

Example Request
curl https://blockchainanalysis.io/api/v1/monitoring/wallets \
  -H "Authorization: Bearer ba_live_..."

Get Wallet Details

GET /v1/monitoring/wallets/{id}

Get details for a specific monitored wallet, including alert and transaction counts. Free.

Update Wallet Settings

PATCH /v1/monitoring/wallets/{id}

Update monitoring settings for a wallet — change label, status (ACTIVE/PAUSED), alert rules, webhook URL, or notes. Free.

Request Body

| Parameter | Type | Description | |---|---|---| | label | string | Update the wallet label | | status | string | ACTIVE or PAUSED — pausing stops webhook processing | | action | string | restore — restore a soft-deleted wallet | | alertThreshold | string | Update alert sensitivity | | enabledRules | string[] | Update enabled alert rules | | customWebhookUrl | string | Update or remove webhook URL | | notes | string | Update internal notes |

Example — Pause Monitoring
curl -X PATCH https://blockchainanalysis.io/api/v1/monitoring/wallets/{id} \
  -H "Authorization: Bearer ba_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "status": "PAUSED" }'

Remove Wallet from Monitoring

DELETE /v1/monitoring/wallets/{id}

Soft-delete a wallet from monitoring. Removes webhook listeners, preserves historical data. Can be restored via PATCH with action: "restore". Free.

List Alerts

GET /v1/monitoring/alerts

Retrieve all monitoring alerts across all wallets, with filtering. Free.

Query Parameters

| Parameter | Type | Description | |---|---|---| | status | string | Filter by status: NEW, INVESTIGATING, RESOLVED, DISMISSED | | severity | string | Filter by severity: LOW, MEDIUM, HIGH, CRITICAL | | walletId | string | Filter by wallet ID | | walletAddress | string | Filter by wallet address (comma-separated for multiple) | | limit | number | Results per page, max 100 (default: 50) | | offset | number | Pagination offset (default: 0) |

Example Request
curl "https://blockchainanalysis.io/api/v1/monitoring/alerts?status=NEW&severity=CRITICAL&limit=10" \
  -H "Authorization: Bearer ba_live_..."
Response
{
  "success": true,
  "data": {
    "alerts": [
      {
        "id": "...",
        "status": "NEW",
        "severity": "CRITICAL",
        "wallet": {
          "walletAddress": "0x28c6...",
          "chain": "ETH",
          "label": "Treasury Wallet"
        },
        "createdAt": "2026-04-14T10:30:00.000Z"
      }
    ],
    "total": 1,
    "limit": 10,
    "offset": 0
  }
}

Update Alert Status

PATCH /v1/monitoring/alerts/{id}

Update the status of a monitoring alert. Free.

Request Body

| Parameter | Type | Required | Description | |---|---|---|---| | status | string | Yes | NEW, INVESTIGATING, RESOLVED, or DISMISSED |

Get Wallet Alerts

GET /v1/monitoring/wallets/{id}/alerts

Retrieve alerts for a specific wallet. Supports the same filters as the global alerts endpoint (status, severity, limit, offset). Free.

Get Wallet Transactions

GET /v1/monitoring/wallets/{id}/transactions

Retrieve monitored transactions for a specific wallet, ordered by most recent. Free.

Query Parameters

| Parameter | Type | Description | |---|---|---| | limit | number | Results per page, max 100 (default: 50) | | offset | number | Pagination offset (default: 0) |

Usage & Balance

GET /v1/usage

Returns the current API credit balance and recent transaction history.

Example Request

curl https://blockchainanalysis.io/api/v1/usage \
  -H "Authorization: Bearer ba_live_..."

Response

{
  "success": true,
  "data": {
    "balance": 99,
    "history": [
      {
        "id": "...",
        "amount": -1,
        "balance": 99,
        "type": "DEDUCTION",
        "reference": "screening:0x28C6...d60:ETH",
        "createdAt": "2026-03-10T15:30:00.000Z"
      },
      {
        "id": "...",
        "amount": 100,
        "balance": 100,
        "type": "PURCHASE",
        "reference": null,
        "createdAt": "2026-03-10T14:28:59.667Z"
      }
    ]
  }
}

API Key Management

API keys are managed through the dashboard at BA | API > Overview & Keys:

  • Create — Generate a new key with a custom name
  • Revoke — Permanently deactivate a key. Revoked keys cannot be reactivated.
  • Permissions — Each key can be scoped to specific endpoint groups: screening (screening, KYT, trace), entity (entity lookup, exchange status), monitoring (transaction monitoring)

Rate Limits

| Endpoint | Limit | Cost | |---|---|---| | Screening (POST /v1/screening) | 20 req/min | 1 credit | | KYT (POST /v1/kyt) | 60 req/min | 1 credit | | Fund Trace (POST /v1/trace) | 5 req/min | 5 credits (10 for path mode) | | Entity Lookup (GET /v1/entity/:address) | 100 req/min | Free | | Exchange Status (GET /v1/exchange-status) | 100 req/min | Free | | Monitoring (/v1/monitoring/*) | 30 req/min | 1 credit (add wallet only) | | Usage (GET /v1/usage) | No limit | Free |

Rate limit headers are included in every response:

X-RateLimit-Limit: 20
X-RateLimit-Remaining: 18
X-RateLimit-Reset: 1709856060

Exceeding the rate limit returns a 429 Too Many Requests response.

API Credit Packages

API credits are separate from dashboard credits. Purchase them from the dashboard at BA | API > Buy Credits:

| Package | Credits | Price | Per Screening | |---|---|---|---| | Free | 10/month | $0 | $0.00 | | Starter | 100 | $199 | $1.99 | | Growth | 500 | $799 | $1.60 | | Business | 2,000 | $2,499 | $1.25 | | Enterprise | 10,000 | $9,999 | $1.00 | | Custom | Negotiated | Custom | Contact sales |

Every account includes a free tier of 10 API screenings per month — no credit card required. For volumes above 10,000 screenings, contact sales@blockchainanalysis.io for custom pricing.

Payment methods: credit card (Stripe), cryptocurrency (CoinGate), and wire transfer.

Entity Lookup is free and does not consume credits.

Error Codes

| Code | Meaning | |---|---| | 400 | Bad Request — Invalid or missing parameters | | 401 | Unauthorized — Invalid, revoked, or missing API key | | 402 | Payment Required — Insufficient API credits | | 403 | Forbidden — API key lacks the required permission | | 429 | Too Many Requests — Rate limit exceeded | | 500 | Internal Server Error — Contact support |

Supported Blockchains

The API supports 33+ blockchains:

EVM chains: ETH, BSC, POLYGON, ARBITRUM, OPTIMISM, BASE, AVALANCHE, LINEA, GNOSIS, FANTOM, CRONOS, ETC, MANTLE, SCROLL, ZKSYNC, CELO, MOONBEAM, ETHERLINK

UTXO chains: BTC, LTC, DOGE, DASH, ZEC, BCH, BSV

Other chains: SOL, TRON, XRP, XLM, ADA, DOT, TON, XMR, ATOM, ALGO, XTZ

Use the chain identifier (e.g., ETH, BTC, SOL) in the chain parameter.

Quick Start Example

import requests

API_KEY = "ba_live_..."
BASE_URL = "https://blockchainanalysis.io/api/v1"

# 1. Check balance
r = requests.get(f"{BASE_URL}/usage", headers={"Authorization": f"Bearer {API_KEY}"})
print(f"Credits: {r.json()['data']['balance']}")

# 2. Entity lookup (free)
r = requests.get(
    f"{BASE_URL}/entity/0x28C6c06298d514Db089934071355E5743bf21d60",
    params={"chain": "ETH"},
    headers={"Authorization": f"Bearer {API_KEY}"}
)
print(r.json()["data"]["labels"])

# 3. Full screening (1 credit)
r = requests.post(
    f"{BASE_URL}/screening",
    json={"address": "0x28C6c06298d514Db089934071355E5743bf21d60", "chain": "ETH"},
    headers={"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"}
)
data = r.json()["data"]
print(f"Risk: {data['riskScore']} ({data['riskLevel']})")

const API_KEY = "ba_live_...";
const BASE = "https://blockchainanalysis.io/api/v1";
const headers = { Authorization: `Bearer ${API_KEY}`, "Content-Type": "application/json" };

// Full screening
const res = await fetch(`${BASE}/screening`, {
  method: "POST",
  headers,
  body: JSON.stringify({ address: "0x28C6c06298d514Db089934071355E5743bf21d60", chain: "ETH" }),
});
const { data } = await res.json();
console.log(`Risk: ${data.riskScore} (${data.riskLevel})`);
BlockchainAnalysis.io — Digital Asset Compliance Platform