MistTrack OpenAPI 技能

概述

MistTrack 是由 SlowMist 开发的加密货币反洗钱（AML）追踪工具，专注于打击加密货币洗钱活动。

• 收录超过 4 亿个地址（涵盖主要交易平台的各类钱包）
• 提供 50 万条威胁情报地址
• 标记超过 9000 万个与恶意活动相关的地址

API 基本信息

Base URL

https://openapi.misttrack.io

认证方式

所有请求均需在 Query Parameter 中传入 api_key（GET 请求）或 Request Body（POST 请求）。

通用响应结构

速率限制（Rate Limits）

超出限制时返回：

{"success": false, "msg": "ExceededDailyRateLimit", "retry_after": 12345}
{"success": false, "msg": "ExceededRateLimit", "retry_after": 1}

常见错误码

错误消息（msg 字段）

多链支持

MistTrack 支持以下区块链及代币：

• Bitcoin: BTC
• Ethereum: ETH, USDT-ERC20, USDC-ERC20, WETH-ERC20, PEPE-ERC20, SHIB-ERC20, DAI-ERC20 等
• TRON: TRX, USDT-TRC20, USDC-TRC20, USDD-TRC20
• BNB Smart Chain: BNB, USDT-BEP20, BUSD-BEP20, ETH-BEP20 等
• Polygon: POL-Polygon, USDT-Polygon, USDC-Polygon, WETH-Polygon 等
• Arbitrum One: ETH-Arbitrum, USDT-Arbitrum, USDC-Arbitrum 等
• OP Mainnet: ETH-Optimism, USDT-Optimism, USDC-Optimism 等
• Base: ETH-Base, USDC-Base, USDT-Base 等
• Avalanche: AVAX-Avalanche, USDT-Avalanche, USDC-Avalanche 等
• zkSync Era: ETH-zkSync, ZK-zkSync, USDT-zkSync, USDC-zkSync
• Toncoin: TON, USDT-TON
• Solana: SOL, USDT-Solana, USDC-Solana, Bonk-Solana 等
• Litecoin: LTC
• Dogecoin: DOGE
• Bitcoin Cash: BCH
• Merlin Chain: BTC-Merlin
• HashKey Chain: HSK
• Sui: SUI, wUSDT-SUI, USDC-SUI
• IoTeX: IOTX

完整代币列表请调用 /v1/status 接口获取。

API 端点列表

1. 获取 API 状态 (v1/status)

功能：返回 API 状态及支持的代币列表。

GET https://openapi.misttrack.io/v1/status

请求参数：无

响应示例：

{
  "success": true,
  "msg": "",
  "data": {
    "support_api": ["status", "address_labels", "risk_score", "transactions_investigation", "address_overview", "address_action", "address_trace"],
    "support_coin": ["ETH", "USDT-ERC20", "BTC", "TRX", "USDT-TRC20", "..."]
  }
}

2. 获取地址标签 (v1/address_labels)

功能：返回指定地址的标签列表，包括实体名称、地址类型、链上标签、链下标签等。

GET https://openapi.misttrack.io/v1/address_labels?coin=ETH&address={address}&api_key={api_key}

请求参数：

响应字段：

响应示例：

{
  "success": true,
  "msg": "",
  "data": {
    "label_list": ["Binance", "hot"],
    "label_type": "exchange"
  }
}

3. 获取地址概览 (v1/address_overview)

功能：返回指定地址的余额及统计数据。

GET https://openapi.misttrack.io/v1/address_overview?coin=ETH&address={address}&api_key={api_key}

请求参数：

响应字段：

响应示例：

{
  "success": true,
  "msg": "",
  "data": {
    "balance": 49.8305,
    "txs_count": 1231,
    "first_seen": 1441800674,
    "last_seen": 1670971955,
    "total_received": 916204.8697,
    "total_spent": 916151.0499,
    "received_txs_count": 1018,
    "spent_txs_count": 213
  }
}

4. 获取风险评分 - 同步模式 (v2/risk_score)

功能：返回指定地址或交易哈希的 AML 风险评分及风险详情（KYT/KYA）。

⚠️ 注意：风险评分基于地址的所有相关交易计算，因此同一地址下所有代币会获得相同的评分。

GET https://openapi.misttrack.io/v2/risk_score?coin=ETH&address={address}&api_key={api_key}

请求参数：

address 和 txid 只传其中一个，不能同时传。

响应字段：

risk_detail 子字段：

风险描述（detail_list 可能的值）

风险级别指南

响应示例：

