Graph Query Tool Free

SKILL.md

---
slug: graph-query-tool-free
name: graph-query-tool-free
version: 1.0.0
displayName: 链上数据查询(免费版)
summary: 区块链数据自然语言查询，路由到免费数据服务，返回实时结果。
license: Proprietary
edition: free
description: '区块链数据自然语言查询，路由到免费数据服务，返回实时结果。核心能力：

  - 自然语言提问自动路由到合适的链上数据服务

  - 覆盖代币余额、持仓、NFT、子图检索等免费查询

  - 返回结构化 JSON 与可执行的 query_ready 参数

  - 无需钱包即可使用免费层


  适用场景：

  - 链上地址余额与持仓查询

  - 协议子图检索与定位

  - DeFi 借贷数据查询

  - 链上数据快速验证与探索


  差异化：采用自然语言路由与免费层优先策略，让非链上专业用户也能快速查询区块链数据，免费版聚焦"问得到、查得到"的核心场景'
tags:
- 集成工具
- 区块链
- 数据查询
tools:
- - read
- exec
homepage: https://skillhub.cn
pricing_tier: L3
pricing_model: per_use
suggested_price: 29.9
tools: ["read", "write", "exec"]
tags: "工具,效率,自动化"
---
# 链上数据查询（免费版）

## 概述

本 Skill 帮助 Agent 将自然语言提问路由到合适的链上数据服务，返回实时数据而非仅推荐。免费版聚焦"无钱包、免费层"场景：用户无需连接钱包即可查询代币余额、NFT、协议子图等基础数据。Skill 自动识别用户意图，选择对应服务并执行查询，返回结构化 JSON。

## 核心能力

| 能力 | 说明 | 免费版支持 |
|---|---|-----|
| 自然语言路由 | 自动匹配意图到服务 | 是 |
| 代币余额查询 | EVM/Solana/TON 钱包数据 | 是 |
| 子图检索 | 15500+ 子图按协议/链搜索 | 是 |
| 借贷数据查询 | Aave V2/V3/V4 基础查询 | 是 |
| 预测市场基础 | Polymarket 基础查询 | 是 |
| 结构化输出 | JSON + query_ready | 是 |
| 免费层配额查询 | 查询剩余免费次数 | 是 |
| 付费端点 | 跨场内价差、地址解析等 | 否（专业版） |
| 高级 MCP工具 | 订单簿、争议、胜率统计 | 否（专业版） |
| 支出控制 | 钱包余额、预算熔断 | 否（专业版） |

### 核心功能执行
用`input_params`参数进行配置。

**输入**: 用户提供核心功能执行所需的指令和必要参数。
**处理**: 解析核心功能执行的输入参数,完成核心逻辑,返回结构化响应。
**输出**: 返回核心功能执行的响应数据,包含状态码、结果和日志。
- 执行此能力时使用`input_params`参数,支持创建/查询/导出操作

### 参数配置与调用
用`config_options`参数进行配置。

**输入**: 用户提供参数配置与调用所需的指令和必要参数。
**处理**: 解析参数配置与调用的输入参数,完成核心逻辑,返回结构化响应。
**输出**: 返回参数配置与调用的响应数据,包含状态码、结果和日志。
- 执行此能力时使用`config_options`参数,支持修改/重置/导入操作

### 结果处理与输出
用`output_format`参数进行配置。

**输入**: 用户提供结果处理与输出所需的指令和必要参数。
**处理**: 解析结果处理与输出的输入参数,完成核心逻辑,返回结构化响应。
**输出**: 返回结果处理与输出的响应数据,包含状态码、结果和日志。
- 执行此能力时使用`output_format`参数,支持导出/保存/转换操作
**能力覆盖范围**：本skill的核心能力覆盖以下场景关键词：区块链数据自然语、言查询、路由到免费数据服、返回实时结果、核心能力、自然语言提问自动、路由到合适的链上、数据服务、覆盖代币余额、NFT、子图检索等免费查、返回结构化、与可执行的、无需钱包即可使用等。这些关键词对应description中声明的使用场景,均已在上述能力点中提供对应的操作支持。

