REST API & ScamDB APIでChainAnalyzerをシステムに統合
REST APIリクエストにはtfk_プレフィックスのAPIキーが必要です。ダッシュボードの「設定」→「API Keys」から作成できます（1アカウント最大5本・作成時に1度だけ全文表示）。
X-API-Keyヘッダーで送信:
curl -H "X-API-Key: tfk_your_key_here" \ https://chain-analyzer.com/api/v1/public/scanhttps://chain-analyzer.com/api/v1全エンドポイントの機械可読な定義（OpenAPI 3.1）。Postman / Insomnia / コード生成ツールにそのまま読み込めます。
curl https://chain-analyzer.com/openapi-enterprise.jsonrisk_scoreは0（安全）〜100（危険）で、値が大きいほどリスクが高い。この規約は単発スキャン・バッチ結果・スキャン履歴・Webhookペイロードで統一されています。履歴・バッチ系のレスポンスにはscore_semantics: "risk_0to100" が付くので、クライアント側で規約をアサートできます。
chainの識別子はbitcoin / ethereum / polygon / bsc / base / arbitrum / optimism / avalanche / kaia / solana / tron / xrp。BNB Smart Chainはbscです（bnbは400）。省略するとアドレス形式から自動判定します。
PATCHメソッドに対応しています（Webhook設定・Follow Mode・ケース/ケースアドレスの部分更新）。
入金の受け入れ判定から継続監視まで、実運用のコアループを4ステップで通します。すべてcurlでそのまま実行できます（tfk_your_key_hereを自分のキーに差し替えてください）。
2段構えにします。ホットパスではGET /public/presign/checkで即座にverdictを得て、ok以外のときだけPOST /public/scanのフルスキャンに落とします。例はTRONのUSDT入金です（token_contract = TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t）。
① 高速レーン — 毎トランザクション呼んで構いません（クォータ消費0・専用レート枠・約120秒キャッシュ）
curl -H "X-API-Key: tfk_your_key_here" \ "https://chain-analyzer.com/api/v1/public/presign/check?chain=tron&to=TAUN6FwrnwwmaEqYcckffC7wYmbaS6cBiX"{
"level": "low",
"verdict": "ok",
"score": 5,
"reasons": [],
"signals": { "sanctioned": false, "scamdb_hit": false },
"confidence": 0.9,
"chain": "tron",
"to": "TAUN6FwrnwwmaEqYcckffC7wYmbaS6cBiX",
"latency_ms": 41,
"cached": false
}verdictはok / caution / dangerの3値で、UIのバナー状態にそのまま対応します。levelはcritical / high / medium / low / unknown（未対応チェーンもunknown）、scoreは0〜100で大きいほど危険です。
② フルスキャン — verdictがok以外のときだけ（1スキャン消費）
curl -X POST https://chain-analyzer.com/api/v1/public/scan \ -H "X-API-Key: tfk_your_key_here" -H "Content-Type: application/json" \ -d '{"address":"TAUN6FwrnwwmaEqYcckffC7wYmbaS6cBiX","chain":"tron"}'{
"success": true,
"address": "TAUN6FwrnwwmaEqYcckffC7wYmbaS6cBiX",
"chain": "tron",
"address_type": "wallet",
"risk_level": "LOW",
"risk_score": 8,
"detection_count": 0,
"detections": [],
"metadata": { "is_sanctioned": false, "total_transactions": 1204 },
"ml_anomaly_score": 0.1147,
"top_counterparties": [
{
"address": "TN3W4H6rK2ce4vX9YnFQHwKENnHjoxb3m9",
"label": "Binance", "category": "exchange",
"tx_count": 42, "sent_count": 18, "received_count": 24,
"value_by_asset": { "USDT": 125000.5 },
"tokens": ["USDT"],
"tx_hash": "0x9f...c1", "label_source": "tronscan_tag"
}
],
"flow_totals": { "sent": { "USDT": 412000 }, "received": { "USDT": 418500 } },
"scan_duration_ms": 6321,
"cached": false
}top_counterpartiesは上位の取引相手先（label / category / 資産別金額 / 代表tx）。categoryはself・whitelist・sanctioned・darknet・drainer・mixer・gambling・bridge・exchange・dex・dex_router・other・unknownのいずれか。label_source: "tronscan_tag" はスキャン時にTronscanの公開タグで補完したラベルです。flow_totalsは今回のスキャンで観測できた資産別の送金／受金合計（下限値）。いずれも履歴の単体取得GET /public/scans/{scan_id}でも返ります。
UTXOの多いBitcoinアドレスや取引頻度の高いEVMアドレスは、同期スキャンだとHTTPのタイムアウトに掛かることがあります。202とジョブIDを受け取り、statusがcompletedになるまでstatus_urlをポーリングしてからresults_urlを読みます。消費クォータは同期スキャンと同じ1件です。
curl -X POST https://chain-analyzer.com/api/v1/public/scan/async \ -H "X-API-Key: tfk_your_key_here" -H "Content-Type: application/json" \ -d '{"address":"347QFbejDBdMZFTxpmn6evvvqyXiqZTCd7","chain":"bitcoin"}'{
"success": true,
"job_id": "550e8400-e29b-41d4-a716-446655440000",
"status": "queued",
"address": "347QFbejDBdMZFTxpmn6evvvqyXiqZTCd7",
"chain": "bitcoin",
"status_url": "/api/v1/public/scan/550e8400-e29b-41d4-a716-446655440000",
"results_url": "/api/v1/public/scan/550e8400-e29b-41d4-a716-446655440000/results",
"message": "Scan queued. Poll status_url until status is 'completed'."
}ポーリング → 結果取得
curl -H "X-API-Key: tfk_your_key_here" \ https://chain-analyzer.com/api/v1/public/scan/550e8400-e29b-41d4-a716-446655440000curl -H "X-API-Key: tfk_your_key_here" \ https://chain-analyzer.com/api/v1/public/scan/550e8400-e29b-41d4-a716-446655440000/results判定済みのアドレスをWatchlistに載せると定期再スキャンの対象になり、リスクレベルが変化した瞬間にWebhookが飛びます。登録直後の初回スキャンは非同期なので、レスポンスのinitial_scan.statusはpendingで返ります（完了後に行が更新されます）。
curl -X POST https://chain-analyzer.com/api/v1/watchlist \ -H "X-API-Key: tfk_your_key_here" -H "Content-Type: application/json" \ -d '{"address":"TAUN6FwrnwwmaEqYcckffC7wYmbaS6cBiX","chain":"tron","label":"deposit-12345"}'{
"success": true,
"item": {
"id": "8f14e45f-ceea-467a-9a1c-1f0d3b6a2f77",
"token_address": "TAUN6FwrnwwmaEqYcckffC7wYmbaS6cBiX",
"chain": "tron",
"label": "deposit-12345",
"monitor_type": "address",
"follow_mode_enabled": false,
"follow_depth": 1,
"last_risk_level": null,
"last_scanned_at": null
},
"initial_scan": {
"status": "pending",
"risk_level": "UNKNOWN",
"risk_score": 0,
"detections": []
}
}Webhookエンドポイントを登録する
curl -X POST https://chain-analyzer.com/api/v1/webhooks/configs \ -H "X-API-Key: tfk_your_key_here" -H "Content-Type: application/json" \ -d '{"webhook_url":"https://ops.example.com/hooks/chainanalyzer", "description":"AML alerts", "events":["risk.changed","risk.critical_detected"]}'{
"config": {
"id": "3d1f0c6e-5a2b-4f19-8f7a-0c9d2e6b41aa",
"webhook_url": "https://ops.example.com/hooks/chainanalyzer",
"description": "AML alerts",
"events": ["risk.changed", "risk.critical_detected"],
"is_active": true,
"created_at": "2026-08-14T02:11:44Z"
},
"secret": "b7c19a2f…8e04d1",
"message": "Save this secret securely. It won't be shown again."
}secretは作成時に1度だけ返ります。配信にはX-ChainAnalyzer-Signature: sha256=<HMAC-SHA256(secret, リクエストボディ全文)> が付くので、受信側はボディのバイト列で検証してください。
risk.critical_detectedの実際の配信ペイロード:
{
"event": "risk.critical_detected",
"timestamp": "2026-08-14T03:27:19.482913",
"data": {
"address": "TAUN6FwrnwwmaEqYcckffC7wYmbaS6cBiX",
"chain": "tron",
"previous_risk_level": "LOW",
"risk_level": "CRITICAL",
"risk_score": 100,
"detections": [
{
"detector_id": "B2",
"detector_name": "OFAC_SANCTIONED",
"severity": "CRITICAL",
"description": "Address is on OFAC SDN sanctions list"
}
],
"detail_url": "https://chain-analyzer.com/scan?address=TAUN6Fwrnwwm…&chain=tron",
"score_semantics": "risk_0to100"
}
}risk.critical_detected / risk.high_detectedは、監視対象が新たにそのレベルを跨いだ瞬間にrisk.changedとは別イベントとして発火します（二重通知を避けるためWatchlist対象に限定）。dataの中身は3イベントとも同じ形です。webhook_urlがhooks.slack.comのときだけ、この形ではなくSlackのblocks形式に変換して送信されます。
プラン上限をクライアント側にハードコードせず、このエンドポイントを参照してください。読み取り専用でクォータを消費しません。-1は無制限を意味します。
curl -H "X-API-Key: tfk_your_key_here" \ https://chain-analyzer.com/api/v1/public/usage{
"plan_id": "enterprise",
"scans_per_month": -1,
"scans_used": 8412,
"scans_remaining": -1,
"topup_remaining": 0,
"period": "2026-08",
"period_reset_at": "2026-09-01T00:00:00Z",
"api_rate_limit_per_min": 300,
"presign_rate_limit_per_min": 1200,
"batch_limit": 500,
"watchlist_limit": -1,
"webhook_limit": -1
}「高速レーンでスクリーニング → 必要ならフルスキャン → 判定」をrequestsで実装した最小例です。
import requests
BASE = "https://chain-analyzer.com/api/v1"
HEADERS = {"X-API-Key": "tfk_your_key_here"}
def screen(address: str, chain: str) -> dict:
"""Fast lane first; escalate to a full scan only when it is not clean."""
r = requests.get(
f"{BASE}/public/presign/check",
params={"chain": chain, "to": address},
headers=HEADERS,
timeout=10,
)
r.raise_for_status()
verdict = r.json()
# "ok" means registry + scam-database lookups found nothing. Accept and stop:
# this call costs no monthly quota, so it is safe on every transaction.
if verdict["verdict"] == "ok":
return {"decision": "accept", "risk_score": verdict["score"]}
# Not clean -> spend 1 scan on the full detector pipeline for the audit trail.
r = requests.post(
f"{BASE}/public/scan",
json={"address": address, "chain": chain},
headers=HEADERS,
timeout=120,
)
r.raise_for_status()
scan = r.json()
# risk_score is 0-100, higher = riskier. CRITICAL always blocks.
decision = "block" if scan["risk_level"] in ("CRITICAL", "HIGH") else "review"
return {
"decision": decision,
"risk_score": scan["risk_score"],
"detections": [d["detector_name"] for d in scan["detections"]],
}
print(screen("TAUN6FwrnwwmaEqYcckffC7wYmbaS6cBiX", "tron"))入金の受け入れ判定・出金前の宛先チェック・ウォレット署名前の警告表示に使う、低レイテンシのリスク判定エンドポイントです。VASPのホットパス向けに設計されています。
| メソッド | パス | 認証 | 説明 |
|---|---|---|---|
| GET | /public/presign/check | tfk_ | 宛先 / spenderの署名前リスク判定（APIキー版） |
主なパラメータ: chain（必須）・to（必須・宛先またはspender）・value・data / calldata・spender・kind・signer・asset。
curl -H "X-API-Key: tfk_your_key_here" \ "https://chain-analyzer.com/api/v1/public/presign/check?chain=ethereum&to=0x1234..."{
"level": "critical",
"verdict": "danger",
"score": 100,
"reasons": ["Address is on the OFAC SDN sanctions list"],
"signals": { "sanctioned": true },
"confidence": 1.0,
"chain": "ethereum",
"to": "0x1234...",
"latency_ms": 12,
"cached": false
}| メソッド | パス | 認証 | 説明 |
|---|---|---|---|
| POST | /public/scan | tfk_ | アドレスをスキャン（全12チェーン対応: Bitcoin / Ethereum / Polygon / BNB / Base / Arbitrum / Optimism / Avalanche / Solana / Kaia / TRON / XRP）。結果は30分キャッシュされます。 |
| GET | /public/scan | tfk_ | 同じスキャンのクエリパラメータ版（GET） |
| POST | /public/scan/async | tfk_ | 1アドレスを非同期スキャン（202 + ジョブID） |
| POST | /public/scan/batch | tfk_ | バッチスキャンジョブを投入（Pro: 100件/回・Business: 200件/回・Enterprise: 500件/回） |
| GET | /public/scan/{job_id} | tfk_ | ジョブの進捗を確認（バッチ / 非同期スキャン共通） |
| GET | /public/scan/{job_id}/results | tfk_ | ジョブの結果を取得（score_semantics付き） |
| GET | /public/scans | tfk_ | 直近の記録済みスキャンを一覧（新しい順・最大100件/ページ） |
| GET | /public/scans/{scan_id} | tfk_ | 記録済みスキャン1件をdetections付きで取得 |
| GET | /public/usage | tfk_ | 当月の使用量とプラン上限を取得 |
| GET | /public/health | 不要 | APIヘルスチェック（認証不要） |
/public/scan{
"address": "347QFbejDBdMZFTxpmn6evvvqyXiqZTCd7",
"chain": "bitcoin"
}{
"success": true,
"address": "347QFbejDBdMZFTxpmn6evvvqyXiqZTCd7",
"chain": "bitcoin",
"address_type": "wallet",
"risk_level": "CRITICAL",
"risk_score": 100,
"detection_count": 4,
"detections": [
{
"detector_id": "B2",
"detector_name": "OFAC_SANCTIONED",
"severity": "CRITICAL",
"description": "Address is on OFAC SDN sanctions list",
"details": { "category": "OFAC_SANCTIONED" }
}
],
"metadata": {
"btc_balance": 0.0,
"total_transactions": 69,
"is_sanctioned": true
},
"ml_anomaly_score": 0.3431,
"scan_duration_ms": 19045,
"cached": false
}risk_scoreは0（安全）〜100（危険）。risk_levelはCRITICAL / HIGH / MEDIUM / LOW / UNKNOWN。
大口UTXOのBitcoinアドレスや取引頻度の高いEVMアドレスは、同期スキャンだとHTTPのタイムアウトに掛かることがあります。その場合はこちらへ。202とジョブIDが即返り、ジョブは永続化されるので処理系の再起動でも消えません。
/public/scan/async{
"success": true,
"job_id": "550e8400-e29b-41d4-a716-446655440000",
"status": "queued",
"address": "0x1234...",
"chain": "ethereum",
"status_url": "/api/v1/public/scan/550e8400-e29b-41d4-a716-446655440000",
"results_url": "/api/v1/public/scan/550e8400-e29b-41d4-a716-446655440000/results",
"message": "Scan queued. Poll status_url until status is 'completed'."
}status_urlをstatusがcompletedになるまでポーリングし、results_urlで結果を取得します。
curl -H "X-API-Key: tfk_your_key_here" \ https://chain-analyzer.com/api/v1/public/scan/550e8400-.../results{
"job_id": "550e8400-e29b-41d4-a716-446655440000",
"score_semantics": "risk_0to100",
"results": [
{
"address": "0x1234...",
"chain": "ethereum",
"status": "completed",
"risk_level": "HIGH",
"risk_score": 78,
"detection_count": 3,
"detections": [],
"metadata": {},
"error_message": null,
"completed_at": "2026-08-13T04:21:07Z"
}
]
}消費クォータは同期スキャンと同じ1件（成功時に1度だけ計上）。バッチ機能が付かないプランでも利用できます。
/public/scan/batchバッチスキャンジョブを投入（Pro: 100件/回・Business: 200件/回・Enterprise: 500件/回）
{
"addresses": [
"DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263",
"0x1234567890123456789012345678901234567890"
],
"include_ai_analysis": true,
"notify_email": "user@example.com"
}{
"success": true,
"job_id": "550e8400-e29b-41d4-a716-446655440000",
"total_addresses": 2,
"message": "Batch scan queued for 2 addresses."
}記録済みスキャンをテナント単位で読み出します。読み取り専用のため月間クォータは消費しません。
curl -H "X-API-Key: tfk_your_key_here" \ "https://chain-analyzer.com/api/v1/public/scans?limit=20&offset=0"プラン上限をクライアント側にハードコードせず、このエンドポイントを参照してください。読み取り専用のため月間クォータは消費しません。-1は無制限を意味します。
/public/usage{
"plan_id": "business",
"scans_per_month": 3000,
"scans_used": 412,
"scans_remaining": 2588,
"topup_remaining": 0,
"period": "2026-08",
"period_reset_at": "2026-09-01T00:00:00Z",
"api_rate_limit_per_min": 120,
"presign_rate_limit_per_min": 480,
"batch_limit": 200,
"watchlist_limit": 100,
"webhook_limit": 5
}アドレスを継続監視し、リスク変化をWebhookで受け取れます。Watchlistの登録数とWebhookのエンドポイント数はプラン上限がサーバー側で強制されます。
| メソッド | パス | 認証 | 説明 |
|---|---|---|---|
| GET | /watchlist | tfk_ | ウォッチリストを取得 |
| POST | /watchlist | tfk_ | アドレスを監視対象に追加 |
| DELETE | /watchlist/{item_id} | tfk_ | 監視対象から削除 |
| POST | /watchlist/{item_id}/rescan | tfk_ | 即時再スキャン（変化検知・通知込み） |
| PATCH | /watchlist/{item_id}/follow | tfk_ | Follow Modeの有効化 / 深度変更（Pro以上・深度はプラン上限に丸め） |
| GET | /watchlist/{item_id}/discoveries | tfk_ | Follow Modeが発見した関連アドレス一覧 |
| GET | /webhooks/configs | tfk_ | Webhook設定一覧 |
| POST | /webhooks/configs | tfk_ | Webhookエンドポイントを登録（署名シークレットは作成時に1度だけ返却） |
| PATCH | /webhooks/configs/{config_id} | tfk_ | Webhook設定の部分更新（URL・購読イベント・有効/無効） |
| DELETE | /webhooks/configs/{config_id} | tfk_ | Webhook設定を削除 |
| POST | /webhooks/test | tfk_ | テスト配信を送信 |
| GET | /webhooks/deliveries | tfk_ | 配信ログを取得（失敗調査用） |
| GET | /webhooks/events | 不要 | 購読可能なイベント一覧（認証不要） |
| イベント | 説明 |
|---|---|
risk.changed | 監視中アドレスのリスクレベルが変化したとき |
risk.high_detected | HIGHリスクを検知したとき |
risk.critical_detected | CRITICALリスクを検知したとき |
scan.completed | スキャンが完了したとき |
batch.completed | バッチジョブが完了したとき |
watchlist.alert | ウォッチリストの一般アラート |
調査ケースの作成・アドレス集約・一括スキャン・統合PDF・エクスポージャー分析・資金フロー探索まで、UIと同じ機能をAPIから呼べます。重い処理（一括スキャン・STRパッケージ生成）は202 + ステータスポーリングです。
| メソッド | パス | 認証 | 説明 |
|---|---|---|---|
| CRUD | /cases | tfk_ | ケースの作成・取得・更新・削除、アドレスとノートの追加/更新/削除 |
| POST | /cases/{case_id}/bulk-scan | tfk_ | ケース内アドレスの一括スキャンを起動（202）／進捗をポーリング |
| GET | /cases/{case_id}/report.pdf | tfk_ | ケース全アドレスの統合PDFレポート |
| POST / GET | /cases/{case_id}/str-package | tfk_ | STR（疑わしい取引の届出）支援パッケージの生成・取得（証跡PDF / ドラフト.docx / 43列CSV） Enterprise |
| GET | /exposure/{address} | tfk_ | 多段エクスポージャー分析（直接・間接をリスク階層別に集計） |
| GET | /exposure/{address}/terminals | tfk_ | 起点アドレスから到達する分類済み終端を経路付きで列挙 Business+ |
| POST | /graph/flow-path | tfk_ | 2アドレス間の有向資金フロー経路 Pro+ |
| POST | /graph/relationship-check | tfk_ | 2アドレスの関連性と共通取引相手 Enterprise |
| POST | /scan/tx | tfk_ | トランザクションハッシュから送信元・宛先を両方スキャン（全12チェーン対応） Enterprise |
| GET | /risk-report/{address} | tfk_ | 単一アドレスのリスク評価レポート（PDF・エクスポージャーとAI要約込み） |
POST /scan/txは8 EVMチェーンに加えてBitcoin・Solana・TRON・XRPでも解決できます（全12チェーン）。tx_hashの形式はチェーン依存で、EVMは0x + 64桁hex、Bitcoin / TRON / XRPは0xなしの64桁hex、Solanaは87〜88文字のbase58です。TRONのTRC-20転送はコントラクトではなくTransferイベントの当事者に解決され、XRPLのPaymentは要求額ではなく実際のdelivered amountを報告します（Payment以外の型は関与アカウントとnoteを返します）。Enterpriseプラン（連携試用枠を含む）限定です。
アドレススキャンでは答えられない「この顧客がこのトークンで先四半期に何をしたか」という照会系の2エンドポイントです。どちらもUTCの期間を明示して呼びます。
| メソッド | パス | 認証 | 説明 |
|---|---|---|---|
| POST | /tx-query | tfk_ | 1アドレス × 1トークンの送受信を期間指定で取得（相手方の集計付き） |
| POST | /contract-alert | tfk_ | トークンコントラクト全体を掃引し、悪性パターンに一致したアドレスを列挙 |
start_date / end_dateは必須です。end_dateはstart_dateより後である必要があり、期間は最大90日です。90日を超えるリクエストは切り詰めではなく400を返します。返却および分析の対象は直近500件が上限なので、それを超える期間は分割して呼んでください。
どちらも読み取り専用で、月間スキャンクォータを消費しません（プランの毎分リクエスト上限は消費します）。
/tx-query指定アドレスが指定トークンで行った送受信を期間内で全件返し、あわせて相手方ごとの集計（件数・金額・ネット）をknown_registryのラベル付きで返します。
{
"address": "TAUN6FwrnwwmaEqYcckffC7wYmbaS6cBiX",
"token_contract": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t",
"chain": "tron",
"start_date": "2026-05-01T00:00:00Z",
"end_date": "2026-07-30T00:00:00Z",
"lang": "en"
}{
"success": true,
"chain": "tron",
"address": "TAUN6FwrnwwmaEqYcckffC7wYmbaS6cBiX",
"token_contract": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t",
"token_symbol": "USDT",
"start_date": "2026-05-01T00:00:00Z",
"end_date": "2026-07-30T00:00:00Z",
"total_transfers": 128,
"transfers": [
{
"tx_hash": "5f2c…",
"block_number": 74210553,
"timestamp": "2026-07-29T11:04:12Z",
"from_address": "TAUN6FwrnwwmaEqYcckffC7wYmbaS6cBiX",
"to_address": "TXLAQ63Xg1NAzckPwKHvzw7CSEmLMEqcdj",
"amount": 24500.0,
"token_symbol": "USDT",
"token_decimals": 6,
"direction": "sent",
"counterparty": "TXLAQ63Xg1NAzckPwKHvzw7CSEmLMEqcdj"
}
],
"counterparties": [
{
"address": "TXLAQ63Xg1NAzckPwKHvzw7CSEmLMEqcdj",
"label": "Unknown",
"category": "unknown",
"sent_count": 12,
"received_count": 3,
"sent_amount": 291400.0,
"received_amount": 18000.0,
"net_amount": -273400.0
}
],
"query_duration_ms": 4187,
"error": null
}クエリ失敗は400 + detailで返るため、200のレスポンスは常にsuccess: true・error: nullです。
/contract-alert/tx-queryの裏返しで、アドレスを指定せずトークンの全転送を掃引し、悪性パターンに一致したアドレスだけを列挙します。発行体が自トークンを定点観測する用途を想定しています。
{
"token_contract": "0xdAC17F958D2ee523a2206206994597C13D831ec7",
"chain": "ethereum",
"start_date": "2026-07-01T00:00:00Z",
"end_date": "2026-07-31T00:00:00Z",
"lang": "en"
}{
"success": true,
"chain": "ethereum",
"token_contract": "0xdAC17F958D2ee523a2206206994597C13D831ec7",
"token_symbol": "USDT",
"start_date": "2026-07-01T00:00:00Z",
"end_date": "2026-07-31T00:00:00Z",
"total_transfers_analyzed": 500,
"flagged_addresses": [
{
"address": "0x1234567890123456789012345678901234567890",
"pattern_type": "address_poisoning",
"severity": "HIGH",
"reason": "Zero-value transfers from an address matching the first and last 4 characters of a real counterparty",
"tx_count": 7,
"total_amount": 0.0,
"sample_tx_hash": "0xabc…"
}
],
"query_duration_ms": 9042,
"error": null
}| pattern_type | 説明 |
|---|---|
known_malicious | レジストリ登録済みの既知悪性アドレス |
address_poisoning | アドレスポイズニング（酷似アドレスによる誤送金誘導） |
relay_chain | 中継チェーン（受領直後にほぼ全額を次へ転送） |
rapid_distribution | 短時間での多数分散 |
large_transfer | 異常な大口転送 |
認証不要の公開OSINT API。IPベースレート制限あり。
| メソッド | パス | 認証 | 説明 |
|---|---|---|---|
| GET | /scamdb/lookup/{address} | 不要 | アドレスがScamDBに登録されているか照合（無料・認証不要） |
| GET | /scamdb/entries | 不要 | 検証済みScamDBエントリー一覧（ページネーション対応） |
| GET | /scamdb/entries/{scam_id} | 不要 | 個別ScamDBエントリーを取得 |
| GET | /scamdb/stats | 不要 | ScamDB統計情報 |
| GET | /scamdb/search?q=... | tfk_ | ScamDB全文検索（tfk_キー必要） |
| POST | /scamdb/report | tfk_ | スキャム報告を送信（tfk_キー必要） |
/scamdb/lookup/{address}curl https://chain-analyzer.com/api/v1/scamdb/lookup/7kMpieh2THdaC5eUvxFJDL3TdsQWVQCwdhsEjLj1eL26{
"found": true,
"entry": {
"id": "SCAM-001",
"address": "7kMpieh2THdaC5eUvxFJDL3TdsQWVQCwdhsEjLj1eL26",
"type": "drainer",
"severity": "danger",
"domains": ["solland.cc", "hibit.app"],
"method": "FCFS airdrop phishing",
"total_stolen_usd": 3700,
"verified": true
},
"match_type": "exact"
}| プラン | リクエスト/分 | 説明 |
|---|---|---|
| Free | 10 | REST API |
| Starter | 30 | REST API |
| Pro | 60 | REST API |
| Business | 120 | REST API |
| Enterprise | 300 | REST API |
| Free / Starter / Pro / Business / Enterprise | 40 / 120 / 240 / 480 / 1200 | 事前スクリーニング（専用枠） |
| Any (IP-based) | 30 | ScamDB reads |
ScamDB読み取り: IPベース30 req/min。レート制限超過時は429エラーが返されます。
| プラン | スキャン/月 |
|---|---|
| Free | 10 |
| Starter | 200 |
| Pro | 1,000 |
| Business | 3,000 |
| Enterprise | Unlimited |
消費するのは実行系のみです。同期スキャン・非同期スキャンは1件、バッチとケース一括スキャンは1アドレス = 1件（成功した分だけ計上）。事前スクリーニング・使用量参照・履歴・レポート取得などの読み取り系は0件です。
| コード | 説明 |
|---|---|
400 | 不正なリクエスト（パラメータエラー） |
401 | 認証エラー（APIキーが無効または未設定） |
403 | アクセス拒否（プランの機能制限） |
404 | リソースが見つからない |
409 | 競合（同じケースのジョブが実行中など） |
410 | 対象が再構築できない（再生成が必要） |
422 | バリデーションエラー（必須フィールド欠落・型不一致） |
429 | レート制限超過、または月間クォータ超過 |
500 | サーバーエラー |
エラーはFastAPI標準の{"detail": "..."}形式です。ステータスごとにクライアント側の取るべき対応が変わります。
X-API-Key（またはAuthorization: Bearer）が無い場合はdetail: "API key required"、キーが失効・無効な場合はdetail: "Invalid API key"。再試行しても回復しません。キーの取り違えとリボークを疑ってください。キーやプランの変更は最大5分で伝播します。
{ "detail": "Invalid API key" }キーは有効だが、その機能が現在のプランに含まれていません。文言は機能ごとに固定です（例: "Transaction-hash scan is an Enterprise feature." / "Batch scanning not available on your plan" / "Watchlist limit reached (100 items)"）。再試行は無意味で、アップグレードまたは登録数の削減が必要です。
{ "detail": "Transaction-hash scan is an Enterprise feature." }存在しないリソース、または他テナント所有のリソースです。両者は区別されません（存在の漏洩を避けるため）。ジョブIDやケースIDの取り違え、保持期間切れを疑ってください。
リクエストボディやパスパラメータの型が合っていません（必須フィールド欠落、UUIDでないscan_idなど）。FastAPIが生成する構造化エラーで、detailは場所と理由を含む配列になります。400と違い、サーバーに届く前段で弾かれています。
{
"detail": [
{
"type": "missing",
"loc": ["body", "token_contract"],
"msg": "Field required"
}
]
}429には性質の異なる2種類があり、ヘッダーの有無で機械的に判別できます。
(a)毎分レート制限 — Retry-Afterあり
detailは "Rate limit exceeded. Max 120 requests per minute."。Retry-After（秒）・X-RateLimit-Limit・X-RateLimit-Remaining: 0が付きます。Retry-Afterに従って待てば必ず回復するので、バックオフして再試行してください。
HTTP/1.1 429 Too Many Requests
Retry-After: 37
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 0
{ "detail": "Rate limit exceeded. Max 120 requests per minute." }(b)月間スキャンクォータ超過 — Retry-Afterなし
detailは残数を含む日本語固定文言です（Accept-Languageやlangによらず日本語で返ります）。Retry-Afterは付きません。翌UTC月まで再試行しても回復しないため、バックオフではなくプランのアップグレードやスキャンパックの購入で解決します。明示リストを送るバッチ系では、残数不足を黙って切り詰めず「残りN件に対してM件の要求」という別文言で返します。
HTTP/1.1 429 Too Many Requests
{
"detail": "月間スキャン上限に達しています（1000 / 1000件）。プランのアップグレード、またはスキャンパックの購入をご検討ください。"
}エラー処理と同じくらい取り違えが多いのがスコアの向きです。risk_score・scoreはいずれも0（安全）〜100（危険）で、大きいほど危険側です。履歴・バッチ・Webhookのペイロードにはscore_semantics: "risk_0to100" が付くので、クライアント側で規約をアサートしてください。
Python、JavaScript、Go用のSDKを準備中です。
© 2026 ChainAnalyzer. All rights reserved.