{
  "success": true,
  "msg": "",
  "data": {
    "score": 35,
    "hacking_event": "",
    "detail_list": ["Involved Illicit Activity", "Interact With High-risk Tag Address"],
    "risk_level": "Moderate",
    "risk_detail": [
      {
        "entity": "huionepay",
        "risk_type": "sanctioned_entity",
        "volume": 6700352.55,
        "hop_num": 2,
        "exposure_type": "indirect",
        "percent": 3.419
      }
    ],
    "risk_report_url": "https://light.misttrack.io/riskReport/0x..."
  }
}

5. 获取风险评分 - 异步模式 (v2/risk_score_create_task & v2/risk_score_query_task)

功能：以异步方式获取地址或交易的风险评分（适用于大批量查询场景）。

5.1 创建任务 (v2/risk_score_create_task)

POST https://openapi.misttrack.io/v2/risk_score_create_task
Content-Type: application/json

请求 Body：

cURL 示例：

curl --location 'https://openapi.misttrack.io/v2/risk_score_create_task' \
  --header 'Content-Type: application/json' \
  --data '{
    "address": "TNXoiAJ3dct8Fjg4M9fkLFh9S2v9TXc32G",
    "coin": "TRX",
    "api_key": "YourApiKey"
  }'

响应字段：

• Cache Miss（has_result: false）：等待 1-10 秒后调用 v2/risk_score_query_task
• Cache Hit（has_result: true）：立即调用 v2/risk_score_query_task

5.2 查询任务结果 (v2/risk_score_query_task)

⚠️ 此接口无速率限制。

GET https://openapi.misttrack.io/v2/risk_score_query_task?coin=ETH&address={address}&api_key={api_key}

请求参数：与创建任务接口相同。

响应：

• 任务未完成：{"success": true, "msg": "TaskUnderRunning"}
• 任务完成：与同步 v2/risk_score 响应结构相同（含 score、risk_level、detail_list、risk_detail）

6. 交易调查 (v1/transactions_investigation)

功能：返回指定地址的交易调查结果，包含转入/转出交易列表及关联地址信息。

GET https://openapi.misttrack.io/v1/transactions_investigation?coin=ETH&address={address}&api_key={api_key}

请求参数：

响应字段：

交易条目子字段：

响应示例：

{
  "success": true,
  "msg": "",
  "data": {
    "out": [
      {
        "address": "0xd90e2f925da726b50c4ed8d0fb90ad053324f31b",
        "tx_hash_list": ["0x48c2601b..."],
        "amount": 743,
        "type": 3,
        "label": "Tornado.Cash: Router"
      }
    ],
    "in": [...],
    "page": 1,
    "total_pages": 1,
    "transactions_on_page": 36
  }
}

7. 地址行为分析 (v1/address_action)

功能：返回指定地址的交易行为分析结果（适合以饼图方式展示）。

GET https://openapi.misttrack.io/v1/address_action?coin=ETH&address={address}&api_key={api_key}

请求参数：

响应字段：

行为条目子字段：

响应示例：

{
  "success": true,
  "msg": "",
  "action_dic": {
    "received_txs": [
      {"action": "DEX", "count": 7, "proportion": 70.0},
      {"action": "Mixer", "count": 1, "proportion": 10.0},
      {"action": "Exchange", "count": 1, "proportion": 10.0},
      {"action": "Swap", "count": 1, "proportion": 10.0}
    ],
    "spent_txs": [
      {"action": "Exchange", "count": 15, "proportion": 57.69},
      {"action": "DEX", "count": 2, "proportion": 7.69},
      {"action": "Transfer", "count": 9, "proportion": 34.62}
    ]
  }
}

8. 地址画像 / 地址追踪 (v1/address_trace)

功能：追踪地址与哪些平台有过交互（交易所、混币器、DeFi 协议、NFT 平台），识别相关恶意事件，并提供地址附加信息（使用的钱包、ENS 名称、关联 Twitter 账号）。

GET https://openapi.misttrack.io/v1/address_trace?coin=ETH&address={address}&api_key={api_key}

请求参数：

响应字段：

响应示例：

{
  "success": true,
  "msg": "",
  "data": {
    "first_address": "sideshift.ai",
    "use_platform": {
      "exchange": {"count": 1, "exchange_list": ["Binance"]},
      "dex": {"count": 3, "dex_list": ["Uniswap", "SushiSwap", "Multichain"]},
      "mixer": {"count": 2, "mixer_list": ["Tornado.Cash", "sideshift.ai"]},
      "nft": {"count": 0, "nft_list": []}
    },
    "malicious_event": {
      "phishing": {"count": 0, "phishing_list": []},
      "ransom": {"count": 0, "ransom_list": []},
      "stealing": {"count": 5, "stealing_list": ["MMFinance Exploiter"]},
      "laundering": {"count": 0, "laundering_list": []}
    },
    "relation_info": {
      "wallet": {"count": 0, "wallet_list": []},
      "ens": {"count": 2, "ens_list": ["destruction.eth", "poma.eth"]},
      "twitter": {"count": 1, "twitter_list": ["@destructioneth"]}
    }
  }
}