## 使用场景

1. **地址余额查询**：输入钱包地址查询 ETH/USDC/NFT 持仓，无需手动拼接 GraphQL。
2. **协议子图定位**：为某个协议（如 Uniswap V3）找到合适的子图，获取 query hints。
3. **DeFi 借贷数据**：查询 Aave 借贷池的利率、清算、TVL 等基础指标。
4. **链上数据快速验证**：核验某地址是否持有某代币、某笔交易是否上链。

## 不适用场景

以下场景链上数据查询(免费版)不适合处理：

- 实时流数据处理
- 小规模数据手动分析
- 非结构化文本情感分析

## 触发条件

需要数据分析、报表生成、统计洞察、数据可视化时使用。不适用于非本工具能力范围的需求。

## 快速开始

> 上手时间：< 60 秒。免费版无需钱包，直接提问即可。

### Step 1：自然语言提问

```text
"以太坊上 USDC 前 10 持仓地址"
"Arbitrum 上 Uniswap V3 用哪个子图？"
"Aave V3 清算额超过 5 万美元的记录"
```

### Step 2：查看路由结果

Skill 返回结构化 JSON，包含推荐服务、理由、置信度与可执行参数：

```json
{
  "recommendation": "subgraph-registry",
  "reason": "查询协议子图，注册表可按协议/链检索 15500+ 子图",
  "confidence": "high",
  "query_ready": { "tool": "subgraph-registry", "args": { "protocol": "uniswap-v3", "chain": "arbitrum" } },
  "execution_result": { "source": "subgraph-gateway", "data": {} },
  "cache_for_seconds": 86400
}
```

### Step 3：查询免费配额

```text
GET https://graph-query.example/quota?sender=0x配置值
```

返回当日剩余免费查询次数，便于规划查询节奏。

## 示例

### 意图路由表（免费层）

| 意图 | 服务 | 适用场景 |
|:-----|:-----|:-----|
| 代币余额、持仓、NFT | token-api | EVM / Solana / TON 钱包数据 |
| 协议子图检索 | subgraph-registry | 15500+ 子图按协议/链搜索 |
| Aave 借贷基础 | graph-aave 工具集 | V2/V3/V4 基础查询 |
| Polymarket 基础 | token-api | 市场、OHLCV、用户持仓 |
| 跨协议借贷对比 | graph-lending 工具集 | 40+ 协议、15 链对比 |
| 预测市场（Limitless） | graph-limitless 工具集 | Base 链预测市场 |
| 预测市场（Predict.fun） | predictfun 工具集 | BNB 链预测市场 |
| 原始区块数据 | substreams | traces、logs、流式转换 |

### 已知限制

- 每日每发送者 3 次免费路由查询
- 超出后返回 402 Payment Required，免费版不触发付费
- 付费端点（跨场内价差、地址解析、自然语言 SQL）免费版不可用

## 最佳实践

1. **免费层优先规划**：每日 3 次免费查询，建议优先用于高价值查询，低价值查询用本地缓存复用。
2. **提问要具体**：包含链名、协议名、地址等具体信息，路由置信度更高。如"以太坊主网 0x... 的 USDC 余额"优于"查余额"。
3. **复用 query_ready**：返回的 `query_ready` 参数可直接用于后续查询，无需重复构造。
4. **利用缓存**：返回结果含 `cache_for_seconds`（默认 86400 秒），同一查询 24 小时内可复用。
5. **免费层无钱包**：免费版从不请求钱包，付费端点未配置时返回 402 即停止，无资金流动。

## 常见问题

### Q1：免费查询次数用完怎么办？

A：免费版每日 3 次。建议：(1) 复用 `cache_for_seconds` 缓存；(2) 次日重试；(3) 升级专业版解锁付费端点与更高配额。

### Q2：查询返回的数据是实时的吗？

