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.
   • Use subscription/* only after runtime validation in the current environment.

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.

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

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

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 } } } }"
}

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. Treat subscription/* as advanced and validate runtime behavior before depending on it.
• 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