{"skill":{"slug":"bitquery-graphql-skill","displayName":"Bitquery GraphQL Skill","summary":"Use Bitquery GraphQL through UXC for onchain trades, transfers, token holder analysis, balances, and market structure queries across supported networks, with...","description":"---\nname: bitquery-graphql-skill\ndescription: 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.\n---\n\n# Bitquery GraphQL Skill\n\nUse this skill to run Bitquery GraphQL API operations through `uxc`.\n\nReuse the `uxc` skill for discovery, GraphQL execution, OAuth lifecycle, and generic error handling.\n\n## Prerequisites\n\n- `uxc` is installed and available in `PATH`.\n- Network access to `https://streaming.bitquery.io/graphql`.\n- A Bitquery application `client_id` and `client_secret` are available.\n\n## Authentication\n\nBitquery uses bearer access tokens. The most stable agent path is OAuth `client_credentials`, not a copied temporary token.\n\n1. Create a Bitquery application and note:\n   - application `client_id`\n   - application `client_secret`\n   - token scope `api`\n2. Login once with OAuth client credentials:\n   - `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`\n   - This flow completes in one command. No browser approval page is required.\n3. Bind the GraphQL endpoint:\n   - `uxc auth binding add --id bitquery-graphql --host streaming.bitquery.io --path-prefix /graphql --scheme https --credential bitquery-graphql --priority 100`\n4. Verify auth mapping:\n   - `uxc auth binding match https://streaming.bitquery.io/graphql`\n   - `uxc auth oauth info bitquery-graphql`\n\n## Core Workflow\n\n1. Use fixed link command by default:\n   - `command -v bitquery-graphql-cli`\n   - If missing, create it: `uxc link bitquery-graphql-cli https://streaming.bitquery.io/graphql`\n   - `bitquery-graphql-cli -h`\n   - If command conflict is detected and cannot be safely reused, stop and ask skill maintainers to pick another fixed command name.\n2. Discover available root operations:\n   - `bitquery-graphql-cli -h`\n   - Verified roots currently include `query/EVM`, `query/Solana`, `query/Trading`, `query/Tron`, and matching `subscription/*` roots.\n3. Inspect a specific operation:\n   - `bitquery-graphql-cli query/EVM -h`\n   - `bitquery-graphql-cli query/Trading -h`\n4. Execute with positional JSON and explicit GraphQL selection sets:\n   - `bitquery-graphql-cli query/EVM '{\"network\":\"base\",\"dataset\":\"combined\",\"_select\":\"DEXTrades(limit: {count: 1}) { Transaction { Hash } }\"}'`\n5. Prefer `query/*` operations first.\n   - `uxc subscribe` now auto-negotiates modern `graphql-transport-ws` and legacy `graphql-ws` compatibility profiles for `subscription/*`.\n   - Live Bitquery subscription validation now succeeds when you provide an explicit `_select` that matches a stream-friendly entity shape.\n   - Prefer `subscription/EVM` as the first validation target rather than `subscription/Trading`.\n\n## Capability Map\n\n- EVM onchain queries:\n  - `query/EVM`\n  - `subscription/EVM`\n- Solana onchain queries:\n  - `query/Solana`\n  - `subscription/Solana`\n- Cross-market / trading queries:\n  - `query/Trading`\n  - `subscription/Trading`\n- Tron onchain queries:\n  - `query/Tron`\n  - `subscription/Tron`\n\nWithin those roots, Bitquery exposes entities for tasks such as:\n\n- DEX trades\n- token balances and holder analysis\n- transfers\n- blocks and transactions\n- mempool and realtime activity\n- market or trading views depending on the root\n\nAlways inspect the current schema with `-h` and use the narrowest `_select` needed.\n\nFor subscriptions specifically:\n\n- always provide `_select`\n- start with a high-frequency root such as `subscription/EVM`\n- prefer direct event shapes before adding `limit`\n- treat empty selections or query-oriented shapes as likely application-level errors\n\n## Recommended Usage Pattern\n\n1. Inspect root arguments first:\n   - `bitquery-graphql-cli query/EVM -h`\n2. Start with a minimal query on one network:\n   - `bitquery-graphql-cli query/EVM '{\"network\":\"eth\",\"dataset\":\"combined\",\"_select\":\"DEXTrades(limit: {count: 1}) { Transaction { Hash } }\"}'`\n3. Add only the fields needed for the task:\n   - buyers / sellers\n   - token addresses\n   - symbols\n   - amounts\n   - timestamps\n4. Narrow with GraphQL arguments inside `_select`:\n   - `limit`\n   - `orderBy`\n   - `where`\n5. Treat large or realtime queries carefully:\n   - avoid wide selections\n   - prefer one chain / token / wallet at a time on first pass\n6. For live subscriptions, start with a known-good high-frequency shape:\n   - `./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`\n\n## Tested Real Scenario\n\nThe following authenticated Bitquery flow was verified successfully through `uxc`:\n\n- OAuth login with `client_credentials`\n- auth binding on `https://streaming.bitquery.io/graphql`\n- GraphQL host help\n- `query/EVM -h`\n- authenticated `query/EVM` call on `base`\n- daemon-backed `subscription/EVM` over WebSocket against live Bitquery infra\n- repeated live `data` events from a BSC mempool transfer stream\n\nThe verified query shape was:\n\n```json\n{\n  \"network\": \"base\",\n  \"dataset\": \"combined\",\n  \"_select\": \"DEXTrades(limit: {count: 1}) { Block { Time } Transaction { Hash } Trade { Buy { Amount Buyer Currency { Symbol SmartContract } } Sell { Amount Seller Currency { Symbol SmartContract } } } }\"\n}\n```\n\nThe verified subscription shape was:\n\n```json\n{\n  \"network\": \"bsc\",\n  \"mempool\": true,\n  \"_select\": \"Transfers { Transaction { Hash From To } Transfer { Amount Type Currency { Name } } }\"\n}\n```\n\n## Guardrails\n\n- Keep automation on JSON output envelope; do not rely on `--text`.\n- Parse stable fields first: `ok`, `kind`, `protocol`, `data`, `error`.\n- Use `bitquery-graphql-cli` as the default command path.\n- `bitquery-graphql-cli <operation> ...` is equivalent to `uxc https://streaming.bitquery.io/graphql <operation> ...`.\n- Prefer positional JSON for GraphQL calls because `_select` is usually required.\n- Keep `_select` small on first pass and add explicit filters before expanding scope.\n- Prefer `query/*` for stable agent workflows. `subscription/*` is now validated at runtime, but still depends on provider-specific selection shape.\n- 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.\n- If a subscription opens successfully but immediately returns GraphQL errors, treat that as a query-shape problem before assuming transport failure.\n- If auth fails:\n  - confirm `uxc auth binding match https://streaming.bitquery.io/graphql` resolves to `bitquery-graphql`\n  - inspect token state with `uxc auth oauth info bitquery-graphql`\n  - manually refresh with `uxc auth oauth refresh bitquery-graphql`\n  - if needed, rerun `uxc auth oauth login ... --flow client_credentials ...`\n- Do not paste temporary IDE tokens into long-lived skill docs. Prefer application-based `client_credentials`.\n\n## References\n\n- Invocation patterns:\n  - `references/usage-patterns.md`\n","tags":{"latest":"1.0.1"},"stats":{"comments":0,"downloads":645,"installsAllTime":24,"installsCurrent":2,"stars":0,"versions":2},"createdAt":1772960555469,"updatedAt":1778491773474},"latestVersion":{"version":"1.0.1","createdAt":1773587485065,"changelog":"Document validated GraphQL subscription flows.","license":"MIT-0"},"metadata":null,"owner":{"handle":"jolestar","userId":"s1769rm50f8wvzw550m22hg10x83gkem","displayName":"jolestar","image":"https://avatars.githubusercontent.com/u/77268?v=4"},"moderation":null}