agent_management/docs/CHAIN_AGENTS_DOC.md

# 链上数据分析 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 时备选 |

### 示例

```bash
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 查询地址余额

### 请求

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

### 参数

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

### 示例

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

### 响应

```json
{
  "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 查询交易记录

### 请求

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

### 参数

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

### 示例

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

### 响应

```json
{
  "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 查询代币信息

### 请求

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

### 参数

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

### 示例

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

### 响应

```json
{
  "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)

### 请求

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

### 参数

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

### 示例

```bash
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"
  }'
```

### 响应

```json
{
  "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 地址活动分析

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

### 请求

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

### 参数

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

### 示例

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

### 响应

```json
{
  "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 交易模式分析

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

### 请求

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

### 参数

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

### 示例

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

### 响应

```json
{
  "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 资金流向分析

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

### 请求

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

### 参数

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

### 示例

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

### 响应

```json
{
  "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 合约交互分析

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

### 请求

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

### 参数

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

### 示例

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

### 响应

```json
{
  "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)

### 请求

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

### 参数

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

### 示例

```bash
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"
  }'
```

### 响应

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

---

## 统一错误格式

### 成功响应

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

### 错误响应

```json
{
  "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 |

---

## 最佳实践

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

---

## 版本历史

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