9. 地址交易对手分析 (v1/address_counterparty)

功能：返回指定地址的交易对手分析结果（适合以饼图方式展示）。

⚠️ 注意：此接口不支持分析热钱包地址，会返回 UnsupportedAddressType 错误。

GET https://openapi.misttrack.io/v1/address_counterparty?coin=ETH&address={address}&api_key={api_key}

请求参数：

响应字段：

交易对手条目子字段：

响应示例：

{
  "success": true,
  "msg": "",
  "address_counterparty_list": [
    {"name": "Uniswap", "amount": 4496524.699, "percent": 49.678},
    {"name": "Tornado.Cash", "amount": 2377637.58, "percent": 26.268},
    {"name": "Binance", "amount": 302.008, "percent": 0.003}
  ]
}

使用示例

场景 1：快速地址风险检测（KYT）

当需要对提币/充值地址进行快速 AML 检查时：

1. 调用 v2/risk_score 获取风险评分
2. 根据 risk_level 决策：
   • Severe (91-100)：拒绝交易并上报
   • High (71-90)：需人工复核
   • Moderate (31-70)：适度监控
   • Low (0-30)：正常放行

场景 2：批量异步风险检测

当需要批量检测大量地址时使用异步模式：

1. 循环调用 POST v2/risk_score_create_task 创建任务
2. 等待 1-10 秒（如 has_result: false）
3. 调用 GET v2/risk_score_query_task 轮询结果（无速率限制）

场景 3：地址完整画像调查

对可疑地址进行全面调查时，建议依次调用：

1. v1/address_labels → 了解地址实体身份
2. v1/address_overview → 了解地址活跃度和资产规模
3. v2/risk_score → 获取 AML 风险评分
4. v1/address_trace → 了解地址平台交互历史及关联信息
5. v1/transactions_investigation → 深入分析具体交易流向
6. v1/address_counterparty → 分析主要交易对手构成

示例脚本

参考 scripts/ 目录中的示例脚本：

• risk_check.py - 单地址风险评分检查
• batch_risk_check.py - 批量异步风险评分
• address_investigation.py - 地址完整调查

与 Bitget Wallet Skill 集成 — 转账地址安全检测

适用场景：当 Agent 同时加载了 bitget-wallet-skill 和 misttrack-skills 时，在执行任何转账 / Swap 操作前，必须自动调用本技能对目标地址（recipient / to-address） 进行 AML 风险检测。

为什么需要地址级安全检测？

bitget-wallet-skill 的 Pre-Trade Workflow 已覆盖代币安全（蜜罐、税率、流动性），但未检测收款方地址的 AML 风险。向被制裁地址、混币器出金地址或黑客钱包转账可能导致：

• 资产被链上追踪机构标记
• 触犯 OFAC 制裁合规要求
• 资金被交易所冻结（如目标是洗钱中转地址）

misttrack-skills 专门填补这一缺口。

链代码映射表

将 bitget-wallet-skill 的 chain 参数映射为 MistTrack coin 参数：

稳定币注意：若转账代币为 USDT/USDC（非原生代币），MistTrack 风险评分对地址是全局计算的（与代币无关），因此使用原生代币的 coin 参数查询即可。

决策逻辑

特例 — 已认证白名单地址：若 v1/address_labels 返回的 label_type 为 exchange（如 Binance、Coinbase 充值地址），且 risk_level 为 Low 或 Moderate，可直接 ALLOW，无需二次确认。

Agent 集成工作流

Agent 在执行 swap-calldata 或任何转账指令之前，自动执行以下步骤（对用户透明，不中断流程）：

转账安全检测流程（Agent 后台自动执行）：

1. 提取目标地址（swap --to-address 或用户指定的收款地址）
2. 识别链类型（通过上方映射表 chain → coin）
3. 调用风险评分脚本：
   python3 scripts/transfer_security_check.py --address <to_address> --chain <chain_code>

4. 读取 exit code 和 JSON 输出，按决策逻辑处理：
   - exit 0 (ALLOW)  → 静默继续，在最终确认摘要中显示 "✅ 收款地址安全"
   - exit 1 (WARN)   → 暂停，向用户显示风险摘要，等待用户明确确认
   - exit 2 (BLOCK)  → 终止流程，向用户说明原因，建议放弃转账
   - exit 3 (ERROR)  → API 不可用，显示 "⚠️ 地址安全检测失败（原因：...）"，由用户决定是否继续

