Files

T

zhanggangyong ca6a30bdab feat: 添加链上数据分析 Agent

新增两个区块链数据分析 Agent：

1. Chain Explorer Agent - 链上数据查询
   - 查询地址余额
   - 查询交易记录
   - 查询代币信息
   - 智能对话功能

2. Chain Analysis Agent - 链上数据分析
   - 地址活动分析
   - 交易模式分析
   - 资金流向分析
   - 合约交互分析
   - 智能分析对话

支持的区块链：
- Ethereum, BSC, Polygon, Arbitrum, Optimism, Base

使用 Etherscan V2 API，支持通过 Header 传递 API Key

2026-02-05 18:29:56 +00:00

14 KiB

Raw Blame History

链上数据分析 AI Agent 文档

本文档详细介绍了两个链上数据分析 Agent 的功能、API 接口和使用方法。

概述

Agent	功能	端口
Chain Explorer Agent	链上数据查询 - 余额、交易、代币	8000
Chain Analysis Agent	链上数据分析 - 活动分析、交易模式、资金流向	8000

支持的区块链

网络	Chain ID	符号	说明
Ethereum	ethereum	ETH	以太坊主网
BSC	bsc	BNB	币安智能链
Polygon	polygon	POL	Polygon 网络
Arbitrum	arbitrum	ETH	Arbitrum L2
Optimism	optimism	ETH	Optimism L2
Base	base	ETH	Coinbase L2

认证方式

所有 API 调用都需要通过请求头传递 API Key：

Header	说明	必需
`etherscan-key`	Etherscan API Key（区块链浏览器）	✅
`api-key`	备选的区块链浏览器 API Key	⭕
`llm-key`	LLM API Key（用于 Chat 功能）	Chat 时必需
`Authorization`	Bearer Token（LLM API Key）	Chat 时备选

示例

curl -X POST "http://agent-url/balance" \
  -H "Content-Type: application/json" \
  -H "etherscan-key: YOUR_ETHERSCAN_API_KEY" \
  -d '{"address": "0x...", "chain": "ethereum"}'

1. Chain Explorer Agent - 链上数据查询

功能概览

端点	方法	功能
`/`	GET	服务状态
`/health`	GET	健康检查
`/chains`	GET	支持的区块链列表
`/balance`	POST	查询地址余额
`/transactions`	POST	查询交易记录
`/tokens`	POST	查询代币信息
`/chat`	POST	智能对话

1.1 查询地址余额

请求

POST /balance
Content-Type: application/json
etherscan-key: YOUR_API_KEY

参数

参数	类型	必需	默认值	说明
address	string	✅	-	钱包地址 (0x开头)
chain	string	❌	ethereum	区块链网络

示例

curl -X POST "http://localhost:8000/balance" \
  -H "Content-Type: application/json" \
  -H "etherscan-key: F71AZ6XW2WN6GK3D63HJ7AVAEDC9M42EZY" \
  -d '{
    "address": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
    "chain": "ethereum"
  }'

响应

{
  "success": true,
  "address": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
  "chain": "ethereum",
  "chain_name": "Ethereum",
  "balance_wei": "32116130289281011210",
  "balance": 32.11613029,
  "symbol": "ETH",
  "explorer_url": "https://etherscan.io/address/0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
  "timestamp": "2026-02-05T17:00:28.539769"
}

1.2 查询交易记录

请求

POST /transactions
Content-Type: application/json
etherscan-key: YOUR_API_KEY

参数

参数	类型	必需	默认值	说明
address	string	✅	-	钱包地址
chain	string	❌	ethereum	区块链网络
page	int	❌	1	页码
limit	int	❌	10	每页数量 (1-100)

示例

curl -X POST "http://localhost:8000/transactions" \
  -H "Content-Type: application/json" \
  -H "etherscan-key: F71AZ6XW2WN6GK3D63HJ7AVAEDC9M42EZY" \
  -d '{
    "address": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
    "chain": "ethereum",
    "limit": 5
  }'

