bitquery-graphql-skill

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Bitquery GraphQL Skill

Use this skill to run Bitquery GraphQL API operations through

uxc

Reuse the

uxc

skill for discovery, GraphQL execution, OAuth lifecycle, and generic error handling.

使用本Skill通过

uxc

执行Bitquery GraphQL API操作。

复用

uxc

Skill来实现服务发现、GraphQL执行、OAuth生命周期管理以及通用错误处理。

Prerequisites

前提条件

```
uxc
```
is installed and available in
```
PATH
```
.
Network access to
```
https://streaming.bitquery.io/graphql
```
.
A Bitquery application
```
client_id
```
and
```
client_secret
```
are available.

已安装
```
uxc
```
且其路径已添加至
```
PATH
```
环境变量。
能够访问
```
https://streaming.bitquery.io/graphql
```
网络地址。
拥有Bitquery应用的
```
client_id
```
和
```
client_secret
```
。

Authentication

认证方式

Bitquery uses bearer access tokens. The most stable agent path is OAuth

client_credentials

, not a copied temporary token.

Create a Bitquery application and note:
- application
```
client_id
```
- application
```
client_secret
```
- token scope
```
api
```

uxc auth oauth login bitquery-graphql --endpoint https://streaming.bitquery.io/graphql --flow client_credentials --client-id <client_id> --client-secret <client_secret> --scope api --token-endpoint https://oauth2.bitquery.io/oauth2/token

This flow completes in one command. No browser approval page is required.

Bind the GraphQL endpoint:

uxc auth binding add --id bitquery-graphql --host streaming.bitquery.io --path-prefix /graphql --scheme https --credential bitquery-graphql --priority 100

Verify auth mapping:

uxc auth binding match https://streaming.bitquery.io/graphql

```
uxc auth oauth info bitquery-graphql
```

Bitquery使用Bearer访问令牌。最稳定的代理方式是采用OAuth

client_credentials

授权流程，而非复制临时令牌。

创建一个Bitquery应用并记录以下信息：
- 应用的
```
client_id
```
- 应用的
```
client_secret
```
- 令牌权限范围
```
api
```

使用OAuth客户端凭证登录一次：

uxc auth oauth login bitquery-graphql --endpoint https://streaming.bitquery.io/graphql --flow client_credentials --client-id <client_id> --client-secret <client_secret> --scope api --token-endpoint https://oauth2.bitquery.io/oauth2/token

该流程通过一条命令即可完成，无需浏览器授权页面。

绑定GraphQL端点：

uxc auth binding add --id bitquery-graphql --host streaming.bitquery.io --path-prefix /graphql --scheme https --credential bitquery-graphql --priority 100

验证认证映射：

uxc auth binding match https://streaming.bitquery.io/graphql

```
uxc auth oauth info bitquery-graphql
```

Core Workflow

核心工作流程

Use fixed link command by default:
- ```
command -v bitquery-graphql-cli
```
- If missing, create it:
```
uxc link bitquery-graphql-cli https://streaming.bitquery.io/graphql
```
- ```
bitquery-graphql-cli -h
```
- If command conflict is detected and cannot be safely reused, stop and ask skill maintainers to pick another fixed command name.
Discover available root operations:
- ```
bitquery-graphql-cli -h
```
- Verified roots currently include
```
query/EVM
```
  ,
```
query/Solana
```
  ,
```
query/Trading
```
  ,
```
query/Tron
```
  , and matching
```
subscription/*
```
  roots.

Inspect a specific operation:

```
bitquery-graphql-cli query/EVM -h
```
```
bitquery-graphql-cli query/Trading -h
```

Execute with positional JSON and explicit GraphQL selection sets:

bitquery-graphql-cli query/EVM '{"network":"base","dataset":"combined","_select":"DEXTrades(limit: {count: 1}) { Transaction { Hash } }"}'

Prefer
```
query/*
```
operations first.
- ```
uxc subscribe
```
  now auto-negotiates modern
```
graphql-transport-ws
```
  and legacy
```
graphql-ws
```
  compatibility profiles for
```
subscription/*
```
  .
- Live Bitquery subscription validation now succeeds when you provide an explicit
```
_select
```
  that matches a stream-friendly entity shape.
- Prefer
```
subscription/EVM
```
  as the first validation target rather than
```
subscription/Trading
```
  .

