bitquery-graphql-skill

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.