响应

{
  "success": true,
  "address": "0x...",
  "chain": "ethereum",
  "transactions": [
    {
      "hash": "0x5b0d81bab...",
      "block": "21780123",
      "timestamp": "2026-02-05T13:43:47",
      "from": "0x...",
      "to": "0x...",
      "value": 0.000505,
      "symbol": "ETH",
      "gas_used": "21000",
      "gas_price": "5000000000",
      "is_error": false,
      "tx_url": "https://etherscan.io/tx/0x..."
    }
  ],
  "count": 5,
  "page": 1,
  "timestamp": "2026-02-05T17:00:30.123456"
}

1.3 查询代币信息

请求

POST /tokens
Content-Type: application/json
etherscan-key: YOUR_API_KEY

参数

参数	类型	必需	默认值	说明
address	string	✅	-	钱包地址
chain	string	❌	ethereum	区块链网络

示例

curl -X POST "http://localhost:8000/tokens" \
  -H "Content-Type: application/json" \
  -H "etherscan-key: F71AZ6XW2WN6GK3D63HJ7AVAEDC9M42EZY" \
  -d '{
    "address": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
    "chain": "ethereum"
  }'

响应

{
  "success": true,
  "address": "0x...",
  "chain": "ethereum",
  "tokens": [
    {
      "contract": "0x...",
      "name": "Dogelon",
      "symbol": "ELON",
      "decimals": 18,
      "tx_count": 5
    }
  ],
  "token_count": 49,
  "timestamp": "2026-02-05T17:00:35.123456"
}

1.4 智能对话 (Chat)

请求

POST /chat
Content-Type: application/json
etherscan-key: YOUR_ETHERSCAN_KEY
llm-key: YOUR_LLM_API_KEY

参数

参数	类型	必需	默认值	说明
message	string	✅	-	用户消息（包含地址）
chain	string	❌	ethereum	默认区块链网络

示例

curl -X POST "http://localhost:8000/chat" \
  -H "Content-Type: application/json" \
  -H "etherscan-key: F71AZ6XW2WN6GK3D63HJ7AVAEDC9M42EZY" \
  -H "llm-key: sk-xxx" \
  -d '{
    "message": "帮我查看 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045 的余额和交易",
    "chain": "ethereum"
  }'

响应

{
  "response": "地址 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045 目前的余额为 32.12 ETH...",
  "data": {
    "balance": { ... },
    "recent_transactions": [ ... ],
    "tokens": [ ... ]
  },
  "timestamp": "2026-02-05T17:01:00.123456"
}

2. Chain Analysis Agent - 链上数据分析

功能概览

端点	方法	功能
`/`	GET	服务状态
`/health`	GET	健康检查
`/chains`	GET	支持的区块链列表
`/address-analysis`	POST	地址活动分析
`/transaction-patterns`	POST	交易模式分析
`/fund-flow`	POST	资金流向分析
`/contract-interactions`	POST	合约交互分析
`/chat`	POST	智能分析对话

2.1 地址活动分析

分析指定时间段内的地址活动，包括收支统计、活跃度等。

请求

POST /address-analysis
Content-Type: application/json
etherscan-key: YOUR_API_KEY

参数

参数	类型	必需	默认值	说明
address	string	✅	-	钱包地址
chain	string	❌	ethereum	区块链网络
days	int	❌	30	分析天数 (1-365)

示例

curl -X POST "http://localhost:8000/address-analysis" \
  -H "Content-Type: application/json" \
  -H "etherscan-key: F71AZ6XW2WN6GK3D63HJ7AVAEDC9M42EZY" \
  -d '{
    "address": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
    "chain": "ethereum",
    "days": 30
  }'

响应