A：是。Skill 返回链上实时数据而非仅推荐。部分聚合数据可能有少量延迟，结果中会标注数据源与缓存时间。

### Q3：路由置信度低怎么办？

A：(1) 补充链名、协议名等上下文；(2) 拆分复杂问题为多个单一问题；(3) 涉及多个服务时，Skill 会同时调用并合并结果。

### Q4：免费版能查询哪些链？

A：覆盖 EVM 系（以太坊、Arbitrum、Base 等）、Solana、TON。具体链支持取决于所选服务的覆盖范围。

### Q5：返回的 query_ready 如何使用？

A：`query_ready` 包含 `tool` 与 `args`，可直接传给对应服务执行，无需重新构造查询参数。

### Q6：免费版支持哪些链的查询？

A：覆盖 EVM 系（以太坊、Arbitrum、Base、Polygon 等）、Solana、TON。具体链支持取决于所选服务的覆盖范围，结果中会标注数据来源链。

### Q7：如何提高路由准确率？

A：(1) 提问包含链名、协议名、地址等具体信息；(2) 避免模糊表述如"查一下余额"；(3) 涉及多个服务时 Skill 会自动合并结果。

### Q8：免费版查询会消耗 Gas 吗？

A：不会。免费版仅读取链上数据，不发送交易，不消耗 Gas，无需钱包连接。

## 错误处理

| 错误场景(现象) | 可能原因 | 解决步骤 | 优先级 |
|------:|------:|------:|------:|
| 路由置信度低 | 提问不具体 | 补充链名、协议名、地址 | P2 |
| 返回空数据 | 地址无活动 / 协议不支持 | 确认地址与协议匹配 | P3 |
| 免费配额耗尽 | 当日 3 次已用完 | 次日执行ping命令测试网络连通性,检查防火墙和代理设置连接后重新执行命令或复用缓存 | P2 |
| 查询超时 | 网络波动 / 服务繁忙 | 稍后执行ping命令测试网络连通性,检查防火墙和代理设置连接后重新执行命令，复用缓存 | P3 |
| 子图未找到 | 协议无对应子图 | 尝试相近协议名或全链搜索 | P3 |
## 免费版限制

本免费体验版限制以下高级功能：
- 付费端点（跨场内价差、地址解析、自然语言 SQL 分析）（专业版支持）
- 高级 MCP工具（订单簿深度、争议市场、胜率/回撤统计）（专业版支持）
- 支出控制（钱包余额检查、预算熔断、重试策略）（专业版支持）
- 付费收据与链上结算凭证（专业版支持）
- 自定义路由策略与批量查询（专业版支持）

解锁全部功能请使用专业版：graph-query-tool-pro

## 依赖说明

### 运行环境
- **Agent 平台**：支持 SKILL.md 的任意 AI Agent（Claude Code / Cursor / Codex / Gemini CLI 等）
- **操作系统**：Windows / macOS / Linux
- **网络**：需访问链上数据服务端点

### 依赖详情
| 依赖项 | 类型 | 是否必需 | 获取方式 |
|:---:|:---:|:---:|:---:|
| LLM API | API | 必需 | 由 Agent 平台内置 LLM 提供 |
| 链上数据服务 | 外部 API | 必需 | 路由服务与子图网关，免费层无需 Key |
| Python 标准库 | 运行时 | 必需 | Python 自带（urllib / json） |
| requests（可选） | Python 包 | 可选 | `pip install requests`，用于更稳定的 HTTP 请求 |

### API Key 配置
- **免费层**：无需 API Key，直接提问即可
- **API Key（可选）**：如需更高配额，可在对应服务官网申请免费 API Key，由专业版完整支持
- **本 Skill 基于指令驱动**：除上述可选 Key 外无需额外凭证

### 可用性分类
- **分类**：MD+EXEC（纯 Markdown 指令，部分功能需要 exec 命令行执行能力）
- **说明**：基于 Markdown 的 AI Skill，通过自然语言指令驱动 Agent 执行任务，仅使用免费数据服务