query-chain

<!-- Documentation lookup path: ${CLAUDE_SKILL_DIR}/../../docs/sources/ --> # Query Cardano Chain Data Help the developer choose and use the right data provider for querying the Cardano blockchain. ## When to use - Developer needs to read UTxOs, transaction history, protocol parameters, or on-chain state - Choosing between Blockfrost, Ogmios, Kupo, Koios, Cardano GraphQL, DB-Sync, or Oura - Setting up a data pipeline from chain data - Querying datum or script information attached to UTxOs - Building a backend service that needs chain data - Comparing hosted vs self-hosted infrastructure options ## When NOT to use - Building or submitting transactions (use transaction-building skills instead) - Setting up a local devnet (use `setup-devnet` skill) - Writing smart contracts (use Aiken/Plutus skills) - Wallet integration in a frontend (use `connect-wallet` skill) ## Key principles 1. **Match the provider to the use case.** There is no single best provider. A dApp frontend has different needs than a data pipeline. 2. **Hosted APIs are faster to start; self-hosted gives control.** Blockfrost and Koios are hosted. Ogmios, Kupo, DB-Sync require running infrastructure. 3. **Combine providers when needed.** Ogmios + Kupo is a common pairing: Ogmios for tx submission and protocol params, Kupo for UTxO queries. 4. **Consider cost at scale.** Hosted APIs have rate limits and pricing tiers. Self-hosted has infrastructure cost. 5. **Think about latency requirements.** WebSocket (Ogmios) is lower latency than REST (Blockfrost). Local node queries are fastest. ## Workflow ### Step 1: Identify the context Ask the developer (if not already clear): - **What are you building?** (backend-service | dapp-frontend | data-pipeline | one-off-query) - **Do you need real-time chain-tip data or historical queries?** - **Are you running your own Cardano node?** - **What language/SDK are you using?** ### Step 2: Search Bundled Documentation Search the bundled documentation for relevant content: - `${CLAUDE_SKILL_DIR}/../../docs/sources/ogmios/` - Ogmios WebSocket bridge docs - `${CLAUDE_SKILL_DIR}/../../docs/sources/blockfrost-openapi/` - Blockfrost API docs - `${CLAUDE_SKILL_DIR}/../../docs/sources/koios/` - Koios API docs - `${CLAUDE_SKILL_DIR}/../../docs/sources/cardano-graphql/` - Cardano GraphQL docs - `${CLAUDE_SKILL_DIR}/../../docs/sources/db-sync/` - DB-Sync docs - `${CLAUDE_SKILL_DIR}/../../docs/sources/yaci-store/` - Yaci Store (modular JVM indexer; see `stores/`, `plugins/`, `usage/as-library/`) - `${CLAUDE_SKILL_DIR}/../../docs/sources/evolution-sdk/` - Evolution SDK docs (TypeScript client; see `providers/` and `querying/`) - `${CLAUDE_SKILL_DIR}/../../docs/sources/blockfrost-go/` - Blockfrost Go client (typed endpoint wrappers) - `${CLAUDE_SKILL_DIR}/../../docs/sources/utxorpc-go-sdk/` - UTxORPC Go SDK (provider-agnostic gRPC) - `${CLAUDE_SKILL_DIR}/../../docs/sources/gouroboros/` - gOuroboros (direct node mini-protocols) - `${CLAUDE_SKILL_DIR}/../../docs/sources/dingo/` - Dingo (Go node serving UTxORPC / Blockfrost-compatible / Mesh) - `${CLAUDE_SKILL_DIR}/../../docs/sources/adder/` - Adder (Go event pipeline; `docs/swagger.yaml` for its REST surface) ### Step 3: Evaluate providers for the context Search the reference file for detailed provider comparisons. ``` File: skills/query-chain/references/provider-comparison.md ``` #### Quick decision guide | Context | Recommended Primary | Alternative | |---|---|---| | **backend-service** | Ogmios + Kupo (self-hosted) or Blockfrost (hosted) | Koios (hosted, free tier) | | **dapp-frontend** | Blockfrost (via SDK) or Koios | Ogmios via backend proxy | | **data-pipeline** | Oura or Adder (streaming) or DB-Sync (SQL) | Cardano GraphQL | | **one-off-query** | Koios (free, no signup) or Blockfrost | cardano-cli with local node | ### Step 4: Describe each viable option For each provider that fits the developer's context, explain: 1. **How to set it up** -- installation, configuration, API keys 2. **How to make the query** -- specific API calls, endpoints, or queries 3. **Code example** -- using their SDK/language of choice 4. **Limitations** -- rate limits, missing data, latency ### Step 5: Provider-specific guidance #### Blockfrost (Hosted REST API) - Sign up at blockfrost.io for a project ID - REST API with comprehensive endpoints - SDKs: JavaScript, Python, Rust, Go, Java, Kotlin, Swift, Elixir - Rate limits: free tier 50k requests/day, 10 req/s sustained, 500 req burst capacity - Great for: quick prototyping, frontend dApps, moderate traffic backends ``` GET /addresses/{address}/utxos GET /txs/{hash} GET /epochs/latest/parameters ``` #### Ogmios (Self-hosted WebSocket) - Requires a running cardano-node - WebSocket JSON-RPC protocol (low latency) - Local state queries: UTxOs, protocol parameters, chain tip - Transaction submission and evaluation - Best for: backends co-located with a node, tx submission workflows #### Kupo (Self-hosted HTTP indexer) - Indexes UTxOs by address, asset, or datum hash - Lightweight, fast, pattern-based matching - REST API on top of indexed data - Often paired with Ogmios for a complete solution - Best for: UTxO lookups, datum resolution, asset queries #### Koios (Hosted REST API, community-run) - Free tier with generous limits - No API key required for basic use - Comprehensive endpoints similar to Blockfrost - Community-maintained, decentralized backend nodes - Best for: open-source projects, quick queries, no-signup needs #### Dingo (Self-hosted node with APIs built in) A Cardano node implementation in Go that serves the query layer itself, so one process replaces the usual node-plus-Ogmios-plus-Kupo stack: - UTxO RPC (default port `9090`), a Blockfrost-compatible REST API (`3000`), and Mesh / Coinbase Rosetta (`8080`), each enabled and bound through `DINGO_PLUGINS_API_*_CONFIG_PORT` - Because the REST API is Blockfrost-compatible, existing Blockfrost client code and the mirrored Blockfrost OpenAPI spec both apply — point the client at your own host instead of the hosted service - **Storage mode is the gotcha.** The client-facing APIs require `storageMode: "api"` (full indexing). The lighter `"core"` mode carries only what consensus needs and will not serve them. - Its own README states Dingo is pre-production: testnets and devnets only, not mainnet with real funds. Treat it as a development and testnet query layer, and keep Blockfrost, Koios, or Ogmios + Kupo for anything mainnet-facing. #### Cardano GraphQL (Self-hosted GraphQL) - GraphQL interface over cardano-db-sync - Flexible queries with relationships - Requires DB-Sync + PostgreSQL + Hasura - Best for: complex relational queries, custom data views #### DB-Sync (Self-hosted PostgreSQL) - Full blockchain data in PostgreSQL - Direct SQL access to all chain data - Heavy resource requirements (100GB+ disk, significant RAM) - Best for: analytics, complex historical queries, data warehousing #### Oura (Self-hosted pipeline) - Event-driven pipeline from cardano-node - Outputs to Kafka, Elasticsearch, webhooks, files - Filters and maps chain events - Best for: real-time event processing, data pipelines, notifications #### Adder (Self-hosted pipeline, Go) - Same shape as Oura in a Go process: an input stage follows the chain, filters narrow the stream, output stages emit it - Inputs are chainsync (over NtC or NtN), mempool, and UTxORPC, so it can follow a node directly or ride on a UTxORPC provider; the chainsync input emits `input.block`, `input.rollback`, `input.transaction`, and `input.governance`, each with its own payload - Outputs include webhook, push, notify, log, and Telegram - Filters narrow by event type, address, asset fingerprint, minting policy, pool ID, or DRep ID (`WithTypes`, `WithAddresses`, `WithAssetFingerprints`, `WithPolicies`, `WithPoolIds`, `WithDRepIds`) - Runs standalone or embeds as a library, which is the reason to pick it over Oura: a Go service can consume the event stream in-process instead of shipping it through a broker first - Best for: Go backends reacting to chain events, webhook fan-out, alerting #### Evolution SDK (TypeScript client over providers) Not a provider — a TypeScript library that wraps Blockfrost, Kupmios, Maestro, and Koios behind one query interface, so the provider becomes a config choice rather than a code rewrite. For read-only work, build a **provider-only client** (no wallet attached): ```typescript import { Address, Client, preprod } from "@evolution-sdk/evolution" const client = Client.make(preprod).withBlockfrost({ baseUrl: "https://cardano-preprod.blockfrost.io/api/v0", projectId: process.env.BLOCKFROST_PROJECT_ID!, }) // or .withKupmios(...) / .withMaestro(...) / .withKoios(...) — same query API const utxos = await client.getUtxos(Address.fromBech32("addr_test1...")) const nftUtxo = await client.getUtxoByUnit(unit) // the one UTxO holding an NFT const datum = await client.getDatum(datumHash) const params = await client.getProtocolParameters() const { poolId, rewards } = await client.getDelegation(rewardAddress) ``` Query methods: `getUtxos`, `getUtxosWithUnit`, `getUtxoByUnit`, `getUtxosByOutRef`, `getDatum`, `getDelegation`, `getProtocolParameters`, `awaitTx`. Best for: TypeScript backends and dApps that want one query API independent of the underlying provider. See `${CLAUDE_SKILL_DIR}/../../docs/sources/evolution-sdk/providers/` and `.../querying/`. #### Go clients over providers Three Go paths, ordered by how much infrastructure you run: - **blockfrost-go** — typed client for the hosted Blockfrost REST API. `NewAPIClient(APIClientOptions{...})`, then methods mirroring the REST surface (`Transaction`, `TransactionUTXOs`, `TransactionMetadata`, and the `Address*` / `Epoch*` / `Pool*` families). Inherits every Blockfrost trade-off above, including rate limits. Also covers IPFS and webhook signature verification. - **UTxORPC Go SDK** — the role Evolution SDK plays for TypeScript: the provider becomes a config choice rather than a code rewrite, against any UTxORPC-compatible backend. Paging query helpers (`GetUtxosByAddressPages`, `GetUtxosByAssetPages`, tuned with `WithSearchMaxItems` / `WithSearchStartToken`); submit and mempool operations on `UtxorpcClient` (`SubmitTx`, `EvalTx`, `WaitForTx`, `ReadMempool`, `WatchMempool`). Best when you may switch providers later. - **gOuroboros** — speaks the node's mini-protocols directly, with no intermediary. `NewConnection(...)`, then `LocalStateQuery().Client` for point-in-time state (`GetUTxOByAddress`, `GetUTxOByTxIn`, `GetCurrentProtocolParams`, `GetStakeDistribution`, `GetDRepState`, `GetProposals`) or `ChainSync().Client` to follow the chain (`GetCurrentTip`, `GetAvailableBlockRange`, `Sync`). Lowest latency and no third party, but you run the node and manage the protocol lifecycle yourself. Runnable examples ship in the mirror: `${CLAUDE_SKILL_DIR}/../../docs/sources/gouroboros/examples/state-query/main.go` and `.../examples/chain-sync/main.go`. Because Go sources mirror `.go` files, `Grep` a method name to get its signature and doc comment. ### Step 6: Provide working code Give the developer a working code snippet for their chosen provider and language. Always include: - Dependency installation - Client initialization - The specific query they need - Error handling - Response parsing ### Step 7: Address common issues - **Stale data**: Hosted APIs may lag behind chain tip by a few seconds - **Datum resolution**: Not all providers return inline datums; may need separate lookup - **Pagination**: Large result sets require pagination (Blockfrost pages, Kupo cursors) - **Network selection**: Ensure provider is configured for the right network (mainnet/preprod/preview) - **CORS**: Frontend apps need CORS-friendly endpoints or a backend proxy ## References - `skills/query-chain/references/provider-comparison.md` -- Detailed comparison of the providers with decision matrix - Blockfrost docs: https://docs.blockfrost.io - Ogmios docs: https://ogmios.dev - Kupo docs: https://cardanosolutions.github.io/kupo - Koios docs: https://api.koios.rest - DB-Sync docs: https://github.com/IntersectMBO/cardano-db-sync - Oura docs: https://github.com/txpipe/oura - UTxORPC: https://utxorpc.org - blockfrost-go: https://pkg.go.dev/github.com/blockfrost/blockfrost-go