默认使用固定链接命令：
- ```
command -v bitquery-graphql-cli
```
- 若该命令不存在，创建它：
```
uxc link bitquery-graphql-cli https://streaming.bitquery.io/graphql
```
- ```
bitquery-graphql-cli -h
```
- 若检测到命令冲突且无法安全复用，请停止操作并联系Skill维护者选择其他固定命令名称。
发现可用的根操作：
- ```
bitquery-graphql-cli -h
```
- 当前已验证的根操作包括
```
query/EVM
```
  、
```
query/Solana
```
  、
```
query/Trading
```
  、
```
query/Tron
```
  以及对应的
```
subscription/*
```
  根操作。

查看特定操作详情：

```
bitquery-graphql-cli query/EVM -h
```
```
bitquery-graphql-cli query/Trading -h
```

使用位置参数JSON和显式GraphQL选择集执行操作：

bitquery-graphql-cli query/EVM '{"network":"base","dataset":"combined","_select":"DEXTrades(limit: {count: 1}) { Transaction { Hash } }"}'

优先使用
```
query/*
```
操作。
- 对于
```
subscription/*
```
  根操作，
```
uxc subscribe
```
  现在会自动协商现代
```
graphql-transport-ws
```
  和旧版
```
graphql-ws
```
  的兼容配置。
- 当你提供与流式友好实体结构匹配的显式
```
_select
```
  时，Bitquery实时订阅验证现在会成功。
- 优先选择
```
subscription/EVM
```
  作为首个验证目标，而非
```
subscription/Trading
```
  。

Capability Map

能力映射

EVM onchain queries:
- ```
query/EVM
```
- ```
subscription/EVM
```
Solana onchain queries:
- ```
query/Solana
```
- ```
subscription/Solana
```
Cross-market / trading queries:
- ```
query/Trading
```
- ```
subscription/Trading
```
Tron onchain queries:
- ```
query/Tron
```
- ```
subscription/Tron
```

Within those roots, Bitquery exposes entities for tasks such as:

DEX trades
token balances and holder analysis
transfers
blocks and transactions
mempool and realtime activity
market or trading views depending on the root

Always inspect the current schema with

-h

and use the narrowest

_select

needed.

For subscriptions specifically:

always provide
```
_select
```
start with a high-frequency root such as
```
subscription/EVM
```
prefer direct event shapes before adding
```
limit
```
treat empty selections or query-oriented shapes as likely application-level errors

EVM链上查询：
- ```
query/EVM
```
- ```
subscription/EVM
```
Solana链上查询：
- ```
query/Solana
```
- ```
subscription/Solana
```
跨市场/交易查询：
- ```
query/Trading
```
- ```
subscription/Trading
```
Tron链上查询：
- ```
query/Tron
```
- ```
subscription/Tron
```

在这些根操作中，Bitquery提供了适用于以下任务的实体：

DEX交易
代币余额与持有者分析
转账
区块与交易
内存池与实时活动
基于根操作的市场或交易视图

始终使用

-h

查看当前模式，并使用所需的最精简

_select

。

针对订阅的特殊说明：

始终提供
```
_select
```
从高频根操作开始，例如
```
subscription/EVM
```
在添加
```
limit
```
之前优先使用直接事件结构
将空选择集或面向查询的结构视为可能的应用级错误

Recommended Usage Pattern

Tested Real Scenario

已测试的真实场景

The following authenticated Bitquery flow was verified successfully through

uxc

OAuth login with
```
client_credentials
```
auth binding on
```
https://streaming.bitquery.io/graphql
```
GraphQL host help
```
query/EVM -h
```
authenticated
```
query/EVM
```
call on
```
base
```
daemon-backed
```
subscription/EVM
```
over WebSocket against live Bitquery infra
repeated live
```
data
```
events from a BSC mempool transfer stream

The verified query shape was:

json

{
  "network": "base",
  "dataset": "combined",
  "_select": "DEXTrades(limit: {count: 1}) { Block { Time } Transaction { Hash } Trade { Buy { Amount Buyer Currency { Symbol SmartContract } } Sell { Amount Seller Currency { Symbol SmartContract } } } }"
}

The verified subscription shape was:

json

{
  "network": "bsc",
  "mempool": true,
  "_select": "Transfers { Transaction { Hash From To } Transfer { Amount Type Currency { Name } } }"
}

以下经过认证的Bitquery流程已通过

uxc

成功验证：

