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. 1. Create a Bitquery application and note:

- application client_id - application client_secret - token scope api

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

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

1. 4. Verify auth mapping:

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

Core Workflow

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

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

1. 3. Inspect a specific operation:

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

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

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

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 INLINECODE45
• start with a high-frequency root such as INLINECODE46
• prefer direct event shapes before adding INLINECODE47
• treat empty selections or query-oriented shapes as likely application-level errors

Recommended Usage Pattern

1. 1. Inspect root arguments first:

- bitquery-graphql-cli query/EVM -h

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

1. 3. Add only the fields needed for the task:

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

1. 4. Narrow with GraphQL arguments inside _select:

- limit - orderBy - where

1. 5. Treat large or realtime queries carefully:

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

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

- INLINECODE54

Tested Real Scenario

The following authenticated Bitquery flow was verified successfully through uxc:

• - OAuth login with INLINECODE56
• auth binding on INLINECODE57
• GraphQL host help
• INLINECODE58
• authenticated query/EVM call on INLINECODE60
• 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:

CODEBLOCK0

The verified subscription shape was:

CODEBLOCK1

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.
• INLINECODE70 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:

- INLINECODE85