API Comparison
To choose the right Bitquery API offering, it helps to understand their differences. The table below summarizes key features and capabilities of GraphQL Query vs GraphQL Subscription vs Kafka Streams:
| Feature / Method | GraphQL Query | GraphQL Subscription (WebSocket) | Kafka Streams (Protobuf) |
|---|---|---|---|
| Use case | On‑demand historical + real‑time via polling | Real-time pushes for new on-chain events | High‑throughput, event-driven pipelines |
| Data model | Flexible GraphQL with filtering, aggregation | Same GraphQL query syntax, live updates | Topic-based structured streams with JSON or Protobuf |
| Latency | ~1 sec | ~1 sec latency | Sub‑second; streamed within 500 ms, supports HFT |
| Delivery model | Pull via REST/GraphQL | Push over WebSocket (GraphQL subscription) | Consumer‑driven pull from Kafka broker |
| Schema granularity | Customizable projections | Customizable projection | Kafka topics per type (e.g., dextrades, transactions) |
| Ordering & duplication | Strong consistency in query response | No guaranteed order; WebSocket delivery | Consumer logic needed |
| Authentication | OAuth/API‑Key | OAuth token over WebSocket | SASL username, password |
| Ideal Implementation Language | Any language | Any language except curl | Go, Java, Python, Rust |
| Best for | Interactive apps, ad-hoc querying | Monitoring, alerts, dashboards, mempool events | Streaming pipelines, HFT, data lakes, analytics workloads |
When to Use Each API
GraphQL Queries
Best for on-demand, ad-hoc, and historical data needs:
- When you need to fetch past blockchain activity (trades, transfers, balances)
- For dashboards, reports, and analytics that rely on filtering, sorting, and pagination
- When requests are driven by user actions or scheduled jobs
- Ideal for combining historical + near-real-time data via polling
GraphQL Subscriptions (WebSocket)
Ideal for lightweight real-time updates and UI integration:
- When you want push-based delivery of live on-chain events (e.g., swaps, transfers, new blocks)
- For wallet trackers, price alerts, or monitoring dashboards
- When you need low-latency updates (~500 ms) but don’t require ultra-high throughput
- Perfect for embedding live feeds into web or mobile interfaces
Kafka Streams (JSON / Protobuf)
Perfect for high-throughput, fault-tolerant streaming pipelines:
- When you need sub-second end-to-end latency for trades, mempool events, or order books
- For building scalable data lakes, HFT bots, or real-time analytics systems
- When you require integration with Kafka-based ecosystems
Pick Queries for flexibility and history, Subscriptions for easy real-time UI feeds, and Kafka Streams when you need industrial-scale, ultra-low-latency pipelines.
How do I specify dataset: realtime vs archive in an API v1 query?
This site documents API V2 GraphQL, where you set dataset on the root field (for example EVM(dataset: archive) or Solana(dataset: combined))—see Dataset options. API V1 uses a different endpoint and schema; realtime/archive semantics are not expressed the same way. For V1 query shapes and examples, use Bitquery V1 documentation and the V1 examples catalog.