Graph Query Tool Free

通过自然语言查询链上代币余额、持仓、NFT及协议子图，无需钱包，返回结构化JSON实时免费区块链数据。

Install

openclaw skills install @thcjp/graph-query-tool-free

链上数据查询（免费版）

概述

本 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中声明的使用场景,均已在上述能力点中提供对应的操作支持。

使用场景

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

不适用场景

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

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

触发条件

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

快速开始

上手时间：< 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）免费版不可用

最佳实践

免费层优先规划：每日 3 次免费查询，建议优先用于高价值查询，低价值查询用本地缓存复用。
提问要具体：包含链名、协议名、地址等具体信息，路由置信度更高。如"以太坊主网 0x... 的 USDC 余额"优于"查余额"。
复用 query_ready：返回的 query_ready 参数可直接用于后续查询，无需重复构造。
利用缓存：返回结果含 cache_for_seconds（默认 86400 秒），同一查询 24 小时内可复用。
免费层无钱包：免费版从不请求钱包，付费端点未配置时返回 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 执行任务，仅使用免费数据服务