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,
"scan_duration_ms": 6321,
"cached": false
}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"
}| プラン | リクエスト/分 | 説明 |
|---|---|---|
| Pro | 60 | REST API |
| Business | 120 | REST API |
| Enterprise | 300 | REST API |
| Pro / Business / Enterprise | 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.