集成到 bitget-wallet-skill Pre-Trade Workflow

在原有 bitget-wallet-skill 的 Pre-Trade Workflow 基础上，插入第 0 步：

0. transfer-security  → 检测收款地址 AML 风险（新增，使用 misttrack-skills）
1. security           → 检查代币安全（honeypot、tax）
2. token-info         → 获取价格、市值
3. liquidity          → 检查池深度
4. swap-quote         → 获取报价和路由

调用示例

基础调用（推荐 Agent 使用）

# ETH 链地址检测
python3 scripts/transfer_security_check.py \
  --address 0xd90e2f925DA726b50C4Ed8D0Fb90Ad053324F31b \
  --chain eth

# Solana 链地址检测
python3 scripts/transfer_security_check.py \
  --address 5tzFkiKscXHK5B17AoKFdroMRCEVGvSqtPkRSLzprFwN \
  --chain sol

# JSON 输出（便于 Agent 解析）
python3 scripts/transfer_security_check.py \
  --address 0x28C6c06298d514Db089934071355E5743bf21d60 \
  --chain eth --json

JSON 输出格式

{
  "decision": "ALLOW",
  "score": 15,
  "risk_level": "Low",
  "detail_list": [],
  "label_type": "exchange",
  "label_list": ["Binance", "hot"],
  "risk_report_url": "https://light.misttrack.io/riskReport/0x...",
  "address": "0x28C6c06298d514Db089934071355E5743bf21d60",
  "coin": "ETH",
  "chain": "eth"
}

WARN 场景示例输出（展示给用户）

⚠️  收款地址安全警告
────────────────────────────────────
地址：    0xABCD...1234
链：      ETH
风险评分：55 (Moderate)
风险描述：Interact With High-risk Tag Address, Involved Illicit Activity
风险报告：https://light.misttrack.io/riskReport/0xABCD...

建议：该地址存在中等风险，请确认收款方身份后再继续。
是否仍要继续转账？[yes/no]

API 不可用时的降级策略

重要：任何 exit 3 情况下，Agent 必须明确告知用户「地址安全检测失败，无法验证收款地址风险」，并让用户决定是否继续。不得静默忽略检测失败。

与 Trust Wallet Skills 集成 — 转账地址安全检测

适用场景：当 Agent 同时加载了 tw-agent-skills（wallet-core 或 trust-web3-provider）和 misttrack-skills 时，在生成任何含收款地址的代码之前，必须自动调用本技能进行 AML 风险检测。

Trust Wallet Skills 的转账场景

Trust Wallet skills 是开发者库（非命令行工具），收款地址通过代码字段传入：

CoinType → MistTrack coin 映射表

trust-web3-provider 链映射：EthereumProvider chainId 0x1→eth，0x38→bnb，0x89→polygon，0xa→optimism，0xa4b1→arbitrum，0x2105→base。

Agent 触发规则

Agent 在以下任意时刻应自动调用安全检测：

wallet-core 场景

当 Agent 生成含 toAddress 的签名代码片段时，在给出代码前先检查该地址：

# 示例：用户请求为 Bitcoin 地址生成签名，先检查目标地址
python3 scripts/transfer_security_check.py \
  --address 1MityqAKBEKHPkBpwDCqPMBNbYPxbNbKzr \
  --chain bitcoin --json

# 示例：用户构建 Ethereum 转账，先检查 toAddress
python3 scripts/transfer_security_check.py \
  --address 0xRecipient... \
  --chain eth --json

trust-web3-provider 场景

当 Agent 帮开发者实现处理 eth_sendTransaction / ton_sendTransaction 的 handler 时，在处理逻辑中插入检测点：

# Handler 收到 eth_sendTransaction，目标地址在 params.to
python3 scripts/transfer_security_check.py \
  --address <params.to> --chain eth --json

# Handler 收到 ton_sendTransaction
python3 scripts/transfer_security_check.py \
  --address <params.to> --chain ton --json

决策规则（与 Bitget Wallet 集成相同）

不支持的链处理

Aptos 和 Cosmos/ATOM 目前 MistTrack 尚未收录，脚本会返回 exit 3 并给出说明：

$ python3 scripts/transfer_security_check.py --address 0xabc --chain aptos --json
{
  "decision": "ERROR",
  "error": "MistTrack 暂不支持 Aptos (APT) 链地址查询。请人工核实收款方身份。"
}
# exit code: 3

Agent 对此类 exit 3 应向用户说明「该链暂无自动安全检测，请通过其他方式核实收款方身份」。

参考资料

• MistTrack 官方文档
• MistTrack OpenAPI 概述
• MistTrack 控制台
• 常见错误消息
• Bitget Wallet Skill
• Trust Wallet tw-agent-skills