# Query Chain

> >-

- **Type:** Skill
- **Install:** `agentstack add skill-cardano-foundation-cardano-dev-skills-query-chain`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [cardano-foundation](https://agentstack.voostack.com/s/cardano-foundation)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** Apache-2.0
- **Upstream author:** [cardano-foundation](https://github.com/cardano-foundation)
- **Source:** https://github.com/cardano-foundation/cardano-dev-skills/tree/main/skills/query-chain
- **Website:** https://cardano-foundation.github.io/cardano-dev-skills/

## Install

```sh
agentstack add skill-cardano-foundation-cardano-dev-skills-query-chain
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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/evolution-sdk/` - Evolution SDK docs (TypeScript client; see `providers/` and `querying/`)

### 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 (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

#### 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

#### 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/`.

### 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 all 7 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

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [cardano-foundation](https://github.com/cardano-foundation)
- **Source:** [cardano-foundation/cardano-dev-skills](https://github.com/cardano-foundation/cardano-dev-skills)
- **License:** Apache-2.0
- **Homepage:** https://cardano-foundation.github.io/cardano-dev-skills/

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-cardano-foundation-cardano-dev-skills-query-chain
- Seller: https://agentstack.voostack.com/s/cardano-foundation
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.