Backend Configuration

The orchestrator routes each call to the right backend type. BACKENDS order = priority; first one is the live backend, rest are historical fallbacks.

BackendRoleUsed For
OgmiosLive (WebSocket)Current UTxOs, protocol params, tx submission
BlockfrostHistoricalBlocks, transactions, metadata, indexed queries
KoiosHistorical (free)Same surface as Blockfrost
BACKENDS=ogmios,blockfrost,koios
         live    historical primary  historical fallback

If Ogmios is down, historical backends absorb live queries too.

Configure

Plugin mode (package.json):

{ "cds": { "requires": { "odatano-core": {
  "network":          "preview",
  "backends":         ["ogmios", "blockfrost", "koios"],
  "blockfrostApiKey": "preview_your_api_key",
  "ogmiosUrl":        "ws://localhost:1337",
  "primaryTimeoutMs":  30000,
  "fallbackTimeoutMs": 60000,
  "indexTtlMs":       3600000
}}}}

Standalone (.env):

NETWORK=preview
BACKENDS=ogmios,blockfrost,koios
OGMIOS_URL=ws://localhost:1337
BLOCKFROST_API_KEY=preview_your_api_key
TX_BUILDERS=buildooor
PRIMARY_TIMEOUT_MS=30000
FALLBACK_TIMEOUT_MS=60000
INDEX_TTL_MS=3600000

What Routes Where

Live (Ogmios): getProtocolParameters, getAddressUtxos, submitTransaction, getAddress, getAccount, getPool, getNetworkInformation.

Historical (Blockfrost / Koios): getBlock, getTransaction, getTransactionMetadata, getDrep.

SetupNotes
ogmios,koiosRecommended fast, free, full history (self-hosted node)
blockfrost,koiosNo-node deployments, fine for most use cases
koiosZero-cost prototyping (rate-limited)
ogmios,blockfrostProduction with paid Blockfrost backup

Reliability

  • Circuit breaker: Per-backend failure tracking; short-circuits to fallback after repeated failures, retries after a cooldown.
  • Request coalescer: Concurrent in-flight requests for the same key are deduplicated.

See Also