Skip to main content

Use a Provider

A query API is the fastest way to serve your application the chain: someone else runs the node and the indexer, and your SDK points at a URL. The three documented here are directly comparable, they answer the same REST-shaped reads and accept the same transaction submissions, so this page sets all three up with one identical skeleton: create access, find your network's endpoint, make a first raw request, point your SDK at it, and know the limits. Pick one tab and the rest of the curriculum works the same; switching later is a configuration change.

The differences that matter are operational, not functional: who operates it, how access is granted, and how usage is limited. Where they genuinely differ, the tabs say so.

Keep keys server-side

An API key identifies and bills you. Store it in an environment variable on your backend, never commit it, and never ship it in client-side code, where anyone can read it. The frontend signs, backend submits pattern exists partly for this reason.

Create access​

Create a free account at blockfrost.io. After signing in, create a project: click + ADD PROJECT, name it, and select the network. Each project is scoped to one network and gets its own project_id, which is your API key (it starts with the network name, e.g. preprod...).

Network endpoints​

Each network has its own base URL, and your access is scoped to the network you set it up for (Koios excepted: same token everywhere, different URL per network).

NetworkBase URL
Mainnethttps://cardano-mainnet.blockfrost.io/api/v0
Preprodhttps://cardano-preprod.blockfrost.io/api/v0
Previewhttps://cardano-preview.blockfrost.io/api/v0

Your first request​

The same request three ways: ask for the chain tip (or latest block) with your key in the provider's auth header. A JSON answer means access, endpoint, and network line up.

Authentication is the project_id header:

curl -H "project_id: $BLOCKFROST_PROJECT_ID" \
  https://cardano-preprod.blockfrost.io/api/v0/blocks/latest
{
  "time": 1641338934,
  "height": 15243593,
  "hash": "4ea1ba291e8eef538635a53e59fddba7810d1679631cc3aed7c8e6c4091a516a",
  "slot": 412162133,
  "epoch": 425,
  "tx_count": 1,
  "fees": "592661"
}

Point your SDK at it​

You will rarely call the REST API directly: the SDK's provider does it behind the interface you already use. Configure the one you set up (base URL and network must match your key):

import { preprod, Client } from "@evolution-sdk/evolution"

// Blockfrost
const bf = Client.make(preprod).withBlockfrost({
  baseUrl: "https://cardano-preprod.blockfrost.io/api/v0",
  projectId: process.env.BLOCKFROST_PROJECT_ID!
})

// Koios
const koios = Client.make(preprod).withKoios({ baseUrl: "https://preprod.koios.rest/api/v1" })

// Maestro
const maestro = Client.make(preprod).withMaestro({
  baseUrl: "https://preprod.gomaestro-api.org/v1",
  apiKey: process.env.MAESTRO_API_KEY!
})

Every query and submission from Query the chain runs unchanged on any of the three.

Limits​

The free tier is rate-limited per project, with paid tiers above it; current numbers are on blockfrost.io. Beyond the chain API, the same account gives you an IPFS gateway for pinning off-chain content and webhooks that push on-chain events to you instead of you polling.

The full references​

Each provider's own documentation is the authority on its endpoints:

  • Blockfrost: blockfrost.dev, with official SDKs for 15+ languages beyond the Cardano SDK providers above
  • Koios: api.koios.rest, every endpoint with a runnable sample query
  • Maestro: docs.gomaestro.org, covering the indexer plus transaction-management extras

The same APIs, self-hosted​

Two of the three are open source end to end, so outgrowing a hosted tier does not mean leaving the API behind:

Running your own serving layer, in these shapes and lighter ones, is the self-hosting page.

Harden it for production​

One hosted API is a single point of failure, and chatty code hits rate limits. Because every provider implements the same interface, failover and caching are composition, not migration: see harden your provider for the pattern in both SDKs.

Next steps​