/bitquery-graphql-skill

name: bitquery-graphql-skill
description: Use Bitquery GraphQL through UXC for onchain trades, transfers, token holder analysis, balances, and market structure queries across supported networks, with OAuth client_credentials authentication and query-first execution.

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.

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.

Authentication

Bitquery uses bearer access tokens. The most stable agent path is OAuth `client_credentials`, not a copied temporary token.

1. Create a Bitquery application and note:

• application `client_id`
• application `client_secret`
• token scope `api`

2. Login once with OAuth client credentials:

• `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.

3. 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`

4. Verify auth mapping:

• `uxc auth binding match https://streaming.bitquery.io/graphql`
• `uxc auth oauth info bitquery-graphql`

Core Workflow

1. 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.

2. Discover available root operations:

• `bitquery-graphql-cli -h`
• Verified roots currently include `query/EVM`, `query/Solana`, `query/Trading`, `query/Tron`, and matching `subscription/*` roots.

3. Inspect a specific operation:

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

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

5. 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`.

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

Recommended Usage Pattern

1. Inspect root arguments first:

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

2. Start with a minimal query on one network:

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

3. Add only the fields needed for the task:

• buyers / sellers
• token addresses
• symbols
• amounts
• timestamps

4. Narrow with GraphQL arguments inside `_select`:

• `limit`
• `orderBy`
• `where`

5. Treat large or realtime queries carefully:

• avoid wide selections
• prefer one chain / token / wallet at a time on first pass

6. For live subscriptions, start with a known-good high-frequency shape:

• `./target/debug/uxc subscribe start https://streaming.bitquery.io/graphql subscription/EVM '{"network":"bsc","mempool":true,"_select":"Transfers { Transaction { Hash From To } Transfer { Amount Type Currency { Name } } }"}' --auth bitquery-graphql --sink file:$HOME/.uxc/subscriptions/bitquery-mempool.ndjson`

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:

{
  "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:

{
  "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 c