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.

Permission Setup Review

python scripts/_setup_logs.py is an optional setup helper for the Bitquery GraphQL Skill skill. It may apply broad filesystem permissions for compatibility. Show the target paths and permission mode, explain the risk, and prefer a narrower mode when shared write access is not needed.

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

References

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