使用
```
client_credentials
```
进行OAuth登录
在
```
https://streaming.bitquery.io/graphql
```
上绑定认证
GraphQL主机帮助
```
query/EVM -h
```
命令
在
```
base
```
网络上执行已认证的
```
query/EVM
```
调用
通过WebSocket基于守护进程连接Bitquery实时基础设施执行
```
subscription/EVM
```
从BSC内存池转账流中接收重复的实时
```
data
```
事件

已验证的查询结构如下：

json

{
  "network": "base",
  "dataset": "combined",
  "_select": "DEXTrades(limit: {count: 1}) { Block { Time } Transaction { Hash } Trade { Buy { Amount Buyer Currency { Symbol SmartContract } } Sell { Amount Seller Currency { Symbol SmartContract } } } }"
}

已验证的订阅结构如下：

json

{
  "network": "bsc",
  "mempool": true,
  "_select": "Transfers { Transaction { Hash From To } Transfer { Amount Type Currency { Name } } }"
}

Guardrails

注意事项

Keep automation on JSON output envelope; do not rely on
```
--text
```
.
Parse stable fields first:
```
ok
```
,
```
kind
```
,
```
protocol
```
,
```
data
```
,
```
error
```
.
Use
```
bitquery-graphql-cli
```
as the default command path.

bitquery-graphql-cli <operation> ...

is equivalent to

uxc https://streaming.bitquery.io/graphql <operation> ...

Prefer positional JSON for GraphQL calls because
```
_select
```
is usually required.
Keep
```
_select
```
small on first pass and add explicit filters before expanding scope.
Prefer
```
query/*
```
for stable agent workflows.
```
subscription/*
```
is now validated at runtime, but still depends on provider-specific selection shape.
For subscription validation or automation, start with
```
subscription/EVM
```
and an explicit
```
_select
```
; do not assume an empty selection or
```
subscription/Trading
```
default shape will yield events.
If a subscription opens successfully but immediately returns GraphQL errors, treat that as a query-shape problem before assuming transport failure.

If auth fails:

confirm

uxc auth binding match https://streaming.bitquery.io/graphql

resolves to

bitquery-graphql

inspect token state with
```
uxc auth oauth info bitquery-graphql
```
manually refresh with
```
uxc auth oauth refresh bitquery-graphql
```

if needed, rerun

uxc auth oauth login ... --flow client_credentials ...

Do not paste temporary IDE tokens into long-lived skill docs. Prefer application-based
```
client_credentials
```
.

自动化流程依赖JSON输出格式，不要依赖
```
--text
```
格式。
优先解析稳定字段：
```
ok
```
、
```
kind
```
、
```
protocol
```
、
```
data
```
、
```
error
```
。
使用
```
bitquery-graphql-cli
```
作为默认命令路径。

bitquery-graphql-cli <operation> ...

等价于

uxc https://streaming.bitquery.io/graphql <operation> ...

。

GraphQL调用优先使用位置参数JSON，因为通常需要
```
_select
```
。
首次执行时保持
```
_select
```
精简，在扩大范围前添加显式过滤器。
稳定的代理工作流优先使用
```
query/*
```
操作。
```
subscription/*
```
现在会在运行时验证，但仍依赖于服务商特定的选择集结构。
对于订阅验证或自动化，从
```
subscription/EVM
```
和显式
```
_select
```
开始；不要假设空选择集或
```
subscription/Trading
```
默认结构会产生事件。
如果订阅成功建立但立即返回GraphQL错误，先将其视为查询结构问题，再考虑传输故障。

如果认证失败：

确认

uxc auth binding match https://streaming.bitquery.io/graphql

解析到

bitquery-graphql

使用
```
uxc auth oauth info bitquery-graphql
```
查看令牌状态
使用
```
uxc auth oauth refresh bitquery-graphql
```
手动刷新令牌

如有必要，重新运行

uxc auth oauth login ... --flow client_credentials ...

命令

不要将临时IDE令牌粘贴到长期使用的Skill文档中，优先使用基于应用的
```
client_credentials
```
。

References

参考资料

Invocation patterns:
- ```
references/usage-patterns.md
```

调用模式：
- ```
references/usage-patterns.md
```

bitquery-graphql-skill

Original

Translation

Bitquery GraphQL Skill

Bitquery GraphQL Skill

Prerequisites

前提条件

Authentication

认证方式

Core Workflow

核心工作流程

Capability Map

能力映射

Recommended Usage Pattern

推荐使用模式

Tested Real Scenario

已测试的真实场景

Guardrails

注意事项

References

参考资料