{
  "address": "0x...",
  "chain": "ethereum",
  "period_days": 30,
  "summary": {
    "total_sent": 1.0,
    "total_received": 0.004591,
    "net_flow": -0.995409,
    "tx_count_in": 52,
    "tx_count_out": 11,
    "total_tx": 63,
    "failed_tx": 2,
    "unique_addresses": 31,
    "active_days": 18
  },
  "symbol": "ETH",
  "current_balance": 32.11613029,
  "daily_activity": { ... },
  "timestamp": "2026-02-05T17:02:00.123456"
}

2.2 交易模式分析

分析地址的交易行为模式，包括时间分布、金额分布、高频交互对手等。

请求

POST /transaction-patterns
Content-Type: application/json
etherscan-key: YOUR_API_KEY

参数

参数	类型	必需	默认值	说明
address	string	✅	-	钱包地址
chain	string	❌	ethereum	区块链网络

示例

curl -X POST "http://localhost:8000/transaction-patterns" \
  -H "Content-Type: application/json" \
  -H "etherscan-key: F71AZ6XW2WN6GK3D63HJ7AVAEDC9M42EZY" \
  -d '{
    "address": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
    "chain": "ethereum"
  }'

响应

{
  "address": "0x...",
  "chain": "ethereum",
  "patterns": {
    "hourly_distribution": { "0": 5, "14": 20, ... },
    "daily_distribution": { "Monday": 10, "Tuesday": 15, ... },
    "value_distribution": {
      "micro": 198,    // < 0.01 ETH
      "small": 1,      // 0.01 - 0.1 ETH
      "medium": 0,     // 0.1 - 1 ETH
      "large": 1,      // 1 - 10 ETH
      "whale": 0       // > 10 ETH
    },
    "avg_interval_hours": 12.5,
    "top_counterparties": [
      { "address": "0x...", "tx_count": 15 }
    ]
  },
  "behavior_summary": "活跃高峰时段: 14:00 UTC; 以小额交易为主（可能是频繁交易者或机器人）",
  "timestamp": "2026-02-05T17:02:30.123456"
}

2.3 资金流向分析

分析资金来源和去向，识别主要入金/出金地址。

请求

POST /fund-flow
Content-Type: application/json
etherscan-key: YOUR_API_KEY

参数

参数	类型	必需	默认值	说明
address	string	✅	-	钱包地址
chain	string	❌	ethereum	区块链网络
limit	int	❌	100	分析交易数量 (10-500)

示例

curl -X POST "http://localhost:8000/fund-flow" \
  -H "Content-Type: application/json" \
  -H "etherscan-key: F71AZ6XW2WN6GK3D63HJ7AVAEDC9M42EZY" \
  -d '{
    "address": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
    "chain": "ethereum",
    "limit": 100
  }'

响应

{
  "address": "0x...",
  "chain": "ethereum",
  "fund_flow": {
    "total_inflow": 5.234,
    "total_outflow": 3.156,
    "net_flow": 2.078,
    "inflow_sources": 42,
    "outflow_destinations": 8,
    "top_inflow": [
      { "address": "0x...", "amount": 2.5, "symbol": "ETH" }
    ],
    "top_outflow": [
      { "address": "0x...", "amount": 1.0, "symbol": "ETH" }
    ]
  },
  "symbol": "ETH",
  "timestamp": "2026-02-05T17:03:00.123456"
}

2.4 合约交互分析

分析地址与智能合约的交互情况。

请求

POST /contract-interactions
Content-Type: application/json
etherscan-key: YOUR_API_KEY

参数

参数	类型	必需	默认值	说明
address	string	✅	-	钱包地址
chain	string	❌	ethereum	区块链网络

示例

curl -X POST "http://localhost:8000/contract-interactions" \
  -H "Content-Type: application/json" \
  -H "etherscan-key: F71AZ6XW2WN6GK3D63HJ7AVAEDC9M42EZY" \
  -d '{
    "address": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
    "chain": "ethereum"
  }'

响应

{
  "address": "0x...",
  "chain": "ethereum",
  "contract_interactions": {
    "total_contracts": 10,
    "top_contracts": [
      {
        "contract": "0x...",
        "interaction_count": 9,
        "unique_methods": 1,
        "total_value": 0.5,
        "symbol": "ETH",
        "explorer_url": "https://etherscan.io/address/0x..."
      }
    ]
  },
  "timestamp": "2026-02-05T17:03:30.123456"
}

