Provider Types

The Evolution SDK supports four provider types, each connecting to different Cardano infrastructure. Choose based on your deployment model, feature requirements, and infrastructure preferences.

Blockfrost

Hosted API service with generous free tier and pay-as-you-grow pricing.

Configuration

import {  } from "@evolution-sdk/evolution";

const  = ({
  : "mainnet",
  : {
    : "blockfrost",
    : "https://cardano-mainnet.blockfrost.io/api/v0",
    : ..!
  }
});

Network Endpoints

// Mainnet
baseUrl: "https://cardano-mainnet.blockfrost.io/api/v0"

// Preprod testnet
baseUrl: "https://cardano-preprod.blockfrost.io/api/v0"

// Preview testnet
baseUrl: "https://cardano-preview.blockfrost.io/api/v0"

Getting Project ID

Sign up at blockfrost.io
Create a project
Copy project ID from dashboard
Store in environment variable

# .env
BLOCKFROST_PROJECT_ID="mainnetYourProjectIdHere"

Best For

Production applications requiring reliable uptime without infrastructure management. Ideal for startups and teams focusing on application logic rather than node operations.

Advantages:

Zero infrastructure setup
Generous free tier
Global CDN distribution
Automatic scaling
Dashboard analytics

Considerations:

API rate limits
Requires internet connectivity
Third-party dependency

Kupmios

Self-hosted combination of Ogmios (Cardano node interface) and Kupo (lightweight chain indexer).

Configuration

import {  } from "@evolution-sdk/evolution";

const  = ({
  : "mainnet",
  : {
    : "kupmios",
    : "http://localhost:1337",
    : "http://localhost:1442"
  }
});

Setup Requirements

Requires running Cardano node, Ogmios, and Kupo services:

# Docker Compose example
services:
  cardano-node:
    image: inputoutput/cardano-node:latest
    # ... node configuration
  
  ogmios:
    image: cardanosolutions/ogmios:latest
    ports:
      - "1337:1337"
    depends_on:
      - cardano-node
  
  kupo:
    image: cardanosolutions/kupo:latest
    ports:
      - "1442:1442"
    depends_on:
      - cardano-node

Network Configuration

// Mainnet
network: "mainnet",
ogmiosUrl: "http://localhost:1337",
kupoUrl: "http://localhost:1442"

// Preprod testnet
network: "preprod",
ogmiosUrl: "http://localhost:1337",
kupoUrl: "http://localhost:1442"

Best For

Organizations requiring full control over infrastructure, data sovereignty, and no third-party API dependencies.

Advantages:

Complete control
No rate limits
Data sovereignty
No external dependencies
Can customize indexing

Considerations:

Infrastructure management overhead
Requires node synchronization
Hardware requirements
Operational expertise needed

Maestro

Hosted API service with advanced features and analytics capabilities.

Configuration

import {  } from "@evolution-sdk/evolution";

const  = ({
  : "mainnet",
  : {
    : "maestro",
    : "https://mainnet.gomaestro-api.org/v1",
    : ..!
  }
});

Network Endpoints

// Mainnet
baseUrl: "https://mainnet.gomaestro-api.org/v1"

// Preprod testnet
baseUrl: "https://preprod.gomaestro-api.org/v1"

// Preview testnet  
baseUrl: "https://preview.gomaestro-api.org/v1"

Getting API Key

Sign up at gomaestro.org
Create API key
Store in environment variable

# .env
MAESTRO_API_KEY="your-api-key-here"

Best For

Applications requiring advanced blockchain analytics, extended historical data, or specialized indexing features.

Advantages:

Advanced analytics
Extended historical data
Specialized indexing
WebSocket support
Enterprise features

Considerations:

Pricing tiers
API rate limits
Third-party dependency

Koios

Community-driven distributed API infrastructure.

Configuration

import {  } from "@evolution-sdk/evolution";

const  = ({
  : "mainnet",
  : {
    : "koios",
    : "https://api.koios.rest/api/v1"
  }
});

Network Endpoints

// Mainnet
baseUrl: "https://api.koios.rest/api/v1"

// Preprod testnet
baseUrl: "https://preprod.koios.rest/api/v1"

// Preview testnet
baseUrl: "https://preview.koios.rest/api/v1"

// Guild network (alternative)
baseUrl: "https://guild.koios.rest/api/v1"

Best For

Applications prioritizing decentralization, community infrastructure, or wanting to avoid single-provider dependency.

Advantages:

Decentralized infrastructure
Community-driven
Free to use
No API key required
Multiple endpoints

Considerations:

Variable performance across nodes
Community support model
Rate limiting varies by node

Provider Comparison Matrix

Feature	Blockfrost	Kupmios	Maestro	Koios
Setup Complexity	Low	High	Low	Low
Infrastructure	Hosted	Self-hosted	Hosted	Community-hosted
API Key Required	Yes	No	Yes	No
Rate Limits	Yes	No	Yes	Varies
Cost	Free tier + paid	Infrastructure costs	Paid tiers	Free
Data Sovereignty	No	Yes	No	No
Decentralization	Low	High	Low	Medium
Advanced Features	Standard	Full control	Extended	Standard
Uptime SLA	Commercial	Self-managed	Commercial	Best effort

Switching Providers

The unified interface allows switching providers with minimal code changes:

import {  } from "@evolution-sdk/evolution";

// Development: Blockfrost
const  = ({
  : "preprod",
  : {
    : "blockfrost",
    : "https://cardano-preprod.blockfrost.io/api/v0",
    : ..!
  }
});

// Production: Self-hosted Kupmios
const  = ({
  : "mainnet",
  : {
    : "kupmios",
    : ..!,
    : ..!
  }
});

// Same query methods work across all providers
const  = await .();

Environment-Based Configuration

Manage provider configuration per environment:

import {  } from "@evolution-sdk/evolution";

const  = (.. || "development") as "development" | "staging" | "production";

const  = {
  : {
    : "blockfrost" as ,
    : "https://cardano-preprod.blockfrost.io/api/v0",
    : ..!
  },
  : {
    : "maestro" as ,
    : "https://preprod.gomaestro-api.org/v1",
    : ..!
  },
  : {
    : "kupmios" as ,
    : ..!,
    : ..!
  }
};

const  = ({
  :  === "production" ? "mainnet" : "preprod",
  : []
});

Next Steps

Now that you understand provider types, learn how to use them:

Provider-Only Client - Query blockchain without wallet
Querying - Master all query methods
Submission - Submit transactions and monitor confirmations

Provider Types

On this page