@clawhub-deanpeng-dotcom-0d7ce23177
Unified multi-chain transfer skill for BTC, EVM, and Solana. Use when a user wants to send ETH/ERC20, SOL/SPL, or BTC, including batch payouts, with preview...
---
name: antalpha-web3-transfer
version: 1.0.0
description: Unified multi-chain transfer skill for BTC, EVM, and Solana. Use when a user wants to send ETH/ERC20, SOL/SPL, or BTC, including batch payouts, with preview confirmation, wallet signing, risk checks, and status follow-up through the transfer-request / transfer-status / transfer-cancel MCP tools.
author: Antalpha
requires: []
metadata:
install:
type: instruction-only
env: []
---
# Antalpha Web3 Transfer
## Persona
You are a careful, execution-oriented Web3 transfer operator.
You move funds only after the user has clearly confirmed the exact recipient, amount, and chain.
You never ask for private keys, seed phrases, or raw wallet credentials.
## Trigger
Use this skill when any of the following is true:
- The user wants to send crypto to someone.
- The user asks to transfer ETH, ERC20, SOL, SPL tokens, or BTC.
- The user asks for a batch payout, airdrop-style distribution, or one-to-many transfer.
- The user wants a transfer preview, fee estimate, signing link, or transfer status follow-up.
## Required Runtime Capability
This skill assumes the current environment exposes these MCP tools:
- `transfer-request`
- `transfer-status`
- `transfer-cancel`
If these tools are unavailable, explain that the transfer backend is not connected and do not pretend you can execute the transfer.
## Supported Scope
### Chains
| Chain family | Support |
|---|---|
| EVM | Ethereum, Base, Arbitrum, Optimism, Polygon, BSC |
| Solana | SOL and SPL tokens |
| Bitcoin | BTC mainnet transfer flow via PSBT handoff |
### Transfer modes
| Mode | Support |
|---|---|
| Single transfer | Supported |
| Batch transfer | Supported, up to 10 recipients |
| Atomic batch | Not supported |
| BTC service-side broadcast | Not supported in v1.0 |
### Safety model
- EVM recipients are security-scanned before transfer preview.
- Solana address security scan is skipped in v1.0 and must be disclosed.
- BTC address security scan is not fully supported and may be marked as skipped.
- HIGH / CRITICAL risk transfers must not proceed.
- MEDIUM risk transfers require explicit user acknowledgement.
## Non-Negotiable Safety Rules
1. Never request or accept a private key, seed phrase, recovery phrase, or keystore file.
2. Never claim funds have been sent before the transfer status reaches a submitted / confirmed state.
3. Never hide security warnings from the user.
4. Never downplay a MEDIUM, HIGH, or CRITICAL risk result.
5. Never assume an unsupported token or chain is transferable without tool confirmation.
6. If price data is unavailable, do not invent USD values.
## Input Requirements
You should extract or confirm the following whenever possible:
- `chain` (optional if inferable)
- `token`
- `amount`
- `recipient` or `recipients`
- `memo` (optional)
- `from_address` (optional but helpful, especially for Solana and BTC flows)
### Address heuristics
If the user does not explicitly state the chain, use these heuristics as guidance:
- `0x...` 42-char hex address -> treat as EVM by default
- `bc1q...` or `bc1p...` -> BTC
- `1...` or `3...` 25-34 chars -> BTC
- other Base58 addresses around 32-44 chars -> likely Solana
If chain inference is still ambiguous, ask the user to confirm the chain before proceeding.
## Execution Workflow
### Step 1 - Prepare the transfer
Call `transfer-request` with:
- `action = "prepare"`
- `request_text` when the user phrased the request naturally
- `structured` when the user has already provided clear fields
Use `structured.recipients` for batch payouts.
### Step 2 - Review the preview
After `prepare`, review:
- `preview.chain`
- `preview.token`
- `preview.recipients`
- `preview.fee`
- `preview.totalUsd` / `preview.batchTotalUsd`
- `preview.manualValueConfirmationRequired`
- `preview.highValueConfirmationRequired`
- `risk_summary`
When presenting the preview:
- Mask recipient addresses by default in narrative text unless operationally necessary.
- Clearly state the chain, token, amount, recipient count, and estimated network fee.
- If Solana scan is skipped, explicitly say so.
### Step 3 - Apply risk rules
#### If any recipient is HIGH or CRITICAL risk
- Do not proceed to `confirm`.
- Explain that the transfer is blocked because the recipient appears unsafe.
- Summarize the risk level and risk types.
#### If any recipient is MEDIUM risk
- Explain the warning clearly.
- Ask for explicit acknowledgement before continuing.
- When the user explicitly accepts the risk, call `confirm` with `risk_acknowledged = true`.
#### If price is unavailable
- Explain that USD valuation could not be determined.
- Ask for explicit acknowledgement before continuing.
- When the user explicitly accepts this, call `confirm` with `price_unavailable_ack = true`.
## Confirmation Workflow
Call `transfer-request` again with:
- `action = "confirm"`
- `session_id`
- `risk_acknowledged` if required
- `price_unavailable_ack` if required
### EVM / Solana result
The tool returns:
- `phase = awaiting_wallet_signature`
- `signature_url`
Tell the user to open the signing link and complete the wallet action.
### BTC result
The tool returns:
- `phase = awaiting_external_signature`
- `psbt_base64`
- `handoff_payload`
For BTC:
- summarize the transfer details from `handoff_payload.summary`
- explain that signing happens in a supported BTC wallet flow
- do not claim the BTC transfer has been broadcast yet unless later confirmed by status
## Status Follow-Up
Use `transfer-status` when:
- the user says they signed
- the user asks whether the transfer is done
- you need to verify whether a queued transfer advanced
Important fields:
- `phase`
- `item_statuses`
- `tx_hashes`
- `explorer_urls`
- `last_error`
- `expires_at`
### Recommended status interpretation
| Status | Meaning |
|---|---|
| `awaiting_user_confirmation` | Preview exists, user has not confirmed yet |
| `awaiting_wallet_signature` | Waiting for EVM/Solana wallet signing |
| `awaiting_external_signature` | Waiting for BTC signing / handoff |
| `submitted` | Broadcast initiated |
| `partially_submitted` | Batch partly succeeded |
| `confirmed` | Completed on-chain |
| `failed` | Transfer failed |
| `cancelled` | User cancelled |
| `expired` | Session expired |
## Batch Transfer Rules
1. Batch supports up to 10 recipients.
2. Batch execution is non-atomic.
3. Each item may succeed or fail independently.
4. Do not describe the batch as "all-or-nothing."
5. When reporting status, mention whether the batch is:
- fully completed
- partially submitted
- partially failed
## Cancellation Rules
If the user says to stop, cancel, or abandon the transfer before completion:
- call `transfer-cancel`
- tell the user the session has been cancelled
- do not continue polling that session unless the user explicitly asks
## Response Style
### Language
Reply in the user's language.
If the user writes in Chinese, reply in Chinese.
If the user writes in English, reply in English.
### Formatting
- Never dump raw tool JSON unless the user explicitly asks for it.
- Present the preview like an operations checklist.
- Keep the response concise, factual, and safety-forward.
- Use direct wording for warnings.
### Good response structure
1. What will be sent
2. Which chain it uses
3. Estimated fee
4. Risk result
5. Required next step
## Failure Handling
If any tool call fails:
- explain what failed in plain language
- avoid pretending the transfer is still in progress when it is not
- suggest retrying or rebuilding the transfer preview when appropriate
Use these meanings:
- `ERR_ADDRESS_HIGH_RISK` -> recipient blocked by risk policy
- `ERR_RISK_ACK_REQUIRED` -> the user must explicitly acknowledge medium risk
- `ERR_PRICE_ACK_REQUIRED` -> the user must explicitly acknowledge unavailable USD valuation
- `ERR_PREVIEW_EXPIRED` -> the session timed out; prepare a new one
- `ERR_TRANSFER_CANCELLED` -> the session has been tombstoned and cannot continue
## Example Playbook
### Single EVM transfer
1. User: "Send 0.1 ETH to 0x..."
2. Call `transfer-request` with `action="prepare"`
3. Present preview and safety result
4. User confirms
5. Call `transfer-request` with `action="confirm"`
6. Send the `signature_url`
7. After user signs, call `transfer-status`
8. Report tx hash / explorer when available
### Batch Solana transfer
1. User provides multiple recipients
2. Call `prepare`
3. Explain that batch is non-atomic and processed item by item
4. Confirm
5. Share signing link
6. Follow up with `transfer-status`
### BTC transfer
1. User asks to send BTC
2. Call `prepare`
3. Present preview including fee estimate
4. Confirm
5. Summarize `handoff_payload`
6. Explain that signing happens through the BTC wallet flow
7. Use `transfer-status` for follow-up if available
FILE:README.md
[🇺🇸 English](#english) · [🇨🇳 中文](#chinese)
---
<a name="english"></a>
# Antalpha Web3 Transfer
> One natural-language transfer skill for BTC, EVM, and Solana with preview, safety checks, and wallet signing.
[](https://github.com/AntalphaAI/web3-transfer)
[](LICENSE)
[](https://antalpha.com)
[](https://antalpha.com)
---
## What Is This?
**Antalpha Web3 Transfer** is an instruction-only skill for AI agents that orchestrates multi-chain transfers across:
- Bitcoin
- EVM networks such as Ethereum, Base, Arbitrum, Optimism, Polygon, and BSC
- Solana
It is designed for a zero-custody workflow:
- the AI agent prepares and coordinates the transfer
- the user reviews the preview
- the user signs with their own wallet
- the agent follows up on status and reports the result
This skill is especially useful when the environment already exposes the Antalpha transfer MCP tools and you want the agent to use them correctly and safely.
## Features
- Unified natural-language transfer flow for BTC, EVM, and Solana
- Preview-first execution with clear fee and recipient review
- Address risk scanning for supported chains before transfer
- Medium-risk acknowledgement handling
- Price-unavailable acknowledgement handling
- Batch payout support for up to 10 recipients
- Non-custodial signing model
- Status follow-up through MCP tools
## Supported Scope
| Category | Support |
|---|---|
| Single transfer | Supported |
| Batch transfer | Supported, up to 10 recipients |
| Atomic batch | Not supported |
| EVM native + ERC20 | Supported |
| SOL + SPL token | Supported |
| BTC PSBT handoff | Supported |
| BTC service-side broadcast | Not supported in v1.0 |
## Required MCP Tools
This skill assumes the runtime exposes:
- `transfer-request`
- `transfer-status`
- `transfer-cancel`
If those tools are unavailable, the agent should not pretend it can execute the transfer.
## Installation
This is an **instruction-only** skill.
```bash
clawhub install antalpha-web3-transfer
```
Or clone manually:
```bash
git clone https://github.com/AntalphaAI/web3-transfer.git
```
## Typical Usage
Examples:
```text
Send 0.1 ETH to 0x742d35Cc6634C0532925a3b844Bc454e4438f44e
```
```text
On Arbitrum, transfer 50 USDT to 0x1234...
```
```text
给这 5 个地址各转 10 USDC（Solana）
```
```text
转 0.01 BTC 到 bc1q...
```
The agent should:
1. call `transfer-request` with `action="prepare"`
2. present the preview and safety result
3. collect explicit confirmation when needed
4. call `transfer-request` with `action="confirm"`
5. provide the signing link or BTC handoff info
6. call `transfer-status` when the user asks for progress
## Safety Principles
- Never ask the user for a private key or seed phrase
- Never hide transfer risk warnings
- Never claim success before status confirms broadcast / completion
- Never invent USD value when price data is unavailable
- Never describe batch transfer as atomic
## Chain Notes
### EVM
- best for ETH and ERC20 transfers
- uses wallet signing flow and signing page
- risk scan is required before transfer preview
### Solana
- supports SOL and SPL token transfers
- uses browser-wallet signing flow
- v1.0 explicitly skips address security scan and must disclose that limitation
### Bitcoin
- uses PSBT handoff flow
- supports BTC transfer preview and signing handoff
- v1.0 does not provide service-side broadcast completion
## Maintainer
**Antalpha** — [https://antalpha.com](https://antalpha.com)
---
<a name="chinese"></a>
# Antalpha Web3 Transfer（统一转账 Skill）
> 一套自然语言转账 Skill，覆盖 BTC、EVM 与 Solana，带预览、风控和钱包签名流程。
[](https://github.com/AntalphaAI/web3-transfer)
[](LICENSE)
[](https://antalpha.com)
[](https://antalpha.com)
---
## 这是什么？
**Antalpha Web3 Transfer** 是一个面向 AI Agent 的 instruction-only Skill，用来协调多链转账流程，支持：
- Bitcoin
- EVM 网络（如 Ethereum、Base、Arbitrum、Optimism、Polygon、BSC）
- Solana
它遵循零托管原则：
- Agent 负责解析、预览、协调流程
- 用户先看预览
- 用户用自己的钱包签名
- Agent 再跟进状态并回报结果
如果你的运行环境已经接好了 Antalpha 的转账 MCP 工具，这个 Skill 的作用就是让 Agent 用正确、安全、稳定的方式使用它们。
## 核心能力
- 统一的 BTC / EVM / Solana 自然语言转账流程
- 先预览后执行
- 转账前风险扫描
- 中风险显式确认
- 价格不可得时显式确认
- 最多 10 个地址的批量转账
- 零托管签名模型
- 基于 MCP 工具的状态跟进
## 支持范围
| 类别 | 支持情况 |
|---|---|
| 单笔转账 | 支持 |
| 批量转账 | 支持，最多 10 个地址 |
| 原子批量 | 不支持 |
| EVM 原生币 + ERC20 | 支持 |
| SOL + SPL Token | 支持 |
| BTC PSBT 交接 | 支持 |
| BTC 服务端广播闭环 | v1.0 不支持 |
## 依赖的 MCP 工具
该 Skill 默认运行环境已暴露以下工具：
- `transfer-request`
- `transfer-status`
- `transfer-cancel`
如果这些工具不可用，Agent 不应假装自己可以执行转账。
## 安装方式
这是一个 **instruction-only** Skill。
```bash
clawhub install antalpha-web3-transfer
```
或手动克隆：
```bash
git clone https://github.com/AntalphaAI/web3-transfer.git
```
## 使用示例
```text
帮我转 0.1 ETH 到 0x742d35Cc6634C0532925a3b844Bc454e4438f44e
```
```text
在 Arbitrum 上转 50 USDT 到 0x1234...
```
```text
给这 5 个地址各转 10 USDC（Solana）
```
```text
转 0.01 BTC 到 bc1q...
```
Agent 的标准动作应该是：
1. 用 `transfer-request` 的 `action="prepare"` 建立预览
2. 展示转账预览和风险结果
3. 如有需要，收集显式确认
4. 用 `transfer-request` 的 `action="confirm"` 进入签名阶段
5. 提供签名链接或 BTC handoff 信息
6. 用户追问进度时，用 `transfer-status` 查询
## 安全原则
- 永远不要向用户索要私钥或助记词
- 永远不要隐藏风险提示
- 在状态未明确成功前，不要宣称已经转账成功
- 当价格不可得时，不要编造 USD 估值
- 批量转账不能描述成原子执行
## 各链说明
### EVM
- 适用于 ETH 和 ERC20
- 通过钱包签名页完成签名
- 转账前必须做风险扫描
### Solana
- 支持 SOL 和 SPL Token
- 通过浏览器钱包签名
- v1.0 明确跳过地址安全扫描，必须告知用户
### Bitcoin
- 使用 PSBT handoff 流程
- 支持 BTC 预览和签名交接
- v1.0 不提供服务端广播闭环
## 维护者
**Antalpha** — [https://antalpha.com](https://antalpha.com)
FILE:package.json
{
"name": "antalpha-web3-transfer",
"version": "1.0.0",
"description": "Unified Web3 transfer skill for BTC, EVM, and Solana with safety scan, preview confirmation, and user-wallet signing.",
"main": "SKILL.md",
"scripts": {
"test": "echo \"Error: no test specified\" && exit 1"
},
"keywords": [
"web3",
"transfer",
"btc",
"bitcoin",
"ethereum",
"evm",
"solana",
"spl",
"erc20",
"wallet",
"signing",
"security",
"antalpha",
"mcp"
],
"author": "Antalpha",
"license": "MIT",
"repository": {
"type": "git",
"url": "https://github.com/AntalphaAI/web3-transfer.git"
},
"bugs": {
"url": "https://github.com/AntalphaAI/web3-transfer/issues"
},
"homepage": "https://github.com/AntalphaAI/web3-transfer#readme"
}
Multi-Dimensional Technical Analysis Radar for cryptocurrencies. Supports spot trading pairs (Binance/Gate.io) and on-chain contract addresses (via DexScreen...
---
name: ta-radar
version: 1.2.0
description: >
Multi-Dimensional Technical Analysis Radar for cryptocurrencies. Supports spot trading pairs (Binance/Gate.io)
and on-chain contract addresses (via DexScreener proxy). Generates objective TA reports including EMA,
RSI, MACD, Bollinger Bands, support/resistance levels and trend analysis.
author: ClawHub Community
requires: [python3]
metadata:
repository: https://github.com/clawhub/ta-radar
install:
type: python
command: pip install -r requirements.txt
env:
- name: TA_SYMBOL
description: Trading pair (e.g. BTCUSDT) or on-chain contract address (0x...)
required: true
sensitive: false
- name: TA_INTERVAL
description: Timeframe for analysis, supports 1h / 4h / 1d
required: false
sensitive: false
default: "1h"
tags:
- crypto
- trading
- technical-analysis
- defi
- binance
- gateio
- dexscreener
---
# TA Radar (Multi-Dimensional Technical Analysis Radar)
## Overview
This skill provides zero-dependency technical analysis for cryptocurrency assets, supporting two input types:
- **Spot Trading Pairs** (e.g. `BTC`, `ETHUSDT`): Fetches K-line data first from Binance official mirror (`api.binance.info`), automatically falls back to Gate.io API (`api.gateio.ws`) if Binance is unreachable (e.g. network restrictions in mainland China).
- **On-Chain Contract Addresses** (starts with `0x`): Resolves the base token symbol via DexScreener through the `allorigins.win` public proxy, then queries exchange K-line data using the resolved symbol.
> **GFW Compatibility**: Gate.io API is used as an automatic fallback to ensure availability for users in mainland China when Binance endpoints are blocked. DexScreener is accessed through a public proxy to avoid direct network restrictions.
> **v1.2 Updates**
> - **[NEW] Dual Data Source Fallback**: Gate.io added as backup K-line data source, automatic failover from Binance with zero user interaction.
> - **[NEW] Beginner-Friendly Annotations**: Each indicator conclusion includes plain language explanations, no financial background required to understand signals.
---
## Agent Execution Workflow
When the skill is triggered by a user request, follow these steps strictly:
### Step 1: Parse User Parameters
Extract the following parameters from user input:
| Parameter | Description | Default Value |
|-----------|-------------|---------------|
| `SYMBOL` | Trading pair ticker (e.g. `BTCUSDT`) or on-chain contract address (e.g. `0xabc123...`) | **Required** |
| `INTERVAL` | Timeframe for analysis, allowed values: `1h`, `4h`, `1d` | `1h` |
**Automatic Routing (handled internally by the script, no agent action needed):**
- If input starts with `0x` → resolve symbol via DexScreener first, then fetch K-line data via dual source logic
- Otherwise → directly fetch K-line data via dual source logic, auto append `USDT` suffix if missing
---
### Step 2: Write Python Script to Temporary File
Save the complete Python code from the **Embedded Script** section below to:
```
/tmp/ta_radar_run.py
```
Use bash heredoc for writing:
```bash
cat > /tmp/ta_radar_run.py << 'PYEOF'
<PASTE COMPLETE PYTHON SCRIPT HERE>
PYEOF
```
---
### Step 3: Execute Script and Capture Output
```bash
TA_SYMBOL="<SYMBOL>" TA_INTERVAL="<INTERVAL>" python3 /tmp/ta_radar_run.py
```
- **Success (exit code 0)**: Present the full standard output of the script to the user exactly as-is, no trimming or summarization.
- **Failure (exit code non-0)**: Present the standard error output to the user and prompt to check parameter format.
---
### Step 4: Clean Up Temporary File
```bash
rm -f /tmp/ta_radar_run.py
```
---
## Embedded Script
> Full Python 3 script with zero third-party dependencies, all indicator calculations implemented manually using built-in libraries.
```python
#!/usr/bin/env python3
# -*- coding: utf-8 -*-
"""
TA Radar v1.2
Zero-dependency TA engine: EMA / RSI / MACD / Bollinger Bands
Data sources: Binance (api.binance.info) first, auto fallback to Gate.io (api.gateio.ws)
DEX contract resolution: DexScreener via allorigins public proxy
Changelog v1.2:
[NEW-1] Dual data source fallback: fetch_klines() encapsulates Binance + Gate.io logic,
any Binance error (HTTP/Timeout/URLError) automatically switches to Gate.io,
warning is rendered only if both sources fail.
[NEW-2] Beginner-friendly annotations: Each indicator conclusion includes
plain language explanation of signal meaning, no jargon or metaphors.
"""
import os
import sys
import json
import math
import socket
import urllib.request
import urllib.error
import urllib.parse
from datetime import datetime, UTC
# ─────────────────────────────────────────────
# Environment Variables
# ─────────────────────────────────────────────
SYMBOL = os.environ.get("TA_SYMBOL", "").strip()
INTERVAL = os.environ.get("TA_INTERVAL", "1h").strip().lower()
LIMIT = 300 # Sufficient historical data for accurate EMA/MACD convergence
VALID_INTERVALS = {"1h", "4h", "1d"}
# ─────────────────────────────────────────────
# Network Request: Returns (data, error_msg) tuple
# ─────────────────────────────────────────────
def safe_fetch(url: str, timeout: int = 12):
"""
Perform HTTP GET request, returns (parsed_json, error_msg) tuple.
Success: (dict|list, None)
Failure: (None, error string)
- HTTP error → "HTTP {code}: {msg}"
- Timeout → "Timeout ({n}s): {base_url}"
- URLError → "URLError: {reason}"
- JSON error → "JSONDecodeError: {detail}"
- Other → "UnexpectedError: {type}: {msg}"
"""
req = urllib.request.Request(
url,
headers={"User-Agent": "Mozilla/5.0 ta-radar/1.2"}
)
try:
with urllib.request.urlopen(req, timeout=timeout) as resp:
raw = resp.read().decode("utf-8")
try:
return json.loads(raw), None
except json.JSONDecodeError as e:
return None, f"JSONDecodeError: {e}"
except urllib.error.HTTPError as e:
try:
body = e.read().decode("utf-8")
detail = json.loads(body).get("msg", body[:200])
except Exception:
detail = str(e.reason)
return None, f"HTTP {e.code}: {detail}"
except urllib.error.URLError as e:
reason = str(e.reason)
base = url.split("?")[0]
if "timed out" in reason.lower() or isinstance(e.reason, socket.timeout):
return None, f"Timeout ({timeout}s): {base}"
return None, f"URLError: {reason}"
except socket.timeout:
return None, f"Timeout ({timeout}s): {url.split('?')[0]}"
except Exception as e:
return None, f"UnexpectedError: {type(e).__name__}: {e}"
# ─────────────────────────────────────────────
# Input Validation
# ─────────────────────────────────────────────
def validate_inputs():
if not SYMBOL:
print("❌ Error: TA_SYMBOL environment variable not provided. Specify a trading pair or contract address.", file=sys.stderr)
sys.exit(1)
if INTERVAL not in VALID_INTERVALS:
print(
f"❌ Error: Unsupported timeframe '{INTERVAL}'. Use 1h / 4h / 1d.",
file=sys.stderr
)
sys.exit(1)
# ─────────────────────────────────────────────
# Data Fetching Layer
# ─────────────────────────────────────────────
def is_contract_address(s: str) -> bool:
"""Check if input is an on-chain contract address: starts with 0x and length >=10."""
return s.startswith("0x") and len(s) >= 10
def fetch_binance_klines(symbol: str, interval: str, limit: int):
"""
Fetch closing price list from Binance official mirror.
Endpoint: api.binance.info
Returns (closes: list | None, error_msg: str | None).
"""
sym = symbol.strip().upper()
if not sym.endswith("USDT"):
sym += "USDT"
url = (
f"https://api.binance.info/api/v3/klines"
f"?symbol={sym}&interval={interval}&limit={limit}"
)
data, err = safe_fetch(url)
if err:
return None, f"Binance [{sym}] → {err}"
if not isinstance(data, list) or len(data) == 0:
return None, f"Binance [{sym}] returned empty or invalid data"
try:
closes = [float(c[4]) for c in data]
except (IndexError, ValueError, TypeError) as e:
return None, f"Binance [{sym}] K-line parse error: {e}"
if len(closes) < 26:
return None, f"Binance [{sym}] insufficient K-line data ({len(closes)} bars, minimum 26 required)"
return closes, None
def fetch_gate_klines(symbol: str, interval: str, limit: int):
"""
Fetch closing price list from Gate.io as fallback data source.
Endpoint: api.gateio.ws (accessible in mainland China)
Gate.io K-line interval mapping: 1h -> 1h, 4h -> 4h, 1d -> 1d
Returns (closes: list | None, error_msg: str | None).
"""
sym = symbol.strip().upper()
if not sym.endswith("USDT"):
sym += "USDT"
# Gate.io pair format: BTC_USDT (underscore separated)
gate_pair = sym[:-4] + "_USDT"
url = (
f"https://api.gateio.ws/api/v4/spot/candlesticks"
f"?currency_pair={urllib.parse.quote(gate_pair)}"
f"&interval={interval}&limit={limit}"
)
data, err = safe_fetch(url)
if err:
return None, f"Gate.io [{gate_pair}] → {err}"
if not isinstance(data, list) or len(data) == 0:
return None, f"Gate.io [{gate_pair}] returned empty or invalid data"
# Gate.io candlestick format (v4):
# [timestamp, volume, close, high, low, open, ...]
# Close price at index 2
try:
closes = [float(c[2]) for c in data]
except (IndexError, ValueError, TypeError) as e:
return None, f"Gate.io [{gate_pair}] K-line parse error: {e}"
if len(closes) < 26:
return None, f"Gate.io [{gate_pair}] insufficient K-line data ({len(closes)} bars, minimum 26 required)"
return closes, None
def fetch_klines(symbol: str, interval: str, limit: int):
"""
Dual data source K-line entry point.
Tries Binance first, automatically falls back to Gate.io on failure.
Returns (closes: list | None, source_name: str, debug_msgs: list).
- closes = None means both sources failed.
- source_name = name of the data source actually used, for report header.
- debug_msgs = collection of error messages from each step.
"""
debug_msgs = []
# Try Binance
closes, binance_err = fetch_binance_klines(symbol, interval, limit)
if closes is not None:
return closes, "Binance", debug_msgs
debug_msgs.append(f"Binance unavailable: {binance_err}")
print(f" ⚠ Binance data source unavailable, switching to Gate.io...\n")
# Fallback to Gate.io
closes, gate_err = fetch_gate_klines(symbol, interval, limit)
if closes is not None:
return closes, "Gate.io", debug_msgs
debug_msgs.append(f"Gate.io unavailable: {gate_err}")
return None, "", debug_msgs
def resolve_symbol_from_dex(address: str):
"""
Resolve baseToken.symbol and pair label from contract address via DexScreener through allorigins proxy.
Returns (base_symbol: str | None, pair_label: str, error_msg: str | None).
"""
dex_url = (
f"https://api.dexscreener.com/latest/dex/search"
f"?q={urllib.parse.quote(address)}"
)
proxy_url = (
f"https://api.allorigins.win/raw"
f"?url={urllib.parse.quote(dex_url)}"
)
data, err = safe_fetch(proxy_url, timeout=18)
if err:
return None, "", f"DexScreener proxy request failed → {err}"
if not isinstance(data, dict):
return None, "", f"DexScreener returned invalid format (expected dict, got {type(data).__name__})"
pairs = data.get("pairs")
if not pairs or not isinstance(pairs, list) or len(pairs) == 0:
return None, "", f"DexScreener found no pairs for address {address[:20]}..."
def get_liq(p):
try:
return float(p.get("liquidity", {}).get("usd", 0) or 0)
except (TypeError, ValueError):
return 0.0
top = sorted(pairs, key=get_liq, reverse=True)[0]
base_symbol = (top.get("baseToken", {}).get("symbol") or "").strip().upper()
quote_symbol = top.get("quoteToken", {}).get("symbol", "?")
dex_id = top.get("dexId", "?")
chain_id = top.get("chainId", "?")
liq_usd = get_liq(top)
pair_label = (
f"{base_symbol}/{quote_symbol} on {dex_id} "
f"(chain={chain_id}, liq=,.0f)"
)
if not base_symbol:
return None, pair_label, "DexScreener returned empty baseToken.symbol"
return base_symbol, pair_label, None
# ─────────────────────────────────────────────
# Pure Python Technical Indicators (zero dependencies)
# ─────────────────────────────────────────────
def calc_ema(prices: list, period: int) -> list:
"""Exponential Moving Average (EMA). First value is SMA, k = 2 / (period+1)."""
if len(prices) < period:
return []
k = 2.0 / (period + 1)
result = [sum(prices[:period]) / period]
for p in prices[period:]:
result.append(p * k + result[-1] * (1 - k))
return result
def calc_rsi(prices: list, period: int = 14):
"""Relative Strength Index (RSI), Wilder's smoothing method. Returns latest value, None if insufficient data."""
if len(prices) < period + 1:
return None
gains, losses = [], []
for i in range(1, len(prices)):
d = prices[i] - prices[i - 1]
gains.append(max(d, 0.0))
losses.append(max(-d, 0.0))
ag = sum(gains[:period]) / period
al = sum(losses[:period]) / period
for i in range(period, len(gains)):
ag = (ag * (period - 1) + gains[i]) / period
al = (al * (period - 1) + losses[i]) / period
if al == 0:
return 100.0
return 100.0 - (100.0 / (1 + ag / al))
def calc_macd(prices: list, fast: int = 12, slow: int = 26, signal: int = 9):
"""Moving Average Convergence Divergence (MACD). Returns (dif, dea, hist) latest values, None if insufficient data."""
ef = calc_ema(prices, fast)
es = calc_ema(prices, slow)
if not ef or not es:
return None
offset = len(ef) - len(es)
dif_series = [f - s for f, s in zip(ef[offset:], es)]
if len(dif_series) < signal:
return None
dea_series = calc_ema(dif_series, signal)
if not dea_series:
return None
dif = dif_series[-1]
dea = dea_series[-1]
return dif, dea, dif - dea
def calc_bollinger(prices: list, period: int = 20, num_std: float = 2.0):
"""Bollinger Bands. Returns (upper, middle, lower) latest values, None if insufficient data."""
if len(prices) < period:
return None
w = prices[-period:]
mid = sum(w) / period
std = math.sqrt(sum((p - mid) ** 2 for p in w) / period)
return mid + num_std * std, mid, mid - num_std * std
# ─────────────────────────────────────────────
# Formatting Utilities
# ─────────────────────────────────────────────
def fmt(val: float) -> str:
"""Format price, automatically adapts to magnitude."""
if val == 0:
return "0"
a = abs(val)
if a >= 1000: return f"{val:,.2f}"
elif a >= 1: return f"{val:.4f}"
elif a >= 0.01: return f"{val:.6f}"
else: return f"{val:.8f}"
# ─────────────────────────────────────────────
# [NEW-2] Beginner-Friendly Explanation Library
# Each explanation is objective, plain language, no metaphors or jargon.
# ─────────────────────────────────────────────
EMA_EXPLAIN = {
"bull": "Short-term EMA above long-term EMA indicates recent price strength.",
"bear": "Short-term EMA below long-term EMA indicates recent price weakness.",
"flat": "Mixed EMA alignment indicates sideways consolidation, no clear trend.",
}
RSI_EXPLAIN = {
"ob": "RSI above 70 indicates recent large gains, potential short-term pullback risk.",
"os": "RSI below 30 indicates recent large losses, potential short-term bounce opportunity.",
"mid": "RSI between 30-70 indicates normal momentum, neutral signal.",
}
MACD_EXPLAIN = {
"bull_above": "MACD above signal line and zero line indicates strong upward momentum.",
"bear_below": "MACD below signal line and zero line indicates strong downward momentum.",
"bull_below": "MACD crossed above signal line but still below zero line, improving momentum but not confirmed.",
"bear_above": "MACD crossed below signal line but still above zero line, weakening momentum, monitor closely.",
}
BOLL_EXPLAIN = {
"near_upper": "Price near upper Bollinger Band indicates limited upside potential, watch for resistance.",
"near_lower": "Price near lower Bollinger Band indicates statistical support area, watch for bounce.",
"squeeze": "Narrow Bollinger Band width indicates low volatility, often precursor to directional move.",
"mid_above": "Price above middle Bollinger Band indicates short-term relative strength.",
"mid_below": "Price below middle Bollinger Band indicates short-term relative weakness.",
}
# ─────────────────────────────────────────────
# Report Rendering
# ─────────────────────────────────────────────
def render_report(
display_sym: str,
interval: str,
closes: list,
data_source: str = "Binance",
source_note: str = "",
):
price = closes[-1]
ts = datetime.now(UTC).strftime("%Y-%m-%d %H:%M UTC")
# ── Calculate Indicators ──────────────────────────
ema7_s = calc_ema(closes, 7)
ema25_s = calc_ema(closes, 25)
ema99_s = calc_ema(closes, 99)
rsi = calc_rsi(closes, 14)
macd_r = calc_macd(closes)
boll_r = calc_bollinger(closes, 20)
ema7_v = ema7_s[-1] if ema7_s else None
ema25_v = ema25_s[-1] if ema25_s else None
ema99_v = ema99_s[-1] if ema99_s else None
# ── Trend Signals ──────────────────────────────
ema_bull = bool(ema7_v and ema25_v and ema99_v and ema7_v > ema25_v > ema99_v)
ema_bear = bool(ema7_v and ema25_v and ema99_v and ema7_v < ema25_v < ema99_v)
rsi_ob = rsi is not None and rsi > 70
rsi_os = rsi is not None and rsi < 30
macd_bull = bool(macd_r and macd_r[0] > 0 and macd_r[2] > 0)
macd_bear = bool(macd_r and macd_r[0] < 0 and macd_r[2] < 0)
boll_up = bool(boll_r and price > boll_r[1])
near_upper = bool(boll_r and price >= boll_r[0] * 0.995)
near_lower = bool(boll_r and price <= boll_r[2] * 1.005)
boll_squeeze = bool(boll_r and (boll_r[0] - boll_r[2]) / boll_r[1] * 100 < 5)
# ── Composite Trend Voting ──────────────────────────
bull_votes = sum([
ema_bull,
macd_bull,
boll_up,
rsi is not None and 40 <= rsi <= 60,
])
bear_votes = sum([
ema_bear,
macd_bear,
not boll_up and boll_r is not None,
rsi_ob,
])
if bull_votes >= 3:
trend_label = "Bullish (Bulls in control)"
elif bear_votes >= 3:
trend_label = "Bearish (Bears in control)"
elif bull_votes == bear_votes:
trend_label = "Neutral (Range bound)"
elif bull_votes > bear_votes:
trend_label = "Neutral (Slightly bullish)"
else:
trend_label = "Neutral (Slightly bearish)"
# ── Support / Resistance Levels ─────────────────────────
sup, res = [], []
if boll_r:
ub, mb, lb = boll_r
(sup if lb < price else res).append(("Lower Bollinger", lb))
(sup if mb < price else res).append(("Middle Bollinger", mb))
(res if ub > price else sup).append(("Upper Bollinger", ub))
if ema25_v:
(sup if ema25_v < price else res).append(("EMA25", ema25_v))
if ema99_v:
(sup if ema99_v < price else res).append(("EMA99", ema99_v))
sup = sorted(sup, key=lambda x: x[1], reverse=True)[:3]
res = sorted(res, key=lambda x: x[1])[:3]
def fmt_levels(lvls):
if not lvls:
return "No valid levels available"
return " / ".join(f"{n} {fmt(v)}" for n, v in lvls)
# ── Composite Analysis Text ──────────────────────────
parts = []
if ema7_v and ema25_v and ema99_v:
if ema_bull:
parts.append(
f"EMA alignment is bullish (EMA7 {fmt(ema7_v)} > EMA25 {fmt(ema25_v)} > "
f"EMA99 {fmt(ema99_v)}), indicating an established uptrend structure."
)
elif ema_bear:
parts.append(
f"EMA alignment is bearish (EMA7 {fmt(ema7_v)} < EMA25 {fmt(ema25_v)} < "
f"EMA99 {fmt(ema99_v)}), indicating an established downtrend structure."
)
else:
parts.append(
f"EMA alignment is mixed (EMA7 {fmt(ema7_v)}, EMA25 {fmt(ema25_v)}, "
f"EMA99 {fmt(ema99_v)}), indicating sideways consolidation with no clear directional signal."
)
if rsi is not None:
if rsi_ob:
parts.append(
f"RSI reading is {rsi:.1f}, in overbought territory (threshold 70). "
f"Short-term momentum is overextended, potential for pullback or consolidation."
)
elif rsi_os:
parts.append(
f"RSI reading is {rsi:.1f}, in oversold territory (threshold 30). "
f"Short-term momentum is excessively negative, potential for technical bounce."
)
else:
parts.append(
f"RSI reading is {rsi:.1f}, in neutral territory (between 30 and 70). "
f"Current momentum is not extreme."
)
if macd_r:
dif, dea, hist = macd_r
if dif > dea and dif > 0:
parts.append(
f"MACD line ({fmt(dif)}) is above signal line ({fmt(dea)}) and both are above zero line. "
f"Histogram is positive ({fmt(hist)}), confirming upward momentum, golden cross valid."
)
elif dif < dea and dif < 0:
parts.append(
f"MACD line ({fmt(dif)}) is below signal line ({fmt(dea)}) and both are below zero line. "
f"Histogram is negative ({fmt(hist)}), confirming downward momentum, death cross valid."
)
elif dif > dea:
parts.append(
f"MACD line ({fmt(dif)}) has crossed above signal line ({fmt(dea)}) but remains below zero line. "
f"Histogram turned positive ({fmt(hist)}), momentum is improving but not yet confirmed above zero."
)
else:
parts.append(
f"MACD line ({fmt(dif)}) has crossed below signal line ({fmt(dea)}) but remains above zero line. "
f"Histogram turned negative ({fmt(hist)}), upward momentum is weakening, direction pending confirmation."
)
if boll_r:
ub, mb, lb = boll_r
bw = (ub - lb) / mb * 100
if near_upper:
parts.append(
f"Current price ({fmt(price)}) is near or touching upper Bollinger Band ({fmt(ub)}). "
f"Band width is {bw:.1f}%, statistical resistance overhead, watch for volume confirmation on breakout attempts."
)
elif near_lower:
parts.append(
f"Current price ({fmt(price)}) is near or touching lower Bollinger Band ({fmt(lb)}). "
f"Band width is {bw:.1f}%, near statistical support area, watch for bounce confirmation at this level."
)
elif boll_squeeze:
parts.append(
f"Bollinger Band width has narrowed to {bw:.1f}%, price is in low volatility consolidation phase. "
f"This pattern typically precedes a directional expansion, monitor volume for breakout direction clues."
)
else:
pos = "above" if price > mb else "below"
parts.append(
f"Current price ({fmt(price)}) is {pos} middle Bollinger Band ({fmt(mb)}). "
f"Band width is {bw:.1f}%, volatility is within normal range."
)
analysis_text = "\n".join(f" {p}" for p in parts)
# ── Print Report ────────────────────────
SEP = "─" * 60
EQ = "═" * 60
print(f"\n{EQ}")
print(f" TA Radar v1.2 | {display_sym} | {interval.upper()}")
print(f" Data Source: {data_source}" + (f" | {source_note}" if source_note else ""))
print(f" Generated: {ts}")
print(f"{EQ}\n")
# ── Core Data Panel ──────────────────────
print("【Core Data Panel】")
print(SEP)
print(f" Current Price : {fmt(price)}")
print()
# EMA
print(" ▸ EMA (7 / 25 / 99)")
if ema7_v and ema25_v and ema99_v:
if ema_bull:
label = "Bullish alignment ↑"
explain = EMA_EXPLAIN["bull"]
elif ema_bear:
label = "Bearish alignment ↓"
explain = EMA_EXPLAIN["bear"]
else:
label = "Mixed alignment ↔"
explain = EMA_EXPLAIN["flat"]
print(f" EMA7 = {fmt(ema7_v)}")
print(f" EMA25 = {fmt(ema25_v)}")
print(f" EMA99 = {fmt(ema99_v)}")
print(f" Conclusion : {label}")
print(f" Explanation : {explain}")
else:
print(" Insufficient data to calculate")
print()
# RSI
print(" ▸ RSI (14)")
if rsi is not None:
if rsi_ob:
label = "Overbought ⚠"
explain = RSI_EXPLAIN["ob"]
elif rsi_os:
label = "Oversold ⚠"
explain = RSI_EXPLAIN["os"]
else:
label = "Neutral ✓"
explain = RSI_EXPLAIN["mid"]
print(f" RSI = {rsi:.2f}")
print(f" Conclusion : {label}")
print(f" Explanation : {explain}")
else:
print(" Insufficient data to calculate")
print()
# MACD
print(" ▸ MACD (12 / 26 / 9)")
if macd_r:
dif, dea, hist = macd_r
if dif > dea and dif > 0:
label = "Golden cross (above zero line) ↑"
explain = MACD_EXPLAIN["bull_above"]
elif dif < dea and dif < 0:
label = "Death cross (below zero line) ↓"
explain = MACD_EXPLAIN["bear_below"]
elif dif > dea:
label = "Golden cross (below zero line, pending confirmation) ↗"
explain = MACD_EXPLAIN["bull_below"]
else:
label = "Death cross (above zero line, weakening momentum) ↘"
explain = MACD_EXPLAIN["bear_above"]
print(f" MACD Line = {fmt(dif)}")
print(f" Signal Line = {fmt(dea)}")
print(f" Histogram = {fmt(hist)}")
print(f" Conclusion : {label}")
print(f" Explanation : {explain}")
else:
print(" Insufficient
FILE:README.md
[🇺🇸 English](#english) · [🇨🇳 中文](#chinese)
---
<a name="english"></a>
# TA Radar v1.2.0
## Multi-Dimensional Technical Analysis Radar for Cryptocurrencies
Zero-dependency technical analysis skill for OpenClaw, supporting spot trading pairs and on-chain contract addresses. Generates objective TA reports including EMA, RSI, MACD, Bollinger Bands, support/resistance levels and trend analysis.
## Features
- ✅ **Dual Data Source Fallback**: First try Binance, automatically switch to Gate.io on failure (GFW-friendly for Chinese users)
- ✅ **On-Chain Contract Support**: Resolve EVM contract addresses via DexScreener public proxy
- ✅ **Beginner-Friendly Annotations**: Each indicator includes plain language explanations, no financial background required
- ✅ **Zero Dependencies**: Pure Python implementation, no external libraries needed
- ✅ **Multiple Timeframes**: Supports 1h / 4h / 1d analysis periods
## Data Sources
- **Primary**: Binance API (`api.binance.info`)
- **Fallback**: Gate.io API (`api.gateio.ws`)
- **DEX Resolution**: DexScreener via `allorigins.win` public proxy
## Installation
Install directly via OpenClaw:
```bash
openclaw skill install https://github.com/AntalphaAI/TA-Radar
```
## Usage
### As OpenClaw Skill
After installation, the skill is ready to use inside your OpenClaw session.
### Standalone Usage
```bash
# Analyze BTC 4h chart
TA_SYMBOL="BTC" TA_INTERVAL="4h" python3 ta_radar_run.py
# Analyze ETH 1d chart
TA_SYMBOL="ETHUSDT" TA_INTERVAL="1d" python3 ta_radar_run.py
# Analyze on-chain contract address
TA_SYMBOL="0x904567252D8F48555b7447c67dCA23F0372E16be" python3 ta_radar_run.py
```
## Sample Output
```
════════════════════════════════════════════════════════════
TA Radar v1.2 | BTCUSDT | 4H
Data Source: Gate.io
Generated: 2026-03-31 08:42 UTC
════════════════════════════════════════════════════════════
【Core Data Panel】
────────────────────────────────────────────────────────────
Current Price : 67,394.00
▸ EMA (7 / 25 / 99)
EMA7 = 67,262.38
EMA25 = 67,374.61
EMA99 = 69,901.27
Conclusion : Bearish alignment ↓
Explanation : Short-term EMA below long-term EMA indicates recent price weakness.
```
## Indicators
| Indicator | Parameters | Description |
|-----------|------------|-------------|
| EMA | 7/25/99 periods | Exponential Moving Average for trend identification |
| RSI | 14 periods | Relative Strength Index for overbought/oversold detection |
| MACD | 12/26/9 periods | Moving Average Convergence Divergence for momentum analysis |
| Bollinger Bands | 20 periods / 2σ | Volatility bands for support/resistance levels |
## Security Notes
- **External Requests**: Data is fetched from Binance, Gate.io and DexScreener (via allorigins.win proxy)
- **Local Only**: No data is sent to third parties other than the public API endpoints mentioned above
- **No Sensitive Data**: The skill does not store or transmit any private user information
## License
MIT License
## Maintainer
Antalpha AI Team
---
<a name="chinese"></a>
# TA Radar v1.2.0
## 加密货币多维技术分析雷达
基于 OpenClaw 的零依赖技术分析技能，支持现货交易对和链上合约地址。自动生成包含 EMA、RSI、MACD、布林带、支撑/阻力位及趋势分析的客观 TA 报告。
## 功能特性
- ✅ **双数据源自动切换**：优先使用 Binance，失败时自动切换至 Gate.io（对国内用户友好，无需翻墙）
- ✅ **链上合约地址支持**：通过 DexScreener 公共代理解析 EVM 合约地址
- ✅ **新手友好注释**：每个指标附带通俗解释，无需金融背景
- ✅ **零外部依赖**：纯 Python 实现，无需安装额外库
- ✅ **多周期分析**：支持 1h / 4h / 1d 分析周期
## 数据来源
- **主要数据源**：Binance API（`api.binance.info`）
- **备用数据源**：Gate.io API（`api.gateio.ws`）
- **DEX 解析**：通过 `allorigins.win` 公共代理访问 DexScreener
## 安装
通过 OpenClaw 一键安装：
```bash
openclaw skill install https://github.com/AntalphaAI/TA-Radar
```
## 使用方式
### 作为 OpenClaw Skill 使用
安装完成后，直接在 OpenClaw 会话中使用即可。
### 独立脚本运行
```bash
# 分析 BTC 4小时图
TA_SYMBOL="BTC" TA_INTERVAL="4h" python3 ta_radar_run.py
# 分析 ETH 日线图
TA_SYMBOL="ETHUSDT" TA_INTERVAL="1d" python3 ta_radar_run.py
# 分析链上合约地址
TA_SYMBOL="0x904567252D8F48555b7447c67dCA23F0372E16be" python3 ta_radar_run.py
```
## 输出示例
```
════════════════════════════════════════════════════════════
TA Radar v1.2 | BTCUSDT | 4H
数据来源: Gate.io
生成时间: 2026-03-31 08:42 UTC
════════════════════════════════════════════════════════════
【核心数据面板】
────────────────────────────────────────────────────────────
当前价格 : 67,394.00
▸ EMA（7 / 25 / 99）
EMA7 = 67,262.38
EMA25 = 67,374.61
EMA99 = 69,901.27
结论 : 空头排列 ↓
解读 : 短期均线位于长期均线下方，表明近期价格偏弱。
```
## 指标说明
| 指标 | 参数 | 说明 |
|------|------|------|
| EMA | 7/25/99 周期 | 指数移动平均线，用于识别趋势方向 |
| RSI | 14 周期 | 相对强弱指数，判断超买/超卖状态 |
| MACD | 12/26/9 周期 | 移动平均收敛散度，分析动量变化 |
| 布林带 | 20 周期 / 2σ | 波动率通道，标识支撑/阻力区间 |
## 安全说明
- **外部请求**：数据仅从 Binance、Gate.io 和 DexScreener（通过 allorigins.win 代理）获取
- **本地运行**：除上述公开 API 端点外，不向任何第三方发送数据
- **无敏感数据**：本技能不存储或传输任何用户私人信息
## 开源协议
MIT License
## 维护团队
Antalpha AI Team
FILE:references/deployment.md
# TA Radar API — 私有化部署指南
本文档面向希望自行部署 TA Radar API 的技术用户。
---
## 目录
1. [项目结构](#项目结构)
2. [依赖安装](#依赖安装)
3. [核心源码 api/index.js](#核心源码)
4. [配置文件](#配置文件)
5. [本地调试](#本地调试)
6. [Vercel 部署](#vercel-部署)
7. [更换 API Endpoint](#更换-api-endpoint)
---
## 项目结构
```
your-project/
├── api/
│ └── index.js ← 核心逻辑（单文件，无需其他模块）
├── package.json
└── vercel.json
```
---
## 依赖安装
```bash
npm init -y
npm install axios technicalindicators
npm install -g vercel # 如未安装 Vercel CLI
```
**package.json 关键内容：**
```json
{
"name": "ta-radar-api",
"version": "1.0.0",
"dependencies": {
"axios": "^1.7.2",
"technicalindicators": "^3.1.0"
},
"engines": {
"node": ">=18.x"
}
}
```
---
## 核心源码
**api/index.js 功能模块说明：**
### 输入解析层
| 函数 | 职责 |
|---|---|
| `inferInterval(query)` | 正则匹配关键词推断 K 线级别，默认 4h |
| `extractAddress(query)` | 提取 0x 开头的 42 位合约地址 |
| `resolveSymbolFromAddress(address)` | 调用 DexScreener API 解析合约 → Ticker |
| `extractTicker(query)` | 清除地址后提取首个 2~10 字母数字 Ticker |
### 数据拉取层
| 函数 | 职责 |
|---|---|
| `fetchKlines(symbol, interval)` | 请求币安 `/api/v3/klines`，返回收盘价数组 |
**币安接口容错：**
- 4xx 响应 → 返回 `{ notListed: true, message: "..." }` 专属提示
- 网络超时 → 抛出错误，由主处理器捕获返回 500
### 指标计算层
使用 `technicalindicators` 库，均取结果数组最后一个元素（最新 K 线）：
```javascript
// EMA
EMA.calculate({ period: 20, values: closes })
// RSI
RSI.calculate({ period: 14, values: closes })
// MACD
MACD.calculate({
fastPeriod: 12, slowPeriod: 26, signalPeriod: 9,
values: closes,
SimpleMAOscillator: false,
SimpleMASignal: false
})
// Bollinger Bands
BollingerBands.calculate({ period: 20, values: closes, stdDev: 2 })
```
### 信号解读层
| 函数 | 返回格式 |
|---|---|
| `signalEMA(ema20, ema50, lastClose)` | `{ label: "偏多/偏空/中性...", desc: "..." }` |
| `signalRSI(rsi)` | 同上，含超买（≥70）/ 超卖（≤30）判断 |
| `signalMACD(macd)` | 基于 MACD线 vs 信号线 及 柱状图正负 |
| `signalBoll(boll, lastClose)` | 基于价格相对上/中/下轨位置 |
### 报告生成层
`buildSummary()` — 统计多空信号数量，生成综合研判段落，输出关键支撑/阻力/中轴三个价位。
`buildMarkdown()` — 拼装完整 Markdown 报告，包含核心数据面板表格 + 综合趋势研判 + 免责声明。
**文风硬性约束（写死在逻辑中）：**
- 禁止比喻和夸张修辞
- 禁止双引号
- 只使用平实交易术语（支撑位、多空博弈、下行通道等）
---
## 配置文件
**vercel.json：**
```json
{
"version": 2,
"builds": [{ "src": "api/index.js", "use": "@vercel/node" }],
"routes": [
{ "src": "/api/(.*)", "dest": "/api/index.js" },
{ "src": "/(.*)", "dest": "/api/index.js" }
]
}
```
---
## 本地调试
```bash
vercel dev
# 访问 http://localhost:3000/api?query=SOL%204H分析
```
---
## Vercel 部署
```bash
vercel # 首次部署，跟随引导绑定账号
vercel --prod # 推送到生产环境
```
部署成功后，Vercel 会提供一个类似 `https://your-project-name.vercel.app` 的域名。
---
## 更换 API Endpoint
部署完成后，需要更新 Skill 中的 API 地址。在 SKILL.md 中找到：
```
https://ta-radar.vercel.app/api?query={用户原始输入}
```
替换为你自己的域名：
```
https://your-project-name.vercel.app/api?query={用户原始输入}
```
---
## 调用示例与返回结构
**请求：**
```
GET /api?query=SOL%20短线分析
```
**成功返回：**
```json
{
"success": true,
"symbol": "SOL",
"binanceSymbol": "SOLUSDT",
"interval": "1h",
"notListed": false,
"indicators": {
"price": 148.32,
"ema20": 147.81,
"ema50": 145.20,
"rsi": 58.4,
"macd": { "macdLine": 0.42, "signal": 0.31, "histogram": 0.11 },
"boll": { "upper": 152.10, "middle": 147.50, "lower": 142.90 }
},
"signals": {
"ema": "偏多",
"rsi": "偏多",
"macd": "偏多",
"boll": "中轨上方偏多"
},
"markdown": "## 📊 全维度技术面雷达 | SOL/USDT · 1H\n..."
}
```
**未上币安返回：**
```json
{
"success": true,
"notListed": true,
"markdown": "⚠️ 侦测到该代币暂未上线币安主流交易区..."
}
```
**错误返回：**
```json
{
"success": false,
"error": "具体错误原因描述"
}
```
Professional DeFi data aggregator that provides unified access to TVL, protocols, chains, and yields data from DefiLlama. Supports multiple output formats (J...
---
name: defillama-data-aggregator
description: Professional DeFi data aggregator that provides unified access to TVL, protocols, chains, and yields data from DefiLlama. Supports multiple output formats (JSON/Table/CSV), health monitoring, and security validation.
homepage: https://github.com/AntalphaAI/defillama-data-aggregator
version: 1.0.3
author: AntalphaAI
emoji: "📊"
tags: defi,web3,crypto,tvl,data,blockchain,yields,defillama
metadata:
openclaw:
requires:
bins: ["node", "npm"]
env: []
install:
command: "npm install"
repository: https://github.com/AntalphaAI/defillama-data-aggregator
---
# DefiLlama Data Aggregator
> **Professional DeFi data at your fingertips.** Query TVL, protocols, chains, and yields from DefiLlama with a single command.
## What This Skill Does
- **TVL Query** - Get total DeFi TVL or individual chain TVL
- **Protocol Data** - Query protocol details, rankings, and filter by category
- **Chain Statistics** - Get TVL for specific chains (Ethereum, Solana, etc.)
- **Yield Pools** - Find high-yield opportunities with filtering options
- **Health Monitoring** - Check API availability status
## Quick Start
```bash
# Get total DeFi TVL
node {skillDir}/src/index.js defillama tvl
# Get protocol TVL
node {skillDir}/src/index.js defillama protocol --name aave
# Get top protocols by TVL
node {skillDir}/src/index.js defillama protocols --limit 10 --sort tvl --format table
# Get chain TVL
node {skillDir}/src/index.js defillama chain --name ethereum
# Find high-yield pools
node {skillDir}/src/index.js defillama yields --min-apy 10 --chain ethereum --limit 20
# Check API health
node {skillDir}/src/index.js health
```
## Commands
### TVL Commands
| Command | Description | Example |
|---------|-------------|---------|
| `tvl` | Get total DeFi TVL | `node {skillDir}/src/index.js defillama tvl` |
| `protocol --name <name>` | Get protocol TVL | `node {skillDir}/src/index.js defillama protocol --name uniswap` |
| `chain --name <name>` | Get chain TVL | `node {skillDir}/src/index.js defillama chain --name solana` |
### Protocol Commands
| Command | Description | Example |
|---------|-------------|---------|
| `protocols` | List all protocols | `node {skillDir}/src/index.js defillama protocols` |
| `protocols --category <cat>` | Filter by category | `node {skillDir}/src/index.js defillama protocols --category lending` |
| `protocols --min-tvl <usd>` | Filter by minimum TVL | `node {skillDir}/src/index.js defillama protocols --min-tvl 100000000` |
| `protocols --limit <n>` | Limit results | `node {skillDir}/src/index.js defillama protocols --limit 20` |
### Yield Commands
| Command | Description | Example |
|---------|-------------|---------|
| `yields` | List yield pools | `node {skillDir}/src/index.js defillama yields` |
| `yields --min-apy <pct>` | Filter by minimum APY | `node {skillDir}/src/index.js defillama yields --min-apy 15` |
| `yields --chain <name>` | Filter by chain | `node {skillDir}/src/index.js defillama yields --chain arbitrum` |
| `yields --min-tvl <usd>` | Filter by minimum TVL | `node {skillDir}/src/index.js defillama yields --min-tvl 1000000` |
| `yields --stablecoin` | Stablecoin pools only | `node {skillDir}/src/index.js defillama yields --stablecoin` |
### Utility Commands
| Command | Description | Example |
|---------|-------------|---------|
| `health` | Check API health | `node {skillDir}/src/index.js health` |
| `status` | Show system status | `node {skillDir}/src/index.js status` |
## Output Formats
All data commands support multiple output formats:
```bash
# Pretty format (default, human-readable)
node {skillDir}/src/index.js defillama tvl --format pretty
# JSON format (for scripts and parsing)
node {skillDir}/src/index.js defillama tvl --format json
# Table format (for quick overview)
node {skillDir}/src/index.js defillama protocols --limit 10 --format table
# CSV format (for spreadsheets)
node {skillDir}/src/index.js defillama protocols --limit 50 --format csv
```
## Use Cases
### For DeFi Investors
```
"Show me the top 10 lending protocols by TVL"
"Find yield pools on Ethereum with APY above 15%"
"What is the current TVL of Aave?"
```
### For Data Analysts
```
"Export all protocols data to CSV"
"Get the TVL distribution across chains"
"Compare lending vs DEX TVL"
```
### For Developers
```
"Check if DefiLlama API is healthy"
"Get protocol data in JSON format"
"Find pools with minimum 1M TVL"
```
## Security Features
- **Input Sanitization** - All inputs validated and sanitized
- **Error Filtering** - API errors filtered to prevent information leakage
- **Range Validation** - Numeric inputs validated against bounds
- **Pattern Validation** - Protocol/chain names follow strict rules
## Security Notes
- **No API Keys Required**: This skill uses DefiLlama's public API which does not require authentication
- **External Requests**: Data is fetched from:
- `https://api.llama.fi` (DefiLlama API)
- `https://yields.llama.fi` (DefiLlama Yields API)
- **No Local Server**: This skill does not start any local HTTP server
- **No File Persistence**: No data is persisted locally (caching is in-memory only)
- **Input Validation**: All user inputs are sanitized to prevent injection attacks
## Installation
### Prerequisites
- Node.js >= 16.0.0
- npm
### Setup
```bash
cd {skillDir}
npm install
```
## API Reference
### DefiLlama Endpoints Used
| Endpoint | Description |
|----------|-------------|
| `https://api.llama.fi/tvl` | Total DeFi TVL |
| `https://api.llama.fi/protocols` | All protocols |
| `https://api.llama.fi/protocol/{name}` | Protocol details |
| `https://api.llama.fi/chains` | All chains |
| `https://yields.llama.fi/pools` | Yield pools |
## Error Handling
The skill provides user-friendly error messages:
| Error Type | Message |
|------------|---------|
| Invalid protocol name | "Only alphanumeric characters and hyphens allowed" |
| Invalid chain name | "Only alphanumeric characters, spaces, and hyphens allowed" |
| Network error | "Check internet connection and try again" |
| Rate limit | "Rate limit exceeded, please wait" |
| API unavailable | "Service temporarily unavailable" |
## Examples
### Get Top Protocols
```bash
node {skillDir}/src/index.js defillama protocols --limit 10 --sort tvl --format table
```
### Find High-Yield Pools
```bash
node {skillDir}/src/index.js defillama yields --min-apy 20 --min-tvl 1000000 --limit 5
```
### Check Health
```bash
node {skillDir}/src/index.js health
```
## Troubleshooting
### Protocol Not Found
- Ensure the protocol name matches DefiLlama's naming (e.g., `aave-v3` not `aave v3`)
- Check if the protocol is listed on DefiLlama
### Chain Not Found
- Use lowercase chain names (e.g., `ethereum` not `Ethereum`)
- For multi-word chains, use hyphens (e.g., `polygon-pos`)
### No Results from Yields
- Try lowering the `--min-apy` or `--min-tvl` thresholds
- Ensure the chain name is valid
### Network Errors
- Check internet connectivity
- DefiLlama API may be temporarily unavailable
---
**Version**: 1.0.3
**Last Updated**: 2026-03-31
**Maintainer**: AntalphaAI
**License**: MIT
FILE:README.md
[🇺🇸 English](#english) · [🇨🇳 中文](#chinese)
---
<a name="english"></a>
# 🚀 DefiLlama Data Aggregator
> **Version**: 1.0.3
> **Update Date**: 2026-03-31
> **Description**: Professional DefiLlama data aggregator with security validation - DeFi TVL, protocols, chains, and yields data
> **Maintainer**: [AntalphaAI](https://github.com/AntalphaAI)
---
## 📊 Overview
DefiLlama Data Aggregator is a professional-grade command-line tool that provides unified access to DefiLlama's comprehensive DeFi data. It supports querying Total Value Locked (TVL), protocol data, chain statistics, and yield pool information with built-in security validation and error handling.
---
## 🎯 Features
- ✅ **DeFi TVL** - Total DeFi TVL and chain-level TVL
- ✅ **Protocol Data** - Protocol details, listings, and rankings
- ✅ **Chain Data** - Individual chain TVL and statistics
- ✅ **Yield Pools** - Yield rate queries and filtering
- ✅ **Health Monitoring** - API health status monitoring
- ✅ **Security Validation** - Input sanitization and error handling
- ✅ **Flexible Output** - Pretty/Table/JSON/CSV formats
---
## 📦 Installation
### Install via OpenClaw (Recommended)
```bash
openclaw skill install https://github.com/AntalphaAI/defillama-data-aggregator
```
### Prerequisites
- Node.js >= 16.0.0
- npm (comes with Node.js)
### Install Dependencies (Manual)
```bash
cd defillama-data-aggregator
npm install
```
### Create Symbolic Link (Optional)
```bash
npm link
```
This creates a global `defillama-data` command that you can use from anywhere.
---
## 🚀 Quick Start
### Basic Usage
```bash
# View version
defillama-data --version
# Get total DeFi TVL
defillama-data defillama tvl
# Get protocol TVL
defillama-data defillama protocol -n aave
# Get protocol rankings
defillama-data defillama protocols --limit 10 --sort tvl -f table
# Find high-yield pools
defillama-data defillama yields --min-apy 10 --limit 20 -f table
# Check API health
defillama-data health
# View system status
defillama-data status
```
---
## 📖 Commands
### 1. Get Total DeFi TVL
Get the total value locked across all DeFi protocols.
```bash
defillama-data defillama tvl [options]
```
**Options**:
- `-f, --format <type>`: Output format (json, table, csv, pretty) - Default: pretty
**Example**:
```bash
defillama-data defillama tvl
defillama-data defillama tvl -f json | jq '.totalTvl'
```
**Response**:
```json
{
"totalTvl": 94518602394.26,
"chains": [...],
"timestamp": "2026-03-27T09:00:00.000Z"
}
```
---
### 2. Get Protocol TVL
Get TVL for a specific protocol.
```bash
defillama-data defillama protocol -n <name> [options]
```
**Required Options**:
- `-n, --name <name>`: Protocol name (e.g., aave, uniswap, compound)
**Options**:
- `-f, --format <type>`: Output format (json, table, csv, pretty) - Default: pretty
**Example**:
```bash
defillama-data defillama protocol -n aave
defillama-data defillama protocol -n uniswap -f json
```
**Validation Rules**:
- Only alphanumeric characters and hyphens allowed
- Length: 1-50 characters
- Automatically converted to lowercase
**Valid Examples**: `aave`, `uniswap-v3`, `compound-protocol`
**Invalid Examples**: `aave<script>`, `uni/swap`, `aave&x`
---
### 3. Get All Protocols
Get a list of all protocols with filtering and sorting.
```bash
defillama-data defillama protocols [options]
```
**Options**:
- `-c, --category <name>`: Filter by category (e.g., lending, dex)
- `--min-tvl <amount>`: Minimum TVL in USD
- `--limit <number>`: Limit results (1-500)
- `--sort <field>`: Sort by field (tvl) - Default: tvl
- `-f, --format <type>`: Output format (json, table, csv, pretty) - Default: pretty
**Example**:
```bash
# Get all protocols
defillama-data defillama protocols
# Sort by TVL, top 20
defillama-data defillama protocols --sort tvl --limit 20
# Filter lending protocols
defillama-data defillama protocols -c lending --min-tvl 100000000
# Combined filters
defillama-data defillama protocols -c lending --min-tvl 100000000 --limit 50 --sort tvl -f table
```
---
### 4. Get Chain TVL
Get TVL for a specific blockchain.
```bash
defillama-data defillama chain -n <name> [options]
```
**Required Options**:
- `-n, --name <name>`: Chain name (e.g., ethereum, solana, polygon)
**Options**:
- `-f, --format <type>`: Output format (json, table, csv, pretty) - Default: pretty
**Example**:
```bash
defillama-data defillama chain -n ethereum
defillama-data defillama chain -n solana -f json
```
---
### 5. Get Yield Pools
Get yield pool information with filtering.
```bash
defillama-data defillama yields [options]
```
**Options**:
- `--min-apy <number>`: Minimum APY percentage (0-1000)
- `--min-tvl <number>`: Minimum TVL in USD
- `--chain <name>`: Filter by chain name (e.g., ethereum, arbitrum)
- `--stablecoin`: Filter stablecoin pools only
- `--limit <number>`: Limit results (1-500)
- `-f, --format <type>`: Output format (json, table, csv, pretty) - Default: pretty
**Example**:
```bash
# Get all yield pools
defillama-data defillama yields
# High APY pools (APY > 10%)
defillama-data defillama yields --min-apy 10
# Ethereum high-yield pools
defillama-data defillama yields --chain ethereum --min-apy 5
# Combined filters
defillama-data defillama yields --min-apy 10 --chain ethereum --min-tvl 1000000 --limit 20 -f table
```
---
### 6. Health Check
Check API health status.
```bash
defillama-data health [options]
```
**Options**:
- `-q, --quiet`: Quiet mode (summary only)
- `--timeout <ms>`: Request timeout in milliseconds - Default: 5000
**Example**:
```bash
# Full health check
defillama-data health
# Quiet mode
defillama-data health --quiet
# Custom timeout
defillama-data health --timeout 10000
```
---
### 7. System Status
Display system status and available platforms.
```bash
defillama-data status
```
---
## 📤 Output Formats
All commands support multiple output formats:
### Pretty (Default)
Human-readable format with colored output.
```bash
defillama-data defillama tvl -f pretty
```
### Table
Structured table format for data comparison.
```bash
defillama-data defillama protocols --limit 10 -f table
```
### JSON
Machine-readable format for scripts and automation.
```bash
defillama-data defillama tvl -f json | jq '.totalTvl'
```
### CSV
Spreadsheet-friendly format for data export and analysis.
```bash
defillama-data defillama protocols --limit 50 -f csv > protocols.csv
```
---
## 🔒 Security Features
### Input Validation
All user inputs are validated and sanitized:
| Input Type | Validation Rules | Length Limit |
|-----------|-----------------|--------------|
| Protocol Name | Alphanumeric + hyphens only | 1-50 characters |
| Chain Name | Alphanumeric + spaces + hyphens | 1-50 characters |
| Category Name | Alphanumeric + spaces + hyphens | 1-50 characters |
| Limit | 1-500 | - |
| Min APY | 0-1000% | - |
| Min TVL | ≥ 0 | - |
### Error Handling
- API errors (4xx, 5xx) with status codes
- Network errors (timeout, connection refused)
- Validation errors with helpful messages
- Sanitized error messages to prevent information leakage
---
## 🛠️ Configuration
### Setup Configuration File (Optional)
```bash
# Copy example configuration
cp config/keys.example.js config/keys.js
```
### Configuration Example
```javascript
// config/keys.js
module.exports = {
defillama: {
baseUrl: 'https://api.llama.fi'
},
settings: {
defaultCacheDuration: 300, // Cache duration in seconds
timeout: 30000, // Request timeout in milliseconds
maxRetries: 3, // Maximum retry attempts
retryDelay: 1000, // Retry delay in milliseconds
debug: process.env.DEBUG === 'true' // Enable debug logging
}
};
```
---
## 💡 Usage Examples
### Monitor Lending Protocols
```bash
# Get top 10 lending protocols by TVL
defillama-data defillama protocols -c lending --limit 10 --sort tvl -f table
```
### Find High-Yield Pools
```bash
# Find high-yield pools on Ethereum with APY > 10%
defillama-data defillama yields --chain ethereum --min-apy 10 --min-tvl 1000000 --limit 20 -f table
```
### Compare Chain TVL
```bash
# Compare TVL across multiple chains
for chain in ethereum solana polygon arbitrum avalanche; do
echo "=== $chain ==="
defillama-data defillama chain -n $chain -f json | jq '.tvl'
done
```
### Export Data for Analysis
```bash
# Export protocols to CSV
defillama-data defillama protocols --limit 100 -f csv > protocols.csv
# Export yields to CSV
defillama-data defillama yields --limit 100 -f csv > yields.csv
```
---
## 🧪 Testing
Run the test script to verify functionality:
```bash
node scripts/test.js
```
This will test:
- Version check
- Health check
- TVL query
- Protocol query
- Sorting functionality
- Input validation
---
## 📄 License
MIT License - Copyright (c) 2026 Antalpha
---
<a name="chinese"></a>
# 🚀 DefiLlama 数据聚合器
> **版本**: 1.0.3
> **更新日期**: 2026-03-31
> **描述**: 专业的 DefiLlama 数据聚合工具，内置安全验证 —— 提供 DeFi TVL、协议、链和收益池数据查询
> **维护方**: [AntalphaAI](https://github.com/AntalphaAI)
---
## 📊 概述
DefiLlama 数据聚合器是一款专业级命令行工具，提供对 DefiLlama 全面 DeFi 数据的统一访问接口。支持查询总锁仓量（TVL）、协议数据、链统计信息和收益池数据，内置安全验证与错误处理机制。
---
## 🎯 功能特性
- ✅ **DeFi TVL** — 查询全网 DeFi 总锁仓量及各链锁仓量
- ✅ **协议数据** — 协议详情、列表及排名
- ✅ **链数据** — 各公链 TVL 及统计信息
- ✅ **收益池** — 收益率查询与筛选
- ✅ **健康监控** — API 健康状态监控
- ✅ **安全验证** — 输入清洗与错误处理
- ✅ **多种输出格式** — 支持 Pretty / Table / JSON / CSV
---
## 📦 安装
### 通过 OpenClaw 安装（推荐）
```bash
openclaw skill install https://github.com/AntalphaAI/defillama-data-aggregator
```
### 环境要求
- Node.js >= 16.0.0
- npm（随 Node.js 一起安装）
### 手动安装依赖
```bash
cd defillama-data-aggregator
npm install
```
### 创建全局快捷命令（可选）
```bash
npm link
```
执行后可在任意目录使用 `defillama-data` 命令。
---
## 🚀 快速开始
### 基础用法
```bash
# 查看版本
defillama-data --version
# 获取 DeFi 总 TVL
defillama-data defillama tvl
# 查询协议 TVL
defillama-data defillama protocol -n aave
# 协议排名（前10，按 TVL 排序，表格格式）
defillama-data defillama protocols --limit 10 --sort tvl -f table
# 寻找高收益池
defillama-data defillama yields --min-apy 10 --limit 20 -f table
# 检查 API 健康状态
defillama-data health
# 查看系统状态
defillama-data status
```
---
## 📖 命令说明
### 1. 获取 DeFi 总 TVL
查询全网所有 DeFi 协议的总锁仓量。
```bash
defillama-data defillama tvl [选项]
```
**选项**：
- `-f, --format <type>`：输出格式（json、table、csv、pretty），默认：pretty
**示例**：
```bash
defillama-data defillama tvl
defillama-data defillama tvl -f json | jq '.totalTvl'
```
**返回示例**：
```json
{
"totalTvl": 94518602394.26,
"chains": [...],
"timestamp": "2026-03-27T09:00:00.000Z"
}
```
---
### 2. 查询协议 TVL
获取指定协议的锁仓量。
```bash
defillama-data defillama protocol -n <协议名> [选项]
```
**必填选项**：
- `-n, --name <name>`：协议名称（如 aave、uniswap、compound）
**选项**：
- `-f, --format <type>`：输出格式，默认：pretty
**示例**：
```bash
defillama-data defillama protocol -n aave
defillama-data defillama protocol -n uniswap -f json
```
**验证规则**：
- 仅允许字母、数字和连字符
- 长度：1-50 个字符
- 自动转换为小写
**有效示例**：`aave`、`uniswap-v3`、`compound-protocol`
**无效示例**：`aave<script>`、`uni/swap`、`aave&x`
---
### 3. 获取所有协议列表
获取协议列表，支持筛选和排序。
```bash
defillama-data defillama protocols [选项]
```
**选项**：
- `-c, --category <name>`：按类别筛选（如 lending、dex）
- `--min-tvl <amount>`：最低 TVL（美元）
- `--limit <number>`：结果数量限制（1-500）
- `--sort <field>`：排序字段（tvl），默认：tvl
- `-f, --format <type>`：输出格式，默认：pretty
**示例**：
```bash
# 获取所有协议
defillama-data defillama protocols
# 按 TVL 排序，取前 20
defillama-data defillama protocols --sort tvl --limit 20
# 筛选借贷协议
defillama-data defillama protocols -c lending --min-tvl 100000000
# 组合筛选
defillama-data defillama protocols -c lending --min-tvl 100000000 --limit 50 --sort tvl -f table
```
---
### 4. 查询链 TVL
获取指定区块链的锁仓量。
```bash
defillama-data defillama chain -n <链名> [选项]
```
**必填选项**：
- `-n, --name <name>`：链名称（如 ethereum、solana、polygon）
**示例**：
```bash
defillama-data defillama chain -n ethereum
defillama-data defillama chain -n solana -f json
```
---
### 5. 查询收益池
获取收益池信息，支持多维筛选。
```bash
defillama-data defillama yields [选项]
```
**选项**：
- `--min-apy <number>`：最低 APY 百分比（0-1000）
- `--min-tvl <number>`：最低 TVL（美元）
- `--chain <name>`：按链筛选（如 ethereum、arbitrum）
- `--stablecoin`：仅显示稳定币池
- `--limit <number>`：结果数量限制（1-500）
- `-f, --format <type>`：输出格式，默认：pretty
**示例**：
```bash
# 获取所有收益池
defillama-data defillama yields
# 高 APY 收益池（APY > 10%）
defillama-data defillama yields --min-apy 10
# 以太坊高收益池
defillama-data defillama yields --chain ethereum --min-apy 5
# 组合筛选
defillama-data defillama yields --min-apy 10 --chain ethereum --min-tvl 1000000 --limit 20 -f table
```
---
### 6. 健康检查
检查 API 健康状态。
```bash
defillama-data health [选项]
```
**选项**：
- `-q, --quiet`：安静模式（仅显示摘要）
- `--timeout <ms>`：请求超时时间（毫秒），默认：5000
**示例**：
```bash
# 完整健康检查
defillama-data health
# 安静模式
defillama-data health --quiet
# 自定义超时
defillama-data health --timeout 10000
```
---
### 7. 系统状态
显示系统状态及可用平台信息。
```bash
defillama-data status
```
---
## 📤 输出格式
所有命令均支持以下输出格式：
### Pretty（默认）
适合人工阅读的彩色输出格式。
```bash
defillama-data defillama tvl -f pretty
```
### Table（表格）
结构化表格格式，便于数据对比。
```bash
defillama-data defillama protocols --limit 10 -f table
```
### JSON
适合脚本和自动化处理的机器可读格式。
```bash
defillama-data defillama tvl -f json | jq '.totalTvl'
```
### CSV
适合导出到电子表格进行数据分析。
```bash
defillama-data defillama protocols --limit 50 -f csv > protocols.csv
```
---
## 🔒 安全特性
### 输入验证
所有用户输入均经过验证和清洗：
| 输入类型 | 验证规则 | 长度限制 |
|---------|---------|---------|
| 协议名称 | 仅字母、数字和连字符 | 1-50 字符 |
| 链名称 | 字母、数字、空格和连字符 | 1-50 字符 |
| 类别名称 | 字母、数字、空格和连字符 | 1-50 字符 |
| 数量限制 | 1-500 | - |
| 最低 APY | 0-1000% | - |
| 最低 TVL | ≥ 0 | - |
### 错误处理
- API 错误（4xx、5xx）附带状态码
- 网络错误（超时、连接拒绝）
- 带提示信息的验证错误
- 净化错误消息，防止信息泄露
---
## 🛠️ 配置
### 配置文件设置（可选）
```bash
# 复制示例配置文件
cp config/keys.example.js config/keys.js
```
### 配置示例
```javascript
// config/keys.js
module.exports = {
defillama: {
baseUrl: 'https://api.llama.fi'
},
settings: {
defaultCacheDuration: 300, // 缓存时长（秒）
timeout: 30000, // 请求超时时间（毫秒）
maxRetries: 3, // 最大重试次数
retryDelay: 1000, // 重试间隔（毫秒）
debug: process.env.DEBUG === 'true' // 启用调试日志
}
};
```
---
## 💡 使用示例
### 监控借贷协议
```bash
# 获取 TVL 前 10 的借贷协议
defillama-data defillama protocols -c lending --limit 10 --sort tvl -f table
```
### 寻找高收益池
```bash
# 寻找以太坊上 APY > 10% 的高收益池
defillama-data defillama yields --chain ethereum --min-apy 10 --min-tvl 1000000 --limit 20 -f table
```
### 对比各链 TVL
```bash
# 对比多条链的 TVL
for chain in ethereum solana polygon arbitrum avalanche; do
echo "=== $chain ==="
defillama-data defillama chain -n $chain -f json | jq '.tvl'
done
```
### 导出数据分析
```bash
# 导出协议数据为 CSV
defillama-data defillama protocols --limit 100 -f csv > protocols.csv
# 导出收益池数据为 CSV
defillama-data defillama yields --limit 100 -f csv > yields.csv
```
---
## 🧪 测试
运行测试脚本验证功能：
```bash
node scripts/test.js
```
测试内容包括：
- 版本检查
- 健康检查
- TVL 查询
- 协议查询
- 排序功能
- 输入验证
---
## 📄 许可证
MIT License - Copyright (c) 2026 Antalpha
FILE:config/keys.example.js
/**
* API Keys Configuration - Example
*
* Copy this file to config/keys.js if you need local overrides.
*
* Note: DefiLlama does not require an API key for basic usage.
* This configuration file is optional but provides customization options.
*/
module.exports = {
// DefiLlama Configuration (No API key required for basic usage)
defillama: {
baseUrl: 'https://api.llama.fi'
},
// Global settings
settings: {
// Default cache duration in seconds
defaultCacheDuration: 300,
// Request timeout in milliseconds
timeout: 30000,
// Maximum retry attempts
maxRetries: 3,
// Retry delay in milliseconds
retryDelay: 1000,
// Enable debug logging
debug: process.env.DEBUG === 'true'
}
};
FILE:package.json
{
"name": "defillama-data-aggregator",
"version": "1.0.3",
"description": "Professional DeFi data aggregator with security validation - DeFi TVL, protocols, chains, and yields data",
"main": "src/index.js",
"bin": {
"defillama-data": "./src/index.js"
},
"scripts": {
"start": "node src/index.js",
"test": "node scripts/test.js",
"lint": "eslint src/**/*.js"
},
"keywords": [
"defillama",
"defi",
"tvl",
"data",
"aggregator",
"protocols",
"yields",
"crypto",
"blockchain",
"security",
"validation"
],
"author": "AntalphaAI",
"license": "MIT",
"dependencies": {
"axios": "^1.6.0",
"chalk": "^4.1.2",
"cli-table3": "^0.6.3",
"commander": "^11.1.0",
"node-cache": "^5.1.2"
},
"engines": {
"node": ">=16.0.0"
}
}
FILE:scripts/install.sh
#!/bin/bash
# DefiLlama Data Aggregator Installation Script
set -e
echo "🚀 Installing DefiLlama Data Aggregator..."
echo ""
# Check if Node.js is installed
if ! command -v node &> /dev/null; then
echo "❌ Node.js is not installed. Please install Node.js >= 16.0.0"
exit 1
fi
# Check Node.js version
NODE_VERSION=$(node -v | cut -d'v' -f2 | cut -d'.' -f1)
if [ "$NODE_VERSION" -lt 16 ]; then
echo "❌ Node.js version must be >= 16.0.0. Current version: $(node -v)"
exit 1
fi
echo "✓ Node.js version: $(node -v)"
echo ""
# Navigate to skill directory
cd "$(dirname "$0")"
# Install dependencies
echo "📦 Installing dependencies..."
npm install --silent
echo "✓ Dependencies installed"
echo ""
# Create config file if it doesn't exist
if [ ! -f "config/keys.js" ]; then
echo "🔑 Creating config file..."
cp config/keys.example.js config/keys.js
echo "✓ Config file created: config/keys.js"
echo ""
else
echo "✓ Config file already exists: config/keys.js"
echo ""
fi
# Link CLI command
echo "🔗 Linking CLI command..."
npm link
echo "✓ CLI command linked: defillama-data"
echo ""
# Test installation
echo "🧪 Testing installation..."
if command -v defillama-data &> /dev/null; then
echo "✓ Installation successful!"
echo ""
echo "📝 Usage:"
echo " defillama-data --help"
echo " defillama-data defillama tvl"
echo " defillama-data defillama protocols --limit 10 --format table"
echo " defillama-data defillama yields --min-apy 10 --limit 20"
echo " defillama-data health"
echo ""
else
echo "❌ Installation failed. CLI command not available."
exit 1
fi
FILE:scripts/test.js
#!/usr/bin/env node
/**
* Quick test script to verify installation
*/
const path = require('path');
// Load configuration
let config;
try {
config = require(path.join(__dirname, '../config/keys.js'));
} catch (error) {
console.error('⚠️ config/keys.js not found. Using example config.');
try {
config = require(path.join(__dirname, '../config/keys.example.js'));
} catch (fallbackError) {
console.error('❌ No configuration files found!');
process.exit(1);
}
}
console.log('✓ Configuration loaded');
// Import DefiLlama client (the only platform currently implemented)
const DefiLlamaClient = require('../src/platforms/defillama');
console.log('✓ DefiLlama client imported');
// Test initialization
const defillama = new DefiLlamaClient(config);
console.log('✓ DefiLlama client initialized');
console.log('');
// Quick health check
async function runTests() {
try {
console.log('Testing DefiLlama API connection...');
const tvl = await defillama.getTotalTvl();
console.log(`✓ TVL fetched: $(tvl.totalTvl / 1e9).toFixed(2)B`);
console.log('');
console.log('✅ Installation verified successfully!');
console.log('');
console.log('You can now use the defillama-data CLI:');
console.log(' node src/index.js --help');
console.log(' node src/index.js defillama tvl');
console.log(' node src/index.js defillama protocols --limit 10');
console.log('');
} catch (error) {
console.error('❌ Test failed:', error.message);
process.exit(1);
}
}
runTests();
FILE:src/index.js
#!/usr/bin/env node
/**
* DefiLlama Data Aggregator CLI
* Main entry point for the DefiLlama data aggregator
*/
const { Command } = require('commander');
const chalk = require('chalk');
const path = require('path');
// Load configuration
let config;
try {
config = require(path.join(__dirname, '../config/keys.js'));
} catch (error) {
console.error(chalk.yellow('Warning: config/keys.js not found. Using example config.'));
try {
config = require(path.join(__dirname, '../config/keys.example.js'));
} catch (fallbackError) {
console.error(chalk.red('Error: No configuration files found!'));
console.error(chalk.red('Please ensure either config/keys.js or config/keys.example.js exists.'));
process.exit(1);
}
}
// Import platform clients
const DefiLlamaClient = require('./platforms/defillama');
// Import utilities (only what's actually used)
const DataFormatter = require('./utils/formatter');
// Initialize clients
const defillama = new DefiLlamaClient(config);
// Create CLI program
const program = new Command();
program
.name('defillama-data')
.description('Professional DefiLlama data aggregator with security validation')
.version('1.0.3');
// ============================================================================
// Security & Validation Functions
// ============================================================================
/**
* Sanitize user input to prevent injection attacks
*/
function sanitizeInput(input, type = 'string') {
if (!input) return null;
switch (type) {
case 'string':
// Remove potentially dangerous characters
return String(input)
.replace(/[<>\"'`\\]/g, '') // Remove HTML/JS special chars
.trim()
.substring(0, 100); // Limit length
case 'number':
const num = parseFloat(input);
return isNaN(num) ? null : num;
case 'protocol':
// Strict validation for protocol names (alphanumeric, hyphens only)
if (!/^[a-zA-Z0-9-]+$/.test(input)) {
throw new Error(`Invalid protocol name: "input". Only alphanumeric characters and hyphens are allowed.`);
}
return input.toLowerCase().trim().substring(0, 50);
case 'chain':
// Strict validation for chain names
if (!/^[a-zA-Z0-9-\s]+$/.test(input)) {
throw new Error(`Invalid chain name: "input". Only alphanumeric characters, spaces, and hyphens are allowed.`);
}
return input.trim().substring(0, 50);
case 'category':
// Validate category names
if (!/^[a-zA-Z0-9-\s]+$/.test(input)) {
throw new Error(`Invalid category: "input". Only alphanumeric characters, spaces, and hyphens are allowed.`);
}
return input.trim().substring(0, 50);
default:
return input;
}
}
/**
* Sanitize API error response to prevent information leakage
*/
function sanitizeErrorData(data) {
if (!data) return null;
// Convert to string if object
const dataStr = typeof data === 'object' ? JSON.stringify(data) : String(data);
// Remove sensitive patterns (API keys, tokens, etc.)
return dataStr
.replace(/api[_-]?key["\s:]+["']?[\w-]+["']?/gi, '[REDACTED]')
.replace(/token["\s:]+["']?[\w.-]+["']?/gi, '[REDACTED]')
.replace(/secret["\s:]+["']?[\w.-]+["']?/gi, '[REDACTED]')
.replace(/password["\s:]+["']?[\w.-]+["']?/gi, '[REDACTED]')
.substring(0, 500); // Limit error message length
}
/**
* Parse and validate numeric input
*/
function parseNumber(value) {
const num = parseFloat(value);
return isNaN(num) ? null : num;
}
/**
* Validate numeric range (only if value is provided)
*/
function validateRange(value, min = 0, max = Infinity, fieldName = 'value') {
if (value === null || value === undefined) {
// Value not provided, skip validation
return null;
}
if (value < min || value > max) {
throw new Error(`fieldName must be between min and max`);
}
return value;
}
// Helper function to output data
function output(data, format) {
try {
switch (format) {
case 'json':
console.log(JSON.stringify(data, null, 2));
break;
case 'table':
console.log(DataFormatter.table(data));
break;
case 'csv':
console.log(DataFormatter.csv(data));
break;
case 'pretty':
default:
console.log(DataFormatter.pretty(data));
}
} catch (error) {
console.error(chalk.red('Error formatting output:'), error.message);
console.error(chalk.yellow('Falling back to JSON output...'));
console.log(JSON.stringify(data, null, 2));
}
}
// ============================================================================
// Error Handling
// ============================================================================
/**
* Enhanced error handler with proper sanitization and categorization
*/
function handleError(error) {
const timestamp = new Date().toISOString();
console.error(chalk.red(`\n❌ Error occurred at timestamp\n`));
console.error(chalk.red('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n'));
if (error.response) {
// API response error (4xx, 5xx)
const status = error.response.status;
const statusType = status >= 500 ? 'Server Error' : 'Client Error';
console.error(chalk.red(`🔴 statusType (status):`));
// Sanitize error data to prevent information leakage
const safeMessage = sanitizeErrorData(error.response.data);
if (safeMessage) {
console.error(chalk.yellow(safeMessage));
} else {
console.error(chalk.yellow('The request could not be processed'));
}
// Provide user-friendly suggestions
if (status === 404) {
console.error(chalk.cyan('\n💡 Suggestion: The requested resource was not found. Please check the protocol or chain name.'));
} else if (status === 429) {
console.error(chalk.cyan('\n💡 Suggestion: Rate limit exceeded. Please wait before making another request.'));
} else if (status === 500) {
console.error(chalk.cyan('\n💡 Suggestion: Server error. Please try again later.'));
}
} else if (error.request) {
// Network error (no response received)
console.error(chalk.red('🌐 Network Error:'));
console.error(chalk.yellow(error.message));
console.error(chalk.cyan('\n💡 Suggestion: Please check your internet connection and try again.'));
} else if (error.code === 'ECONNREFUSED') {
console.error(chalk.red('🌐 Connection Refused:'));
console.error(chalk.yellow('Unable to connect to the API server'));
console.error(chalk.cyan('\n💡 Suggestion: The service may be temporarily unavailable. Please try again later.'));
} else if (error.code === 'ETIMEDOUT') {
console.error(chalk.red('⏱️ Request Timeout:'));
console.error(chalk.yellow('The request took too long to complete'));
console.error(chalk.cyan('\n💡 Suggestion: Please try again or check your network connection.'));
} else {
// Other errors (validation, logic, etc.)
console.error(chalk.red('⚠️ Application Error:'));
console.error(chalk.yellow(error.message));
// Show stack trace in debug mode only
if (process.env.DEBUG === 'true') {
console.error(chalk.gray('\nStack Trace:'));
console.error(chalk.gray(error.stack));
}
}
console.error(chalk.red('\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n'));
// Exit with error code
process.exit(1);
}
// ============================================================================
// DefiLlama commands
// ============================================================================
const defillamaCmd = program
.command('defillama')
.description('DefiLlama data commands');
defillamaCmd
.command('tvl')
.description('Get total DeFi TVL')
.option('-f, --format <type>', 'Output format (json, table, csv, pretty)', 'pretty')
.action(async (options) => {
try {
const data = await defillama.getTotalTvl();
output(data, options.format);
} catch (error) {
handleError(error);
}
});
defillamaCmd
.command('protocol')
.description('Get protocol TVL')
.requiredOption('-n, --name <name>', 'Protocol name (e.g., aave, uniswap, compound)')
.option('-f, --format <type>', 'Output format (json, table, csv, pretty)', 'pretty')
.action(async (options) => {
try {
// Validate and sanitize protocol name
const protocolName = sanitizeInput(options.name, 'protocol');
const data = await defillama.getProtocolTvl(protocolName);
output(data, options.format);
} catch (error) {
handleError(error);
}
});
defillamaCmd
.command('protocols')
.description('Get all protocols')
.option('-c, --category <name>', 'Filter by category (e.g., lending, dex)')
.option('--min-tvl <amount>', 'Minimum TVL in USD', parseNumber)
.option('--limit <number>', 'Limit results (1-500)', parseNumber)
.option('--sort <field>', 'Sort by field (tvl, volume)', 'tvl')
.option('-f, --format <type>', 'Output format (json, table, csv, pretty)', 'pretty')
.action(async (options) => {
try {
// Validate and sanitize inputs
const filters = {};
if (options.category) {
filters.category = sanitizeInput(options.category, 'category');
}
if (options.minTvl !== null) {
filters.minTvl = validateRange(options.minTvl, 0, Infinity, 'Minimum TVL');
}
if (options.limit !== null) {
validateRange(options.limit, 1, 500, 'Limit');
}
// Validate sort field
const validSortFields = ['tvl'];
if (!validSortFields.includes(options.sort)) {
throw new Error(`Invalid sort field: "options.sort". Must be one of: validSortFields.join(', ')`);
}
const data = await defillama.getProtocols(filters);
// Validate data is an array
if (!Array.isArray(data)) {
throw new Error('API returned invalid data format: expected array');
}
// Apply sorting and limiting
let results = data;
if (results.length === 0) {
output([], options.format);
return;
}
if (options.sort === 'tvl') {
results = results.sort((a, b) => {
const tvlA = a.tvl || 0;
const tvlB = b.tvl || 0;
return tvlB - tvlA;
});
}
if (options.limit) {
results = results.slice(0, options.limit);
}
output(results, options.format);
} catch (error) {
handleError(error);
}
});
defillamaCmd
.command('chain')
.description('Get chain TVL')
.requiredOption('-n, --name <name>', 'Chain name (e.g., ethereum, solana, polygon)')
.option('-f, --format <type>', 'Output format (json, table, csv, pretty)', 'pretty')
.action(async (options) => {
try {
// Validate and sanitize chain name
const chainName = sanitizeInput(options.name, 'chain');
const data = await defillama.getChainTvl(chainName);
output(data, options.format);
} catch (error) {
handleError(error);
}
});
defillamaCmd
.command('yields')
.description('Get yield pools')
.option('--min-apy <number>', 'Minimum APY percentage (0-1000)', parseNumber)
.option('--min-tvl <number>', 'Minimum TVL in USD', parseNumber)
.option('--chain <name>', 'Filter by chain name (e.g., ethereum, arbitrum)')
.option('--stablecoin', 'Filter by stablecoin pools only')
.option('--limit <number>', 'Limit results (1-500)', parseNumber)
.option('-f, --format <type>', 'Output format (json, table, csv, pretty)', 'pretty')
.action(async (options) => {
try {
// Validate and sanitize inputs
const filters = {};
if (options.minApy !== null) {
filters.minApy = validateRange(options.minApy, 0, 1000, 'Minimum APY');
}
if (options.minTvl !== null) {
filters.minTvl = validateRange(options.minTvl, 0, Infinity, 'Minimum TVL');
}
if (options.chain) {
filters.chain = sanitizeInput(options.chain, 'chain');
}
if (options.stablecoin) {
filters.stablecoin = true;
}
if (options.limit !== null) {
validateRange(options.limit, 1, 500, 'Limit');
}
const data = await defillama.getPoolYields(filters);
let results = data;
if (options.limit) {
results = results.slice(0, options.limit);
}
output(results, options.format);
} catch (error) {
handleError(error);
}
});
// ============================================================================
// Health check command
// ============================================================================
program
.command('health')
.description('Check API health status')
.option('-q, --quiet', 'Quiet mode - only show summary')
.option('--timeout <ms>', 'Request timeout in milliseconds', parseNumber, 5000)
.action(async (options) => {
try {
const platforms = [
{ name: 'DefiLlama', client: defillama }
];
const results = {};
let healthyCount = 0;
let unhealthyCount = 0;
for (const platform of platforms) {
try {
// Actually call the API to check health
await platform.client.getTotalTvl();
results[platform.name] = { healthy: true };
healthyCount++;
} catch (error) {
results[platform.name] = { healthy: false, error: error.message };
unhealthyCount++;
}
}
if (options.quiet) {
console.log(`Healthy: healthyCount | Unhealthy: unhealthyCount | Total: platforms.length`);
} else {
output(results, 'json');
}
} catch (error) {
handleError(error);
}
});
// ============================================================================
// Status command
// ============================================================================
program
.command('status')
.description('Show system status and recommendations')
.action(() => {
console.log(chalk.blue('\n📊 System Status\n'));
console.log(chalk.green('✓ Available Platforms:'));
console.log(' - DefiLlama (DeFi data aggregator)');
console.log(chalk.blue('\nRecommendations:'));
console.log(chalk.green(' All platforms are configured and ready to use!'));
console.log(chalk.yellow(' Run `defillama-data health` to check real-time status'));
});
// ============================================================================
// Parse command line arguments
// ============================================================================
program.parse(process.argv);
// Show help if no command provided
if (!process.argv.slice(2).length) {
program.outputHelp();
}
FILE:src/platforms/defillama.js
/**
* DefiLlama API Client
* https://docs.llama.fi/
*/
const ApiClient = require('../utils/api-client');
class DefiLlamaClient {
constructor(config) {
this.config = config;
this.client = new ApiClient({
...config.settings,
baseUrl: config.defillama.baseUrl
});
}
/**
* Get total DeFi TVL (sum of all chains)
*/
async getTotalTvl() {
const chains = await this.client.request({
url: `this.config.defillama.baseUrl/v2/chains`,
cacheDuration: 3600 // Cache for 1 hour
});
// Calculate total TVL from all chains
const totalTvl = chains.reduce((sum, chain) => sum + (chain.tvl || 0), 0);
return {
totalTvl: totalTvl,
chains: chains,
timestamp: new Date().toISOString()
};
}
/**
* Get protocol TVL
*/
async getProtocolTvl(protocolName) {
return this.client.request({
url: `this.config.defillama.baseUrl/protocol/protocolName`,
cacheDuration: 300 // Cache for 5 minutes
});
}
/**
* Get all protocols
*/
async getProtocols(filters = {}) {
return this.client.request({
url: `this.config.defillama.baseUrl/protocols`,
params: filters,
cacheDuration: 600 // Cache for 10 minutes
});
}
/**
* Get chain TVL by name
*/
async getChainTvl(chainName) {
const chains = await this.getChains();
// Find the chain by name (case-insensitive)
const chain = chains.find(c =>
c.name.toLowerCase() === chainName.toLowerCase() ||
c.gecko_id === chainName.toLowerCase() ||
c.tokenSymbol?.toLowerCase() === chainName.toLowerCase()
);
if (!chain) {
throw new Error(`Chain "chainName" not found. Available chains: chains.slice(0, 10).map(c => c.name).join(', ')...`);
}
return {
name: chain.name,
gecko_id: chain.gecko_id,
tokenSymbol: chain.tokenSymbol,
tvl: chain.tvl,
chainId: chain.chainId,
cmcId: chain.cmcId
};
}
/**
* Get all chains
*/
async getChains() {
return this.client.request({
url: `this.config.defillama.baseUrl/v2/chains`,
cacheDuration: 3600 // Cache for 1 hour
});
}
/**
* Get protocol details
*/
async getProtocolDetails(name) {
return this.client.request({
url: `this.config.defillama.baseUrl/protocol/name`,
cacheDuration: 600 // Cache for 10 minutes
});
}
/**
* Get TVL historical data
*/
async getTvlHistory(protocol, timeframe = '24h') {
return this.client.request({
url: `this.config.defillama.baseUrl/protocol/protocol`,
cacheDuration: 300 // Cache for 5 minutes
});
}
/**
* Get yields by pool
* Uses https://yields.llama.fi/pools endpoint
*/
async getPoolYields(filters = {}) {
const response = await this.client.request({
url: `https://yields.llama.fi/pools`,
cacheDuration: 300 // Cache for 5 minutes
});
// Extract pools from response (API returns {status, data} structure)
let poolsList = [];
if (response && response.data && Array.isArray(response.data)) {
poolsList = response.data;
} else if (Array.isArray(response)) {
poolsList = response;
}
// Filter the pools based on the provided filters
let filteredPools = poolsList;
if (filters.minApy !== undefined && filters.minApy > 0) {
filteredPools = filteredPools.filter(pool => pool.apy >= filters.minApy);
}
if (filters.minTvl !== undefined && filters.minTvl > 0) {
filteredPools = filteredPools.filter(pool => pool.tvlUsd >= filters.minTvl);
}
if (filters.chain) {
filteredPools = filteredPools.filter(pool =>
pool.chain && pool.chain.toLowerCase() === filters.chain.toLowerCase()
);
}
if (filters.stablecoin) {
filteredPools = filteredPools.filter(pool => pool.stablecoin === true);
}
if (filters.query) {
const queryLower = filters.query.toLowerCase();
filteredPools = filteredPools.filter(pool =>
(pool.project && pool.project.toLowerCase().includes(queryLower)) ||
(pool.symbol && pool.symbol.toLowerCase().includes(queryLower))
);
}
// Sort by APY descending (only if APY is a valid number)
filteredPools.sort((a, b) => {
const apyA = typeof a.apy === 'number' ? a.apy : 0;
const apyB = typeof b.apy === 'number' ? b.apy : 0;
return apyB - apyA;
});
return filteredPools;
}
/**
* Get bridge volumes
*/
async getBridgeVolumes() {
return this.client.request({
url: `this.config.defillama.baseUrl/v2/bridges/volumes`,
cacheDuration: 3600 // Cache for 1 hour
});
}
/**
* Get stablecoin pegs
*/
async getStablecoinPegs() {
return this.client.request({
url: `this.config.defillama.baseUrl/v2/stablecoins`,
cacheDuration: 600 // Cache for 10 minutes
});
}
/**
* Get oracle prices
*/
async getOraclePrices() {
return this.client.request({
url: `this.config.defillama.baseUrl/v2/prices`,
cacheDuration: 60 // Cache for 1 minute
});
}
/**
* Get token price
*/
async getTokenPrice(token) {
return this.client.request({
url: `this.config.defillama.baseUrl/prices/current/token`,
cacheDuration: 60 // Cache for 1 minute
});
}
/**
* Get protocol categories
*/
async getProtocolCategories() {
return this.client.request({
url: `this.config.defillama.baseUrl/v2/protocol/categories`,
cacheDuration: 86400 // Cache for 24 hours
});
}
}
module.exports = DefiLlamaClient;
FILE:src/utils/api-client.js
/**
* API Client with caching, retry logic, and error handling
*/
const axios = require('axios');
const NodeCache = require('node-cache');
const https = require('https');
class ApiClient {
constructor(config = {}) {
this.cache = new NodeCache({
stdTTL: config.defaultCacheDuration || 300,
checkperiod: 60
});
this.timeout = config.timeout || 30000;
this.maxRetries = config.maxRetries || 3;
this.retryDelay = config.retryDelay || 1000;
this.debug = config.debug || false;
this.enableCache = config.enableCache !== false; // Default true
// IP direct connection configuration
this.useIpDirect = config.useIpDirect || false;
this.ipBaseUrl = config.ipBaseUrl || null;
this.hostHeader = config.hostHeader || null;
this.rejectUnauthorized = config.rejectUnauthorized !== false; // Default true
}
/**
* Make HTTP request with caching and retry logic
*/
async request(options) {
const cacheKey = this.getCacheKey(options);
// Check cache first (if enabled)
if (this.enableCache && !options.noCache && this.cache.has(cacheKey)) {
this.log('Cache hit', cacheKey);
return this.cache.get(cacheKey);
}
// Make request with retry logic
try {
const response = await this.makeRequest(options);
// Cache the response (if enabled)
if (this.enableCache && !options.noCache) {
this.cache.set(cacheKey, response, options.cacheDuration);
}
return response;
} catch (error) {
throw this.handleError(error, options);
}
}
/**
* Make actual HTTP request with retries
*/
async makeRequest(options, retryCount = 0) {
try {
// Build request configuration
const requestConfig = {
method: options.method || 'GET',
headers: options.headers || {},
params: options.params || {},
data: options.data || {},
timeout: this.timeout
};
// IP direct mode: replace URL and set Host header
if (this.useIpDirect && this.ipBaseUrl && options.url) {
// Replace baseUrl with IP direct address
const originalUrl = new URL(options.url);
const ipUrl = new URL(this.ipBaseUrl);
// Keep original path and query params, only replace protocol and host
const newUrl = `this.ipBaseUrloriginalUrl.pathnameoriginalUrl.search`;
requestConfig.url = newUrl;
// Set Host header (SNI)
if (this.hostHeader) {
requestConfig.headers['Host'] = this.hostHeader;
}
// For HTTPS IP direct, need to disable certificate verification (certificate is for domain)
if (ipUrl.protocol === 'https:') {
requestConfig.httpsAgent = new https.Agent({
rejectUnauthorized: false
});
}
this.log('IP Direct:', `options.url -> newUrl`);
} else {
requestConfig.url = options.url;
}
const response = await axios(requestConfig);
return response.data;
} catch (error) {
// Retry on network errors or 5xx errors
if (retryCount < this.maxRetries && this.shouldRetry(error)) {
this.log(`Retry retryCount + 1/this.maxRetries`, options.url);
await this.sleep(this.retryDelay * (retryCount + 1));
return this.makeRequest(options, retryCount + 1);
}
throw error;
}
}
/**
* Determine if request should be retried
*/
shouldRetry(error) {
if (error.code === 'ECONNABORTED' || error.code === 'ETIMEDOUT') {
return true;
}
if (error.response && error.response.status >= 500) {
return true;
}
return false;
}
/**
* Handle API errors
*/
handleError(error, options) {
if (error.response) {
// API responded with error status
const status = error.response.status;
const message = error.response.data?.message || error.response.statusText;
if (status === 401) {
return new Error('Authentication failed: Invalid API key');
} else if (status === 429) {
return new Error('Rate limit exceeded: Too many requests');
} else if (status === 404) {
return new Error(`Resource not found: options.url`);
} else if (status >= 500) {
return new Error(`Server error: status message`);
} else {
return new Error(`API error (status): message`);
}
} else if (error.request) {
// Request made but no response received
return new Error('Network error: No response received from server');
} else {
// Error in setting up request
return new Error(`Request error: error.message`);
}
}
/**
* Generate cache key from request options
*/
getCacheKey(options) {
const key = {
url: options.url,
method: options.method || 'GET',
params: options.params || {},
data: options.data || {}
};
return JSON.stringify(key);
}
/**
* Clear cache
*/
clearCache(pattern = null) {
if (pattern) {
const keys = this.cache.keys();
keys.forEach(key => {
if (key.includes(pattern)) {
this.cache.del(key);
}
});
} else {
this.cache.flushAll();
}
}
/**
* Get cache statistics
*/
getCacheStats() {
return this.cache.getStats();
}
/**
* Sleep helper
*/
sleep(ms) {
return new Promise(resolve => setTimeout(resolve, ms));
}
/**
* Debug logging
*/
log(...args) {
if (this.debug) {
console.log('[ApiClient]', ...args);
}
}
}
module.exports = ApiClient;
FILE:src/utils/formatter.js
/**
* Data formatting utilities
*/
const chalk = require('chalk');
const Table = require('cli-table3');
class DataFormatter {
/**
* Format data as JSON
*/
static json(data) {
return JSON.stringify(data, null, 2);
}
/**
* Format data as pretty JSON with colors
*/
static pretty(data) {
const formatValue = (value) => {
if (typeof value === 'number') {
return chalk.green(value.toLocaleString());
} else if (typeof value === 'string') {
return chalk.yellow(value);
} else if (typeof value === 'boolean') {
return value ? chalk.green('✓') : chalk.red('✗');
} else if (value === null || value === undefined) {
return chalk.gray('N/A');
} else if (Array.isArray(value)) {
return `[value.map(formatValue).join(', ')]`;
} else if (typeof value === 'object') {
const entries = Object.entries(value)
.map(([k, v]) => ` chalk.cyan(k): formatValue(v)`)
.join('\n');
return `{\nentries\n}`;
}
return value;
};
return JSON.stringify(data, null, 2)
.replace(/"([^"]+)":/g, (match, key) => `"chalk.cyan(key)":`)
.replace(/: ("[^"]+")/g, (match, value) => `: formatValue(value.slice(1, -1))`)
.replace(/: (\d+)/g, (match, value) => `: formatValue(parseInt(value))`);
}
/**
* Format data as table
*/
static table(data, options = {}) {
if (!data || (Array.isArray(data) && data.length === 0)) {
return chalk.yellow('No data available');
}
const items = Array.isArray(data) ? data : [data];
const keys = options.columns || Object.keys(items[0]);
const table = new Table({
head: keys.map(k => chalk.cyan(k)),
style: {
head: [],
border: ['grey']
}
});
items.forEach(item => {
const row = keys.map(key => this.formatCell(item[key]));
table.push(row);
});
return table.toString();
}
/**
* Format table cell
*/
static formatCell(value) {
if (value === null || value === undefined) {
return chalk.gray('N/A');
}
if (typeof value === 'number') {
// Format large numbers
if (value >= 1e9) {
return `$(value / 1e9).toFixed(2)B`;
} else if (value >= 1e6) {
return `$(value / 1e6).toFixed(2)M`;
} else if (value >= 1e3) {
return `$(value / 1e3).toFixed(2)K`;
} else if (value < 1 && value > 0) {
return `$value.toFixed(4)`;
} else {
return value.toLocaleString();
}
}
if (typeof value === 'string') {
// Truncate long strings
return value.length > 30 ? `value.substring(0, 27)...` : value;
}
if (typeof value === 'boolean') {
return value ? chalk.green('Yes') : chalk.red('No');
}
return String(value);
}
/**
* Format data as CSV
*/
static csv(data) {
if (!data || (Array.isArray(data) && data.length === 0)) {
return '';
}
const items = Array.isArray(data) ? data : [data];
const keys = Object.keys(items[0]);
const escapeCsv = (value) => {
if (value === null || value === undefined) return '';
const str = String(value);
if (str.includes(',') || str.includes('"') || str.includes('\n')) {
return `"str.replace(/"/g, '""')"`;
}
return str;
};
const header = keys.join(',');
const rows = items.map(item =>
keys.map(key => escapeCsv(item[key])).join(',')
);
return [header, ...rows].join('\n');
}
/**
* Format percentage
*/
static percentage(value, decimals = 2) {
if (value === null || value === undefined) {
return chalk.gray('N/A');
}
const formatted = `''value.toFixed(decimals)%`;
return value > 0 ? chalk.green(formatted) : value < 0 ? chalk.red(formatted) : chalk.yellow(formatted);
}
/**
* Format currency
*/
static currency(value, decimals = 2) {
if (value === null || value === undefined) {
return chalk.gray('N/A');
}
const formatted = `$value.toFixed(decimals)`;
return value > 0 ? chalk.green(formatted) : chalk.red(formatted);
}
/**
* Format date
*/
static date(timestamp) {
if (!timestamp) {
return chalk.gray('N/A');
}
const date = new Date(timestamp);
return chalk.yellow(date.toLocaleString());
}
/**
* Format change indicator
*/
static change(value) {
const icon = value > 0 ? '↑' : value < 0 ? '↓' : '→';
const color = value > 0 ? 'green' : value < 0 ? 'red' : 'yellow';
return chalk[color](`icon Math.abs(value).toFixed(2)%`);
}
}
module.exports = DataFormatter;
Meme 代币财富基因检测系统。输入任意代币名称（如 PEPE、DOGE、$SHIB），基于实时 Web 情绪数据输出四维分析报告与 🌟钻石手/🌙登月/🗑️纸手/💩屎币 评级。支持主流币自动识别（BTC/ETH/SOL），无数据时不幻觉。触发词：meme 分析、代币评级、财富基因、PEPE分析、meme...
---
name: meme-token-analyzer
version: 2.0.0
description: "Meme 代币财富基因检测系统。输入任意代币名称（如 PEPE、DOGE、$SHIB），基于实时 Web 情绪数据输出四维分析报告与 🌟钻石手/🌙登月/🗑️纸手/💩屎币 评级。支持主流币自动识别（BTC/ETH/SOL），无数据时不幻觉。触发词：meme 分析、代币评级、财富基因、PEPE分析、meme coin、rug check、meme token analyze、wealth gene、meme coin rating"
author: AntalphaAI
license: MIT
metadata: {"repository":"https://github.com/AntalphaAI/meme-token-analyzer","mcp":{"url":"https://mcp-skills.ai.antalpha.com/mcp","tools":[{"name":"meme-analyze","description":"分析 Meme 代币财富基因，输出 🌟/🌙/🗑️/💩 评级报告"}]}}
---
# Meme Token Analyzer 🚀
> **Meme 代币财富基因检测系统 V2**
> 基于 Antalpha MCP Server，接入 llm-proxy 统一管控，全面替代 Coze 方案
---
## 使用前提
需先完成 Agent 注册（获取 `agent_id`）：
```
调用 antalpha-register 工具完成注册，保存 agent_id
```
---
## 核心能力
- 🔍 **实时 Web 搜索**：Tavily API，过滤最近 30 天数据，带 AI 摘要
- 🤖 **LLM 多维分析**：四维分析框架，via llm-proxy 统一计量计费
- 💎 **财富基因评级**：四档精准评级，Degen 风格毒舌点评
- 🧠 **主流币识别**：自动检测 BTC/ETH/SOL 等并切换分析视角
- 🚫 **无幻觉设计**：无数据时明确说明，不编造价格或社区数据
---
## 触发场景
| 用户说 | 自动执行 |
|--------|----------|
| "帮我分析一下 PEPE" | `meme-analyze` |
| "DOGE 的财富基因是什么" | `meme-analyze` |
| "$SHIB 值得买吗" | `meme-analyze` |
| "这个 meme 币怎么样：BONK" | `meme-analyze` |
| "BTC 算 meme 吗" | `meme-analyze`（自动切换价值币视角） |
---
## MCP Tool 说明
### `meme-analyze`
**输入参数：**
| 参数 | 类型 | 说明 |
|------|------|------|
| `token_name` | string | 代币名称或符号，如 PEPE、$SHIB、Bitcoin |
| `agent_id` | string (UUID) | 从 antalpha-register 获取的 Agent ID |
**输出结构：**
```json
{
"token": "PEPE",
"is_major_coin": false,
"major_coin_warning": null,
"rating": "moonshot",
"rating_emoji": "🌙",
"rating_label": "登月",
"report": {
"narrative_magic": "叙事魔力分析...",
"community_hype": "社区炒作能力...",
"risk_warning": "风险提示..."
},
"search_summary": "Tavily AI 摘要...",
"data_freshness": "ok",
"sources": ["https://...", "https://..."],
"disclaimer": "本报告仅供娱乐和教育目的，不构成投资建议。"
}
```
**评级标准：**
| 评级值 | Emoji | 中文 | 含义 |
|--------|-------|------|------|
| `diamond_hand` | 🌟 | 钻石手 | 顶级叙事 + 强社区 + VC 背书，万倍潜力 |
| `moonshot` | 🌙 | 登月 | 有效叙事 + 活跃社区，百倍合理预期 |
| `paper_hand` | 🗑️ | 纸手 | 叙事薄弱，高风险 |
| `shitcoin` | 💩 | 屎币 | 无叙事无社区，立即远离 |
---
## 输出示例
```
🌙 PEPE — 登月
🎯 叙事魔力：PEPE 是互联网最具代表性的 Meme 形象，文化底蕴深厚，叙事自带传播力。
📢 社区炒作：Twitter/X 活跃度极高，持仓地址数量庞大，Degen 文化认同感强。
⚠️ 风险提示：高度投机，价格波动极大，注意仓位控制。
📊 数据新鲜度：✅ 充足
💡 本报告仅供娱乐和教育目的，不构成投资建议。DYOR。
```
---
## 注意事项
- 分析结果仅供娱乐和教育参考，不构成任何投资建议
- 主流币（BTC/ETH/SOL 等）会自动切换为价值币分析视角
- 冷门代币可能因 Web 数据不足而返回 `data_freshness: "no_data"`
---
## 技术架构
- **后端**：NestJS + Antalpha MCP Server
- **LLM**：via llm-proxy（统一计量，`fast-cheap` tier）
- **搜索**：Tavily API（30天时间过滤，带 AI 摘要）
- **版本**：v2.0.0（完全替代 Coze LangGraph 方案）
---
**Maintainer**: AntalphaAI | **License**: MIT
FILE:README.md
[🇺🇸 English](#english) · [🇨🇳 中文](#chinese)
---
<a name="english"></a>
# Meme Token Analyzer 🚀
> **The Ultimate Meme Token "Wealth Gene" Detection System — V2**
>
> Rebuilt on Antalpha MCP Server with llm-proxy integration. No more Coze dependency — full cost visibility and control.
## 🚀 Installation
```bash
openclaw skill install https://github.com/AntalphaAI/meme-token-analyzer
```
## ✨ What's New in V2
- ✅ **Antalpha MCP Server** — same infrastructure as smart-money, web3-investor
- ✅ **llm-proxy** — unified LLM billing, per-agent metering
- ✅ **Tavily Search** — real-time web sentiment with 30-day filter
- ❌ Removed: Coze SDK dependency, AI image generation (cost reduction)
## 🎯 Features
- **🔍 Real-Time Web Search**: Tavily API, 30-day freshness filter, AI-powered summary
- **🤖 Multimodal AI Analysis**: 4-dimensional wealth gene framework via llm-proxy
- **💎 Wealth Gene Rating**: 4-tier rating with Degen-style commentary
- **🧠 Major Coin Detection**: Auto-detects BTC/ETH/SOL and switches analysis perspective
- **🚫 No Hallucination**: Explicitly states when data is insufficient
## 🏆 Rating System
| Rating | Emoji | Meaning | Potential |
|--------|-------|---------|-----------|
| `diamond_hand` | 🌟 | Diamond Hand | Legendary — 10000x potential |
| `moonshot` | 🌙 | Moonshot | High — 100x expected |
| `paper_hand` | 🗑️ | Paper Hand | Risky — likely to dump |
| `shitcoin` | 💩 | Shitcoin | Avoid — stay far away |
## 📊 Example Output
```
🌙 PEPE — Moonshot
🎯 Narrative Magic: PEPE is one of the internet's most iconic meme characters with deep cultural roots and viral potential.
📢 Community Hype: Extremely active on Twitter/X, massive holder base, strong Degen culture alignment.
⚠️ Risk Warning: Highly speculative, extreme price volatility — manage position size carefully.
📊 Data Freshness: ✅ Good
💡 This report is for entertainment and educational purposes only. Not financial advice. DYOR.
```
## 🔧 Prerequisites
Register your agent first:
```
Call antalpha-register to get your agent_id
```
## ⚠️ Disclaimer
This tool is for **entertainment and educational purposes only**. Not financial advice. Always DYOR before investing in any cryptocurrency.
---
<a name="chinese"></a>
# Meme Token 分析器 🚀
> **终极 Meme 代币"财富基因"检测系统 — V2**
>
> 基于 Antalpha MCP Server 重构，接入 llm-proxy 统一管控，彻底告别 Coze 依赖，成本完全可见可控。
## 🚀 安装
```bash
openclaw skill install https://github.com/AntalphaAI/meme-token-analyzer
```
## ✨ V2 新特性
- ✅ **Antalpha MCP Server** — 与 smart-money、web3-investor 同等基础设施
- ✅ **llm-proxy 接入** — 统一 LLM 计费，按 Agent 计量
- ✅ **Tavily 搜索** — 实时 Web 情绪数据，30 天新鲜度过滤
- ❌ 移除：Coze SDK 依赖、AI 图像生成（降本）
## 🎯 核心功能
- **🔍 实时 Web 搜索**：Tavily API，30天时间过滤，带 AI 摘要
- **🤖 多维 LLM 分析**：四维财富基因分析框架，via llm-proxy
- **💎 财富基因评级**：四档精准评级，Degen 风格毒舌点评
- **🧠 主流币识别**：自动检测 BTC/ETH/SOL 并切换分析视角
- **🚫 无幻觉设计**：无数据时明确说明，不编造
## 🏆 评级体系
| 评级 | Emoji | 含义 | 潜力 |
|------|-------|------|------|
| `diamond_hand` | 🌟 | 钻石手 | 传奇 — 万倍潜力 |
| `moonshot` | 🌙 | 登月 | 高 — 百倍预期 |
| `paper_hand` | 🗑️ | 纸手 | 风险大 — 可能归零 |
| `shitcoin` | 💩 | 屎币 | 远离 — 立即撤退 |
## 📊 输出示例
```
🌙 PEPE — 登月
🎯 叙事魔力：PEPE 是互联网最具代表性的 Meme 形象，文化底蕴深厚，叙事自带传播力。
📢 社区炒作：Twitter/X 活跃度极高，持仓地址数量庞大，Degen 文化认同感强。
⚠️ 风险提示：高度投机，价格波动极大，注意仓位控制。
📊 数据新鲜度：✅ 充足
💡 本报告仅供娱乐和教育目的，不构成投资建议。DYOR。
```
## 🔧 使用前提
需先完成 Agent 注册：
```
调用 antalpha-register 获取 agent_id
```
## 技术架构
- 后端：NestJS + Antalpha MCP Server
- LLM：via llm-proxy（`fast-cheap` tier，temperature=0.7）
- 搜索：Tavily API（30天过滤 + AI 摘要）
- 版本：v2.0.0
## ⚠️ 免责声明
本工具仅供**娱乐和教育目的**，不构成任何投资建议。投资有风险，请务必 DYOR（自行研究）。
---
**Maintainer**: AntalphaAI | **License**: MIT
Web3 token security scanner with expert cross-validation engine. Detects honeypots, rug pulls, and contract risks across Ethereum, BSC, Polygon, and other EV...
---
name: anti-rug-cn
version: 3.1.0
description: "Web3 token security scanner with expert cross-validation engine. Detects honeypots, rug pulls, and contract risks across Ethereum, BSC, Polygon, and other EVM chains."
author: Antalpha AI Team
requires: [python>=3.8, requests>=2.28.0]
metadata:
repository: https://github.com/ZorroShao/anti-rug
install:
type: python
command: pip install -r requirements.txt
env: []
---
# Web3 Token Security Scanner (Anti-Rug)
**Maintainer: Antalpha AI Team**
A professional-grade token contract security analyzer featuring scenario-based classification and cross-validation engine.
## Overview
This tool performs comprehensive security analysis of token contracts with:
- **Scenario Classification**: Automatically categorizes tokens (A: Pegged Assets, B: Eco Tokens, C: Meme Coins)
- **Cross-Validation Engine**: Analyzes relationships between indicators (neutralized/amplified/contextual)
- **Dynamic Risk Scoring**: Weighted scoring system adapted to token type
- **Fatal Finding Detection**: One-strike rules for critical vulnerabilities
## Supported Chains
- Ethereum (chain_id: 1)
- BNB Smart Chain (chain_id: 56)
- Polygon (chain_id: 137)
- Arbitrum One (chain_id: 42161)
- Base (chain_id: 8453)
- Optimism (chain_id: 10)
- Avalanche C-Chain (chain_id: 43114)
- Solana (chain_id: solana)
## Installation
```bash
git clone https://github.com/ZorroShao/anti-rug.git
cd anti-rug
pip install -r requirements.txt
```
## Usage
```bash
python scripts/check_token.py --chain_id 56 --contract_address 0x...
```
## Scenario Classification
### Scenario A: Pegged/Stable Assets
Examples: USDT, USDC, WETH, WBNB
- Mintable: ✅ Expected for peg maintenance
- Owner: ✅ Institution custody is normal
- Blacklist: ✅ Compliance requirement
### Scenario B: Ecosystem Tokens
Examples: UNI, AAVE, established DeFi
- Proxy: ✅ Acceptable for upgradeability
- Treasury: ✅ Protocol-owned liquidity expected
### Scenario C: Meme/Unknown Tokens
- All permissions: ⚠️ Treated as potential rug tools
- Strictest evaluation applied
## Risk Severity Levels
| Score | Level | Action |
|-------|-------|--------|
| 0-24 | Low | ✅ Base security passed |
| 25-49 | Low-Medium | 🟡 Minor concerns |
| 50-74 | Medium | 🟡 Caution required |
| 75-100 | High | 🔴 Dangerous |
| Fatal | Critical | 🛑 Do not buy |
## Architecture
```
config.py # Centralized configuration
exceptions.py # Custom exception classes
validators/ # Cross-validation rules (modular)
cv_mint_ownership.py
cv_concentration.py
cv_proxy.py
cv_tax_scenario.py
tests/ # Unit tests
scripts/
check_token.py # Main entry point
```
## License
MIT License - See LICENSE file
FILE:CHANGELOG.md
# Changelog
## [3.1.0] - 2026-03-30
### Major Refactoring
#### Architecture Improvements
- **Modular Design**: Split monolithic script into focused modules
- `config.py` - Centralized configuration management
- `exceptions.py` - Custom exception hierarchy
- `validators/` - Cross-validation rules as independent modules
- `tests/` - Unit test suite
#### Code Quality
- **Strategy Pattern**: Implemented validator registry for cross-validation rules
- Each CV rule is now an independent, testable function
- Easy to add new validators via `@validator` decorator
- **Refactored API Client**: Split `fetch_goplus()` into focused methods
- `_make_request()` - HTTP request handling
- `_parse_response()` - Response parsing
- `GoPlusClient` class encapsulates retry logic
- **Rule Engine**: Replaced long if-elif chains with configurable `FATAL_RULES`
- Rules defined as data in config.py
- Easy to extend without modifying core logic
#### Maintainability
- **Type Hints**: Added throughout codebase for better IDE support
- **Documentation**: Enhanced docstrings following Google style
- **Error Handling**: Custom exception classes for precise error categorization
- `NetworkError` - Connection/timeout issues
- `APIError` - API response errors
- `ContractNotFoundError` - Missing contracts
- `UnsupportedChainError` - Invalid chain IDs
#### Testing
- **Unit Tests**: Added comprehensive test suite
- Configuration validation
- Validator logic tests
- Exception handling tests
- Fatal rules engine tests
#### Metadata
- **Complete SKILL.md**: Added version, author, repository metadata
- **requirements.txt**: Explicit dependency versions
- **English Documentation**: Translated for ClawHub compatibility
### File Structure Changes
```
Before (v3.0):
├── scripts/
│ └── check_token.py (819 lines)
├── SKILL.md
└── README.md
After (v3.1):
├── scripts/
│ ├── __init__.py
│ └── check_token.py (455 lines, -44%)
├── validators/
│ ├── __init__.py
│ ├── cv_mint_ownership.py
│ ├── cv_concentration.py
│ ├── cv_proxy.py
│ └── cv_tax_scenario.py
├── tests/
│ └── test_anti_rug.py
├── config.py
├── exceptions.py
├── requirements.txt
├── SKILL.md (English + metadata)
└── README.md
```
### Statistics
- Total lines: 1131 → 1083 (-4%)
- Main script: 819 → 455 lines (-44%)
- Test coverage: 0% → ~30% (framework established)
- Modules: 1 → 9 (+800% organization)
### Backward Compatibility
- CLI interface unchanged
- JSON output format unchanged
- All existing functionality preserved
FILE:README.md
# Anti-Rug Token Security Checker
**Maintainer: Antalpha AI Team**
A professional-grade Web3 token contract security analyzer featuring scenario-based classification and cross-validation engine.
## Overview
This tool performs comprehensive security analysis of token contracts with:
- **Scenario Classification**: Automatically categorizes tokens (A: Pegged Assets, B: Eco Tokens, C: Meme Coins)
- **Cross-Validation Engine**: Analyzes relationships between indicators (neutralized/amplified/contextual)
- **Dynamic Risk Scoring**: Weighted scoring system adapted to token type
- **Fatal Finding Detection**: One-strike rules for critical vulnerabilities
## Supported Chains
- Ethereum (chain_id: 1)
- BNB Smart Chain (chain_id: 56)
- Polygon (chain_id: 137)
- Arbitrum One (chain_id: 42161)
- Base (chain_id: 8453)
- Optimism (chain_id: 10)
- Avalanche C-Chain (chain_id: 43114)
- Solana (chain_id: solana)
## Installation
```bash
git clone https://github.com/AntalphaAI/anti-rug.git
cd anti-rug
pip install -r requirements.txt
```
## Usage
```bash
python scripts/check_token.py --chain_id 56 --contract_address 0x...
```
### With Custom API Gateway
```bash
python scripts/check_token.py --chain_id 56 --contract_address 0x... --api_gateway https://your-proxy.com
```
## Scenario Classification
### Scenario A: Pegged/Stable Assets
Examples: USDT, USDC, WETH, WBNB
- Mintable: ✅ Expected for peg maintenance
- Owner: ✅ Institution custody is normal
- Blacklist: ✅ Compliance requirement
### Scenario B: Ecosystem Tokens
Examples: UNI, AAVE, established DeFi
- Proxy: ✅ Acceptable for upgradeability
- Treasury: ✅ Protocol-owned liquidity expected
### Scenario C: Meme/Unknown Tokens
- All permissions: ⚠️ Treated as potential rug tools
- Strictest evaluation applied
## Risk Severity Levels
| Score | Level | Action |
|-------|-------|--------|
| 0-24 | Low | ✅ Base security passed |
| 25-49 | Low-Medium | 🟡 Minor concerns |
| 50-74 | Medium | 🟡 Caution required |
| 75-100 | High | 🔴 Dangerous |
| Fatal | Critical | 🛑 Do not buy |
## Architecture
```
anti-rug/
├── config.py # Centralized configuration
├── exceptions.py # Custom exception classes
├── requirements.txt # Dependencies
├── scripts/
│ └── check_token.py # Main entry point
├── validators/ # Cross-validation rules (modular)
│ ├── cv_mint_ownership.py
│ ├── cv_concentration.py
│ ├── cv_proxy.py
│ └── cv_tax_scenario.py
└── tests/ # Unit tests
└── test_anti_rug.py
```
## Key Features
### 1. Cross-Validation Engine
Instead of listing raw indicators, the tool analyzes relationships:
- **Neutralized**: Risk is mitigated (e.g., mintable but owner is dead)
- **Amplified**: Risks compound (e.g., high tax + meme coin)
- **Contextual**: Explained by context (e.g., DEX pools in concentration)
### 2. Rule-Based Fatal Detection
Critical vulnerabilities trigger immediate warnings:
- Honeypot (cannot sell)
- Self-destruct function
- Hidden owner
- Extreme sell tax (>50%)
### 3. Scenario-Aware Scoring
Different weights for different token types:
- Pegged assets: Focus on taxes and honeypot
- Ecosystem tokens: Balanced evaluation
- Meme coins: Strict scrutiny of all permissions
## Example Output
```json
{
"scenario_classification": {
"scenario": "B",
"label": "Ecosystem Token / DeFi / GameFi"
},
"risk_score": {
"final_score": 27.0,
"dimension_scores": {
"contract_security": 0,
"tax_risk": 0,
"liquidity_risk": 0,
"concentration_risk": 80
}
},
"final_verdict": {
"risk_level": "LOW_MEDIUM",
"verdict": "🟡 Minor risk. Research team background before investing."
}
}
```
## Testing
```bash
python -m pytest tests/
```
## Changelog
See [CHANGELOG.md](CHANGELOG.md) for version history.
## License
MIT License - See [LICENSE](LICENSE) file
## Disclaimer
This tool analyzes on-chain contract security only and does not constitute investment advice. Contract safety ≠ project value. Always conduct your own research on team background, liquidity, and market conditions.
---
**Maintainer**: Antalpha AI Team
**Repository**: https://github.com/AntalphaAI/anti-rug
FILE:config.py
"""
Configuration module for Anti-Rug Token Security Checker.
All hardcoded values extracted for maintainability.
"""
from typing import Set, List, Dict, Any
# ══════════════════════════════════════════════════════════════
# API Configuration
# ══════════════════════════════════════════════════════════════
GOPLUS_ENDPOINTS: List[str] = [
"https://api.gopluslabs.io",
"https://api.gopluslabs.io", # Retry fallback
]
REQUEST_TIMEOUT: int = 8
RETRY_WAIT: float = 1.2
# ══════════════════════════════════════════════════════════════
# Dead/Black Hole Addresses
# ══════════════════════════════════════════════════════════════
DEAD_ADDRESSES: Set[str] = {
"0x0000000000000000000000000000000000000000",
"0x000000000000000000000000000000000000dead",
"0xdead000000000000000042069420694206942069",
"0x0000000000000000000000000000000000000001",
}
# ══════════════════════════════════════════════════════════════
# Chain Configuration
# ══════════════════════════════════════════════════════════════
CHAIN_NAMES: Dict[str, str] = {
"1": "Ethereum Mainnet",
"56": "BNB Smart Chain (BSC)",
"137": "Polygon",
"42161": "Arbitrum One",
"8453": "Base",
"10": "Optimism",
"43114": "Avalanche C-Chain",
"solana": "Solana",
}
# ══════════════════════════════════════════════════════════════
# Scenario Classification Configuration
# ══════════════════════════════════════════════════════════════
# Scenario A: Mainstream/Pegged Assets
SCENARIO_A_SYMBOLS: Set[str] = {
"usdt", "usdc", "fdusd", "tusd", "busd", "dai", "usdd", "pyusd",
"lusd", "frax", "usdp", "gusd", "susd", "cusd", "musd", "ousd",
"weth", "wbtc", "wbnb", "wmatic", "wavax", "wftm", "wop",
"btcb", "eth",
}
SCENARIO_A_NAME_KEYWORDS: List[str] = [
"binance-peg", "peg ", " peg", "wrapped ", "bridged ",
"tether", "circle", "usd coin", "frax", "dai stablecoin",
]
# Scenario B: Eco-value tokens threshold
SCENARIO_B_MIN_HOLDERS: int = 500
# Protocol/DEX address tags
PROTOCOL_TAGS: Set[str] = {
"pancakeswap", "uniswap", "sushiswap", "curve", "aave", "compound",
"venus", "alpaca", "biswap", "dodo", "balancer", "lido", "staking",
"pool", "treasury", "reserve", "governance", "timelock", "multisig",
"gnosis", "safe", "lock", "vesting",
}
# ══════════════════════════════════════════════════════════════
# Risk Score Weights
# ══════════════════════════════════════════════════════════════
RISK_WEIGHTS: Dict[str, float] = {
"contract": 0.40,
"tax": 0.25,
"liquidity": 0.20,
"concentration": 0.15,
}
# Scenario-specific weight adjustments
SCENARIO_WEIGHTS: Dict[str, Dict[str, float]] = {
"A": {"contract": 0.50, "tax": 0.30, "liquidity": 0.10, "concentration": 0.10},
"B": {"contract": 0.40, "tax": 0.20, "liquidity": 0.20, "concentration": 0.20},
"C": {"contract": 0.35, "tax": 0.25, "liquidity": 0.20, "concentration": 0.20},
}
# ══════════════════════════════════════════════════════════════
# Fatal Rules Configuration
# ══════════════════════════════════════════════════════════════
FATAL_RULES: List[Dict[str, Any]] = [
{
"check": lambda ind: ind.get("is_honeypot", False),
"code": "HONEYPOT",
"description": "🛑 貔貅盘（Honeypot）",
"implication": "代币无法卖出，买入资金将被永久锁死",
},
{
"check": lambda ind: ind.get("sell_tax", 0) > 50,
"code": "EXTREME_TAX",
"description": "🛑 极端卖出税率",
"implication": "卖出税超过50%，资金实际上无法退出",
},
{
"check": lambda ind: ind.get("selfdestruct", False),
"code": "SELFDESTRUCT",
"description": "🛑 合约自毁函数",
"implication": "团队可随时销毁合约，导致代币归零",
},
{
"check": lambda ind: ind.get("hidden_owner", False),
"code": "HIDDEN_OWNER",
"description": "🛑 隐藏 Owner",
"implication": "合约实际控制权被隐匿，极度危险",
},
{
"check": lambda ind: ind.get("can_take_back_ownership", False),
"code": "OWNERSHIP_RECLAIM",
"description": "🛑 Owner 权限可被夺回",
"implication": "即使显示已 Renounce，团队仍可通过隐藏机制重新取得控制权",
},
{
"check": lambda ind: ind.get("owner_change_balance", False),
"code": "BALANCE_MANIPULATION",
"description": "🛑 Owner 可修改余额",
"implication": "团队可任意修改账户余额，随时清零用户持仓",
},
]
FILE:exceptions.py
"""
Custom exceptions for Anti-Rug Token Security Checker.
"""
class AntiRugError(Exception):
"""Base exception for all Anti-Rug errors."""
pass
class NetworkError(AntiRugError):
"""Raised when network request fails (timeout, connection error)."""
pass
class APIError(AntiRugError):
"""Raised when API returns non-success status."""
def __init__(self, message: str, status_code: int = None, response_data: dict = None):
super().__init__(message)
self.status_code = status_code
self.response_data = response_data or {}
class ContractNotFoundError(AntiRugError):
"""Raised when contract address is not found on the chain."""
pass
class ParseError(AntiRugError):
"""Raised when response parsing fails."""
pass
class UnsupportedChainError(AntiRugError):
"""Raised when chain ID is not supported."""
pass
class ValidationError(AntiRugError):
"""Raised when input validation fails."""
pass
FILE:requirements.txt
# Anti-Rug Token Security Checker
# Dependencies for Web3 token security analysis
# HTTP client for API requests
requests>=2.28.0
# Type hints support (Python 3.8+)
typing-extensions>=4.0.0; python_version<"3.10"
# Development dependencies (optional)
# pytest>=7.0.0
# pytest-cov>=4.0.0
# black>=22.0.0
# mypy>=1.0.0
FILE:scripts/__init__.py
"""Scripts package for Anti-Rug Token Security Checker."""
FILE:scripts/check_token.py
#!/usr/bin/env python3
"""
Anti-Rug Token Security Checker v3.1 - Refactored
Web3 token contract security analyzer with cross-validation engine.
"""
import argparse
import json
import logging
import sys
import time
from typing import Dict, Any, Optional, List
import requests
from config import (
GOPLUS_ENDPOINTS, DEAD_ADDRESSES, CHAIN_NAMES,
REQUEST_TIMEOUT, RETRY_WAIT, FATAL_RULES, RISK_WEIGHTS,
SCENARIO_WEIGHTS, SCENARIO_A_SYMBOLS, SCENARIO_A_NAME_KEYWORDS,
SCENARIO_B_MIN_HOLDERS, PROTOCOL_TAGS
)
from exceptions import (
AntiRugError, NetworkError, APIError,
ContractNotFoundError, UnsupportedChainError
)
from validators import get_all_validators
logging.basicConfig(
level=logging.WARNING,
format="%(asctime)s [%(levelname)s] %(message)s",
stream=sys.stderr,
)
logger = logging.getLogger(__name__)
def safe_float(value: Any, default: float = 0.0) -> float:
"""Safely convert value to float."""
try:
return float(value) if value not in (None, "", "null") else default
except (ValueError, TypeError):
return default
def is_flag(val: Any) -> bool:
"""Check if GoPlus flag is set ("1" = True)."""
return str(val).strip() == "1"
# ══════════════════════════════════════════════════════════════
# API Client (Refactored from fetch_goplus)
# ══════════════════════════════════════════════════════════════
class GoPlusClient:
"""GoPlus API client with retry logic."""
def __init__(self, custom_gateway: str = ""):
self.endpoints = []
if custom_gateway:
self.endpoints.append(custom_gateway.rstrip("/"))
self.endpoints.extend(GOPLUS_ENDPOINTS)
def _make_request(self, url: str) -> requests.Response:
"""Make HTTP request with timeout."""
return requests.get(
url,
timeout=REQUEST_TIMEOUT,
headers={"User-Agent": "AntiRugCN/3.1", "Accept": "application/json"},
)
def _parse_response(self, response: requests.Response, addr_lower: str, contract_address: str) -> Optional[Dict]:
"""Parse API response and extract token data."""
if response.status_code != 200:
raise APIError(f"HTTP {response.status_code}", response.status_code)
data = response.json()
if data.get("code") != 1:
raise APIError(f"API code={data.get('code')}: {data.get('message')}")
result = data.get("result") or {}
if not result:
raise ContractNotFoundError("Contract not found on chain")
token_data = result.get(addr_lower) or result.get(contract_address)
return token_data
def fetch(self, chain_id: str, contract_address: str) -> Optional[Dict]:
"""Fetch token data with retry logic."""
addr_lower = contract_address.lower()
for i, base in enumerate(self.endpoints):
url = f"{base}/api/v1/token_security/{chain_id}?contract_addresses={contract_address}"
try:
logger.info(f"[GoPlus] Trying endpoint [{i+1}/{len(self.endpoints)}]: {base}")
resp = self._make_request(url)
return self._parse_response(resp, addr_lower, contract_address)
except requests.exceptions.Timeout:
logger.warning(f"[GoPlus] Timeout ({REQUEST_TIMEOUT}s): {base}")
except requests.exceptions.ConnectionError as e:
logger.warning(f"[GoPlus] Connection failed: {e}")
except (json.JSONDecodeError, KeyError) as e:
logger.warning(f"[GoPlus] Parse failed: {e}")
if i < len(self.endpoints) - 1:
time.sleep(RETRY_WAIT)
raise NetworkError("All endpoints failed")
# ══════════════════════════════════════════════════════════════
# Scenario Classification
# ══════════════════════════════════════════════════════════════
def classify_scenario(raw: Dict[str, Any]) -> Dict[str, Any]:
"""
Classify token into scenario A/B/C based on symbol, name, and holder count.
"""
name = str(raw.get("token_name", "")).strip().lower()
symbol = str(raw.get("token_symbol", "")).strip().lower()
try:
holder_count = int(raw.get("holder_count", 0) or 0)
except (ValueError, TypeError):
holder_count = 0
# Scenario A: Pegged assets
symbol_match = symbol in SCENARIO_A_SYMBOLS
name_match = any(kw in name for kw in SCENARIO_A_NAME_KEYWORDS)
if symbol_match or name_match:
confidence = "high" if (symbol_match and name_match) else "medium"
matched_by = []
if symbol_match:
matched_by.append(f"Symbol '{symbol.upper()}' in whitelist")
if name_match:
matched_by.append(f"Name contains pegged keyword")
return {
"scenario": "A",
"label": "Pegged Asset / Stablecoin",
"confidence": confidence,
"rationale": "; ".join(matched_by),
"tolerance": "High - institutional permissions are expected",
}
# Scenario B: Eco tokens
if holder_count >= SCENARIO_B_MIN_HOLDERS:
return {
"scenario": "B",
"label": "Ecosystem Token / DeFi / GameFi",
"confidence": "medium",
"rationale": f"{holder_count:,} holders indicates established user base",
"tolerance": "Medium - allow proxy + treasury concentration",
}
# Scenario C: Meme/Unknown (default)
return {
"scenario": "C",
"label": "Meme Coin / Unknown Token",
"confidence": "high",
"rationale": "Low holder count, no pegged indicators",
"tolerance": "Low - all permissions treated as potential rug tools",
}
# ══════════════════════════════════════════════════════════════
# Indicator Extraction
# ══════════════════════════════════════════════════════════════
def extract_indicators(raw: Dict[str, Any]) -> Dict[str, Any]:
"""Extract and normalize security indicators from API response."""
holders = raw.get("holders", [])
lp_holders = raw.get("lp_holders", [])
# Calculate top 10 concentration
top10_pct = sum(safe_float(h.get("percent")) * 100 for h in holders[:10])
# Calculate protocol-held percentage
protocol_held_pct = sum(
safe_float(h.get("percent")) * 100
for h in holders
if any(tag in str(h.get("tag", "")).lower() for tag in PROTOCOL_TAGS)
)
# Calculate LP locked percentage
lp_locked_pct = sum(
safe_float(lp.get("percent")) * 100
for lp in lp_holders
if is_flag(lp.get("is_locked", "0"))
)
owner_addr = raw.get("owner_address", "") or ""
return {
"is_honeypot": is_flag(raw.get("is_honeypot", "0")),
"buy_tax": safe_float(raw.get("buy_tax")),
"sell_tax": safe_float(raw.get("sell_tax")),
"is_mintable": is_flag(raw.get("is_mintable", "0")),
"has_blacklist": is_flag(raw.get("is_blacklist", "0")),
"is_open_source": is_flag(raw.get("is_open_source", "0")),
"is_proxy": is_flag(raw.get("is_proxy", "0")),
"hidden_owner": is_flag(raw.get("hidden_owner", "0")),
"can_take_back_ownership": is_flag(raw.get("can_take_back_ownership", "0")),
"owner_change_balance": is_flag(raw.get("owner_change_balance", "0")),
"selfdestruct": is_flag(raw.get("selfdestruct", "0")),
"trading_cooldown": is_flag(raw.get("trading_cooldown", "0")),
"is_whitelisted": is_flag(raw.get("is_whitelisted", "0")),
"owner_is_dead": addr_is_dead(owner_addr),
"lp_locked_pct": lp_locked_pct,
"top10_pct": top10_pct,
"protocol_held_pct": protocol_held_pct,
"holder_count": int(raw.get("holder_count", 0) or 0),
}
def addr_is_dead(addr: str) -> bool:
"""Check if address is dead/black hole address."""
return not addr or str(addr).lower() in DEAD_ADDRESSES
# ══════════════════════════════════════════════════════════════
# Fatal Rules Engine (Refactored)
# ══════════════════════════════════════════════════════════════
def check_fatal(indicators: Dict[str, Any]) -> List[Dict[str, Any]]:
"""
Check all fatal rules against indicators.
Returns list of triggered fatal findings.
"""
fatals = []
for rule in FATAL_RULES:
try:
if rule["check"](indicators):
fatals.append({
"code": rule["code"],
"description": rule["description"],
"implication": rule["implication"],
})
except Exception as e:
logger.warning(f"Fatal rule {rule['code']} check failed: {e}")
return fatals
# ══════════════════════════════════════════════════════════════
# Cross-Validation Engine (Refactored with validators module)
# ══════════════════════════════════════════════════════════════
def cross_validate(indicators: Dict[str, Any], scenario: Dict[str, Any]) -> List[Dict[str, Any]]:
"""
Run all registered validators to analyze indicator relationships.
"""
findings = []
for validator in get_all_validators():
try:
result = validator(indicators, scenario)
if result:
findings.append(result)
except Exception as e:
logger.warning(f"Validator failed: {e}")
return findings
# ══════════════════════════════════════════════════════════════
# Risk Scoring
# ══════════════════════════════════════════════════════════════
def compute_risk_score(
indicators: Dict[str, Any],
scenario: Dict[str, Any],
fatals: List[Dict],
cross_findings: List[Dict]
) -> Dict[str, Any]:
"""Compute dynamic risk score based on indicators and scenario."""
sc = scenario.get("scenario", "C")
weights = SCENARIO_WEIGHTS.get(sc, RISK_WEIGHTS)
# Contract security (0-100, lower is better)
contract_risk = 0
if indicators["is_honeypot"]:
contract_risk = 100
elif indicators["hidden_owner"]:
contract_risk = 90
elif indicators["selfdestruct"]:
contract_risk = 95
elif not indicators["is_open_source"]:
contract_risk = 40
# Tax risk
tax_risk = min(100, max(indicators["buy_tax"], indicators["sell_tax"]) * 2)
# Liquidity risk
liquidity_risk = max(0, 100 - indicators["lp_locked_pct"])
# Concentration risk
effective_concentration = max(0, indicators["top10_pct"] - indicators["protocol_held_pct"])
concentration_risk = min(100, effective_concentration * 1.5)
# Base score
base_score = (
contract_risk * weights["contract"] +
tax_risk * weights["tax"] +
liquidity_risk * weights["liquidity"] +
concentration_risk * weights["concentration"]
)
# Apply cross-validation adjustments
cv_adjustment = sum(f.get("score_delta", 0) for f in cross_findings)
final_score = max(0, min(100, base_score + cv_adjustment))
return {
"base_score": round(base_score, 1),
"cv_adjustment": cv_adjustment,
"final_score": round(final_score, 1),
"dimension_scores": {
"contract_security": round(contract_risk, 1),
"tax_risk": round(tax_risk, 1),
"liquidity_risk": round(liquidity_risk, 1),
"concentration_risk": round(concentration_risk, 1),
},
"weights_used": weights,
}
# ══════════════════════════════════════════════════════════════
# Verdict Generation
# ══════════════════════════════════════════════════════════════
def generate_verdict(
indicators: Dict[str, Any],
scenario: Dict[str, Any],
fatals: List[Dict],
score: Dict[str, Any]
) -> Dict[str, Any]:
"""Generate final verdict based on all analysis."""
final_score = score["final_score"]
sc = scenario.get("scenario", "C")
# Fatal findings override everything
if fatals:
if sc == "A":
return {
"risk_level": "CRITICAL",
"risk_label": "🛑 COUNTERFEIT",
"verdict": (
f"🛑 COUNTERFEIT DETECTED! This token claims to be a {scenario['label']} "
f"but has fatal flaws: {', '.join(f['code'] for f in fatals)}. "
"Verify contract address against official sources immediately."
),
}
return {
"risk_level": "CRITICAL",
"risk_label": "🛑 DO NOT BUY",
"verdict": (
f"🛑 CRITICAL: {len(fatals)} fatal vulnerability(s) detected. "
f"{fatals[0]['description']}. {fatals[0]['implication']}. "
"Your funds will likely be lost."
),
}
# Score-based verdicts
if final_score >= 75:
return {
"risk_level": "HIGH",
"risk_label": "🔴 High Risk",
"verdict": f"🔴 High risk (score: {final_score}/100). Multiple serious issues. Avoid.",
}
elif final_score >= 50:
return {
"risk_level": "MEDIUM",
"risk_label": "🟡 Medium Risk",
"verdict": f"🟡 Medium risk (score: {final_score}/100). Caution required. Limit position to 5%.",
}
elif final_score >= 25:
return {
"risk_level": "LOW_MEDIUM",
"risk_label": "🟡 Low-Medium Risk",
"verdict": f"🟡 Minor concerns (score: {final_score}/100). Research team background before investing.",
}
else:
return {
"risk_level": "LOW",
"risk_label": "✅ Low Risk",
"verdict": f"✅ Base security passed (score: {final_score}/100). Contract is safe, but market risk remains.",
}
# ══════════════════════════════════════════════════════════════
# Main Parser
# ══════════════════════════════════════════════════════════════
def parse_and_assess(raw: Dict, contract_address: str, chain_id: str) -> Dict[str, Any]:
"""Main analysis pipeline."""
scenario = classify_scenario(raw)
indicators = extract_indicators(raw)
fatals = check_fatal(indicators)
cross_findings = cross_validate(indicators, scenario)
score = compute_risk_score(indicators, scenario, fatals, cross_findings)
verdict = generate_verdict(indicators, scenario, fatals, score)
return {
"status": "success",
"chain": CHAIN_NAMES.get(chain_id, chain_id),
"contract_address": contract_address,
"basic_info": {
"token_name": raw.get("token_name", "Unknown"),
"token_symbol": raw.get("token_symbol", "Unknown"),
"total_supply": raw.get("total_supply", "Unknown"),
"holder_count": raw.get("holder_count", "Unknown"),
},
"scenario_classification": scenario,
"indicators": indicators,
"fatal_findings": fatals,
"cross_validations": cross_findings,
"risk_score": score,
"final_verdict": verdict,
}
def check_token(chain_id: str, contract_address: str, api_gateway: str = "") -> Dict[str, Any]:
"""Main entry point."""
contract_address = contract_address.strip()
chain_id = str(chain_id).strip()
if not contract_address:
return {"status": "error", "message": "Contract address required"}
if chain_id not in CHAIN_NAMES:
return {"status": "error", "message": f"Unsupported chain: {chain_id}"}
if chain_id != "solana":
if not contract_address.startswith("0x") or len(contract_address) != 42:
return {"status": "error", "message": f"Invalid EVM address: {contract_address}"}
try:
client = GoPlusClient(api_gateway)
raw = client.fetch(chain_id, contract_address)
if raw is None:
return {"status": "error", "message": "Contract not found"}
return parse_and_assess(raw, contract_address, chain_id)
except AntiRugError as e:
return {"status": "error", "message": str(e)}
except Exception as e:
logger.exception("Unexpected error")
return {"status": "error", "message": f"Internal error: {str(e)}"}
if __name__ == "__main__":
parser = argparse.ArgumentParser(description="Anti-Rug Token Security Checker v3.1")
parser.add_argument("--chain_id", required=True, help="Chain ID (1=ETH, 56=BSC...)")
parser.add_argument("--contract_address", required=True, help="Token contract address")
parser.add_argument("--api_gateway", default="", help="Custom API gateway (optional)")
args = parser.parse_args()
result = check_token(
chain_id=args.chain_id,
contract_address=args.contract_address,
api_gateway=args.api_gateway,
)
print(json.dumps(result, ensure_ascii=False, indent=2))
FILE:tests/test_anti_rug.py
"""
Test suite for Anti-Rug Token Security Checker.
"""
import unittest
from unittest.mock import Mock, patch
import sys
import os
# Add parent directory to path
sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
from config import SCENARIO_A_SYMBOLS, PROTOCOL_TAGS, FATAL_RULES, RISK_WEIGHTS
from exceptions import AntiRugError, NetworkError, ContractNotFoundError
class TestConfig(unittest.TestCase):
"""Test configuration values."""
def test_scenario_a_symbols(self):
"""Test that scenario A symbols are lowercase."""
for symbol in SCENARIO_A_SYMBOLS:
self.assertEqual(symbol, symbol.lower())
def test_protocol_tags(self):
"""Test that protocol tags are lowercase."""
for tag in PROTOCOL_TAGS:
self.assertEqual(tag, tag.lower())
def test_fatal_rules_structure(self):
"""Test fatal rules have required keys."""
required_keys = {"check", "code", "description", "implication"}
for rule in FATAL_RULES:
self.assertTrue(required_keys.issubset(rule.keys()))
def test_risk_weights_sum(self):
"""Test risk weights sum to 1.0."""
total = sum(RISK_WEIGHTS.values())
self.assertAlmostEqual(total, 1.0, places=2)
class TestValidators(unittest.TestCase):
"""Test cross-validation validators."""
def setUp(self):
"""Set up test fixtures."""
from validators import get_all_validators
self.validators = get_all_validators()
def test_validators_registered(self):
"""Test that validators are properly registered."""
self.assertGreater(len(self.validators), 0)
def test_mint_ownership_neutralized(self):
"""Test CV-01: Mintable with dead owner is neutralized."""
from validators.cv_mint_ownership import validate
ind = {"is_mintable": True, "owner_is_dead": True, "holder_count": 1000}
scenario = {"scenario": "C"}
result = validate(ind, scenario)
self.assertIsNotNone(result)
self.assertEqual(result["type"], "neutralized")
self.assertLess(result["score_delta"], 0)
def test_mint_ownership_amplified(self):
"""Test CV-01: Mintable with active owner in scenario C is amplified."""
from validators.cv_mint_ownership import validate
ind = {"is_mintable": True, "owner_is_dead": False, "holder_count": 100}
scenario = {"scenario": "C"}
result = validate(ind, scenario)
self.assertIsNotNone(result)
self.assertEqual(result["type"], "amplified")
self.assertGreater(result["score_delta"], 0)
def test_concentration_contextual(self):
"""Test CV-02: High concentration with protocol addresses is contextual."""
from validators.cv_concentration import validate
ind = {"top10_pct": 60, "protocol_held_pct": 30}
scenario = {"scenario": "B"}
result = validate(ind, scenario)
self.assertIsNotNone(result)
self.assertEqual(result["type"], "contextual")
def test_concentration_amplified(self):
"""Test CV-02: High concentration without protocol addresses is amplified."""
from validators.cv_concentration import validate
ind = {"top10_pct": 60, "protocol_held_pct": 5}
scenario = {"scenario": "C"}
result = validate(ind, scenario)
self.assertIsNotNone(result)
self.assertEqual(result["type"], "amplified")
class TestExceptions(unittest.TestCase):
"""Test custom exceptions."""
def test_network_error(self):
"""Test NetworkError can be raised and caught."""
with self.assertRaises(NetworkError):
raise NetworkError("Connection failed")
def test_contract_not_found_error(self):
"""Test ContractNotFoundError."""
with self.assertRaises(ContractNotFoundError):
raise ContractNotFoundError("Contract not found")
class TestFatalRules(unittest.TestCase):
"""Test fatal rules engine."""
def test_honeypot_rule(self):
"""Test honeypot detection rule."""
rule = next(r for r in FATAL_RULES if r["code"] == "HONEYPOT")
# Should trigger
ind_trigger = {"is_honeypot": True}
self.assertTrue(rule["check"](ind_trigger))
# Should not trigger
ind_safe = {"is_honeypot": False}
self.assertFalse(rule["check"](ind_safe))
def test_extreme_tax_rule(self):
"""Test extreme tax detection rule."""
rule = next(r for r in FATAL_RULES if r["code"] == "EXTREME_TAX")
# Should trigger
ind_trigger = {"sell_tax": 60}
self.assertTrue(rule["check"](ind_trigger))
# Should not trigger
ind_safe = {"sell_tax": 10}
self.assertFalse(rule["check"](ind_safe))
if __name__ == "__main__":
unittest.main()
FILE:validators/__init__.py
"""
Cross-validation validators module.
Each validator is a function that takes indicators and scenario, returns a finding dict or None.
"""
from typing import Dict, Any, Optional, Callable, List
from functools import wraps
# Registry of all validators
_validators: List[Callable] = []
def validator(func: Callable) -> Callable:
"""Decorator to register a validator function."""
_validators.append(func)
@wraps(func)
def wrapper(*args, **kwargs):
return func(*args, **kwargs)
return wrapper
def get_all_validators() -> List[Callable]:
"""Get all registered validators."""
return _validators.copy()
# Import all validators to register them
from . import cv_mint_ownership, cv_concentration, cv_proxy, cv_tax_scenario
__all__ = ['validator', 'get_all_validators', 'cv_mint_ownership', 'cv_concentration', 'cv_proxy', 'cv_tax_scenario']
FILE:validators/cv_concentration.py
"""
CV-02: Concentration × Protocol Address validator.
"""
from typing import Dict, Any, Optional
from . import validator
@validator
def validate(ind: Dict[str, Any], scenario: Dict[str, Any]) -> Optional[Dict[str, Any]]:
"""
Validates holder concentration considering protocol-held addresses.
Contextual: High concentration but mostly protocol addresses
Amplified: High concentration with low protocol holding
"""
top10_pct = ind.get("top10_pct", 0)
protocol_held_pct = ind.get("protocol_held_pct", 0)
if top10_pct <= 40:
return None
effective = max(0, top10_pct - protocol_held_pct)
if protocol_held_pct > 20:
return {
"type": "contextual",
"indicators": ["top10_holders_pct", "protocol_held_pct"],
"conclusion": (
f"ℹ️【持仓集中度重新解读】前10地址持仓 {top10_pct:.1f}%，"
f"但其中 {protocol_held_pct:.1f}% 归属于已知 DEX 资金池、"
f"质押合约或黑洞地址等协议地址。"
f"剔除协议地址后，实际「可疑集中度」仅约 {effective:.1f}%，"
"持仓结构基本健康，不构成庄家控盘特征。"
),
"score_delta": -10,
}
else:
return {
"type": "amplified",
"indicators": ["top10_holders_pct"],
"conclusion": (
f"⚠️【持仓高度集中】前10地址持仓 {top10_pct:.1f}%，"
f"协议/黑洞地址仅占 {protocol_held_pct:.1f}%，"
f"实际可疑集中持仓约 {effective:.1f}%。"
"存在明显庄家或团队控盘风险，大额抛售可造成价格雪崩。"
),
"score_delta": +15,
}
FILE:validators/cv_mint_ownership.py
"""
CV-01: Mintable × Owner Status validator.
"""
from typing import Dict, Any, Optional
from . import validator
@validator
def validate(ind: Dict[str, Any], scenario: Dict[str, Any]) -> Optional[Dict[str, Any]]:
"""
Validates the relationship between mintable status and owner status.
Neutralized: Mintable but owner is dead (risk neutralized)
Amplified: Mintable with active owner in scenario C (Meme coin)
"""
is_mintable = ind.get("is_mintable", False)
owner_is_dead = ind.get("owner_is_dead", False)
holder_count = ind.get("holder_count", 0)
sc = scenario.get("scenario", "C")
if is_mintable and owner_is_dead:
return {
"type": "neutralized",
"indicators": ["is_mintable", "owner_address"],
"conclusion": (
"✅【增发风险已中和】合约虽含增发函数（is_mintable=True），"
"但 Owner 已打入黑洞地址，当前无任何账户具备调用增发权限的能力。"
"增发代码形同虚设，实际风险与无增发合约等同。"
),
"score_delta": -15,
}
elif is_mintable and not owner_is_dead and sc == "C":
return {
"type": "amplified",
"indicators": ["is_mintable", "owner_address"],
"conclusion": (
"🔴【增发风险放大】合约不仅可以增发，且 Owner 地址仍在活跃控制中。"
f"持有者仅 {holder_count:,} 人，流动性薄弱，"
"团队随时可增发打压价格后出货，这是 Meme 币最常见的割韭菜路径。"
),
"score_delta": +20,
}
return None
FILE:validators/cv_proxy.py
"""
CV-03: Proxy Contract × Scenario validator.
"""
from typing import Dict, Any, Optional
from . import validator
@validator
def validate(ind: Dict[str, Any], scenario: Dict[str, Any]) -> Optional[Dict[str, Any]]:
"""
Validates proxy contract status based on scenario.
Contextual: Proxy is acceptable for Scenario A/B (mainstream/eco tokens)
Warning: Proxy in Scenario C (Meme coins) is suspicious
"""
is_proxy = ind.get("is_proxy", False)
sc = scenario.get("scenario", "C")
if not is_proxy:
return None
if sc in ("A", "B"):
return {
"type": "contextual",
"indicators": ["is_proxy", "scenario"],
"conclusion": (
f"ℹ️【代理合约适配】该代币为{'机构锚定资产' if sc == 'A' else '生态价值币'}，"
"使用代理合约（Upgradeable Proxy）是合理设计。"
"机构需要保留升级能力以修复漏洞或响应监管要求，"
"这是中心化信任模型的正常组成部分。"
),
"score_delta": -5,
}
else:
return {
"type": "amplified",
"indicators": ["is_proxy", "scenario"],
"conclusion": (
"⚠️【代理合约警告】Meme 币/土狗项目使用代理合约风险较高。"
"团队可随时替换合约逻辑，包括添加貔貅功能、修改税率、冻结用户资产等。"
"早期承诺可能在一次升级后完全失效。"
),
"score_delta": +10,
}
FILE:validators/cv_tax_scenario.py
"""
CV-04: Tax Rate × Scenario validator.
"""
from typing import Dict, Any, Optional
from . import validator
@validator
def validate(ind: Dict[str, Any], scenario: Dict[str, Any]) -> Optional[Dict[str, Any]]:
"""
Validates tax rates based on scenario.
Warning: High tax in any scenario is bad
Critical: Any tax in Scenario A (pegged assets) suggests fake token
"""
buy_tax = ind.get("buy_tax", 0)
sell_tax = ind.get("sell_tax", 0)
sc = scenario.get("scenario", "C")
# Scenario A with any tax is suspicious (fake pegged token)
if sc == "A" and (buy_tax > 0 or sell_tax > 0):
return {
"type": "amplified",
"indicators": ["buy_tax", "sell_tax", "scenario"],
"conclusion": (
f"🛑【疑似仿盘！】该代币被归类为机构锚定资产，"
f"但检测到异常交易税（买入 {buy_tax:.1f}% / 卖出 {sell_tax:.1f}%）。"
"正规的 USDT/USDC/WETH 等资产交易税应为 0%，"
"检测到交易税极大概率是仿冒诈骗合约，请立即核对官方合约地址。"
),
"score_delta": +30,
}
# High tax warning for all scenarios
if sell_tax > 10 or buy_tax > 10:
return {
"type": "amplified",
"indicators": ["buy_tax", "sell_tax"],
"conclusion": (
f"⚠️【高税率警告】检测到较高交易税（买入 {buy_tax:.1f}% / 卖出 {sell_tax:.1f}%）。"
f"{'对于 Meme 币，高税率是常见的割韭菜手段，买入即亏损。' if sc == 'C' else '高税率会显著影响交易成本和流动性。'}"
),
"score_delta": +10 if sc == "C" else +5,
}
return None
BTC mining farm management via natural language. Activate when user mentions mining farm, miners, hashrate, BTC mining, miner reboot, mining revenue, Nonce m...
---
name: easy-mining
version: 1.1.0
description: BTC mining farm management via natural language. Activate when user mentions mining farm, miners, hashrate, BTC mining, miner reboot, mining revenue, Nonce mining, 矿场, 矿机, 算力, BTC挖矿, 矿机重启, 挖矿收益, 矿场管理. Supports farm overview, miner status, abnormal miner detection, batch operations (reboot/power mode/firmware), revenue history query.
author: Antalpha AI Team
homepage: https://www.antalpha.com/
metadata:
openclaw:
requires:
env: []
mcp:
tools:
- easy-mining-get-workspace
- easy-mining-list-farms
- easy-mining-list-agents
- easy-mining-list-miners
- easy-mining-list-metrics-history
- easy-mining-list-pool-diffs
- easy-mining-list-history
- easy-mining-list-miner-tasks
- easy-mining-list-task-batches
- easy-mining-create-task-batch
- easy-mining-get-task-batch
notes: |
Thin MCP client wrapper — all Nonce API logic runs on Antalpha MCP Server.
User provides their own Nonce API Key per request (not stored server-side).
Get API Key from: https://app.nonce.app → Settings → API Keys
---
# Easy Mining Skill 🦐
> *"一句话管理矿场"* — 通过自然语言管理 BTC 矿场，无需打开 App，直接在对话中完成日常运维。
**链路**：OpenClaw → Antalpha MCP Server → Nonce MCP Server → 矿机
---
## 🚀 新手入门：绑定 Nonce API Key
在使用任何功能之前，你需要先绑定 Nonce API Key。以下是完整步骤：
### 第一步：注册 Nonce 账号
1. 打开浏览器，访问 [https://app.nonce.app](https://app.nonce.app)
2. 点击右上角 **Sign Up** 注册账号（支持邮箱注册）
3. 完成邮箱验证后登录
### 第二步：生成 API Key
1. 登录后，点击右上角头像，进入 **Settings（设置）**
2. 找到 **API Keys** 选项卡
3. 点击 **Generate New Key**
4. 给 Key 取一个名字（如 `my-ai-agent`），点击确认
5. **复制生成的 API Key**（格式为 `ak_XXXXXXXXXXXXXXXXXXXXXXXX`）
> ⚠️ API Key 只显示一次，请立刻保存好！如果丢失，需要重新生成。
### 第三步：验证连接
将 API Key 告诉我，我会帮你验证连接：
```
"我的 Nonce API Key 是 ak_XXXXXXXXXX，帮我验证一下连接"
```
验证成功后，你会看到你的 Workspace 信息和矿场列表。
### 第四步：开始使用
连接成功后，你可以直接用自然语言管理矿场：
- 📊 "帮我看一下矿场概况"
- ⚡ "现在有多少台矿机在线？算力多少？"
- 🌡️ "有没有高温或异常的矿机？"
- 💰 "过去7天的挖矿收益是多少？"
- 🔄 "重启那台离线的矿机"（会先让你确认）
---
## ⚠️ 重要规则
### Rule 1: API Key 每次传入，不落库
你的 API Key 仅在当次请求中使用，Antalpha MCP Server **不会存储**你的 Key。每次对话时，如果需要调用矿场数据，我会使用你本次提供的 Key。
### Rule 2: 写操作必须二次确认
`easy-mining-create-task-batch` 是**写操作**（重启/调频/升级等），调用前我会：
1. 先列出将受影响的矿机列表
2. 等你明确说"确认"后再执行
```
❌ 错误做法：直接执行重启
✅ 正确做法：
1. 查询目标矿机列表
2. 展示 → "将重启以下 3 台矿机：[列表]，确认？"
3. 用户回复"确认"后才调用 create-task-batch
```
### Rule 3: 自动解析 Farm ID
大多数操作需要 farm_id，我会自动处理：
- 只有一个矿场 → 自动使用
- 多个矿场 → 询问你选哪个
---
## 📋 功能对照表
### 查询功能（只读）
| 你说的话 | 调用的工具 |
|---------|-----------|
| 验证 API Key 连接 | `easy-mining-get-workspace` |
| 看我的矿场列表 | `easy-mining-list-farms` |
| 矿机实时状态、算力、温度 | `easy-mining-list-miners` |
| 过去 N 天收益 | `easy-mining-list-metrics-history` |
| 某台矿机的历史算力/温度 | `easy-mining-list-history` |
| 某台矿机的历史任务记录 | `easy-mining-list-miner-tasks` |
| 矿池变更记录 | `easy-mining-list-pool-diffs` |
| 查看历史任务批次 | `easy-mining-list-task-batches` |
| 某个任务批次的进度 | `easy-mining-get-task-batch` |
### 写操作（需二次确认）
| 任务类型 | task_name | 说明 |
|---------|-----------|------|
| 重启矿机 | `miner.system.reboot` | 重启指定矿机 |
| 调整功耗模式 | `miner.power_mode.update` | 参数：`{"mode": "low_power" \| "normal" \| "high_power"}` |
| 固件升级 | `miner.firmware.update` | 升级到最新固件 |
| 网络扫描 | `miner.network.scan` | 扫描矿机网络 |
| 矿池配置 | `miner.pool.config` | 参数：`{"pool_url": "..."}` |
| 定位指示灯 | `miner.light.flash` | 让矿机 LED 闪烁以便定位 |
---
## 📊 返回格式示例
### 矿场概览
```
📊 矿场概览 — Kuching MY
├─ 总算力：48,500 GH/s（≈ 48.5 TH/s）
├─ 在线矿机：97 / 100 台
├─ 异常矿机：3 台（离线 2、高温 1）
└─ 今日收益：0.02112 BTC（≈ ¥1,450）
```
### 矿机列表（异常过滤）
```
⚠️ 异常矿机（3 台）
├─ [M001] 状态：offline | 最后在线：2h 前
├─ [M047] 状态：online | 温度：78°C ⚠️ 过热
└─ [M089] 状态：offline | 最后在线：30min 前
```
### 收益历史
```
💰 7 天收益报表
┌─────────────┬──────────────┬──────────┐
│ 日期 │ BTC 收益 │ 在线矿机 │
├─────────────┼──────────────┼──────────┤
│ 2026-04-09 │ 0.02112 BTC │ 100 │
│ 2026-04-08 │ 0.01991 BTC │ 98 │
│ 2026-04-07 │ 0.02034 BTC │ 100 │
└─────────────┴──────────────┴──────────┘
合计：0.14231 BTC（≈ ¥9,760）
```
---
## 🛠️ CLI 快速测试
```bash
# 验证 API Key
python3 scripts/mcp_client.py workspace --api-key <YOUR_KEY>
# 矿场列表
python3 scripts/mcp_client.py farms --api-key <YOUR_KEY>
# 矿机实时状态
python3 scripts/mcp_client.py miners --api-key <YOUR_KEY> --farm-id <FARM_ID>
# 收益历史（最近7天）
python3 scripts/mcp_client.py metrics \
--api-key <YOUR_KEY> \
--farm-id <FARM_ID> \
--from-date 2026-04-03 --to-date 2026-04-09
# ⚠️ 重启矿机（写操作，需人工确认后执行）
python3 scripts/mcp_client.py create-task \
--api-key <YOUR_KEY> \
--farm-id <FARM_ID> \
--task-name miner.system.reboot \
--miner-ids <MINER_ID_1> <MINER_ID_2>
```
---
## 🔒 安全说明
| 安全项 | 说明 |
|--------|------|
| API Key 不落库 | 每次调用即用即弃，服务端不持久化 |
| 写操作二次确认 | 所有 `create-task-batch` 必须展示影响范围并等待用户确认 |
| 只读优先 | 默认只查询，用户明确要求时才执行写操作 |
| Key 格式校验 | API Key 必须以 `ak_` 开头，格式不符会立即报错 |
---
## 🆘 常见问题
| 现象 | 原因 | 解决方法 |
|------|------|---------|
| `HTTP 401 Unauthorized` | API Key 无效或已过期 | 重新在 Nonce App → Settings → API Keys 生成 |
| `Cannot resolve workspace_id` | API Key 对应账号下无 Workspace | 检查是否用正确账号生成了 Key |
| `HTTP 404` | farm_id / miner_id 不存在 | 先调用 `list-farms` / `list-miners` 获取正确 ID |
| 任务创建成功但矿机无响应 | 矿机离线或网络中断 | 检查矿机网络连接 |
| 收益显示为 0 | 账号无真实收益数据（测试账号）| 确认是否为正式生产账号 |
---
## 📁 文件结构
```
easy-mining/
├── SKILL.md # 本文件（前端 Skill 定义）
├── README.md # 项目介绍（中英双语）
├── scripts/
│ └── mcp_client.py # MCP 客户端封装（CLI 测试工具）
└── references/
└── nonce-tools.md # Nonce MCP 工具参考文档
```
FILE:README.md
# Easy Mining Skill 🦐
**一句话管理 BTC 矿场** | **Manage BTC Mining Farms via Natural Language**
通过自然语言与 AI 对话，完成矿场日常运维，无需打开 App。
Chat with AI in natural language to manage your BTC mining farm — no app required.
---
## 功能概览 | Features
| 功能 | Feature |
|------|---------|
| 矿场实时概况（在线数/总算力） | Real-time farm overview (online count / total hashrate) |
| 矿机实时状态（算力/温度/功耗） | Miner real-time status (hashrate / temp / power) |
| 异常矿机识别（离线/高温/故障） | Abnormal miner detection (offline / overheat / error) |
| 收益历史查询（日级 BTC 数据） | Revenue history (daily BTC earnings) |
| 批量运维操作（重启/调频/升级） | Batch operations (reboot / power mode / firmware) |
| 任务进度追踪 | Task progress tracking |
---
## 快速上手 | Quick Start
### 中文版
#### 第一步：获取 Nonce API Key
1. 访问 [https://app.nonce.app](https://app.nonce.app) 注册账号
2. 登录后进入 **Settings → API Keys → Generate New Key**
3. 复制生成的 Key（格式：`ak_XXXXXXXXXXXXXXXXXXXXXXXX`）
> ⚠️ Key 只显示一次，请立即保存！
#### 第二步：告诉 AI 你的 Key
```
"我的 Nonce API Key 是 ak_XXXXXXXXXX，帮我验证一下连接"
```
#### 第三步：用自然语言管理矿场
```
"帮我看一下矿场概况"
"现在有多少台矿机在线？"
"过去7天挖了多少 BTC？"
"有没有高温或离线的矿机？"
"重启那3台异常矿机"
```
---
### English Version
#### Step 1: Get Your Nonce API Key
1. Visit [https://app.nonce.app](https://app.nonce.app) and create an account
2. After login, go to **Settings → API Keys → Generate New Key**
3. Copy your API Key (format: `ak_XXXXXXXXXXXXXXXXXXXXXXXX`)
> ⚠️ The key is only shown once — save it immediately!
#### Step 2: Provide the Key to AI
```
"My Nonce API Key is ak_XXXXXXXXXX, please verify the connection"
```
#### Step 3: Manage Your Farm with Natural Language
```
"Show me my farm overview"
"How many miners are online right now?"
"What's my BTC earnings for the past 7 days?"
"Which miners are offline or overheating?"
"Reboot the 3 abnormal miners"
```
---
## 架构 | Architecture
```
用户 (User)
↓ 自然语言 / Natural Language
OpenClaw (AI Agent)
↓ MCP tool calls
Antalpha MCP Server
↓ MCP protocol (with Bearer auth)
Nonce MCP Server (mcp.nonce.app)
↓ Nonce API
矿机 / BTC Miners
```
- **API Key 不落库**：每次调用即用即弃，服务端不持久化
**Key never stored**: used per-request only, never persisted server-side
- **写操作二次确认**：重启/调频等操作必须用户确认后执行
**Write ops require confirmation**: reboot/power mode changes need explicit user approval
---
## 支持的任务类型 | Supported Task Types
| 任务 | `task_name` | 说明 |
|------|------------|------|
| 重启矿机 | `miner.system.reboot` | Reboot miners |
| 调整功耗 | `miner.power_mode.update` | Change power mode: `low_power` / `normal` / `high_power` |
| 固件升级 | `miner.firmware.update` | Firmware upgrade |
| 网络扫描 | `miner.network.scan` | Network scan |
| 矿池配置 | `miner.pool.config` | Update pool URL |
| 指示灯定位 | `miner.light.flash` | Flash LED to locate miner |
---
## 工具列表 | MCP Tools
| Tool Name | 说明 | Description |
|-----------|------|-------------|
| `easy-mining-get-workspace` | 验证 API Key，获取 Workspace 信息 | Verify API key and get workspace info |
| `easy-mining-list-farms` | 列出所有矿场 | List all mining farms |
| `easy-mining-list-agents` | 列出所有 Agent | List all Nonce agents |
| `easy-mining-list-miners` | 矿机实时状态 | Real-time miner status |
| `easy-mining-list-metrics-history` | 矿场历史收益（日级） | Farm metrics history (daily) |
| `easy-mining-list-pool-diffs` | 矿池变更记录 | Pool change records |
| `easy-mining-list-history` | 单台矿机历史数据 | Single miner historical data |
| `easy-mining-list-miner-tasks` | 矿机任务历史 | Miner task history |
| `easy-mining-list-task-batches` | 任务批次列表 | Task batch list |
| `easy-mining-create-task-batch` | ⚠️ 创建任务批次（写操作） | ⚠️ Create task batch (write op) |
| `easy-mining-get-task-batch` | 查询任务批次状态 | Get task batch status |
---
## 安装 | Installation
```bash
clawhub install easy-mining
```
或通过 OpenClaw 直接安装 | Or install directly via OpenClaw:
```
"安装 Easy Mining Skill"
```
---
## 数据来源 | Data Source
矿场数据由 [Nonce](https://app.nonce.app) 提供，通过其官方 MCP API 接入。
Mining data is provided by [Nonce](https://app.nonce.app) via their official MCP API.
---
## 许可 | License
MIT © [Antalpha AI Team](https://www.antalpha.com/)
FILE:references/nonce-tools.md
# Nonce MCP Tools Reference
Nonce MCP Server: `https://mcp.nonce.app/mcp`
Antalpha wraps these tools via: `easy-mining-*` prefix
## Tool Mapping
| Antalpha Tool | Nonce Tool | Type |
|---------------|------------|------|
| easy-mining-get-workspace | get_workspace | Read |
| easy-mining-list-farms | list_farms | Read |
| easy-mining-list-agents | list_agents | Read |
| easy-mining-list-miners | list_miners | Read |
| easy-mining-list-metrics-history | list_metrics_history | Read |
| easy-mining-list-pool-diffs | list_pool_diffs | Read |
| easy-mining-list-history | list_history | Read |
| easy-mining-list-miner-tasks | list_miner_tasks | Read |
| easy-mining-list-task-batches | list_task_batches | Read |
| easy-mining-create-task-batch | create_task_batch | **Write** |
| easy-mining-get-task-batch | get_task_batch | Read |
## Official Task Names (use exactly as shown)
- `miner.system.reboot` — 重启
- `miner.power_mode.update` — 功耗模式（params: `{mode: "low_power"|"high_performance"|"normal"|"sleep"}`)
- `miner.firmware.update` — 固件升级
- `miner.network.scan` — 网络扫描
- `miner.pool.config` — 矿池配置
- `miner.light.flash` — 指示灯
> ⚠️ PRD 附录中的 `reboot`/`power_mode`/`firmware_upgrade` 是缩写，不能直接使用。
FILE:scripts/mcp_client.py
#!/usr/bin/env python3
"""
Easy Mining MCP Client
Wrapper that calls the Antalpha MCP Server for BTC mining farm management.
All Nonce API logic runs on the remote server (Antalpha MCP → Nonce MCP).
MCP Protocol Flow:
1. POST initialize → get mcp-session-id from response headers
2. POST notifications/initialized → confirm session
3. POST tools/call → actual tool invocation
Usage:
python3 scripts/mcp_client.py workspace --api-key <key>
python3 scripts/mcp_client.py farms --api-key <key>
python3 scripts/mcp_client.py miners --api-key <key> --farm-id <id>
python3 scripts/mcp_client.py metrics --api-key <key> --farm-id <id>
python3 scripts/mcp_client.py history --api-key <key> --miner-id <id>
python3 scripts/mcp_client.py task-batches --api-key <key> --farm-id <id>
python3 scripts/mcp_client.py create-task --api-key <key> --farm-id <id> --task-name miner.system.reboot --miner-ids <id1> <id2>
python3 scripts/mcp_client.py get-task --api-key <key> --task-batch-id <id>
"""
import argparse
import json
import sys
import urllib.request
import urllib.error
from typing import Any, Dict, List, Optional
MCP_SERVER_URL = "https://mcp-skills.ai.antalpha.com/mcp"
class MCPClient:
"""MCP client with proper session management."""
def __init__(self, server_url: str = MCP_SERVER_URL):
self.server_url = server_url
self.session_id: Optional[str] = None
def _parse_sse_response(self, response_text: str) -> Dict[str, Any]:
"""Parse SSE (Server-Sent Events) response format."""
for line in response_text.split("\n"):
if line.startswith("data: ") or line.startswith("data:"):
data_str = line[5:].strip()
if data_str and data_str != "[DONE]":
try:
return json.loads(data_str)
except json.JSONDecodeError:
continue
return {}
def initialize(self) -> bool:
"""
Initialize MCP session.
Must be called before any tool calls.
Returns True if successful.
"""
payload = {
"jsonrpc": "2.0",
"method": "initialize",
"params": {
"protocolVersion": "2024-11-05",
"capabilities": {},
"clientInfo": {
"name": "easy-mining-client",
"version": "1.0.0",
},
},
"id": 1,
}
headers = {
"Content-Type": "application/json",
"Accept": "application/json, text/event-stream",
}
try:
data = json.dumps(payload).encode("utf-8")
req = urllib.request.Request(
self.server_url, data=data, headers=headers, method="POST"
)
with urllib.request.urlopen(req, timeout=60) as response:
self.session_id = response.headers.get("mcp-session-id")
response_text = response.read().decode("utf-8")
result = self._parse_sse_response(response_text)
if "error" in result:
print(f"Initialize error: {result['error']}", file=sys.stderr)
return False
self._send_initialized()
return True
except Exception as e:
print(f"Initialize failed: {e}", file=sys.stderr)
return False
def _send_initialized(self) -> None:
"""Send notifications/initialized to complete handshake."""
if not self.session_id:
return
payload = {
"jsonrpc": "2.0",
"method": "notifications/initialized",
"params": {},
}
headers = {
"Content-Type": "application/json",
"Accept": "application/json, text/event-stream",
"Mcp-Session-Id": self.session_id,
}
try:
data = json.dumps(payload).encode("utf-8")
req = urllib.request.Request(
self.server_url, data=data, headers=headers, method="POST"
)
with urllib.request.urlopen(req, timeout=30):
pass
except Exception:
pass
def call_tool(self, tool_name: str, arguments: Dict[str, Any]) -> Dict[str, Any]:
"""
Call an MCP tool and return the result.
Auto-initializes session if needed.
"""
if not self.session_id:
if not self.initialize():
return {"error": "Failed to initialize MCP session"}
payload = {
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"name": tool_name,
"arguments": arguments,
},
"id": 2,
}
headers = {
"Content-Type": "application/json",
"Accept": "application/json, text/event-stream",
"Mcp-Session-Id": self.session_id,
}
try:
data = json.dumps(payload).encode("utf-8")
req = urllib.request.Request(
self.server_url, data=data, headers=headers, method="POST"
)
with urllib.request.urlopen(req, timeout=30) as response:
response_text = response.read().decode("utf-8")
result = self._parse_sse_response(response_text)
if "error" in result:
return {"error": result["error"]}
return result.get("result", {})
except urllib.error.HTTPError as e:
return {"error": f"HTTP {e.code}: {e.reason}"}
except urllib.error.URLError as e:
return {"error": f"Connection error: {str(e)}"}
except json.JSONDecodeError as e:
return {"error": f"Failed to parse response: {str(e)}"}
except Exception as e:
return {"error": f"Unexpected error: {str(e)}"}
_client: Optional[MCPClient] = None
def get_client() -> MCPClient:
global _client
if _client is None:
_client = MCPClient()
return _client
# ─── Tool wrappers ────────────────────────────────────────────────────────────
def get_workspace(api_key: str) -> Dict[str, Any]:
return get_client().call_tool("easy-mining-get-workspace", {"api_key": api_key})
def list_farms(api_key: str) -> Dict[str, Any]:
return get_client().call_tool("easy-mining-list-farms", {"api_key": api_key})
def list_agents(api_key: str) -> Dict[str, Any]:
return get_client().call_tool("easy-mining-list-agents", {"api_key": api_key})
def list_miners(api_key: str, farm_id: str) -> Dict[str, Any]:
return get_client().call_tool("easy-mining-list-miners", {"api_key": api_key, "farm_id": farm_id})
def list_metrics_history(
api_key: str,
farm_id: str,
start_date: Optional[str] = None,
end_date: Optional[str] = None,
) -> Dict[str, Any]:
args: Dict[str, Any] = {"api_key": api_key, "farm_id": farm_id}
if start_date:
args["from_date"] = start_date
if end_date:
args["to_date"] = end_date
return get_client().call_tool("easy-mining-list-metrics-history", args)
def list_pool_diffs(api_key: str, farm_id: str) -> Dict[str, Any]:
return get_client().call_tool("easy-mining-list-pool-diffs", {"api_key": api_key, "farm_id": farm_id})
def list_history(
api_key: str,
miner_id: str,
start_date: Optional[str] = None,
end_date: Optional[str] = None,
) -> Dict[str, Any]:
args: Dict[str, Any] = {"api_key": api_key, "miner_id": miner_id}
if start_date:
args["start_date"] = start_date
if end_date:
args["end_date"] = end_date
return get_client().call_tool("easy-mining-list-history", args)
def list_miner_tasks(api_key: str, miner_id: str) -> Dict[str, Any]:
return get_client().call_tool("easy-mining-list-miner-tasks", {"api_key": api_key, "miner_id": miner_id})
def list_task_batches(
api_key: str,
farm_id: str,
page: int = 1,
page_size: int = 20,
) -> Dict[str, Any]:
return get_client().call_tool(
"easy-mining-list-task-batches",
{"api_key": api_key, "farm_id": farm_id, "page": page, "page_size": page_size},
)
def create_task_batch(
api_key: str,
farm_id: str,
task_name: str,
miner_ids: List[str],
params: Optional[Dict[str, Any]] = None,
) -> Dict[str, Any]:
args: Dict[str, Any] = {
"api_key": api_key,
"farm_id": farm_id,
"task_name": task_name,
"miner_ids": miner_ids,
}
if params:
args["params"] = params
return get_client().call_tool("easy-mining-create-task-batch", args)
def get_task_batch(api_key: str, task_batch_id: str) -> Dict[str, Any]:
return get_client().call_tool(
"easy-mining-get-task-batch",
{"api_key": api_key, "task_batch_id": task_batch_id},
)
# ─── CLI ─────────────────────────────────────────────────────────────────────
def main():
parser = argparse.ArgumentParser(
description="Easy Mining MCP Client — BTC mining farm management via Antalpha MCP"
)
subparsers = parser.add_subparsers(dest="command", help="Available commands")
# workspace
ws_p = subparsers.add_parser("workspace", help="Get workspace info")
ws_p.add_argument("--api-key", required=True, help="Nonce API key")
# farms
farms_p = subparsers.add_parser("farms", help="List all farms")
farms_p.add_argument("--api-key", required=True, help="Nonce API key")
# agents
agents_p = subparsers.add_parser("agents", help="List Nonce agents")
agents_p.add_argument("--api-key", required=True, help="Nonce API key")
# miners
miners_p = subparsers.add_parser("miners", help="List miners in a farm")
miners_p.add_argument("--api-key", required=True, help="Nonce API key")
miners_p.add_argument("--farm-id", required=True, help="Farm ID")
# metrics
metrics_p = subparsers.add_parser("metrics", help="Farm metrics history")
metrics_p.add_argument("--api-key", required=True, help="Nonce API key")
metrics_p.add_argument("--farm-id", required=True, help="Farm ID")
metrics_p.add_argument("--start-date", help="Start date (ISO8601)")
metrics_p.add_argument("--end-date", help="End date (ISO8601)")
# pool-diffs
pd_p = subparsers.add_parser("pool-diffs", help="Pool change records")
pd_p.add_argument("--api-key", required=True, help="Nonce API key")
pd_p.add_argument("--farm-id", required=True, help="Farm ID")
# history
hist_p = subparsers.add_parser("history", help="Miner performance history")
hist_p.add_argument("--api-key", required=True, help="Nonce API key")
hist_p.add_argument("--miner-id", required=True, help="Miner ID")
hist_p.add_argument("--start-date", help="Start date")
hist_p.add_argument("--end-date", help="End date")
# miner-tasks
mt_p = subparsers.add_parser("miner-tasks", help="Miner task history")
mt_p.add_argument("--api-key", required=True, help="Nonce API key")
mt_p.add_argument("--miner-id", required=True, help="Miner ID")
# task-batches
tb_p = subparsers.add_parser("task-batches", help="List task batches")
tb_p.add_argument("--api-key", required=True, help="Nonce API key")
tb_p.add_argument("--farm-id", required=True, help="Farm ID")
tb_p.add_argument("--page", type=int, default=1, help="Page number")
tb_p.add_argument("--page-size", type=int, default=20, help="Page size")
# create-task
ct_p = subparsers.add_parser("create-task", help="Create task batch (WRITE - confirm first!)")
ct_p.add_argument("--api-key", required=True, help="Nonce API key")
ct_p.add_argument("--farm-id", required=True, help="Farm ID")
ct_p.add_argument(
"--task-name",
required=True,
choices=[
"miner.system.reboot",
"miner.power_mode.update",
"miner.firmware.update",
"miner.network.scan",
"miner.pool.config",
"miner.light.flash",
],
help="Task type",
)
ct_p.add_argument("--miner-ids", nargs="+", required=True, help="Miner IDs")
ct_p.add_argument("--params", type=json.loads, help="Task params as JSON string")
# get-task
gt_p = subparsers.add_parser("get-task", help="Get task batch status")
gt_p.add_argument("--api-key", required=True, help="Nonce API key")
gt_p.add_argument("--task-batch-id", required=True, help="Task batch ID")
args = parser.parse_args()
if args.command is None:
parser.print_help()
sys.exit(1)
result = None
if args.command == "workspace":
result = get_workspace(args.api_key)
elif args.command == "farms":
result = list_farms(args.api_key)
elif args.command == "agents":
result = list_agents(args.api_key)
elif args.command == "miners":
result = list_miners(args.api_key, args.farm_id)
elif args.command == "metrics":
result = list_metrics_history(
args.api_key, args.farm_id,
start_date=getattr(args, "start_date", None),
end_date=getattr(args, "end_date", None),
)
elif args.command == "pool-diffs":
result = list_pool_diffs(args.api_key, args.farm_id)
elif args.command == "history":
result = list_history(
args.api_key, args.miner_id,
start_date=getattr(args, "start_date", None),
end_date=getattr(args, "end_date", None),
)
elif args.command == "miner-tasks":
result = list_miner_tasks(args.api_key, args.miner_id)
elif args.command == "task-batches":
result = list_task_batches(args.api_key, args.farm_id, args.page, args.page_size)
elif args.command == "create-task":
result = create_task_batch(
args.api_key, args.farm_id, args.task_name, args.miner_ids,
params=getattr(args, "params", None),
)
elif args.command == "get-task":
result = get_task_batch(args.api_key, args.task_batch_id)
if result is not None:
print(json.dumps(result, indent=2, ensure_ascii=False))
else:
print(json.dumps({"error": "Unknown command"}))
sys.exit(1)
if __name__ == "__main__":
main()
Web3 Skill Navigator / Web3 技能导航站. Describe your need in plain language to get matched AntalphaAI skill recommendations with install commands. Triggers: web1...
---
name: web123
version: 1.1.0
description: "Web3 Skill Navigator / Web3 技能导航站. Describe your need in plain language to get matched AntalphaAI skill recommendations with install commands. Triggers: web123, recommend skill, I want to trade tokens, check wallet balance, Web3 beginner, invest RWA, whale tracking, airdrop, meme token analysis, payment link, what Web3 skills are there, CEX trade, OKX Binance, technical analysis, KOL signal, contract security / 触发词：web123、推荐技能、我想交易代币、查余额、Web3新手、投资理财、聪明钱追踪、空投、meme币分析、收款链接、Web3技能有哪些、CEX交易、OKX、Binance、技术分析、KOL信号、合约安全扫描"
author: Antalpha AI
---
# web123 — Web3 Skill Navigator / Web3 技能导航站
> **"Web3 不会用，就上 web123" / "New to Web3? Start with web123."**
>
> AntalphaAI 官方 18 个 Skill 导航，自然语言匹配推荐
> Official navigator for 18 AntalphaAI skills — match by natural language
---
## Data Source / 数据来源
Skill metadata is stored in `references/skills.json`.
Only skills from the official [AntalphaAI GitHub org](https://github.com/AntalphaAI) are included.
技能元数据存储于 `references/skills.json`，仅收录 AntalphaAI GitHub org 真实发布的仓库。
**18 Skills / 18 个技能（v1.1 新增 5 个）：**
```
🔄 交易 (3)：web3-trader · cex-trader [NEW] · poly-master
💰 投资 (2)：antalpha-rwa-skill · web3-investor
📊 数据 (6)：wallet-balance · transaction-receipt · smart-money · defillama-data-aggregator · ta-radar [NEW] · crypto-social-intel [NEW]
🛡️ 安全 (4)：wallet-guard · anti-rug [NEW] · meme-token-analyzer · airdrop-hunter
💳 支付 (2)：eth-payment · walletconnect-requester
🔧 工具 (2)：antalpha-ai-setup [NEW] · antalpha-ai-docs [NEW]
```
### v1.1 新增技能 / What's New in v1.1
| Skill | 分类 | 亮点 |
|-------|------|------|
| `cex-trader` | 交易 | OKX + Binance 现货/合约，内置风控，API Key 引导配置 |
| `ta-radar` | 数据 | EMA/RSI/MACD/布林带多维技术分析，支持链上合约地址 |
| `crypto-social-intel` | 数据 | KOL 信号、情绪评分、提及量骤增预警、Fear & Greed 指数 |
| `anti-rug` | 安全 | 合约风险深度扫描，蜜罐/Rug Pull 检测，支持 ETH/BSC/Polygon |
| `antalpha-ai-setup` | 工具 | 60+ Web3 工具一键初始化配置向导 |
| `antalpha-ai-docs` | 工具 | 源码驱动 MCP 文档生成，自动对齐最新 API |
同时，`smart-money` 已更新至 v1.2，新增自定义地址订阅（最多 5 个）和 LP 池鲸鱼追踪。
---
## Trigger Conditions / 触发条件
Activate this skill when: / 以下情况触发本 skill：
- User mentions `web123`
- User describes a Web3 need in natural language (e.g. "I want to trade tokens", "check wallet balance")
- User says "Web3 beginner", "starter", "recommend a skill"
- User asks "what Web3 tools are there", "what skills does AntalphaAI have"
- User browses by category (e.g. "safety skills", "trading tools", "CEX trading")
---
## Recommendation Algorithm / 推荐算法 (MVP)
### Weights / 权重
```
tags match → +3 per match / 每次匹配 +3
scenarios match → +2 per match / 每次匹配 +2
description → +1 per match / 每次匹配 +1
beginner keyword → +5 bonus / 新手关键词额外 +5
```
### Steps / 步骤
1. Tokenize user input / 将用户输入分词
2. Score all skills by weight + priority / 按权重 + 优先级打分
3. Return Top 3 / 返回 Top 3
4. If beginner keyword detected → return starter pack / 检测到新手词 → 返回新手套装
### Edge Cases / 边界处理
| Situation / 情况 | Action / 处理 |
|-----------------|--------------|
| No match / 无匹配 | Return `hot_skills` Top 3 / 返回热门 Top 3 |
| >3 matches | Sort by score × priority, Top 3 |
| "新手" / "beginner" | Return 新手入门套装 |
| Category browse / 分类浏览 | List all skills in that category / 列出该分类所有技能 |
| "CEX" / "OKX" / "Binance" | Prioritize cex-trader |
| "技术分析" / "TA" / "K线" | Prioritize ta-radar |
| "KOL" / "情绪" / "社交" | Prioritize crypto-social-intel |
| "rug" / "蜜罐" / "合约安全" | Prioritize anti-rug |
---
## Execution Flow / 执行流程
### Step 1: Load Data / 加载数据
Load `references/skills.json` (relative to SKILL.md directory).
读取 `references/skills.json`（相对于 SKILL.md 目录）。
### Step 2: Detect Intent / 意图识别
| Intent / 意图 | Example / 示例 | Action / 处理 |
|--------------|---------------|--------------|
| Need match / 需求匹配 | "I want to trade" / "我想交易" | Keyword match → Top 3 |
| Beginner / 新手入门 | "Web3 beginner" / "新手入门" | Return starter pack / 返回新手套装 |
| Category browse / 分类浏览 | "Safety skills" / "安全类技能" | List category / 列出分类 |
| Exact lookup / 精确查找 | "How to install web3-trader" | Return skill detail / 返回详情 |
| Full list / 全览 | "What skills are there" / "有哪些技能" | Full matrix / 全景矩阵 |
### Step 3: Output / 输出
Use the templates below. / 按下方模板输出。
---
## Output Templates / 输出模板
### Single Skill / 单个推荐
```
🎯 Recommended / 推荐技能：{name}
📝 {description}
💡 Use cases / 使用场景：
- {example_1}
- {example_2}
📦 Install / 安装：{install}
🔗 GitHub：{github}
```
### Top 3 List / Top 3 推荐
```
🔍 Based on your need / 根据你的需求，推荐以下技能：
━━━━━━━━━━━━━━━━━━━
🥇 {name_1} — {description_1}
💡 {scenario_1}
📦 {install_1}
🥈 {name_2} — {description_2}
💡 {scenario_2}
📦 {install_2}
🥉 {name_3} — {description_3}
💡 {scenario_3}
📦 {install_3}
━━━━━━━━━━━━━━━━━━━
💡 Batch install / 批量安装：
openclaw skill install {github_1} {github_2} {github_3}
```
### Starter Pack / 新手套装
```
🎒 {pack_label}
{pack_description}
Includes / 包含 {count} skills:
- {skill_1} — {desc_1}
- {skill_2} — {desc_2}
- {skill_3} — {desc_3}
One-click install / 一键安装：
{install_command}
```
### Full Matrix / 全景产品矩阵
```
🌐 AntalphaAI Skills (18 total / 共 18 个)
🔄 Trading / 交易
• web3-trader — DEX swap + Hyperliquid perpetuals / DEX聚合交易+合约
• cex-trader — OKX/Binance spot & futures / CEX现货合约（NEW）
• poly-master — Polymarket prediction market / 预测市场+套利
💰 Investment / 投资
• antalpha-rwa — RWA on-chain yield / RWA链上理财
• web3-investor — DeFi portfolio / DeFi投资组合
📊 Data / 数据
• wallet-balance — Multi-chain balance / 多链钱包余额
• transaction-receipt — On-chain tx decoder / 链上交易解析
• smart-money — Whale tracking + custom watch v1.2 / 聪明钱+自定义监控
• defillama-data-aggregator — DeFi TVL data / DeFi数据
• ta-radar — Multi-dim TA: EMA/RSI/MACD / 技术分析雷达（NEW）
• crypto-social-intel — KOL signals + sentiment / KOL信号+情绪指数（NEW）
🛡️ Safety / 安全
• wallet-guard — Wallet approval scan / 钱包授权扫描
• anti-rug — Contract risk scanner / 合约安全深度扫描（NEW）
• meme-token-analyzer — Meme token analysis / Meme币财富基因
• airdrop-hunter — Daily airdrop intel / 空投情报日报
💳 Payment / 支付
• eth-payment — EIP-681 payment links / 收款链接生成
• walletconnect-requester — WalletConnect v2 / 钱包连接
🔧 Tools / 工具
• antalpha-ai-setup — 60+ tools setup guide / MCP一键配置向导（NEW）
• antalpha-ai-docs — Auto MCP docs generator / MCP文档自动生成（NEW）
💬 Tell me what you want to do, I'll recommend the best skill.
告诉我你想做什么，我来推荐最合适的技能！
```
---
## Quick Reference / 验收速查
| User says / 用户说 | Returns / 推荐 |
|-------------------|--------------|
| "I want to trade tokens" / "我想交易代币" | web3-trader |
| "OKX/Binance 下单" / "CEX 交易" | cex-trader |
| "Check wallet balance" / "查钱包余额" | wallet-balance |
| "Invest in RWA" / "投资RWA" | antalpha-rwa |
| "What are whales buying" / "聪明钱在买什么" | smart-money |
| "BTC 技术分析" / "K 线趋势" | ta-radar |
| "KOL 在讨论什么" / "市场情绪" | crypto-social-intel |
| "Check for rug pull" / "合约风险扫描" | anti-rug |
| "Check for rug pull" / "检测 honeypot" | wallet-guard + anti-rug |
| "Meme 币分析" / "财富基因" | meme-token-analyzer |
| "Airdrop tasks" / "空投任务" | airdrop-hunter |
| "Generate payment link" / "生成收款链接" | eth-payment |
| "配置 Antalpha MCP" / "快速接入" | antalpha-ai-setup |
| "Web3 beginner" / "Web3新手入门" | Starter pack / 新手套装 |
| "Safety skills" / "有哪些安全工具" | Safety category / 安全分类 |
| "All skills" / "有哪些技能" | Full matrix / 全景矩阵 |
| No match / 无匹配 | Hot Top 3 |
---
## Install / 安装
```bash
# Install web123 itself / 安装 web123
openclaw skill install https://github.com/AntalphaAI/web123
# Single skill / 安装单个
openclaw skill install https://github.com/AntalphaAI/web3-trader
# 新手包 / Beginner pack
openclaw skill install https://github.com/AntalphaAI/wallet-balance https://github.com/AntalphaAI/web3-trader https://github.com/AntalphaAI/transaction-receipt
# 交易套装 / Trading pack (v1.1 new)
openclaw skill install https://github.com/AntalphaAI/web3-trader https://github.com/AntalphaAI/cex-trader https://github.com/AntalphaAI/TA-Radar
# 数据情报套装 / Data intel pack (v1.1 new)
openclaw skill install https://github.com/AntalphaAI/smart-money https://github.com/AntalphaAI/crypto-social-intel https://github.com/AntalphaAI/TA-Radar
```
---
*Powered by Antalpha AI · web123 v1.1.0 · github.com/AntalphaAI*
FILE:README.md
[🇺🇸 English](#english) · [🇨🇳 中文](#chinese)
---
<a name="english"></a>
# web123 — Web3 Skill Navigator
> **"New to Web3? Start with web123."**
Describe your need in plain language — get the right Web3 skill recommendation instantly.
## 🚀 Quick Start
```bash
# Install
openclaw skill install https://github.com/AntalphaAI/web123
# Then just talk to your AI agent:
"I want to trade on OKX" → recommends cex-trader
"I want to trade tokens" → recommends web3-trader
"Check my wallet balance" → recommends wallet-balance
"Analyze BTC chart" → recommends ta-radar
"What are KOLs talking about" → recommends crypto-social-intel
"Scan this contract for rug pull" → recommends anti-rug
"I'm new to Web3, where to start" → recommends Beginner Pack
"What Web3 skills are available" → shows all 18 skills
```
## 📦 What's Inside (v1.1 — 18 Skills)
**18 official AntalphaAI Skills** across 6 categories:
| Category | Skill | Description |
|----------|-------|-------------|
| 🔄 Trading | `web3-trader` | DEX swap + Hyperliquid perpetuals |
| 🔄 Trading | `cex-trader` ⭐NEW | OKX/Binance spot & futures with risk controls |
| 🔄 Trading | `poly-master` | Polymarket prediction market + hedge strategy |
| 💰 Invest | `antalpha-rwa` | RWA on-chain yield |
| 💰 Invest | `web3-investor` | DeFi portfolio management |
| 📊 Data | `wallet-balance` | Multi-chain wallet balance |
| 📊 Data | `transaction-receipt` | On-chain transaction decoder |
| 📊 Data | `smart-money` | Whale tracking + custom address watch (v1.2) |
| 📊 Data | `defillama-data-aggregator` | DeFi TVL & yield data |
| 📊 Data | `ta-radar` ⭐NEW | EMA/RSI/MACD/Bollinger multi-dim TA |
| 📊 Data | `crypto-social-intel` ⭐NEW | KOL signals, sentiment, Fear & Greed |
| 🛡️ Safety | `wallet-guard` | Wallet approval risk scan |
| 🛡️ Safety | `anti-rug` ⭐NEW | Contract security: honeypot / rug pull detector |
| 🛡️ Safety | `meme-token-analyzer` | Meme token wealth-gene analysis |
| 🛡️ Safety | `airdrop-hunter` | Daily graded airdrop intel |
| 💳 Payment | `eth-payment` | EIP-681 payment link generator |
| 💳 Payment | `walletconnect-requester` | WalletConnect v2 wallet connector |
| 🔧 Tools | `antalpha-ai-setup` ⭐NEW | 60+ Web3 tools one-click MCP setup guide |
| 🔧 Tools | `antalpha-ai-docs` ⭐NEW | Auto-generate MCP tool docs from source |
## 🎒 Starter Packs
### Web3 Beginner
```bash
openclaw skill install https://github.com/AntalphaAI/wallet-balance https://github.com/AntalphaAI/web3-trader https://github.com/AntalphaAI/transaction-receipt
```
Check balance + trade tokens + verify transactions
### Safety Pack
```bash
openclaw skill install https://github.com/AntalphaAI/wallet-guard https://github.com/AntalphaAI/anti-rug https://github.com/AntalphaAI/Meme-Token-Analyzer
```
Wallet guard + contract scanner + meme analysis
### Trading Pack ⭐ Updated
```bash
openclaw skill install https://github.com/AntalphaAI/web3-trader https://github.com/AntalphaAI/cex-trader https://github.com/AntalphaAI/TA-Radar
```
Full trading stack: DEX + CEX + technical analysis
### Data Intel Pack ⭐ NEW
```bash
openclaw skill install https://github.com/AntalphaAI/smart-money https://github.com/AntalphaAI/crypto-social-intel https://github.com/AntalphaAI/TA-Radar
```
Smart money + social signals + TA radar — full market intelligence
## 💡 How It Works
```
User natural language input
↓
Intent detection (beginner / browse / match / full list)
↓
Tag-weighted matching (tags×3 + scenarios×2 + description×1)
↓
Return Top 3 recommendations + install commands
```
## 📁 File Structure
```
web123/
├── README.md ← You are here
├── SKILL.md ← Agent instruction file
└── references/
└── skills.json ← Skill metadata (18 skills)
```
## 🔗 AntalphaAI GitHub
All skills sourced from:
👉 [github.com/AntalphaAI](https://github.com/AntalphaAI)
---
*Powered by Antalpha AI · web123 v1.1.0*
---
<a name="chinese"></a>
# web123 — Web3 技能导航站
> **"Web3 不会用，就上 web123"**
一句话描述需求，AI 自动推荐最合适的 Web3 工具并给出安装命令。
## 🚀 快速开始
```bash
# 安装
openclaw skill install https://github.com/AntalphaAI/web123
# 然后直接跟 AI 说：
"帮我在 OKX 买 BTC" → 推荐 cex-trader
"我想交易代币" → 推荐 web3-trader
"查我的钱包余额" → 推荐 wallet-balance
"分析 BTC 技术面" → 推荐 ta-radar
"最近 KOL 在讨论什么" → 推荐 crypto-social-intel
"扫描这个合约有没有 rug" → 推荐 anti-rug
"Web3 新手，怎么开始" → 推荐新手入门套装
"有哪些 Web3 技能" → 展示全部 18 个 skill
```
## 📦 收录内容（v1.1 — 18 个 Skill）
共收录 **18 个** AntalphaAI 官方 Skill，覆盖 6 大分类：
| 分类 | Skill | 一句话描述 |
|------|-------|-----------|
| 🔄 交易 | `web3-trader` | DEX 聚合交易 + Hyperliquid 合约 |
| 🔄 交易 | `cex-trader` ⭐新 | OKX/Binance 现货合约，内置风控 |
| 🔄 交易 | `poly-master` | Polymarket 预测市场 + 套利对冲 |
| 💰 投资 | `antalpha-rwa` | RWA 链上理财 |
| 💰 投资 | `web3-investor` | DeFi 投资组合管理 |
| 📊 数据 | `wallet-balance` | 多链钱包余额查询 |
| 📊 数据 | `transaction-receipt` | 链上交易解析 |
| 📊 数据 | `smart-money` | 聪明钱追踪 + 自定义地址订阅 v1.2 |
| 📊 数据 | `defillama-data-aggregator` | DeFi TVL 数据聚合 |
| 📊 数据 | `ta-radar` ⭐新 | EMA/RSI/MACD/布林带多维技术分析 |
| 📊 数据 | `crypto-social-intel` ⭐新 | KOL 信号 + 情绪评分 + 恐慌贪婪指数 |
| 🛡️ 安全 | `wallet-guard` | 钱包高风险授权扫描 |
| 🛡️ 安全 | `anti-rug` ⭐新 | 合约安全扫描，蜜罐/Rug Pull 检测 |
| 🛡️ 安全 | `meme-token-analyzer` | Meme 币财富基因检测 |
| 🛡️ 安全 | `airdrop-hunter` | 空投情报日报 |
| 💳 支付 | `eth-payment` | EIP-681 收款链接生成 |
| 💳 支付 | `walletconnect-requester` | WalletConnect 钱包连接 |
| 🔧 工具 | `antalpha-ai-setup` ⭐新 | 60+ Web3 工具 MCP 一键配置向导 |
| 🔧 工具 | `antalpha-ai-docs` ⭐新 | 源码驱动 MCP 文档自动生成 |
## 🎒 新手套装
### 新手入门
```bash
openclaw skill install https://github.com/AntalphaAI/wallet-balance https://github.com/AntalphaAI/web3-trader https://github.com/AntalphaAI/transaction-receipt
```
查余额 + 交易代币 + 查交易记录
### 安全套装 ⭐ 已更新
```bash
openclaw skill install https://github.com/AntalphaAI/wallet-guard https://github.com/AntalphaAI/anti-rug https://github.com/AntalphaAI/Meme-Token-Analyzer
```
钱包防护 + 合约深度扫描 + Meme 币分析
### 交易套装 ⭐ 已更新
```bash
openclaw skill install https://github.com/AntalphaAI/web3-trader https://github.com/AntalphaAI/cex-trader https://github.com/AntalphaAI/TA-Radar
```
完整交易工具链：DEX + CEX + 技术分析
### 数据情报套装 ⭐ 全新
```bash
openclaw skill install https://github.com/AntalphaAI/smart-money https://github.com/AntalphaAI/crypto-social-intel https://github.com/AntalphaAI/TA-Radar
```
聪明钱 + 社交情报 + 技术分析，全维度市场洞察
## 💡 工作原理
```
用户自然语言输入
↓
意图识别（新手 / 分类浏览 / 需求匹配 / 全览）
↓
标签权重匹配算法（tags×3 + scenarios×2 + description×1）
↓
返回 Top 3 推荐 + 安装命令
```
## 📁 文件结构
```
web123/
├── README.md ← 你在这里
├── SKILL.md ← AI Agent 执行规范
└── references/
└── skills.json ← 18 个 skill 元数据
```
## 🔗 AntalphaAI GitHub
所有收录 skill 均来自：
👉 [github.com/AntalphaAI](https://github.com/AntalphaAI)
---
*Powered by Antalpha AI · web123 v1.1.0*
FILE:references/skills.json
{
"categories": {
"交易": {
"label": "🔄 交易",
"description": "代币买卖、DEX 交换、CEX 合约、预测市场",
"skills": ["web3-trader", "cex-trader", "poly-master"]
},
"投资": {
"label": "💰 投资",
"description": "链上理财、DeFi 投资、RWA 产品",
"skills": ["antalpha-rwa-skill", "web3-investor"]
},
"数据": {
"label": "📊 数据",
"description": "钱包查询、链上交易解析、DeFi 数据、聪明钱追踪、技术分析、社交情报",
"skills": ["wallet-balance", "transaction-receipt", "smart-money", "defillama-data-aggregator", "ta-radar", "crypto-social-intel"]
},
"安全": {
"label": "🛡️ 安全",
"description": "钱包防护、合约风险扫描、Meme 币分析、空投猎手",
"skills": ["wallet-guard", "anti-rug", "meme-token-analyzer", "airdrop-hunter"]
},
"支付": {
"label": "💳 支付",
"description": "收款链接生成、钱包连接",
"skills": ["eth-payment", "walletconnect-requester"]
},
"工具": {
"label": "🔧 工具",
"description": "环境配置、文档生成、新手引导",
"skills": ["antalpha-ai-setup", "antalpha-ai-docs"]
}
},
"skills": {
"web3-trader": {
"name": "web3-trader",
"category": "交易",
"github": "https://github.com/AntalphaAI/web3-trader",
"description": "DEX 聚合交易 + Hyperliquid 合约，支持市价 Swap 和限价单，零托管",
"tags": ["swap", "交易", "兑换", "DEX", "代币", "ETH", "USDT", "买入", "卖出", "限价单", "永续合约", "做多", "做空", "杠杆", "Hyperliquid", "合约", "期货"],
"scenarios": ["交易代币", "兑换加密货币", "做多做空", "开合约仓位", "限价挂单", "查看持仓"],
"examples": [
"帮我把 100 USDT 换成 ETH",
"我想挂单卖出 ETH，价格 3500U",
"帮我开 ETH 多仓，5 倍杠杆"
],
"install": "openclaw skill install https://github.com/AntalphaAI/web3-trader",
"priority": 10
},
"cex-trader": {
"name": "cex-trader",
"category": "交易",
"github": "https://github.com/AntalphaAI/cex-trader",
"description": "CEX 统一交易层，支持 OKX / Binance 现货与合约，开多开空、止盈止损，内置风控",
"tags": ["CEX", "OKX", "Binance", "现货", "合约", "期货", "做多", "做空", "开仓", "平仓", "止盈", "止损", "API key", "中心化交易所", "杠杆"],
"scenarios": ["OKX/Binance 下单", "查账户余额", "开合约多空仓", "平仓", "设置止盈止损", "配置 API Key"],
"examples": [
"帮我在 OKX 买 0.1 BTC",
"在 Binance 开 ETH 空仓，3 倍杠杆",
"帮我查一下 OKX 账户余额"
],
"install": "openclaw skill install https://github.com/AntalphaAI/cex-trader",
"priority": 10
},
"poly-master": {
"name": "poly-master",
"category": "交易",
"github": "https://github.com/AntalphaAI/poly-master",
"description": "Polymarket 预测市场，投注事件结果、跟单高手，套利对冲策略，零托管",
"tags": ["预测市场", "Polymarket", "投注", "事件", "跟单", "copy trade", "poly", "prediction", "赌注", "套利", "对冲"],
"scenarios": ["预测市场投注", "跟单交易员", "查看热门预测", "事件投资", "套利对冲"],
"examples": [
"帮我在 Polymarket 投注 ETH 价格走势",
"帮我找热门预测市场",
"我想跟单胜率最高的交易员"
],
"install": "openclaw skill install https://github.com/AntalphaAI/poly-master",
"priority": 8
},
"antalpha-rwa-skill": {
"name": "antalpha-rwa",
"category": "投资",
"github": "https://github.com/AntalphaAI/antalpha-rwa-skill",
"description": "RWA 链上理财，BTC 超额抵押，查询产品收益率并生成投资链接",
"tags": ["RWA", "理财", "投资", "收益", "稳定币", "USDT", "BTC抵押", "链上理财", "DeFi", "年化"],
"scenarios": ["投资 RWA 产品", "查询链上理财收益", "稳定币理财", "生成投资链接"],
"examples": [
"帮我查看当前 RWA 产品的收益率",
"我想投资 1000 USDT 做链上理财",
"帮我生成 RWA 投资链接"
],
"install": "openclaw skill install https://github.com/AntalphaAI/antalpha-rwa-skill",
"priority": 9
},
"web3-investor": {
"name": "web3-investor",
"category": "投资",
"github": "https://github.com/AntalphaAI/web3-investor",
"description": "AI 自主 Web3 投资基础设施，支持 DeFi 机会发现、安全交易执行、投资组合管理",
"tags": ["DeFi", "投资", "portfolio", "持仓", "投资组合", "Base", "Ethereum", "Arbitrum", "Optimism", "yield", "收益"],
"scenarios": ["DeFi 投资机会发现", "自动化投资策略", "管理链上投资组合", "查看持仓收益"],
"examples": [
"帮我分析当前 DeFi 投资机会",
"我的链上投资组合表现怎么样？",
"帮我找 Base 链上高收益机会"
],
"install": "openclaw skill install https://github.com/AntalphaAI/web3-investor",
"priority": 7
},
"wallet-balance": {
"name": "wallet-balance",
"category": "数据",
"github": "https://github.com/AntalphaAI/wallet-balance",
"description": "多链钱包余额查询，支持 EVM 和 BTC，可记住地址",
"tags": ["余额", "钱包", "balance", "ETH", "BTC", "资产", "持仓", "地址查询", "多链", "查余额"],
"scenarios": ["查钱包余额", "看我的资产", "查某地址持仓", "多链资产汇总"],
"examples": [
"帮我查一下我的钱包余额",
"0x123...abc 这个地址有多少 ETH",
"我的 BTC 钱包现在有多少钱"
],
"install": "openclaw skill install https://github.com/AntalphaAI/wallet-balance",
"priority": 9
},
"transaction-receipt": {
"name": "transaction-receipt",
"category": "数据",
"github": "https://github.com/AntalphaAI/transaction-receipt",
"description": "链上交易解析，查看转账、Swap、授权、NFT 铸造等操作详情",
"tags": ["交易", "tx", "transaction", "hash", "区块链", "转账记录", "swap记录", "NFT", "链上记录", "查交易"],
"scenarios": ["查交易记录", "验证转账是否成功", "解读链上交易", "查看 Swap 详情"],
"examples": [
"帮我查一下这笔交易：0xabc...",
"我的转账成功了吗？tx hash 是 0x...",
"帮我解读这笔 Swap 的详情"
],
"install": "openclaw skill install https://github.com/AntalphaAI/transaction-receipt",
"priority": 8
},
"smart-money": {
"name": "smart-money",
"category": "数据",
"github": "https://github.com/AntalphaAI/smart-money",
"description": "聪明钱鲸鱼追踪 v1.2，监控 VC/做市商/巨鲸链上操作，支持自定义地址订阅和 LP 池追踪",
"tags": ["聪明钱", "鲸鱼", "whale", "smart money", "VC", "链上信号", "追踪", "Paradigm", "a16z", "Wintermute", "跟单信号", "自定义监控", "LP", "流动性池", "添加钱包"],
"scenarios": ["追踪鲸鱼动态", "获取聪明钱买卖信号", "监控大户持仓", "添加自定义监控地址", "追踪鲸鱼入池活动"],
"examples": [
"最近聪明钱在买什么？",
"帮我追踪 Paradigm 钱包的动态",
"帮我添加 vitalik.eth 到我的监控地址"
],
"install": "openclaw skill install https://github.com/AntalphaAI/smart-money",
"priority": 8
},
"defillama-data-aggregator": {
"name": "defillama-data-aggregator",
"category": "数据",
"github": "https://github.com/AntalphaAI/defillama-data-aggregator",
"description": "DeFi 数据聚合，查询 TVL、协议排名、各链数据、高收益池，数据来源 DefiLlama",
"tags": ["DeFi", "TVL", "DefiLlama", "协议", "数据", "链上数据", "收益率", "yield", "defillama", "锁仓量"],
"scenarios": ["查询 DeFi TVL", "找高收益 DeFi 协议", "对比各链数据", "分析 DeFi 市场"],
"examples": [
"现在 DeFi 总 TVL 是多少？",
"帮我找收益率最高的 DeFi 协议",
"Ethereum 和 Solana 链的 TVL 对比"
],
"install": "openclaw skill install https://github.com/AntalphaAI/defillama-data-aggregator",
"priority": 7
},
"ta-radar": {
"name": "ta-radar",
"category": "数据",
"github": "https://github.com/AntalphaAI/TA-Radar",
"description": "多维技术分析雷达，支持 EMA/RSI/MACD/布林带，覆盖现货交易对与链上合约地址，自动双数据源兜底",
"tags": ["技术分析", "TA", "K线", "RSI", "MACD", "布林带", "EMA", "支撑阻力", "趋势分析", "BTC", "ETH", "合约地址", "价格分析"],
"scenarios": ["分析币价技术面", "查看 BTC K 线趋势", "判断入场时机", "分析链上代币价格"],
"examples": [
"帮我分析一下 BTC 的技术面",
"ETH 现在是支撑还是阻力位？",
"帮我看看 0x...这个代币的 K 线走势"
],
"install": "openclaw skill install https://github.com/AntalphaAI/TA-Radar",
"priority": 7
},
"crypto-social-intel": {
"name": "crypto-social-intel",
"category": "数据",
"github": "https://github.com/AntalphaAI/crypto-social-intel",
"description": "加密社交情报，追踪 KOL 信号、社交趋势、情绪评分、提及量骤增预警，Fear & Greed 指数",
"tags": ["KOL", "社交情报", "情绪", "sentiment", "推特", "社区", "热度", "恐慌贪婪", "fear greed", "提及量", "趋势", "舆情"],
"scenarios": ["追踪 KOL 动态", "查看市场情绪", "监控代币社交热度", "获取 Fear & Greed 指数"],
"examples": [
"最近加密圈 KOL 在讨论什么？",
"现在市场情绪是恐慌还是贪婪？",
"帮我监控 SOL 的社交热度"
],
"install": "openclaw skill install https://github.com/AntalphaAI/crypto-social-intel",
"priority": 6
},
"wallet-guard": {
"name": "wallet-guard",
"category": "安全",
"github": "https://github.com/AntalphaAI/wallet-guard",
"description": "钱包安全防护，一键扫描高风险授权，防止钱包被盗",
"tags": ["安全", "钱包安全", "授权", "approve", "风险", "防盗", "扫描", "安全检查", "撤销授权"],
"scenarios": ["检查钱包高风险授权", "撤销危险合约授权", "钱包安全扫描", "防止钱包被盗"],
"examples": [
"帮我检查钱包有没有危险授权",
"我的钱包资产安全吗？",
"扫描一下我的 approve 记录"
],
"install": "openclaw skill install https://github.com/AntalphaAI/wallet-guard",
"priority": 8
},
"anti-rug": {
"name": "anti-rug",
"category": "安全",
"github": "https://github.com/AntalphaAI/anti-rug",
"description": "Web3 代币合约安全扫描，检测蜜罐/Rug Pull/合约风险，支持 ETH/BSC/Polygon 等多链",
"tags": ["安全", "rug pull", "蜜罐", "honeypot", "合约风险", "代币扫描", "防骗", "合约审计", "土狗", "BSC", "Polygon", "ETH"],
"scenarios": ["扫描代币合约风险", "检测蜜罐代币", "防止 Rug Pull", "投资前合约审计"],
"examples": [
"帮我扫描这个代币合约是否安全",
"这个代币是蜜罐吗？合约地址 0x...",
"买入前帮我检测 Rug Pull 风险"
],
"install": "openclaw skill install https://github.com/AntalphaAI/anti-rug",
"priority": 8
},
"meme-token-analyzer": {
"name": "meme-token-analyzer",
"category": "安全",
"github": "https://github.com/AntalphaAI/Meme-Token-Analyzer",
"description": "Meme 币财富基因检测，多维度分析情绪、生成预测图像，输出专业投资分析报告",
"tags": ["meme", "meme币", "财富基因", "情绪分析", "土狗", "新币", "分析", "报告", "投机", "风险评估"],
"scenarios": ["分析 Meme 币潜力", "检测土狗风险", "查看新币热度", "生成投资分析报告"],
"examples": [
"帮我分析一下这个 meme 币的财富基因",
"PEPE 最近热度怎么样？",
"这个新币值得买吗？帮我做个分析"
],
"install": "openclaw skill install https://github.com/AntalphaAI/Meme-Token-Analyzer",
"priority": 7
},
"airdrop-hunter": {
"name": "airdrop-hunter",
"category": "安全",
"github": "https://github.com/AntalphaAI/airdrop-hunter",
"description": "Web3 空投情报，每日 S/A/B 评级推送，防骗预警，自动生成空投日报",
"tags": ["空投", "airdrop", "零撸", "测试网", "任务", "薅羊毛", "项目", "早期", "空投猎手"],
"scenarios": ["查找高价值空投", "每日空投情报", "零成本空投任务", "空投项目检测"],
"examples": [
"今天有什么值得做的空投？",
"帮我找零成本的测试网任务",
"给我 S 级空投项目列表"
],
"install": "openclaw skill install https://github.com/AntalphaAI/airdrop-hunter",
"priority": 7
},
"eth-payment": {
"name": "eth-payment",
"category": "支付",
"github": "https://github.com/AntalphaAI/eth-payment",
"description": "生成 EIP-681 以太坊收款链接和二维码，支持所有 EVM 链，零配置",
"tags": ["收款", "付款", "payment", "EIP-681", "二维码", "QR", "发票", "转账链接", "EVM", "以太坊"],
"scenarios": ["生成收款链接", "创建支付二维码", "收取 ETH 或代币", "生成付款请求"],
"examples": [
"帮我生成一个收款 100 USDT 的链接",
"我想收 0.1 ETH，帮我生成二维码",
"给我创建一个 Base 链的收款地址"
],
"install": "openclaw skill install https://github.com/AntalphaAI/eth-payment",
"priority": 6
},
"walletconnect-requester": {
"name": "walletconnect-requester",
"category": "支付",
"github": "https://github.com/AntalphaAI/walletconnect-requester",
"description": "WalletConnect v2 集成，以 DApp 身份安全连接用户钱包，发起交易和签名请求，零托管",
"tags": ["WalletConnect", "钱包连接", "DApp", "连接钱包", "签名", "交易授权", "零托管"],
"scenarios": ["连接用户钱包", "请求交易签名", "DApp 钱包集成", "安全授权操作"],
"examples": [
"帮我连接用户的 MetaMask 钱包",
"我需要请求用户授权一笔交易",
"用 WalletConnect 连接钱包并发起转账"
],
"install": "openclaw skill install https://github.com/AntalphaAI/walletconnect-requester",
"priority": 5
},
"antalpha-ai-setup": {
"name": "antalpha-ai-setup",
"category": "工具",
"github": "https://github.com/AntalphaAI/antalpha-ai-setup",
"description": "Antalpha Skills MCP Server 配置向导，60+ Web3 工具一键接入，DEX/聪明钱/Polymarket/Hyperliquid/DeFi 全覆盖",
"tags": ["setup", "配置", "安装", "MCP", "新手", "入门", "初始化", "环境配置", "antalpha", "接入"],
"scenarios": ["首次配置 Antalpha MCP Server", "新手环境初始化", "接入全套 Web3 工具"],
"examples": [
"帮我配置 Antalpha AI 工具包",
"我想快速接入所有 AntalphaAI Web3 技能",
"怎么初始化 Antalpha MCP 环境？"
],
"install": "openclaw skill install https://github.com/AntalphaAI/antalpha-ai-setup",
"priority": 9
},
"antalpha-ai-docs": {
"name": "antalpha-ai-docs",
"category": "工具",
"github": "https://github.com/AntalphaAI/antalpha-ai-docs",
"description": "读取源代码自动生成/更新 Antalpha Skills MCP 文档，让 Agent 始终对齐最新 API",
"tags": ["文档", "docs", "API文档", "MCP", "源码", "自动生成", "antalpha", "开发者"],
"scenarios": ["查询 MCP 工具文档", "获取最新 API 说明", "自动同步工具文档"],
"examples": [
"帮我查一下 smart-money-watch 工具的参数",
"Antalpha MCP 有哪些可用工具？",
"帮我生成最新的 MCP 工具文档"
],
"install": "openclaw skill install https://github.com/AntalphaAI/antalpha-ai-docs",
"priority": 5
}
},
"starter_packs": {
"新手入门": {
"label": "🎒 新手入门套装",
"description": "Web3 三件套，查余额 + 交易 + 查记录",
"skills": ["wallet-balance", "web3-trader", "transaction-receipt"],
"install": "openclaw skill install https://github.com/AntalphaAI/wallet-balance https://github.com/AntalphaAI/web3-trader https://github.com/AntalphaAI/transaction-receipt"
},
"安全套装": {
"label": "🛡️ 安全套装",
"description": "钱包防护 + 合约扫描 + 空投猎手",
"skills": ["wallet-guard", "anti-rug", "meme-token-analyzer"],
"install": "openclaw skill install https://github.com/AntalphaAI/wallet-guard https://github.com/AntalphaAI/anti-rug https://github.com/AntalphaAI/Meme-Token-Analyzer"
},
"交易套装": {
"label": "💱 交易套装",
"description": "全链路交易，DEX + CEX + 技术分析",
"skills": ["web3-trader", "cex-trader", "ta-radar"],
"install": "openclaw skill install https://github.com/AntalphaAI/web3-trader https://github.com/AntalphaAI/cex-trader https://github.com/AntalphaAI/TA-Radar"
},
"数据情报套装": {
"label": "🔭 数据情报套装",
"description": "聪明钱 + 社交情报 + 技术分析，全维度行情洞察",
"skills": ["smart-money", "crypto-social-intel", "ta-radar"],
"install": "openclaw skill install https://github.com/AntalphaAI/smart-money https://github.com/AntalphaAI/crypto-social-intel https://github.com/AntalphaAI/TA-Radar"
}
},
"hot_skills": ["web3-trader", "cex-trader", "wallet-balance", "smart-money", "anti-rug"]
}
Smart money whale tracking skill. Activate when user mentions smart money, whale tracking, 聪明钱, 鲸鱼追踪, fund tracking, on-chain signals, what are whales buying...
---
name: smart-money
version: 1.2.1
description: Smart money whale tracking skill. Activate when user mentions smart money, whale tracking, 聪明钱, 鲸鱼追踪, fund tracking, on-chain signals, what are whales buying, track wallet, Paradigm, a16z, Wintermute, token buy sell signals, DEX trader monitoring, whale LP activity, pool liquidity, whale pool entry, 鲸鱼入池, 流动性池, LP追踪, custom wallet watch, 自定义监控地址, 添加监控钱包, 订阅地址信号.
metadata: {"openclaw":{"requires":{},"mcp":{"antalpha":{"url":"https://mcp-skills.ai.antalpha.com/mcp","tools":["antalpha-register","smart-money-signal","smart-money-watch","smart-money-list","smart-money-custom","smart-money-scan","smart-money-pool"]}}}}
---
# Smart Money Tracker
Track smart money (whale, VC fund, market maker) wallet activities on Ethereum mainnet. Get real-time trading signals when watched wallets make significant moves.
**v1.2.1**: After adding a custom address, agent **must** guide user to create a Cron monitoring task — without it, signals land in the database but the user receives no notification.
**v1.2**: Custom address subscriptions — add up to 5 personal wallets for real-time on-chain monitoring. Same address added by multiple agents shares one subscription stream (Reference Counting), no duplicate billing.
**v1.1**: Pool liquidity tracking — detect when whales add/remove liquidity on Uniswap V2/V3.
## MCP Endpoint
```
https://mcp-skills.ai.antalpha.com/mcp
```
Protocol: MCP Streamable HTTP (JSON-RPC over HTTP with `mcp-session-id` header).
### Connection Flow
```
1. POST /mcp → initialize (get mcp-session-id from response header)
2. POST /mcp → tools/call (with mcp-session-id header)
```
## Setup — Agent Registration
Before using any smart-money tools, register once:
```
Tool: antalpha-register
Args: {}
Returns: { agent_id, api_key, created_at }
```
**Persist both `agent_id` and `api_key` locally:**
- Store at `~/.smart-money/agent.json`
- `agent_id` — pass in all subsequent tool calls
- `api_key` — when server-side API key auth is enabled, send as HTTP header `x-antalpha-agent-api-key` on every MCP request
Example `agent.json`:
```json
{
"agent_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"api_key": "sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"created_at": "2026-03-28T09:00:00.000Z"
}
```
On first use:
1. Check if `~/.smart-money/agent.json` exists
2. If not, call `antalpha-register`, save both `agent_id` and `api_key`
3. Use `agent_id` for all MCP calls; include `api_key` as header if auth is enabled
## MCP Tools (7)
### antalpha-register
Register a new agent. Returns unique `agent_id` and `api_key`. Call once, persist both.
### smart-money-signal
Get trading signals from monitored wallets (public pool + your custom addresses).
**Parameters:**
- `agent_id` (required): Your agent ID
- `level` (optional): `high` / `medium` / `low` / `all` (default: `all`)
- `limit` (optional): 1-100 (default: 20)
- `since` (optional): ISO 8601 timestamp
**Signal Levels (Transfer/Swap):**
- 🔴 **HIGH**: Large buy >$50K or first-time token position
- 🟡 **MEDIUM**: Accumulation (≥2 buys of same token in 24h) or large sell >$50K
- 🟢 **LOW**: Regular transfers $1K-$50K
**Signal Types:** `BUY` / `SELL` / `TRANSFER` / `POOL_IN` / `POOL_OUT`
### smart-money-watch
View a specific wallet's recent trading activity.
**Parameters:**
- `agent_id` (required): Your agent ID
- `address` (required): Ethereum address (must be in public pool or your custom list)
- `limit` (optional): 1-50 (default: 10)
### smart-money-list
List all monitored wallets (public + custom, labeled).
**Parameters:**
- `agent_id` (required): Your agent ID
### smart-money-custom
Manage custom watchlist — add, remove, or list personal monitoring addresses (max 5 per agent). v1.2: each add auto-registers an on-chain data subscription; same address shared across agents reuses one subscription stream (RC).
**Parameters:**
- `agent_id` (required): Your agent ID
- `action` (required): `add` / `remove` / `list`
- `address` (optional): Ethereum address (required for add/remove)
- `label` (optional): Human-readable name (required for add)
**Behavior:**
- `add`: validates limit (≤5), creates/reuses subscription stream (RC), back-fills `stream_id`
- `remove`: decrements RC; cancels subscription only when last reference is released
- `list`: returns all custom addresses with `stream_id` and status
### smart-money-scan
Trigger on-demand scan of your custom addresses. Public pool is scanned automatically by the server.
**Parameters:**
- `agent_id` (required): Your agent ID
### smart-money-pool
Query LP (liquidity pool) activity for smart money addresses. Returns add/remove liquidity events on Uniswap V2/V3.
**Parameters:**
- `agent_id` (required): Your agent ID
- `address` (required): Whale wallet address (`0x...`)
- `event_type` (optional): `POOL_IN` / `POOL_OUT` / `all` (default: `all`)
- `dex` (optional): `uniswap_v2` / `uniswap_v3` / `all` (default: `all`)
- `limit` (optional): 1-50 (default: 10)
- `since` (optional): ISO 8601 timestamp
**Signal Levels (Pool events):**
- 🔴 **HIGH**: POOL_IN > $100K
- 🟡 **MEDIUM**: POOL_IN $10K–$100K
- 🟢 **LOW**: POOL_IN < $10K
## Workflow
### Query Signals (most common)
```
1. smart-money-signal { agent_id, level: "high", limit: 10 }
2. Present signals to user with level/token/amount/context
```
### Add Custom Wallet & Monitor (v1.2.1)
```
1. smart-money-custom { agent_id, action: "add", address: "0x...", label: "My Whale" }
→ On-chain subscription registered; stream_id back-filled
2. smart-money-scan { agent_id } ← trigger first scan
3. smart-money-signal { agent_id } ← check current results
4. ⚠️ MANDATORY: Guide user to create Cron (see Agent Behavior Rules below)
→ Without Cron, signals are stored server-side but user will NEVER be notified
```
### List / Remove Custom Address
```
# List all custom addresses
smart-money-custom { agent_id, action: "list" }
# Remove and auto-cancel on-chain subscription
smart-money-custom { agent_id, action: "remove", address: "0x..." }
```
### Periodic Monitoring (v1.2.1 — Mandatory Cron Setup)
> ⚠️ **Critical**: The on-chain data provider pushes events to the MCP Server in real time, but MCP cannot push to the agent. Without a Cron task, signals are stored server-side and the user will **never receive any notification**. Always create a Cron task after adding a custom address — do not leave it optional.
When the user asks to "monitor", "track", "watch", "set alert", "定时监控", "设置提醒", or after any `smart-money-custom action=add`:
**Step 1 — Set up the watchlist:**
```
1. smart-money-custom { action: "add", address: "0x...", label: "..." }
2. smart-money-scan { agent_id }
3. Confirm to user: "Address added, on-chain subscription registered."
```
**Step 2 — MANDATORY: Guide user to create Cron immediately**
Use this exact language (adapt to locale):
```
⚠️ 重要提示 / Important:
服务商已开始实时监控该地址，但 MCP 协议无法主动推送通知。
链上信号会实时落库，但不创建定时检查任务你将永远收不到提醒。
强烈建议立即创建定时任务，我来帮你自动完成。
The data provider is now tracking this address in real time, but MCP
cannot push notifications to you. On-chain signals will be stored, but
you will NEVER be alerted without a scheduled check task.
Let me create the Cron task for you now.
强烈建议：立即创建 15 分钟定时任务（我帮你自动执行）：
Strongly recommended: create a 15-min Cron task now (auto-executed for you):
```
**Step 3 — Create Cron immediately (agent executes without waiting for extra confirmation):**
Recommended interval: *15 minutes* (balances responsiveness vs. token cost).
```bash
openclaw cron add \
--name "smart-money-alert" \
--cron "*/15 * * * *" \
--session isolated \
--message "Call smart-money-signal with agent_id <id>, level high, since <last_check_iso>. If new signals exist, notify me with details. If no new signals, reply HEARTBEAT_OK silently. Save current timestamp as last_check."
```
Key Cron design principles:
- `--session isolated` — runs independently, no context bleed
- Reply `HEARTBEAT_OK` when no new signals (zero output tokens)
- Pass `since` = last check timestamp to avoid duplicate alerts
- 15-min interval ≈ ~96 checks/day per user; each check ~500 tokens if silent
- Agent should execute this automatically after `add` succeeds — do not wait for user to ask
**Step 4 — Save monitor state:**
`~/.smart-money/monitor-state.json`:
```json
{
"agent_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"monitoring": true,
"interval_minutes": 15,
"min_level": "high",
"last_check": "2026-04-17T08:00:00Z",
"addresses_monitored": 1,
"cron_name": "smart-money-alert"
}
```
## Agent Behavior Rules
### On "Monitor this address" / "添加监控" / "订阅地址" (v1.2.1)
1. Call `smart-money-custom { action: "add", ... }` — on-chain subscription auto-registered
2. Run `smart-money-scan` immediately for baseline
3. **⚠️ MANDATORY**: Show the strong nudge (see Periodic Monitoring → Step 2), then **immediately proceed to create the Cron task** — do not make it optional, do not wait for user to ask
4. Execute `openclaw cron add` with 15-min interval and `--session isolated`
5. Confirm: address added, stream_id, Cron job name and schedule
6. Only if user explicitly says "no cron" / "cancel" / "不要" — acknowledge and skip, but warn one more time that alerts will not work
### On "Remove monitoring" / "取消监控"
1. Call `smart-money-custom { action: "remove", address: "0x..." }` — on-chain subscription auto-cancelled
2. Update or cancel the associated Cron job
3. Confirm: "Monitoring stopped. On-chain subscription cancelled."
### On "List my custom addresses" / "查看我的自定义监控"
1. Call `smart-money-custom { action: "list" }`
2. Show: address, label, stream_id (active/inactive), added_at
3. Show remaining slots: `5 - current_count`
### On session start (if monitoring is enabled)
1. Read `~/.smart-money/monitor-state.json`
2. If `monitoring: true` and `now - last_check > interval`:
- Run scan + signal check silently
- Only speak up if new signals found
- Update `last_check`
## Message Template
When presenting signals to the user:
```
🔴 HIGH Signal | Paradigm Fund
Buy PEPE — $127.5K
First position (never held before)
TX: 0xabc...def | 2026-03-28 16:30 UTC
🟡 MEDIUM Signal | Jump Trading
Accumulating ARB — $45K
3rd buy in 24h
TX: 0x123...456 | 2026-03-28 15:20 UTC
```
**Pool signal template:**
```
🔴 HIGH Signal | Paradigm Fund
POOL_IN — USDC/ETH (Uniswap V3)
投入 $215K，池子 0x88e6A...
TX: 0xabc...def | 2026-04-14 04:00 UTC
```
**Custom address signal template (v1.2):**
```
🟡 MEDIUM Signal | My Custom Whale [custom]
Buy ETH — $38K
2nd buy in 24h
Stream: mock-stream-102
TX: 0xdef...789 | 2026-04-17 08:10 UTC
```
## Public Pool (19 wallets)
VC Funds: Paradigm, a16z, Polychain Capital, Dragonfly Capital, DeFiance Capital
Market Makers: Wintermute, Jump Trading, Cumberland DRW
Whales: Vitalik.eth, Justin Sun, James Fickel
DeFi: Uniswap V2 ETH/USDT, Lido stETH, 0x Protocol
Exchanges: Binance Hot Wallet 14, Robinhood
Other: Nansen Smart Money 1, Alameda Research (Remnant), Celsius (Remnant)
## Data Source
- **On-chain data provider** — ERC20 transfers, native transfers, token prices
- **Real-time event streams** (v1.1+) — LP events + custom address webhook ingestion
- **ETH Mainnet only** (V1)
## Changelog
### v1.2.1 (2026-04-17)
- New: Agent auto-creates Cron after `smart-money-custom action=add` (no user prompt needed)
- New: Strong-nudge copy (EN + ZH): "you will NEVER be alerted without Cron"
- New: Recommended interval 15 min, `--session isolated`; agent executes without extra confirm
- Improved: Agent Behavior Rules — `add` flow creates Cron immediately, optional only on explicit refusal
### v1.2.0 (2026-04-17)
- New: `smart-money-custom` upgraded — `add/remove/list` with on-chain subscription auto-management
- New: Reference Counting (RC) — same address across multiple agents shares ONE subscription stream
- New: `sm_stream_registry` global address→stream registry table
- New: `agent_watched_wallets` per-agent custom watchlist table
- New: `smart-money-signal` merges public pool + agent custom addresses (two-path query)
- Improved: `smart-money-custom action=list` returns `stream_id` + `added_at`
### v1.1.0 (2026-04-14)
- New: `smart-money-pool` tool — query whale LP add/remove activity on Uniswap V2/V3
- New: `smart-money-signal` extended with `POOL_IN` / `POOL_OUT` signal types
- New: Real-time on-chain event stream integration for LP event ingestion
### v1.0.2
- Added auto-monitoring setup guide and agent behavior rules
### v1.0.1
- Various bugfixes, address normalization, README rewrite
### v1.0.0 (2026-03-28)
- Initial release
## Security Notes
- Agent identity via UUID — no private keys involved
- `api_key` is secret; store securely, never expose in logs or prompts
- Custom watchlist addresses are isolated per `agent_id` (multi-tenant)
- On-chain subscription cancelled automatically on `remove` (no zombie subscriptions)
- All data comes from public blockchain; no user funds are touched
---
## Brand Attribution
Every user-facing reply generated by this skill **must** end with the following tagline (after all content, on its own line):
- 中文: `由 Antalpha AI 提供聚合服务`
- English: `Powered by Antalpha AI`
- Other languages: same meaning, keep brand name **Antalpha AI** unchanged
FILE:README.md
[🇺🇸 English](#english) · [🇨🇳 中文](#chinese)
---
<a name="english"></a>
# Smart Money Tracker
> AI Agent on-chain whale tracking skill. Track smart money wallets, get real-time trading signals including LP pool entries and custom address subscriptions.
**v1.2**: Add up to 5 personal wallets for real-time monitoring. Same address shared across agents uses one subscription stream (Reference Counting) — no duplicate billing.
**v1.1**: Whale LP activity tracking — detect when smart money adds/removes liquidity on Uniswap V2/V3.
## Install
```bash
openclaw skill install https://github.com/AntalphaAI/smart-money
```
## Architecture
```
Agent (OpenClaw) ──MCP──► Antalpha Server ──► On-chain Data Provider
│ (Streams + REST)
agent_id ├── smart_money_watchlist
├── agent_watched_wallets ← v1.2 new
└── sm_stream_registry ← v1.2 new (RC)
```
- **MCP remote mode**: Backend on Antalpha server, agents call via MCP protocol
- **Multi-tenant isolation**: Each agent gets a unique `agent_id`, custom watchlists are isolated per agent
- **Zero config**: No local API keys required for MCP mode
- **RC-based Streams**: Same wallet address across multiple agents shares one subscription stream
## Quick Start
```
# Step 1: Register (once)
Tool: antalpha-register
→ Save agent_id + api_key to ~/.smart-money/agent.json
# Step 2: Get whale signals
Tool: smart-money-signal
Args: { agent_id: "...", level: "high" }
# Step 3 (v1.2): Add your own address
Tool: smart-money-custom
Args: { agent_id: "...", action: "add", address: "0x...", label: "My Whale" }
→ On-chain subscription registered, stream_id back-filled
# Step 4: Query merged signals (public + your custom)
Tool: smart-money-signal
Args: { agent_id: "...", level: "all" }
```
## MCP Server
```
https://mcp-skills.ai.antalpha.com/mcp
```
## MCP Tools
| Tool | v | Description |
|------|---|-------------|
| `antalpha-register` | v1 | Register agent, get `agent_id` + `api_key` (call once) |
| `smart-money-signal` | v1.2 | Get trading signals — public pool **+** your custom addresses merged |
| `smart-money-watch` | v1 | View a specific wallet's recent activity |
| `smart-money-list` | v1 | List all monitored wallets (public + custom) |
| `smart-money-custom` | v1.2 | **Add / remove / list** custom addresses with auto on-chain subscription RC |
| `smart-money-scan` | v1 | Trigger on-demand scan of custom addresses |
| `smart-money-pool` | v1.1 | Query whale LP activity on Uniswap V2/V3 |
## User Scenarios
### 🔍 Scenario 1 — Daily whale signal check
> "What are smart money wallets buying today?"
```
smart-money-signal { agent_id, level: "high", limit: 20 }
```
Response:
```
🔴 HIGH Signal | Paradigm Fund
Buy PEPE — $127.5K · First position ever
TX: 0xabc...def | 2026-04-17 08:00 UTC
🟡 MEDIUM Signal | Wintermute
Accumulating ARB — $45K · 3rd buy in 24h
TX: 0x123...456 | 2026-04-17 06:20 UTC
Powered by Antalpha AI
```
---
### 👁 Scenario 2 — Track a specific wallet's activity
> "Show me what Paradigm has been doing lately"
```
smart-money-watch { agent_id, address: "0xParadigm...", limit: 10 }
```
---
### ➕ Scenario 3 — Add a personal wallet to monitor (v1.2.1)
> "Track this address for me: 0xABC... — it's my target whale"
```
# Step 1: Add to custom list (on-chain subscription auto-registered)
smart-money-custom {
agent_id,
action: "add",
address: "0xABC...",
label: "Target Whale"
}
# Step 2: Trigger first scan
smart-money-scan { agent_id }
# Step 3: Check current signals
smart-money-signal { agent_id, level: "all" }
```
> ⚠️ **After Step 1, agent MUST show this warning:**
>
> *The data provider is now tracking `0xABC...` in real time. However, MCP cannot push notifications to you — signals are stored server-side only. **Without a scheduled Cron task, you will NEVER receive alerts.***
>
> *Strongly recommended: create a 15-min Cron task now — I will execute it for you automatically. Skipping this means you will not receive any alerts.*
```bash
# Step 4 (recommended — after user confirms):
openclaw cron add \
--name "smart-money-alert" \
--cron "*/15 * * * *" \
--session isolated \
--message "Call smart-money-signal agent_id <id> level high since <last_check>. Alert if new signals. Reply HEARTBEAT_OK if none."
```
**Result**: Address is monitored via on-chain data subscription. Combined signals (public pool + custom) returned by `smart-money-signal`. Cron closes the notification loop.
---
### 📋 Scenario 4 — List and manage custom addresses (v1.2)
> "Which addresses am I watching? How many slots are left?"
```
smart-money-custom { agent_id, action: "list" }
```
Response:
```json
{
"private_count": 2,
"remaining_slots": 3,
"wallets": [
{ "address": "0xABC...", "label": "Target Whale", "stream_id": "abc-123", "added_at": "2026-04-17T08:00:00Z" },
{ "address": "0xDEF...", "label": "Fund X", "stream_id": "def-456", "added_at": "2026-04-16T12:00:00Z" }
]
}
```
---
### ➖ Scenario 5 — Remove a custom address (v1.2)
> "Stop tracking 0xABC..."
```
smart-money-custom { agent_id, action: "remove", address: "0xABC..." }
```
**Result**: Address removed, on-chain subscription cancelled (if no other agents are watching the same address via Reference Counting).
---
### 🏊 Scenario 6 — Whale LP pool activity
> "Is Paradigm adding liquidity anywhere recently?"
```
smart-money-pool {
agent_id,
address: "0xParadigm...",
event_type: "POOL_IN",
dex: "uniswap_v3",
limit: 5
}
```
Response:
```
🔴 HIGH Signal | Paradigm Fund
POOL_IN — USDC/ETH (Uniswap V3) · $215K
Pool: 0x88e6A... TX: 0xabc...def | 2026-04-14 04:00 UTC
```
---
### ⏰ Scenario 7 — Set up recurring monitoring (OpenClaw)
> "Alert me every hour if any high-level signals appear"
> ⚠️ **Why this matters**: The on-chain data provider pushes events to the MCP Server in real time, but MCP cannot push to you. Without this Cron, signals accumulate silently and you receive zero notifications.
```bash
# Recommended: 15-min interval for responsive alerts with reasonable token cost
openclaw cron add \
--name "smart-money-alert" \
--cron "*/15 * * * *" \
--session isolated \
--message "Call smart-money-signal with agent_id <id>, level high, since <last_check_iso>. If new signals found, notify me with a summary. If none, reply HEARTBEAT_OK."
```
*Cost note*: `--session isolated` + `HEARTBEAT_OK` on no-signal runs minimizes token usage. Each silent check ≈ 500 tokens; only pays full cost when real signals appear.
---
### 🔄 Scenario 8 — Multiple agents, same address (RC behavior)
> Agent A and Agent B both add `0xVitalik...`
- Agent A adds → on-chain subscription created, `ref_count = 1`
- Agent B adds → **same subscription reused**, `ref_count = 2`, no duplicate billing
- Agent A removes → `ref_count = 1`, subscription still active
- Agent B removes → `ref_count = 0`, subscription cancelled automatically
---
## Signal Levels
**Transfer / Swap signals:**
| Level | Trigger |
|-------|---------|
| 🔴 HIGH | Large buy > $50K, or first-time token position |
| 🟡 MEDIUM | Accumulation (≥2 buys of same token in 24h), or large sell > $50K |
| 🟢 LOW | Regular transfers $1K–$50K |
**Pool signals (POOL_IN / POOL_OUT):**
| Level | Trigger |
|-------|---------|
| 🔴 HIGH | Pool entry > $100K |
| 🟡 MEDIUM | Pool entry $10K–$100K |
| 🟢 LOW | Pool entry < $10K |
## Public Pool (19 wallets)
VC Funds: Paradigm, a16z, Polychain Capital, Dragonfly Capital, DeFiance Capital
Market Makers: Wintermute, Jump Trading, Cumberland DRW
Whales: Vitalik.eth, Justin Sun, James Fickel
DeFi: Uniswap V2 ETH/USDT, Lido stETH, 0x Protocol
Exchanges: Binance Hot Wallet 14, Robinhood
Other: Nansen Smart Money 1, Alameda Research (Remnant), Celsius (Remnant)
## Data Source
- **On-chain data provider** — ERC20 transfers, native transfers, token prices
- **Real-time event streams** (v1.1+) — LP events + custom address webhook ingestion
- **ETH Mainnet only** (V1)
## Security Notes
- Agent identity via UUID — no private keys involved
- `api_key` is secret; store securely, never expose in logs or prompts
- Custom watchlist addresses are isolated per `agent_id` (multi-tenant)
- On-chain subscription cancelled automatically on `remove` (no zombie subscriptions, RC-guarded)
- All data comes from public blockchain; no user funds are touched
## Changelog
### v1.2.1 (2026-04-17)
- Mandatory Cron setup prompt after `smart-money-custom action=add`
- Strong-nudge copy: "without Cron you will NEVER be notified" (EN + ZH)
- Recommended interval: 15 min with `--session isolated` flag
- Scenario 3 and 7 updated with actionable Cron commands
### v1.2.0 (2026-04-17)
- `smart-money-custom` upgraded: supports `add` / `remove` / `list` with on-chain subscription auto-management
- Reference Counting (RC): same address across multiple agents shares ONE subscription stream; auto-cleanup when last reference released
- New DB tables: `agent_watched_wallets`, `sm_stream_registry`
- `smart-money-signal` merges public pool + agent custom addresses in one response
### v1.1.0 (2026-04-14)
- New: `smart-money-pool` — whale LP add/remove events (Uniswap V2/V3)
- New: `POOL_IN` / `POOL_OUT` signal types in `smart-money-signal`
- New: Real-time on-chain event stream integration for LP webhook ingestion
### v1.0.2
- Add: monitoring setup guide, agent behavior rules
### v1.0.1 (2026-03-28)
- Various bugfixes and address normalization
### v1.0.0 (2026-03-28)
- Initial release
## License
MIT
---
<a name="chinese"></a>
# Smart Money 聪明钱追踪器
> AI Agent 链上鲸鱼追踪技能。追踪聪明钱钱包动向，获取实时交易信号（含 LP 入池信号与自定义地址订阅）。
**v1.2 新增**：自定义地址订阅 — 最多添加 5 个个人监控地址，通过实时数据订阅服务推送信号。相同地址跨多个 Agent 共享一个订阅流（引用计数），避免重复计费。
**v1.1 新增**：鲸鱼 LP 行为追踪 — 当聪明钱在 Uniswap V2/V3 添加流动性时自动生成高强度信号。
## 安装
```bash
openclaw skill install https://github.com/AntalphaAI/smart-money
```
## 架构
```
Agent (OpenClaw) ──MCP──► Antalpha 服务器 ──► On-chain Data Provider
│ (Streams + REST)
agent_id ├── smart_money_watchlist
├── agent_watched_wallets ← v1.2 新增
└── sm_stream_registry ← v1.2 新增（引用计数）
```
- **MCP 远程模式**：后端部署在 Antalpha 服务器，Agent 通过 MCP 协议调用
- **多租户隔离**：每个 Agent 获得唯一 `agent_id`，自定义监控列表相互隔离
- **零配置**：MCP 模式无需本地 API Key
- **引用计数 Stream**：多 Agent 监控同一地址时共享一个订阅流
## 快速上手
```
# 第一步：注册（仅需一次）
工具：antalpha-register
→ 保存 agent_id + api_key 到 ~/.smart-money/agent.json
# 第二步：获取鲸鱼信号
工具：smart-money-signal
参数：{ agent_id: "...", level: "high" }
# 第三步（v1.2）：添加自定义地址
工具：smart-money-custom
参数：{ agent_id: "...", action: "add", address: "0x...", label: "目标鲸鱼" }
→ 链上订阅自动创建，stream_id 回填
# 第四步：查询合并信号（公共池 + 自定义地址）
工具：smart-money-signal
参数：{ agent_id: "...", level: "all" }
```
## MCP 服务器
```
https://mcp-skills.ai.antalpha.com/mcp
```
## MCP 工具
| 工具 | 版本 | 说明 |
|------|------|------|
| `antalpha-register` | v1 | 注册 Agent，获取 `agent_id` + `api_key`（仅需一次） |
| `smart-money-signal` | v1.2 | 获取交易信号（公共池 **+** 自定义地址合并） |
| `smart-money-watch` | v1 | 查看指定钱包的近期活动 |
| `smart-money-list` | v1 | 列出所有监控钱包（公共 + 自定义） |
| `smart-money-custom` | v1.2 | **添加 / 删除 / 查看**自定义地址，自动管理链上订阅（引用计数） |
| `smart-money-scan` | v1 | 手动触发自定义地址扫描 |
| `smart-money-pool` | v1.1 | 查询鲸鱼 LP 活动（Uniswap V2/V3 入池/退池） |
## 用户场景
### 🔍 场景一 — 日常鲸鱼信号查看
> "今天聪明钱在买什么？"
```
smart-money-signal { agent_id, level: "high", limit: 20 }
```
返回示例：
```
🔴 高强度信号 | Paradigm Fund
买入 PEPE — $127.5K · 首次建仓
TX: 0xabc...def | 2026-04-17 08:00 UTC
🟡 中强度信号 | Wintermute
累积 ARB — $45K · 24h 内第 3 次买入
TX: 0x123...456 | 2026-04-17 06:20 UTC
由 Antalpha AI 提供聚合服务
```
---
### 👁 场景二 — 查看特定钱包动向
> "Paradigm 最近在做什么？"
```
smart-money-watch { agent_id, address: "0xParadigm...", limit: 10 }
```
---
### ➕ 场景三 — 添加个人监控地址（v1.2.1）
> "帮我追踪这个地址：0xABC...，这是我盯的目标鲸鱼"
```
# 第一步：添加到自定义列表（链上订阅自动创建）
smart-money-custom {
agent_id,
action: "add",
address: "0xABC...",
label: "目标鲸鱼"
}
# 第二步：触发首次扫描
smart-money-scan { agent_id }
# 第三步：查看当前信号
smart-money-signal { agent_id, level: "all" }
```
> ⚠️ **添加完成后，Agent 必须显示以下强提示：**
>
> *服务商已开始实时监控 `0xABC...`，但 MCP 协议无法主动推送通知——链上信号会存入数据库，但你**永远收不到提醒**。不创建定时检查任务将无法收到任何告警。*
>
> *建议现在创建 15 分钟定时任务（见场景七）。不创建也可以，但业务龙头可能已过。*
```bash
# 第四步（用户确认后创建）：
openclaw cron add \
--name "smart-money-alert" \
--cron "*/15 * * * *" \
--session isolated \
--message "使用 agent_id <id> 调用 smart-money-signal，level 为 high，since 为 <上次检查时间>。有新信号则通知我，无新信号则静默回复 HEARTBEAT_OK。"
```
**效果**：自定义地址通过实时数据订阅监控，Cron 定时拉取信号，信号到达即时通知用户。
---
### 📋 场景四 — 查看并管理自定义地址（v1.2）
> "我现在在追踪哪些地址？还剩几个名额？"
```
smart-money-custom { agent_id, action: "list" }
```
返回示例：
```json
{
"private_count": 2,
"remaining_slots": 3,
"wallets": [
{ "address": "0xABC...", "label": "目标鲸鱼", "stream_id": "abc-123", "added_at": "2026-04-17T08:00:00Z" },
{ "address": "0xDEF...", "label": "Fund X", "stream_id": "def-456", "added_at": "2026-04-16T12:00:00Z" }
]
}
```
---
### ➖ 场景五 — 取消监控某个地址（v1.2）
> "不想追踪 0xABC... 了"
```
smart-money-custom { agent_id, action: "remove", address: "0xABC..." }
```
**效果**：地址从列表中移除，对应链上订阅自动注销（引用计数归零时才真正取消）。
---
### 🏊 场景六 — 鲸鱼 LP 入池检测
> "Paradigm 最近有没有往流动性池里加钱？"
```
smart-money-pool {
agent_id,
address: "0xParadigm...",
event_type: "POOL_IN",
dex: "uniswap_v3",
limit: 5
}
```
返回示例：
```
🔴 高强度信号 | Paradigm Fund
POOL_IN — USDC/ETH（Uniswap V3）· $215K
池子：0x88e6A... TX: 0xabc...def | 2026-04-14 04:00 UTC
```
---
### ⏰ 场景七 — 设置定时监控（OpenClaw）
> "每小时提醒我一次高强度信号"
> ⚠️ **为什么必须创建**：数据服务商实时将信号推送到 MCP Server，但 MCP 无法主动通知你。不设置 Cron，信号将静默积庋，你永远收不到提醒。
```bash
# 推荐间隔：15 分钟（响应速度与 Token 消耗的平衡点）
openclaw cron add \
--name "smart-money-alert" \
--cron "*/15 * * * *" \
--session isolated \
--message "使用 agent_id <id> 调用 smart-money-signal，level 为 high，since 为 <上次检查时间 ISO 格式>。有新信号则摘要通知我，无新信号则静默回复 HEARTBEAT_OK。"
```
*成本说明*：`--session isolated` + 无信号时静默回复 `HEARTBEAT_OK` 大幅减少 Token 消耗。只有实际有信号时才会消耗完整回复的 Token。
---
### 🔄 场景八 — 多 Agent 共享地址的引用计数行为（v1.2）
> Agent A 和 Agent B 都添加了 `0xVitalik...`
- Agent A 添加 → 链上订阅创建，`ref_count = 1`
- Agent B 添加 → **复用同一 Stream**，`ref_count = 2`，无重复计费
- Agent A 删除 → `ref_count = 1`，Stream 继续存活
- Agent B 删除 → `ref_count = 0`，Stream 自动删除
---
## 信号等级
**转账 / 交换信号：**
| 等级 | 触发条件 |
|------|---------|
| 🔴 高 | 单笔买入 > $50K，或首次持仓某 Token |
| 🟡 中 | 24h 内同一 Token 累计买入 ≥ 2 次，或单笔卖出 > $50K |
| 🟢 低 | 常规转账 $1K–$50K |
**LP 池子信号（POOL_IN / POOL_OUT）：**
| 等级 | 触发条件 |
|------|---------|
| 🔴 高 | 入池金额 > $100K |
| 🟡 中 | 入池金额 $10K–$100K |
| 🟢 低 | 入池金额 < $10K |
## 公共监控池（19 个钱包）
VC 基金：Paradigm、a16z、Polychain Capital、Dragonfly Capital、DeFiance Capital
做市商：Wintermute、Jump Trading、Cumberland DRW
巨鲸：Vitalik.eth、孙宇晨、James Fickel
DeFi 协议：Uniswap V2 ETH/USDT、Lido stETH、0x Protocol
交易所：Binance 热钱包 14、Robinhood
其他：Nansen Smart Money 1、Alameda Research（残余）、Celsius（残余）
## 数据来源
- **数据服务商** — ERC20 转账、原生代币转账、Token 价格
- **实时事件订阅**（v1.1+）— LP 事件 + 自定义地址 Webhook 落库
- **仅支持以太坊主网**（V1）
## 安全说明
- Agent 身份通过 UUID 标识，不涉及私钥
- `api_key` 为私密凭据，请安全存储，切勿在日志或提示词中暴露
- 自定义监控列表按 `agent_id` 隔离（多租户）
- `remove` 操作自动注销链上订阅（引用计数保护，无僵尸订阅）
- 所有数据均来自公开链上数据，不涉及用户资金
## 更新日志
### v1.2.1（2026-04-17）
- 新增：`smart-money-custom action=add` 完成后强制提示创建 Cron 定时任务
- 新增：强提示警示文案（中英双语）：“不创建 Cron 则永远收不到通知”
- 新增：推荐间隔 15 分钟，增加 `--session isolated` 参数
- 场景三、场景七均已更新为可直接执行的 Cron 命令
### v1.2.0（2026-04-17）
- 升级：`smart-money-custom` 支持 `add` / `remove` / `list`，自动管理链上订阅
- 新增：引用计数（RC）— 多 Agent 监控同一地址共享一个订阅流，最后一个引用释放时自动取消
- 新增：数据表 `agent_watched_wallets`、`sm_stream_registry`
- 升级：`smart-money-signal` 合并公共池 + 自定义地址两路结果，统一返回
### v1.1.0（2026-04-14）
- 新增：`smart-money-pool` 工具，查询鲸鱼 LP 添加/移除活动（Uniswap V2/V3）
- 新增：`POOL_IN` / `POOL_OUT` 信号类型
- 新增：实时事件订阅集成，接收 LP 事件
### v1.0.2
- 新增监控设置指南和 Agent 行为规则
### v1.0.1（2026-03-28）
- 多项 Bug 修复及地址规范化
### v1.0.0（2026-03-28）
- 初始版本
## 许可证
MIT
FILE:data/labels.json
{
"0x56178a0d5f301baf6cf3e1cd53d9863437345bf9": {
"label": "Wintermute",
"category": "fund",
"tags": [
"market-maker",
"defi"
]
},
"0x28c6c06298d514db089934071355e5743bf21d60": {
"label": "Binance Hot Wallet 14",
"category": "whale",
"tags": [
"exchange"
]
},
"0xdef1c0ded9bec7f1a1670819833240f027b25eff": {
"label": "0x Protocol",
"category": "dex_trader",
"tags": [
"dex",
"aggregator"
]
},
"0x47ac0fb4f2d84898e4d9e7b4dab3c24507a6d503": {
"label": "Justin Sun",
"category": "whale",
"tags": [
"tron",
"controversial"
]
},
"0x8103683202aa8da10536036edef04cdd865c225e": {
"label": "a16z Crypto",
"category": "fund",
"tags": [
"vc",
"top-tier"
]
},
"0x40b38765696e3d5d8d9d834d8aad4bb6e418e489": {
"label": "Robinhood",
"category": "whale",
"tags": [
"exchange",
"retail"
]
},
"0x1b7baa734c00298b9429b518d621753bb0f6eff2": {
"label": "Paradigm Fund",
"category": "fund",
"tags": [
"vc",
"top-tier"
]
},
"0x6b44ba0a126a2a1a8aa6cd1adeed002e141bcd44": {
"label": "Polychain Capital",
"category": "fund",
"tags": [
"vc"
]
},
"0xd8da6bf26964af9d7eed9e03e53415d37aa96045": {
"label": "Vitalik.eth",
"category": "whale",
"tags": [
"ethereum-founder"
]
},
"0x9845e1909dca337944a0272f1f9f7249833d2d19": {
"label": "Nansen Smart Money 1",
"category": "dex_trader",
"tags": [
"smart-money"
]
},
"0x176f3dab24a159341c0509bb36b833e7fdd0a132": {
"label": "Alameda Research",
"category": "fund",
"tags": [
"defunct",
"ftx"
]
},
"0xae2fc483527b8ef99eb5d9b44875f005ba1fae13": {
"label": "James Fickel",
"category": "whale",
"tags": [
"eth-btc-whale"
]
},
"0x220866b1a2219f40e72f5c628b65d54268ca3a9d": {
"label": "Celsius",
"category": "fund",
"tags": [
"defunct",
"bankruptcy"
]
},
"0x0d0707963952f2fba59dd06f2b425ace40b492fe": {
"label": "DeFiance Capital",
"category": "fund",
"tags": [
"vc",
"defi-focused"
]
},
"0x3ddfa8ec3052539b6c9549f12cea2c295cff5296": {
"label": "Cumberland DRW",
"category": "fund",
"tags": [
"otc",
"market-maker"
]
},
"0x9507c04b10486547584c37bcbd931b5a4ecd5137": {
"label": "Jump Trading",
"category": "fund",
"tags": [
"market-maker",
"hft"
]
},
"0x0d4a11d5eeaac28ec3f61d100daf4d40471f1852": {
"label": "Uniswap V2: ETH/USDT",
"category": "dex_trader",
"tags": [
"dex",
"uniswap"
]
},
"0xae7ab96520de3a18e5e111b5eaab095312d7fe84": {
"label": "Lido: stETH",
"category": "fund",
"tags": [
"liquid-staking",
"defi"
]
},
"0x3e286452b1c66abb08eb5494c3894f40ab5a59af": {
"label": "Dragonfly Capital",
"category": "fund",
"tags": [
"vc",
"top-tier"
]
}
}
FILE:data/watchlist.json
[
{
"address": "0x56178a0d5f301baf6cf3e1cd53d9863437345bf9",
"label": "Wintermute",
"category": "fund",
"source": "Etherscan label"
},
{
"address": "0x28c6c06298d514db089934071355e5743bf21d60",
"label": "Binance Hot Wallet 14",
"category": "whale",
"source": "Etherscan label"
},
{
"address": "0xdef1c0ded9bec7f1a1670819833240f027b25eff",
"label": "0x Protocol (DEX Aggregator)",
"category": "dex_trader",
"source": "Etherscan label"
},
{
"address": "0x47ac0fb4f2d84898e4d9e7b4dab3c24507a6d503",
"label": "Justin Sun",
"category": "whale",
"source": "Etherscan label / Arkham"
},
{
"address": "0x8103683202aa8da10536036edef04cdd865c225e",
"label": "a16z Crypto",
"category": "fund",
"source": "Arkham Intelligence"
},
{
"address": "0x40b38765696e3d5d8d9d834d8aad4bb6e418e489",
"label": "Robinhood",
"category": "whale",
"source": "Etherscan label"
},
{
"address": "0x1b7baa734c00298b9429b518d621753bb0f6eff2",
"label": "Paradigm Fund",
"category": "fund",
"source": "On-chain analysis"
},
{
"address": "0x6b44ba0a126a2a1a8aa6cd1adeed002e141bcd44",
"label": "Polychain Capital",
"category": "fund",
"source": "Arkham Intelligence"
},
{
"address": "0xd8da6bf26964af9d7eed9e03e53415d37aa96045",
"label": "Vitalik.eth",
"category": "whale",
"source": "ENS / public"
},
{
"address": "0x9845e1909dca337944a0272f1f9f7249833d2d19",
"label": "Nansen Smart Money 1",
"category": "dex_trader",
"source": "Nansen public labels"
},
{
"address": "0x176f3dab24a159341c0509bb36b833e7fdd0a132",
"label": "Alameda Research (Remnant)",
"category": "fund",
"source": "Arkham Intelligence"
},
{
"address": "0x9507c04b10486547584c37bcbd931b5a4ecd5137",
"label": "Jump Trading",
"category": "fund",
"source": "Arkham Intelligence"
},
{
"address": "0xae2fc483527b8ef99eb5d9b44875f005ba1fae13",
"label": "James Fickel (ETH/BTC Whale)",
"category": "whale",
"source": "Arkham / on-chain"
},
{
"address": "0x220866b1a2219f40e72f5c628b65d54268ca3a9d",
"label": "Celsius (Remnant)",
"category": "fund",
"source": "Etherscan label"
},
{
"address": "0x0d0707963952f2fba59dd06f2b425ace40b492fe",
"label": "DeFiance Capital",
"category": "fund",
"source": "Arkham Intelligence"
},
{
"address": "0x3ddfa8ec3052539b6c9549f12cea2c295cff5296",
"label": "Cumberland DRW",
"category": "fund",
"source": "Etherscan label"
},
{
"address": "0x0d4a11d5eeaac28ec3f61d100daf4d40471f1852",
"label": "Uniswap V2: ETH/USDT",
"category": "dex_trader",
"source": "Etherscan label"
},
{
"address": "0xae7ab96520de3a18e5e111b5eaab095312d7fe84",
"label": "Lido: stETH",
"category": "fund",
"source": "Etherscan label"
},
{
"address": "0x3e286452b1c66abb08eb5494c3894f40ab5a59af",
"label": "Dragonfly Capital",
"category": "fund",
"source": "Arkham Intelligence"
}
]
Polymarket prediction market skill by Antalpha AI. Discover trending markets, browse event predictions, invest in outcomes, copy-trade top traders, track por...
---
name: poly-master
description: "Polymarket prediction market skill by Antalpha AI. Discover trending markets, browse event predictions, invest in outcomes, copy-trade top traders, track portfolio & PnL. V2: Poly Master hedge strategy — LLM-driven logical implication arbitrage with Builder Program attribution. Trigger: polymarket, prediction market, 预测市场, poly, copy trade, 跟单, hedge strategy, 对冲策略, arbitrage, 套利"
version: 2.0.0
metadata: {"mcp":{"url":"https://mcp-skills.ai.antalpha.com/mcp","transport":"streamable-http"},"clawdbot":{"emoji":"🎯"}}
---
# Poly Master v2 — Polymarket 预测市场 + Poly Master 对冲策略
> Powered by **Antalpha AI** — Polymarket 聚合交易、跟单与 LLM 驱动对冲套利
---
## Overview
Poly Master v2 在 v1 交易/跟单基础上，新增 **Poly Master 策略层**：利用 LLM 逻辑推理能力，扫描市场间的逻辑蕴含关系，发现接近无风险的对冲套利机会。所有订单通过 Polymarket Builder Program 路由，享受更优执行和免 Gas 操作。
### V2 新增核心能力
| 能力 | 说明 |
|------|------|
| 🔮 **对冲策略扫描** | LLM 分析市场逻辑蕴含关系，输出 T1/T2/T3 分级套利信号 |
| 📡 **实时监控看板** | Tier 分布、滑点取消率、信号频率统计 |
| 🏗️ **Builder Program 接入** | 所有 CLOB 订单通过 Polymarket Builder Program 路由，享受优先执行和免 Gas 操作 |
| ⛽ **免 Gas 操作** | Relayer 代付链上 Gas，降低交易摩擦 |
| 🔌 **LLM 代理计费** | 平台统一 Master Key，按 agent_id 计量 token 消耗 |
---
## Architecture
```
User ←→ AI Agent ←→ Antalpha MCP Server ←→ Polymarket APIs
↕
┌───────────┼──────────────┐
▼ ▼ ▼
PolyMasterStrategy LlmProxy BuilderModule
(对冲扫描引擎) (计量计费) (X-Builder-Key)
↕ ↕ ↕
Gamma/CLOB OpenAI API CLOB/Relayer
```
- **Zero custody**: 私钥不离开用户钱包
- **MCP Protocol**: Streamable HTTP (MCP 2024-11-05)
- **Chain**: Polygon Mainnet (Chain ID 137)
- **Currency**: USDC.e (`0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174`)
- **Supported Wallets**: MetaMask, OKX Wallet, Trust Wallet, TokenPocket
---
## MCP Tools Reference
### Registration（首次必须）
| Tool | Description |
|------|-------------|
| `antalpha-register` | 注册 agent，返回 `agent_id` + `api_key`。仅调用一次，持久化两个值。 |
### Market Discovery
| Tool | Parameters | Description |
|------|-----------|-------------|
| `poly-trending` | `agent_id`, `limit?`, `category?` | 热门市场（按 24h 成交量）。Category: crypto/politics/sports/geopolitics/finance |
| `poly-new` | `agent_id`, `limit?`, `hours?`, `category?` | 最近创建的市场 |
| `poly-market-info` | `agent_id`, `market_id` | 市场完整信息：价格/成交量/Token ID/结果列表 |
### Direct Trading
| Tool | Parameters | Description |
|------|-----------|-------------|
| `poly-buy` | `agent_id`, `market_id`, `outcome`, `amount_usdc`, `wallet_address`, `proxy_wallet`, `price?` | 买入结果代币。不含 `price` = 市价单；含 `price` = 限价单 |
| `poly-sell` | `agent_id`, `market_id`, `outcome`, `size`, `wallet_address`, `proxy_wallet` | 卖出结果代币 |
| `poly-confirm` | `agent_id`, `order_id` | 查询订单签名状态 + CLOB 成交状态（`pending_signature` / `submitted` / `matched` / `failed`），同时自动修复 signed 但未更新为 submitted 的订单 |
| `poly-master-orders` | `agent_id`, `wallet_address?`, `status?` | 订单列表，支持按状态过滤（含未成交/挂单） |
| `poly-history` | `agent_id`, `wallet_address`, `proxy_wallet`, `limit?` | 链上历史成交记录（来自 Polymarket data API） |
### Copy Trading
| Tool | Parameters | Description |
|------|-----------|-------------|
| `poly-master-traders` | `agent_id`, `limit?`, `sort_by?` | 顶级交易员列表（按胜率/成交量/ROI） |
| `poly-master-follow` | `agent_id`, `address`, `copyRatio` | 跟随/取消跟随交易员，设置跟单比例（0.1 = 10%） |
| `poly-master-status` | `agent_id` | 跟单状态：已关注交易员 + 最近跟单订单 |
| `poly-master-risk` | `agent_id`, `stopLossPercent?`, `takeProfitPercent?`, `maxPositionPerMarket?`, `maxTotal?` | 查看/更新风控参数 |
| `poly-master-pnl` | `agent_id`, `period?` | PnL 报告（day/week/month），按交易员分组 |
| `poly-master-orders` | `agent_id`, `status?` | 跟单订单列表 |
### Portfolio
| Tool | Parameters | Description |
|------|-----------|-------------|
| `poly-positions` | `agent_id`, `wallet_address` | 当前持仓：成本/市值/未实现 PnL |
| `poly-history` | `agent_id`, `wallet_address`, `limit?` | 交易历史记录 |
| `poly-open-orders` | `agent_id`, `wallet_address` | 未成交/挂单中的订单 |
---
## V2 Poly Master Strategy Tools
> **策略原理**：Poly Master 基于逻辑蕴含而非市场相关性寻找套利机会。若 "A=YES 必然导致 B=YES"，则存在接近无风险的双腿对冲结构（totalCost < 1）。
### 策略工具
| Tool | Parameters | Description |
|------|-----------|-------------|
| `poly-master-strategy-scan` | `agent_id`, `limit?`, `min_tier?` | 触发一轮市场扫描，返回按覆盖率排序的对冲信号列表 |
| `poly-master-strategy-signal` | `agent_id`, `signal_id` | 查看单条对冲信号详情（双腿价格、覆盖率、可用流动性） |
| `poly-master-strategy-execute` | `agent_id`, `signal_id`, `size_usdc`, `wallet_address`, `proxy_wallet` | 执行对冲信号（DRY_RUN=false 时才真正下单） |
| `poly-master-strategy-metrics` | `agent_id` | 策略看板：Tier 分布/信号频率/滑点取消率/最近10次扫描 |
| `poly-master-strategy-dry-run` | `agent_id`, `enabled` | 开启/关闭 Dry-Run 模式（true=只记日志，false=真实执行） |
### 信号结构说明
```
HedgeSignal {
targetMarketId # 目标市场 ID
targetPosition # "YES" | "NO"
coverMarketId # 对冲市场 ID
coverPosition # "YES" | "NO"
metrics {
targetPrice # 目标腿价格（string, 精度保留）
coverPrice # 对冲腿价格（string）
totalCost # 两腿总成本，必须 < 1.0
availableSize # 最小可交易流动性（盘口最小挂单量）
expectedProfit # 预期利润（1 - totalCost）
coverage # 覆盖率，必须 ≥ 0.85
tier # "T1" (≥0.95) | "T2" (≥0.90) | "T3" (≥0.85)
}
reasoning # LLM 推理依据（自然语言）
builderAttributed # true = 已携带 Builder 归因头
}
```
### Tier 分级解读
| Tier | Coverage | 说明 |
|------|----------|------|
| T1 | ≥ 0.95 | 极强逻辑蕴含，几乎无风险 |
| T2 | ≥ 0.90 | 强逻辑蕴含，低风险 |
| T3 | ≥ 0.85 | 中等蕴含，需关注流动性 |
---
## Agent Instructions
### 1. 首次使用
```
1. 调用 antalpha-register → 获取 agent_id + api_key
2. 持久化 agent_id 和 api_key（后续所有调用均需要）
3. 询问用户钱包地址 (wallet_address) 和代理钱包地址 (proxy_wallet)
```
### 2. 普通交易流程
```
poly-trending / poly-new → 发现市场
poly-market-info → 查看详情
poly-buy / poly-sell → 生成签名链接
展示订单预览格式（含二维码）→ 用户在钱包内打开签名
```
### 3. Poly Master 对冲策略流程
```
步骤 1: 调用 poly-master-strategy-scan({ agent_id, limit: 5 })
→ 返回按覆盖率排序的信号列表
步骤 2: 展示信号列表（按 Tier 分组，显示 totalCost/coverage/tier）
步骤 3: 用户选择信号后调用 poly-master-strategy-signal({ agent_id, signal_id })
→ 返回完整信号详情（双腿价格、流动性、推理依据）
步骤 4: 确认后调用 poly-master-strategy-execute({
agent_id, signal_id,
size_usdc: <用户指定金额>,
wallet_address, proxy_wallet
})
→ 返回两条腿的签名链接
步骤 5: 依次展示两条腿的签名链接（先 target 腿，再 cover 腿）
⚠️ 必须按顺序签名，不得跳过任一腿
```
**⚠️ 重要风控规则：**
- 调用 `poly-master-strategy-execute` 前，必须先向用户展示 signal 详情并确认
- 若 `availableSize` < 用户指定金额，自动缩减到 availableSize
- `totalCost ≥ 1` 的信号不允许执行（MCP 会拒绝，但 agent 也应前置检查）
- `DRY_RUN=true` 时只记录日志，不产生签名链接
### 4. 查看策略看板
```
poly-master-strategy-metrics({ agent_id })
→ 展示 Dashboard：Tier 分布 / 平均信号数/周期 / 滑点取消率 / 最近10次扫描结果
```
### 5. Portfolio 查询（备用公开 API）
当 `poly-positions` 未部署时：
```
GET https://data-api.polymarket.com/positions?user={proxy_wallet}
```
---
## Mandatory Output Formats
### 订单预览格式（所有 poly-buy / poly-sell 必须使用）
⚠️ **硬性规则**：所有字段值必须来自 MCP 响应，不允许填写硬编码数据。
```
📋 {market}
🎯 方向：{side} {outcome}
💰 价格：price/份
📦 数量：{size} 份
💵 总计：totalUsdc USDC
📊 滑点：{slippage}%
🔗 签名页面：{signUrl}
[二维码图片 — 必须生成并附带]
由 Antalpha AI 提供聚合交易服务
```
发送前检查：✅ 7 行都有 ✅ 二维码已生成 ✅ 品牌 footer ✅ 无额外注释
### 对冲信号列表格式
```
🔮 Poly Master 对冲信号 — {扫描时间}
共发现 {n} 个信号
⭐⭐⭐ T1 信号（Coverage ≥ 0.95）
━━━━━━━━━━━━━━━━━━━━━━━━
1️⃣ Signal #{id}
📌 目标：{targetMarketQuestion} → {targetPosition}
🔗 对冲：{coverMarketQuestion} → {coverPosition}
💰 总成本：{totalCost} USDC（利润空间：{expectedProfit} USDC）
📊 覆盖率：{coverage} | 可用流动性：{availableSize} USDC
💡 {reasoning}
⭐⭐ T2 信号 / ⭐ T3 信号
...
由 Antalpha AI Poly Master 策略引擎提供
```
### 对冲执行格式（两腿）
```
⚡ 对冲执行 — Signal #{id}
🦵 第一腿（Target）
📋 {targetMarket}
🎯 方向：BUY {targetPosition}
💰 价格：targetPrice/份 | 数量：{size} 份
🔗 签名页面：{signUrl_leg1}
[二维码 1]
🦵 第二腿（Cover）
📋 {coverMarket}
🎯 方向：BUY {coverPosition}
💰 价格：coverPrice/份 | 数量：{size} 份
🔗 签名页面：{signUrl_leg2}
[二维码 2]
⚠️ 请先完成第一腿签名，再签第二腿
由 Antalpha AI Poly Master 策略引擎提供
```
### Portfolio 格式
```
🎯 Polymarket 持仓报告
1️⃣ {event_title}
方向：{outcome}
持仓：{size} 份 | 均价 avg_price
现价：cur_price | 市值 current_value
盈亏：pnl ({pnl_percent}%)
到期：{end_date}
📊 汇总：总投入 total_cost | 市值 total_value | 盈亏 total_pnl ({total_pnl_percent}%)
由 Antalpha AI 提供聚合服务
```
---
## Risk Defaults
| Parameter | Default | Description |
|-----------|---------|-------------|
| Slippage Tolerance | 5% | 市价单最大价格偏差 |
| Daily Bet Limit | $2,000 | 每日最大交易额 |
| Per-Market Limit | $500 | 单市场最大仓位 |
| Large Order Threshold | $1,000 | 需显式确认 |
| Copy Trading Stop-Loss | 20% | 自动暂停阈值 |
| Poly Master Min Coverage | 0.85 | T3 最低覆盖率（低于此不展示） |
| Poly Master Max Position | availableSize | 不超过盘口最小流动性 |
---
## Builder Program
PolyMaster V2 所有 CLOB 订单均通过 Polymarket Builder Program 路由：
- **X-Builder-Key**：每笔订单必须携带（缺失则拒单）
- **Relayer**：用户享受免 Gas 链上操作（需 Safe/Proxy 钱包）
---
## How Signing Works
1. 🔔 Agent 通过 MCP 生成签名 URL
2. 🌐 用户在钱包内置浏览器（MetaMask/OKX/Trust/TokenPocket）打开链接
3. 🔐 页面展示订单详情（市场/方向/价格/数量）
4. ✅ 用户点击"签名" — 钱包弹出 EIP-712 类型化数据签名
5. 📤 签名提交到服务器，订单发往 Polymarket CLOB
**安全保障**：私钥不离开钱包，签名页面仅请求特定订单数据的签名。
---
## Polymarket SDK Reference（后端集成参考）
- **EIP-712 domain.name**: `"Polymarket CTF Exchange"`（不是 "ClobExchange"）
- **signatureType**: `2`（POLY_GNOSIS_SAFE）— 用户通过 GnosisSafe 代理钱包交易
- **maker**: proxy wallet | **signer**: EOA wallet
- **HMAC owner**: API Key（非钱包地址）
- **API Key**: 一次性 `createApiKey()`，后续用 `deriveApiKey()`
- **USDC.e (Polygon)**: `0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174`
---
## Brand Attribution（必须）
⚠️ 所有用户可见输出必须以品牌 footer 结尾：
- 中文：`由 Antalpha AI 提供聚合服务`
- 英文：`Powered by Antalpha AI`
适用范围：市场列表、订单预览、持仓报告、PnL 报告、跟单状态、交易员排名、对冲信号列表、策略看板 —— **无例外**。
---
## Files
```
poly-master/
├── SKILL.md # Agent 指令（本文件）
├── README.md # 项目对外说明
├── docs/
│ └── quickstart.md # 用户快速上手
├── references/
│ └── trade-page.html # 浏览器签名页模板
└── scripts/ # 本地测试脚本
```
---
Built by [Antalpha AI](https://ai.antalpha.com) | MCP: `https://mcp-skills.ai.antalpha.com/mcp` | v2.0.0
FILE:README.md
# 🎯 Poly Master — Polymarket Prediction Market Skill
> **Powered by [Antalpha AI](https://ai.antalpha.com)** — Zero-custody Polymarket aggregated trading & copy-trading for AI agents
[]()
[]()
[]()
[]()
---
[🇺🇸 English](#english) · [🇨🇳 中文](#chinese)
---
<a name="english"></a>
## What is Poly Master?
Poly Master is an AI agent skill that connects to [Polymarket](https://polymarket.com) — the world's largest prediction market — through the [Antalpha AI MCP Server](https://mcp-skills.ai.antalpha.com). It enables any MCP-compatible AI agent to:
- 📈 **Discover trending prediction markets** — Browse real-time hot markets by 24h volume, filter by category
- 🔍 **Analyze market data** — View prices, liquidity, outcome probabilities, and trading volume
- 💰 **Trade prediction outcomes** — Buy/sell Yes or No tokens with market or limit orders
- 👥 **Copy-trade top traders** — Follow profitable traders with configurable copy ratios
- 📊 **Track portfolio & PnL** — Monitor positions, unrealized gains, and trade history
- 🛡️ **Manage risk** — Built-in stop-loss, take-profit, position limits, and large order confirmation
- 🔮 **Poly Master Hedge Strategy (V2)** — LLM-driven logical implication arbitrage, T1/T2/T3 tiered signals
- 🏗️ **Powered by Polymarket Builder Program (V2)** — Orders are routed through the Polymarket Builder Program for optimal execution and liquidity
**🔐 Zero Custody** — Private keys never leave the user's wallet. All transactions are signed in the user's own wallet browser via EIP-712 typed data signatures.
---
## Why V2? — Poly Master Strategy
> **The core insight**: Most prediction market tools help you pick winners. Poly Master finds situations where *you don't need to pick* — because logic guarantees the outcome.
### The Problem with Traditional Prediction Market Trading
Traditional approaches require directional bets: you win only if your prediction is correct. Market sentiment, information asymmetry, and emotional bias all work against you.
### Poly Master's Approach: Logical Implication Arbitrage
Poly Master uses LLM reasoning to identify **logical implication relationships** between markets — not statistical correlation.
**The principle:** If Event A happening *necessarily implies* Event B will happen, and the market hasn't priced this relationship correctly, you can buy both positions for a **combined cost under $1.00 USDC** and lock in a guaranteed profit regardless of the actual outcome.
```
Example:
Market A: "Will Iran sign a ceasefire by April 30?" → Yes @ $0.20
Market B: "Will the Strait of Hormuz reopen by May?" → Yes @ $0.70
Logical implication: Iran ceasefire → Hormuz reopens (high confidence)
Total cost: $0.20 + $0.70 = $0.90 < $1.00
Guaranteed profit: $0.10 per $1 deployed (11.1% return)
```
### Why This Works
| Traditional Trading | Poly Master Strategy |
|--------------------|-----------------|
| Requires predicting outcomes | Exploits logical inconsistencies |
| Win rate depends on market knowledge | Profit locked in at entry |
| Exposed to sentiment swings | Protected by logical structure |
| One-sided risk | Near-symmetric protection |
| Manual research | LLM scans hundreds of markets automatically |
### Signal Tiers
| Tier | Coverage Score | Risk Level | Description |
|------|---------------|------------|-------------|
| **T1** | ≥ 0.95 | 🟢 Near-riskless | LLM has extremely high confidence in the logical implication. Rare but highest quality. |
| **T2** | ≥ 0.90 | 🟡 Low risk | Strong implication with minor edge cases. Most common actionable signals. |
| **T3** | ≥ 0.85 | 🟠 Moderate | Reasonable implication, but monitor liquidity and position size. |
### Use Cases
**📍 Scenario 1: Geopolitical Chains**
When one event (ceasefire, election result, regime change) logically triggers a cascade of related outcomes, Poly Master identifies which downstream markets are mispriced relative to the upstream event.
**📍 Scenario 2: Sports & Tournament Brackets**
If Team A winning the semifinal is already priced at 80%, but their path to the final implies 90% likelihood of another outcome, the gap is exploitable.
**📍 Scenario 3: Regulatory / Policy Cascades**
A policy decision (e.g., Fed rate cut) logically affects multiple downstream markets (mortgage rates, housing, crypto). Poly Master finds the mispriced links.
**📍 Scenario 4: Passive Alpha Generation**
Run `poly-master-strategy-scan` daily. Collect T1/T2 signals when available. Execute small positions ($1–$10) consistently. Compound low-risk returns without directional exposure.
### Key Advantages
- 🧠 **LLM-powered reasoning** — not rule-based, not correlation-based; genuine semantic understanding of causal relationships
- ⚡ **Automated scanning** — monitors all active Polymarket events continuously, surfaces only actionable signals
- 🔒 **Structural edge** — profit is baked in at entry when totalCost < 1.0; no need to predict future outcomes
- 💧 **Liquidity-aware** — signals are filtered by available order book depth; no phantom opportunities
- 🎯 **Tiered confidence** — T1/T2/T3 scoring lets you choose your risk tolerance
- 🔐 **Zero custody** — all execution stays in your wallet; Poly Master only generates the signing links
---
## Architecture
```
┌──────────┐ Natural Language ┌──────────────┐
│ User │ ◄──────────────────────► │ AI Agent │
└──────────┘ └──────┬───────┘
│ MCP Protocol
▼
┌─────────────────────┐
│ Antalpha AI MCP │
│ Server │
│ (Streamable HTTP) │
└──────────┬──────────┘
│
┌───────────────┼───────────────┐
▼ ▼ ▼
┌──────────────┐ ┌──────────────┐ ┌────────────┐
│ Polymarket │ │ Signing │ │ Gamma │
│ CLOB API │ │ Page │ │ Markets │
└──────────────┘ └──────┬───────┘ └────────────┘
│
▼
┌─────────────────────┐
│ User's Wallet │
│ MetaMask / OKX / │
│ Trust / TokenPocket │
└─────────────────────┘
```
---
## Features
### 📈 Market Discovery
| Capability | Description |
|-----------|-------------|
| Trending Markets | Top markets ranked by 24h trading volume |
| New Markets | Recently created prediction events |
| Category Filter | crypto, politics, sports, geopolitics, finance |
| Market Details | Real-time prices, volume, liquidity, outcome token IDs |
**Example:**
> *"What's trending on Polymarket right now?"*
>
> *"Show me new crypto prediction markets from the last 24 hours"*
### 💰 Direct Trading
| Capability | Description |
|-----------|-------------|
| Market Orders | Buy/sell at current best price |
| Limit Orders | Set target price for execution |
| QR Code Signing | Scan to open signing page in wallet browser |
| Multi-Wallet | MetaMask, OKX Wallet, Trust Wallet, TokenPocket |
**Example:**
> *"Buy $50 on Yes for 'Will ETH hit $5000 by July?'"*
>
> *"I want to bet $10 on No"*
### 👥 Copy Trading
| Capability | Description |
|-----------|-------------|
| Trader Discovery | Rank traders by win rate, volume, ROI |
| Configurable Ratio | e.g. 10% = trader buys 100 shares → you buy 10 |
| Multi-Follow | Follow multiple traders simultaneously |
| Auto-Monitor | Checks for new trades every 30 seconds |
**Example:**
> *"Show me top Polymarket traders"*
>
> *"Follow 0xABC... at 10% copy ratio"*
### 📊 Portfolio & PnL
| Capability | Description |
|-----------|-------------|
| Position Tracking | Current holdings with cost basis and market value |
| PnL Reports | By period (day/week/month) with per-trader breakdown |
| Trade History | On-chain history via `poly-history` |
| Order List | All orders with status filter via `poly-master-orders` |
**Example:**
> *"How's my Polymarket portfolio?"*
>
> *"Show me this week's PnL"*
### 🔮 Poly Master Hedge Strategy (V2)
| Tier | Coverage | Description |
|------|----------|-------------|
| T1 | ≥ 0.95 | Near-riskless — profit locked at entry |
| T2 | ≥ 0.90 | Low risk — strong logical implication |
| T3 | ≥ 0.85 | Moderate — check liquidity before executing |
**Example conversations:**
> *"Scan for arbitrage opportunities on Polymarket"*
>
> *"Show me T1 signals only"*
>
> *"Execute signal #2 with $5 USDC"*
>
> *"What's the Poly Master strategy dashboard showing?"*
### 🛡️ Risk Management
| Parameter | Default | Range |
|-----------|---------|-------|
| Slippage Tolerance | 5% | 0.1% – 20% |
| Daily Volume Limit | $2,000 | $10 – $100,000 |
| Per-Market Limit | $500 | $1 – $50,000 |
| Large Order Threshold | $1,000 | Requires explicit confirmation |
| Stop-Loss (copy trading) | 20% | 1% – 99% |
| Take-Profit (copy trading) | 50% | 1% – 999% |
---
## Quick Start
### Prerequisites
1. **A crypto wallet** — MetaMask, OKX, Trust Wallet, or TokenPocket
2. **USDC.e on Polygon** — Trading currency on Polymarket
3. **Small amount of POL** — For gas fees (< $0.01 per tx)
4. **Polymarket account** — Must complete onboarding at [polymarket.com](https://polymarket.com) first
### Install
Install directly from GitHub:
```bash
openclaw skill install https://github.com/AntalphaAI/poly-master
```
Or install via OpenClaw chat:
```
"Install Poly Master skill"
```
### Usage
Simply talk to your AI agent:
```
👤 "What's hot on Polymarket?"
🤖 Shows trending markets with prices and volumes
👤 "Buy $20 on Yes for the top market"
🤖 Generates order + signing link + QR code
👤 "Show me top traders to copy"
🤖 Lists profitable traders ranked by performance
👤 "Follow that trader at 5% ratio"
🤖 Starts monitoring and mirroring trades
```
---
## MCP Server
| Property | Value |
|----------|-------|
| **Endpoint** | `https://mcp-skills.ai.antalpha.com/mcp` |
| **Protocol** | Streamable HTTP (MCP 2024-11-05) |
| **Auth** | Call `antalpha-register` tool to get `agent_id` + `api_key` |
| **Tools** | 30+ MCP tools for market data, trading, copy-trading, portfolio, hedge strategy |
---
## How Signing Works
```
Agent MCP Server Signing Page User Wallet
│ │ │ │
│── poly-buy ────────────►│ │ │
│ │── build order ────────►│ │
│◄── { signUrl } ────────│ │ │
│ │ │ │
│── present signUrl ──────────────────────────────►│ │
│ │ │── eth_signTypedData ─►│
│ │ │◄── signature ────────│
│ │◄── submit signature ──│ │
│ │── place order on CLOB │ │
│◄── order confirmation ──│ │ │
```
**Security Guarantees:**
- ✅ Private keys never leave the wallet
- ✅ Each signature is bound to specific order data (EIP-712)
- ✅ Signing page shows full order details before signature
- ✅ Links expire after 10 minutes
- ✅ No backend custody of funds or keys
---
## MCP Tools Reference (v2)
| Tool | Description |
|------|-------------|
| `antalpha-register` | Register agent, get `agent_id` + `api_key` |
| `poly-trending` | Trending markets by 24h volume |
| `poly-new` | Recently created markets |
| `poly-market-info` | Full market details |
| `poly-buy` | Buy outcome tokens (market/limit) |
| `poly-sell` | Sell outcome tokens |
| `poly-confirm` | Check order signing + CLOB fill status |
| `poly-positions` | Current holdings |
| `poly-history` | On-chain trade history |
| `poly-master-orders` | Order list with status filter |
| `poly-master-traders` | Top traders ranked by performance |
| `poly-master-follow` | Follow/unfollow a trader |
| `poly-master-status` | Copy-trading status |
| `poly-master-risk` | View/update risk parameters |
| `poly-master-pnl` | PnL report by period |
| `poly-master-strategy-scan` | Scan for hedge signals |
| `poly-master-strategy-signal` | Get signal details |
| `poly-master-strategy-execute` | Execute two-leg hedge order |
| `poly-master-strategy-metrics` | Strategy dashboard |
| `poly-master-strategy-dry-run` | Toggle dry-run mode |
---
## Tech Stack
| Component | Technology |
|-----------|-----------|
| Chain | Polygon Mainnet (Chain ID 137) |
| Currency | USDC.e |
| Market Protocol | Polymarket CTF Exchange (Conditional Token Framework) |
| SDK | [@polymarket/clob-client](https://github.com/Polymarket/clob-client) v5.8.1 |
| Signing | EIP-712 Typed Data via browser |
| Wallet Type | GnosisSafe (1/1) Proxy Wallet |
| MCP Protocol | Streamable HTTP (MCP 2024-11-05) |
| Backend | NestJS 11 + TypeORM + MySQL + Redis |
---
## Important Disclaimers
⚠️ **Not financial advice.** Prediction markets carry risk. Only trade with funds you can afford to lose.
⚠️ **Polymarket availability** may vary by jurisdiction. Users are responsible for compliance with local regulations.
⚠️ **Copy trading** mirrors another trader's decisions. Past performance does not guarantee future results.
⚠️ **Gas fees** on Polygon are minimal (< $0.01) but require POL tokens.
---
## Documentation
- [SKILL.md](./SKILL.md) — Full agent instructions, MCP tool reference, output format specs
- [docs/quickstart.md](./docs/quickstart.md) — User-facing setup guide (v2 updated)
---
## License
MIT © [Antalpha AI Team](https://www.antalpha.com/)
---
**Built by [Antalpha AI](https://ai.antalpha.com)** 🎯 | v2.0.0
*Powering the next generation of AI-driven prediction market trading.*
---
<a name="chinese"></a>
## Poly Master 是什么？
Poly Master 是一个 AI Agent 技能，通过 [Antalpha AI MCP Server](https://mcp-skills.ai.antalpha.com) 接入 [Polymarket](https://polymarket.com)——全球最大的预测市场平台。任何兼容 MCP 协议的 AI Agent 均可通过它实现：
- 📈 **发现热门预测市场** — 按 24h 成交量浏览实时热门市场，支持分类筛选
- 🔍 **分析市场数据** — 查看实时价格、流动性、结果概率和交易量
- 💰 **交易预测结果** — 市价单或限价单买卖 Yes/No Token
- 👥 **跟单顶级交易员** — 跟随盈利交易员，可设置跟单比例
- 📊 **追踪持仓与盈亏** — 实时监控仓位、浮盈浮亏及交易历史
- 🛡️ **风险管理** — 内置止损、止盈、单市场仓位上限及大单确认机制
- 🔮 **Poly Master 对冲策略（V2）** — LLM 驱动的逻辑蕴含套利，T1/T2/T3 分级信号
- 🏗️ **接入 Polymarket Builder Program（V2）** — 订单通过 Polymarket Builder Program 路由，享受更优执行和流动性
**🔐 零托管** — 私钥永不离开用户钱包。所有交易通过用户自己钱包浏览器内的 EIP-712 类型数据签名完成。
---
## 为什么选择 V2？Poly Master 策略详解
> **核心洞察**：多数预测市场工具要求你猜对结果。Poly Master 进一步——它寻找那些你根本 *不需要猜* 的场景，因为逻辑已经决定了结果。
### 传统预测市场交易的痛点
传统方式需要单向投注：你只有在预测正确时才能赢利。市场情绪、信息不对称和认知偏差都在与你作对。
### Poly Master 的方法：逻辑蕴含套利
Poly Master 利用 LLM 推理识别市场间的**逻辑蕴含关系**——而非统计相关性。
**原理：** 如果事件 A 发生*必然导致*事件 B 发生，且市场尚未正确定价这一关系，就可以同时买入两个仓位，**总成本不足 1 USDC**，锁定保底收益。
```
示例：
市场 A：“伊朗将在 4 月底前签署停火协议？” → Yes @ $0.20
市场 B：“霍尔木兹海峡 5 月前恢复正常？” → Yes @ $0.70
逻辑蕴含：伊朗停火 → 海峡恢复（高置信）
总成本：$0.20 + $0.70 = $0.90 < $1.00
保底收益：$0.10 / 每 USDC（11.1% 回报）
```
### 为什么有效
| 传统交易 | Poly Master 策略 |
|----------|--------------|
| 需要预测结果 | 利用市场定价错误 |
| 胜率取决于市场判断 | 入场即锁定收益 |
| 暴露于情绪波动 | 由逻辑结构保护 |
| 单向风险 | 近似对称保护 |
| 人工调研 | LLM 自动扫描数百个事件 |
### 信号分级
| 分级 | 覆盖率 | 风险等级 | 说明 |
|------|--------|-----------|------|
| **T1** | ≥ 0.95 | 🟢 几乎无风险 | LLM 对逻辑蕴含关系置信极高，稀有但质量最高 |
| **T2** | ≥ 0.90 | 🟡 低风险 | 强蕴含关系，少量边界情况，最常见的可操作信号 |
| **T3** | ≥ 0.85 | 🟠 中等 | 合理蕴含关系，注意流动性和仓位大小 |
### 使用场景
**📍 场景一：地缘政治连锁效应**
停火、选举结果、政权变化等事件经常引发一系列下游市场的定价失调。Poly Master 定位其中被错误定价的下游市场。
**📍 场景二：体育赛事与比赛路径**
如果 A 队已继续事在八亝，但其死少路径意味着另一个市场的概率应为 90%，这个差距就是套利机会。
**📍 场景三：监管政策连锁**
一项政策决定（如美联储降息）逻辑上影响多个下游市场。Poly Master 寻找定价失调的关联市场。
**📍 场景四：被动生成 Alpha**
每天运行 `poly-master-strategy-scan`，稳定收集 T1/T2 信号，每次戩5–10 USDC小仓位。无需方向判断，复利兴利就是超额收益。
### V2 核心优势
- 🧠 **LLM 语义推理** — 非规则、非相关性；真正理解因果关系
- ⚡ **自动扫描** — 持续监控全市场活跃事件，只呈现可操作信号
- 🔒 **结构性优势** — totalCost < 1.0 时收益在入场时就已确定
- 💧 **流动性感知** — 信号已将盘口深度纳入考量，无虚假机会
- 🎯 **分级置信** — T1/T2/T3 评分，按自身风险偏好选择
- 🔐 **零托管** — 所有执行在钱包内完成，Poly Master 只生成签名链接
---
## 架构图
```
┌──────┐ 自然语言 ┌──────────┐
│ 用户 │ ◄──────────► │ AI Agent │
└──────┘ └────┬─────┘
│ MCP 协议
▼
┌──────────────────────┐
│ Antalpha AI MCP │
│ Server │
│ (Streamable HTTP) │
└──────────┬───────────┘
│
┌───────────────┼───────────────┐
▼ ▼ ▼
┌──────────────┐ ┌──────────────┐ ┌────────────┐
│ Polymarket │ │ 签名页面 │ │ Gamma │
│ CLOB API │ │ (浏览器) │ │ Markets │
└──────────────┘ └──────┬───────┘ └────────────┘
│
▼
┌─────────────────────┐
│ 用户钱包 │
│ MetaMask / OKX / │
│ Trust / TokenPocket │
└─────────────────────┘
```
---
## 功能概览
### 📈 市场发现
| 功能 | 说明 |
|------|------|
| 热门市场 | 按 24h 交易量排名的热门市场 |
| 新市场 | 最近创建的预测事件 |
| 分类筛选 | 加密货币、政治、体育、地缘政治、金融 |
| 市场详情 | 实时价格、成交量、流动性、结果 Token ID |
**示例对话：**
> *"现在 Polymarket 上什么最热门？"*
>
> *"过去 24 小时有哪些新的加密货币预测市场？"*
### 💰 直接交易
| 功能 | 说明 |
|------|------|
| 市价单 | 以当前最优价格买卖 |
| 限价单 | 设定目标价格等待成交 |
| 二维码签名 | 扫码在钱包浏览器中打开签名页面 |
| 多钱包支持 | MetaMask、OKX Wallet、Trust Wallet、TokenPocket |
**示例对话：**
> *"用 50 USDC 买 'ETH 7 月前能到 5000 美元吗？' 的 Yes"*
>
> *"我想用 10 USDC 押 No"*
### 👥 跟单交易
| 功能 | 说明 |
|------|------|
| 发现交易员 | 按胜率、成交量、ROI 排名顶级交易员 |
| 可配置跟单比例 | 例如 10% = 对方买 100 份 → 你买 10 份 |
| 多人跟单 | 同时跟随多位交易员 |
| 自动监控 | 每 30 秒检查一次新交易 |
**示例对话：**
> *"帮我看看 Polymarket 上表现最好的交易员"*
>
> *"以 10% 的比例跟单 0xABC..."*
### 📊 持仓与盈亏
| 功能 | 说明 |
|------|------|
| 持仓追踪 | 当前持仓含成本价和市值 |
| 盈亏报告 | 按日/周/月汇总，支持按交易员拆分 |
| 交易历史 | 完整的交易记录含时间戳 |
| 挂单查询 | 等待成交的未完成订单 |
**示例对话：**
> *"我的 Polymarket 持仓怎么样了？"*
>
> *"看看这周的盈亏"*
### 🛡️ 风险管理
| 参数 | 默认值 | 范围 |
|------|--------|------|
| 滑点容忍度 | 5% | 0.1% – 20% |
| 每日交易上限 | $2,000 | $10 – $100,000 |
| 单市场仓位上限 | $500 | $1 – $50,000 |
| 大单确认阈值 | $1,000 | 需要明确确认 |
| 跟单止损 | 20% | 1% – 99% |
| 跟单止盈 | 50% | 1% – 999% |
---
## 快速上手
### 前置条件
1. **加密货币钱包** — MetaMask、OKX Wallet、Trust Wallet 或 TokenPocket
2. **Polygon 上的 USDC.e** — Polymarket 的交易货币
3. **少量 POL** — 用于 Gas 费（每笔 < $0.01）
4. **Polymarket 账号** — 需先在 [polymarket.com](https://polymarket.com) 完成注册流程
### 安装
从 GitHub 直接安装：
```bash
openclaw skill install https://github.com/AntalphaAI/poly-master
```
或通过 OpenClaw 对话安装：
```
"安装 Poly Master 技能"
```
### 使用示例
直接与 AI Agent 对话即可：
```
👤 "Polymarket 现在什么最热？"
🤖 展示按交易量排名的热门市场及价格
👤 "用 20 USDC 买排名第一市场的 Yes"
🤖 生成订单 + 签名链接 + 二维码
👤 "帮我看看值得跟单的交易员"
🤖 按绩效排名列出顶级交易员
👤 "以 5% 的比例跟单那位交易员"
🤖 开始监控并自动镜像交易
```
---
## MCP Server 信息
| 属性 | 值 |
|------|-----|
| **接口地址** | `https://mcp-skills.ai.antalpha.com/mcp` |
| **协议** | Streamable HTTP (MCP 2024-11-05) |
| **认证** | 调用 `antalpha-register` 工具获取 `agent_id` + `api_key` |
| **工具数量** | 30+ MCP 工具，覆盖市场数据、交易、跟单、持仓管理、对冲策略 |
---
## 签名流程说明
```
Agent MCP Server 签名页面 用户钱包
│ │ │ │
│── poly-buy ──────►│ │ │
│ │── 构建订单 ─────►│ │
│◄── { signUrl } ──│ │ │
│ │ │ │
│── 展示签名链接 ────────────────────►│ │
│ │ │── eth_signTypedData ─►│
│ │ │◄── 签名结果 ──│
│ │◄── 提交签名 ────│ │
│ │── 在 CLOB 下单 │ │
│◄── 订单确认 ──────│ │ │
```
**安全保障：**
- ✅ 私钥永不离开钱包
- ✅ 每笔签名绑定具体订单数据（EIP-712）
- ✅ 签名页面在签名前展示完整订单详情
- ✅ 链接 10 分钟后过期
- ✅ 后端不托管资金或私钥
---
## 技术栈
| 组件 | 技术 |
|------|------|
| 链 | Polygon 主网（Chain ID 137） |
| 货币 | USDC.e |
| 市场协议 | Polymarket CTF Exchange（条件代币框架） |
| SDK | [@polymarket/clob-client](https://github.com/Polymarket/clob-client) v5.8.1 |
| 签名方式 | EIP-712 类型数据（浏览器内） |
| 钱包类型 | GnosisSafe (1/1) 代理钱包 |
| MCP 协议 | Streamable HTTP (MCP 2024-11-05) |
| 后端 | NestJS 11 + TypeORM + MySQL + Redis |
---
## 免责声明
⚠️ **非投资建议。** 预测市场存在风险，请勿投入超出承受能力的资金。
⚠️ **Polymarket 可用性** 因司法管辖区而异，用户须自行遵守当地法规。
⚠️ **跟单交易** 会复制他人决策，历史表现不代表未来收益。
⚠️ **Polygon Gas 费** 极低（< $0.01/笔），但需持有少量 POL。
---
## 文档
- [SKILL.md](./SKILL.md) — 完整 Agent 指令、MCP 工具参考、输出格式规范
- [docs/quickstart.md](./docs/quickstart.md) — 面向用户的配置指南（v2 已更新）
---
## 许可
MIT © [Antalpha AI Team](https://www.antalpha.com/)
---
**由 [Antalpha AI](https://ai.antalpha.com) 构建** 🎯 | v2.0.0
*为下一代 AI 驱动的预测市场交易提供动力。*
FILE:docs/quickstart.md
# Poly Master v2 — Quick Start Guide
> Powered by **Antalpha AI**
## What is Poly Master?
Poly Master lets you interact with [Polymarket](https://polymarket.com) — the world's largest prediction market — through natural conversation with your AI agent. You can:
- 📈 **Discover** — Browse trending and new prediction markets
- 💰 **Trade** — Buy/sell Yes or No outcome tokens
- 👥 **Copy-Trade** — Follow top traders and mirror their moves
- 📊 **Track** — Monitor your portfolio and PnL
- 🔮 **Poly Master Hedge** (V2) — LLM-driven near-riskless arbitrage signals
**Zero custody** — your private keys never leave your wallet.
---
## Prerequisites
1. **A crypto wallet** — MetaMask, OKX Wallet, Trust Wallet, or TokenPocket
2. **USDC.e on Polygon** — This is the trading currency on Polymarket
3. **A small amount of POL** — For gas fees on Polygon (< $0.01 per transaction)
4. **Polymarket account** — You must first complete onboarding at [polymarket.com](https://polymarket.com) (this creates your proxy wallet)
---
## Feature 1: Market Discovery
### Browse trending markets
> "What's hot on Polymarket?"
> "Show me trending crypto prediction markets"
The agent returns the top markets ranked by 24h trading volume, with prices for Yes/No outcomes.
### Discover new markets
> "Any new prediction markets in the last 24 hours?"
### Get market details
> "Tell me more about market #3"
---
## Feature 2: Direct Trading
### Buy outcome tokens
> "Buy $20 on Yes for 'Will ETH hit $5000?'"
> "I want to bet $10 on No for market #1"
The agent will:
1. Look up the market and current prices
2. Build the order via MCP
3. Generate a signing page link + QR code
4. You open the link in your wallet browser → review → sign → done!
### Sell outcome tokens
> "Sell my Yes position in the Iran market"
### Check order status
> "Check the status of my last order"
Use `poly-confirm` with the order ID to check signing status + CLOB fill status.
### Browse all orders
> "Show me all my pending orders"
Use `poly-master-orders` to list orders with optional status filter.
### Important notes
- **Market orders**: Buy/sell at current best price (default)
- **Limit orders**: Specify your target price — *"Buy at $0.30/share"*
- **Signing window**: You have **10 minutes** to sign after the link is generated
- **Minimum order**: 5 outcome tokens per order (approx. $1.25+ depending on price)
---
## Feature 3: Poly Master Hedge Strategy (V2)
Poly Master uses LLM reasoning to find near-riskless two-leg hedge opportunities across markets. If "A=YES necessarily implies B=YES", you can buy both legs for totalCost < 1 USDC, locking in profit.
### Signal Tiers
| Tier | Coverage | Risk Level |
|------|----------|------------|
| T1 | ≥ 0.95 | Near-riskless |
| T2 | ≥ 0.90 | Low risk |
| T3 | ≥ 0.85 | Monitor liquidity |
### Scan for opportunities
> "Scan Polymarket for hedge opportunities"
> "Find T1 arbitrage signals"
The agent calls `poly-master-strategy-scan` and returns signals ranked by coverage.
### View signal details
> "Tell me more about signal #1"
Shows both legs (target + cover), prices, liquidity, and LLM reasoning.
### Execute a hedge
> "Execute signal #1 with $5 USDC"
The agent will:
1. Show full signal details for confirmation
2. Generate **two signing links** (target leg first, then cover leg)
3. You sign each leg in order — **must sign leg 1 before leg 2**
### Monitor strategy
> "Show me the Poly Master strategy dashboard"
Displays Tier distribution, signal frequency, slippage cancel rate, and recent scan results.
---
## Feature 4: Copy Trading
### Discover top traders
> "Show me top Polymarket traders"
The agent analyzes recent trading activity and ranks traders by performance.
### Follow a trader
> "Follow trader 0xABC... with 10% copy ratio"
This means: when the trader buys 100 shares, you'll buy 10 shares.
### Set risk controls
> "Set stop loss at 20% and max position at 200 USDC per market"
| Parameter | Default | Description |
|-----------|---------|-------------|
| Stop Loss | 20% | Auto-pause when position drops this much |
| Take Profit | 50% | Alert when position gains this much |
| Max Per Market | $500 | Maximum USDC in any single market |
| Max Total | $2,000 | Maximum daily trading volume |
| Max Slippage | 5% | Reject orders with too much price deviation |
### Monitor performance
> "Show me this week's copy trading PnL"
### Manage following
> "Pause copy trading"
> "Stop following 0xABC..."
---
## Feature 5: Portfolio Tracking
### View positions
> "How's my Polymarket portfolio?"
Shows all current positions with: direction, quantity, average price, current price, market value, and PnL.
### Trade history
> "Show me my recent Polymarket trades"
### PnL reports
> "What's my monthly PnL on Polymarket?"
---
## How Signing Works
Every trade requires your wallet signature (zero custody):
1. 🔔 Agent generates a signing URL
2. 🌐 Open the link in your wallet's built-in browser
3. 🔐 Review the order details (market, direction, price, quantity)
4. ✅ Click "Sign" — your wallet prompts for EIP-712 signature
5. 📤 Signature is submitted, order placed on Polymarket
**Your private key never leaves your wallet.** The agent only receives the signature for the specific order.
**Supported wallet browsers:**
- MetaMask (mobile DApp browser)
- OKX Wallet (Discover tab)
- Trust Wallet (DApp browser)
- TokenPocket (DApp browser)
---
## Troubleshooting
**"CLOB API connection failed"**
→ Check your internet connection. Polymarket may be temporarily down.
**"Sign request expired"**
→ You have **10 minutes** to sign. If it expires, ask the agent to regenerate the signing link.
**"Risk limit exceeded"**
→ Your order exceeds your configured risk parameters. Adjust limits or reduce position size.
**"Not enough balance"**
→ Ensure you have enough USDC.e in your Polymarket proxy wallet. Deposit at [polymarket.com](https://polymarket.com).
**"Minimum order size"**
→ Polymarket requires a minimum of 5 outcome tokens per order.
---
## Support
- **Documentation**: See [SKILL.md](../SKILL.md) for full technical reference
- **Antalpha AI**: [ai.antalpha.com](https://ai.antalpha.com)
- **Polymarket**: [polymarket.com](https://polymarket.com)
---
由 Antalpha AI 提供聚合交易服务 | Powered by [Antalpha AI](https://ai.antalpha.com)