2.5 智能分析对话 (Chat)

请求

POST /chat
Content-Type: application/json
etherscan-key: YOUR_ETHERSCAN_KEY
llm-key: YOUR_LLM_API_KEY

参数

参数	类型	必需	默认值	说明
message	string	✅	-	分析请求（包含地址）
chain	string	❌	ethereum	默认区块链网络

示例

curl -X POST "http://localhost:8000/chat" \
  -H "Content-Type: application/json" \
  -H "etherscan-key: F71AZ6XW2WN6GK3D63HJ7AVAEDC9M42EZY" \
  -H "llm-key: sk-xxx" \
  -d '{
    "message": "分析 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045 是不是巨鲸或机器人",
    "chain": "ethereum"
  }'

响应

{
  "response": "### 地址分析报告\n\n#### 一、基本信息\n- **当前余额**: 32.12 ETH\n...",
  "analysis": {
    "activity": { ... },
    "patterns": { ... },
    "fund_flow": { ... },
    "contracts": { ... },
    "balance": 32.11613029
  },
  "timestamp": "2026-02-05T17:04:00.123456"
}

统一错误格式

成功响应

{
  "success": true,
  "data": { ... },
  "timestamp": "2026-02-05T17:00:00.000000"
}

错误响应

{
  "detail": "错误信息描述"
}

HTTP 状态码

状态码	说明
200	成功
400	请求参数错误
401	未提供 API Key
404	未找到数据
500	服务器错误

部署信息

Agent	镜像地址	端口
Chain Explorer	`agnettaiji.azurecr.io/ai-agents/chain-explorer-agent:latest`	8000
Chain Analysis	`agnettaiji.azurecr.io/ai-agents/chain-analysis-agent:latest`	8000

环境变量

变量	默认值	说明
`SERVICE_HOST`	0.0.0.0	服务绑定地址
`SERVICE_PORT`	8000	服务端口
`LLM_BASE_URL`	https://litellm.xxx	LLM 服务地址
`LLM_MODEL`	taiji/gpt-4o-mini	LLM 模型

测试用地址

地址	说明
`0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045`	Vitalik Buterin
`0xBE0eB53F46cd790Cd13851d5EFf43D12404d33E8`	Binance Cold Wallet
`0x28C6c06298d514Db089934071355E5743bf21d60`	Binance Hot Wallet

最佳实践

API Key 管理：Etherscan API 有速率限制，建议申请付费 API Key
缓存策略：对于不常变化的数据（如历史交易），建议本地缓存
并发控制：避免短时间内大量请求，建议间隔 200ms
多链支持：使用统一的 Etherscan V2 API，通过 chainid 区分网络

版本历史

版本	日期	更新内容
1.0.0	2026-02-05	初始版本，支持 Etherscan V2 API

14 KiB Raw Blame History Unescape Escape

链上数据分析 AI Agent 文档

概述

支持的区块链

认证方式

示例

1. Chain Explorer Agent - 链上数据查询

功能概览

1.1 查询地址余额

请求

参数

示例

响应

1.2 查询交易记录

请求

参数

示例

响应

1.3 查询代币信息

请求

参数

示例

响应

1.4 智能对话 (Chat)

请求

参数

示例

响应

2. Chain Analysis Agent - 链上数据分析

功能概览

2.1 地址活动分析

请求

参数

示例

响应

2.2 交易模式分析

请求

参数

示例

响应

2.3 资金流向分析

请求

参数

示例

响应

2.4 合约交互分析

请求

参数

示例

响应

2.5 智能分析对话 (Chat)

请求

参数

示例

响应

统一错误格式

成功响应

错误响应

HTTP 状态码

部署信息

环境变量

测试用地址

最佳实践

版本历史

14 KiB

Raw Blame History