UXC

One CLI for tools across protocols.

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

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

Within those roots, Bitquery exposes entities for tasks such as:

Always inspect the current schema with -h and use the narrowest _select needed.

For subscriptions specifically:

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:

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

References