Create a Midnight project on blockfrost.io and make your first API call:

curl -X POST https://midnight-mainnet.blockfrost.io/api/v0 \
  -H "project_id: YOUR_PROJECT_ID" \
  -H "Content-Type: application/json" \
  -d '{"query": "{ block { hash height timestamp } }"}'

Response:

{
  "data": {
    "block": {
      "hash": "d193b2686197789ace64962eb3049c5b94c4bbf9b07da04bef034cd75d83afc4",
      "height": 192998,
      "timestamp": 1770787800000
    }
  }
}

Blockfrost exposes three Midnight services. Available networks: mainnet, preprod, preview.

Service	URL
Indexer API	https://midnight-{network}.blockfrost.io/api/v0
Indexer WebSocket	wss://midnight-{network}.blockfrost.io/api/v0/ws
Node RPC	https://rpc.midnight-{network}.blockfrost.io

Indexer API — Send GraphQL queries and mutations over HTTP POST. This is the main entry point for fetching blockchain data (blocks, transactions, contracts, DUST status).

Indexer WebSocket — Subscribe to real-time events using the graphql-transport-ws protocol. Supports block streaming, contract actions, shielded/unshielded transactions, and ledger events.

Node RPC — Direct JSON-RPC connection to the Midnight Node for low-level runtime access, wallet providers, and transaction submission. Use it with libraries like midnight.js that need a node connection.

All requests require a valid project ID. There are two ways to pass it:

HTTP header

Include project_id as a request header.

curl -X POST https://midnight-mainnet.blockfrost.io/api/v0 \
  -H "project_id: YOUR_PROJECT_ID" \
  -H "Content-Type: application/json" \
  -d '{"query": "{ block { hash height } }"}'

Query parameter

Append ?project_id=YOUR_PROJECT_ID to the endpoint URL. Use this when your client doesn't support setting custom headers (e.g. Midnight.js SDK).

https://midnight-{network}.blockfrost.io/api/v0?project_id=YOUR_PROJECT_ID
wss://midnight-{network}.blockfrost.io/api/v0/ws?project_id=YOUR_PROJECT_ID
https://rpc.midnight-{network}.blockfrost.io?project_id=YOUR_PROJECT_ID

Replace {network} with mainnet, preprod, or preview.

Send a POST request with a JSON body containing:

• query (required): The GraphQL query, mutation, or subscription string
• variables (optional): Variables for the GraphQL operation

Example:

{
  "query": "query GetBlock(: BlockOffset) { block(offset: ) { hash height } }",
  "variables": { "offset": { "height": 100 } }
}

or without variables:

{
  "query": "query { block(offset: { height: 100 }) { hash height } }"
}

Responses follow the standard GraphQL format:

{
  "data": {
    "block": {
      "hash": "d193b2686197789ace64962eb3049c5b94c4bbf9b07da04bef034cd75d83afc4",
      "height": 192998,
      "timestamp": 1770787800000
    }
  }
}

On error:

{
  "data": null,
  "errors": [
    {
      "message": "Invalid value for argument \"offset.height\" expected type \"Int\"",
      "locations": [{ "line": 1, "column": 15 }],
      "path": ["block"]
    }
  ]
}

Query the latest block:

curl -X POST https://midnight-mainnet.blockfrost.io/api/v0 \
  -H "project_id: YOUR_PROJECT_ID" \
  -H "Content-Type: application/json" \
  -d '{"query": "{ block { hash height timestamp author transactions { hash } } }"}'

Query a block by height:

curl -X POST https://midnight-mainnet.blockfrost.io/api/v0 \
  -H "project_id: YOUR_PROJECT_ID" \
  -H "Content-Type: application/json" \
  -d '{"query": "{ block(offset: { height: 3 }) { hash height protocolVersion timestamp transactions { hash } } }"}'

Query transactions by hash:

curl -X POST https://midnight-mainnet.blockfrost.io/api/v0 \
  -H "project_id: YOUR_PROJECT_ID" \
  -H "Content-Type: application/json" \
  -d '{"query": "{ transactions(offset: { hash: \"YOUR_TX_HASH\" }) { hash protocolVersion fees { paidFees estimatedFees } block { height hash } } }"}'

Query DUST generation status:

curl -X POST https://midnight-mainnet.blockfrost.io/api/v0 \
  -H "project_id: YOUR_PROJECT_ID" \
  -H "Content-Type: application/json" \
  -d '{"query": "{ dustGenerationStatus(cardanoRewardAddresses: [\"YOUR_CARDANO_REWARD_ADDRESS\"]) { cardanoRewardAddress dustAddress registered nightBalance generationRate currentCapacity } }"}'

Query contract actions:

curl -X POST https://midnight-mainnet.blockfrost.io/api/v0 \
  -H "project_id: YOUR_PROJECT_ID" \
  -H "Content-Type: application/json" \
  -d '{"query": "{ contractAction(address: \"YOUR_CONTRACT_ADDRESS\") { address state transaction { hash } unshieldedBalances { tokenType amount } } }"}'

Subscriptions use a WebSocket connection following the GraphQL over WebSocket protocol.

Most subscriptions accept an optional offset parameter, allowing you to resume from a specific block height or transaction hash instead of starting from the tip. This is useful for catching up after a reconnect without re-processing events you've already seen.

Connecting with websocat:

websocat wss://midnight-mainnet.blockfrost.io/api/v0/ws \
  --protocol "graphql-transport-ws" \
  -H "project_id: YOUR_PROJECT_ID"

Step 1 — Initialize the connection:

After connecting, send a connection_init message:

{"type": "connection_init"}

The server responds with:

{"type": "connection_ack"}

Step 2 — Send a subscription:

Once acknowledged, send a subscribe message with your GraphQL subscription query:

{
  "id": "1",
  "type": "subscribe",
  "payload": {
    "query": "subscription { blocks { hash height timestamp transactions { hash } } }"
  }
}

Step 3 — Receive events:

The server pushes next messages whenever new data is available:

{
  "id": "1",
  "type": "next",
  "payload": {
    "data": {
      "blocks": {
        "hash": "d193b2686197789ace64962eb3049c5b94c4bbf9b07da04bef034cd75d83afc4",
        "height": 192998,
        "timestamp": 1770787800000,
        "transactions": []
      }
    }
  }
}

Connecting from JavaScript:

const url = "wss://midnight-mainnet.blockfrost.io/api/v0/ws?project_id=YOUR_PROJECT_ID";
            const ws = new WebSocket(url, "graphql-transport-ws");
            
            ws.onopen = () => {
              ws.send(JSON.stringify({ type: "connection_init" }));
            };
            
            ws.onmessage = (event) => {
              const msg = JSON.parse(event.data);
            
              if (msg.type === "connection_ack") {
                ws.send(
                  JSON.stringify({
                    id: "1",
                    type: "subscribe",
                    payload: {
                      query: "subscription { blocks { hash height timestamp } }",
                    },
                  })
                );
              }
            
              if (msg.type === "next") {
                console.log("New block:", msg.payload.data);
              }
            };
            

The server may apply limitations to queries:

• max-depth: Maximum nesting depth
• max-fields: Maximum number of fields
• timeout: Query execution timeout
• complexity: Query complexity cost

Requests exceeding limits return errors:

{
  "data": null,
  "errors": [{ "message": "Query has too many fields: 20. Max fields: 10." }]
}

Many queries support offsets for pagination:

BlockOffset (oneOf — provide exactly one):

• hash: Hex-encoded block hash
• height: Block height number

TransactionOffset (oneOf — provide exactly one):

• hash: Hex-encoded transaction hash
• identifier: Hex-encoded transaction identifier

ContractActionOffset (oneOf — provide exactly one):

• blockOffset: A BlockOffset
• transactionOffset: A TransactionOffset

If no offset is provided, the latest result is returned.

Shielded transactions are at the core of Midnight's privacy model. Because transaction data is encrypted on-chain, the indexer needs a viewing key to determine which transactions are relevant to a specific wallet.

The connect mutation establishes a server-side session for a given viewing key. The indexer uses this key to scan the chain and filter shielded transactions relevant to that wallet. It returns a session ID used to authenticate the shieldedTransactions subscription.

When you no longer need to monitor shielded transactions for a wallet, call the disconnect mutation with the session ID to end the session and free server-side resources.

Step 1 — Connect with a viewing key:

curl -X POST https://midnight-mainnet.blockfrost.io/api/v0 \
  -H "project_id: YOUR_PROJECT_ID" \
  -H "Content-Type: application/json" \
  -d '{"query": "mutation { connect(viewingKey: \"YOUR_VIEWING_KEY\") }"}'

Response:

{
  "data": {
    "connect": "SESSION_ID_HEX"
  }
}

The viewing key can be in Bech32m format (preferred, e.g. mn_shield-esk1...) or hex.

Step 2 — Subscribe to shielded transactions:

Using the session ID from the connect mutation, subscribe via WebSocket:

{
  "id": "1",
  "type": "subscribe",
  "payload": {
    "query": "subscription(: HexEncoded!) { shieldedTransactions(sessionId: , sendProgressUpdates: true) { ... on ViewingUpdate { index update { ... on RelevantTransaction { transaction { hash } } } } ... on ShieldedTransactionsProgress { highestIndex highestRelevantIndex highestRelevantWalletIndex } } }",
    "variables": { "sid": "SESSION_ID_HEX" }
  }
}

The subscription emits two event types:

• ViewingUpdate — contains relevant transactions and Merkle tree updates for the wallet
• ShieldedTransactionsProgress — reports sync progress (highestIndex, highestRelevantIndex, highestRelevantWalletIndex), useful for showing progress in a UI. Controlled by the sendProgressUpdates parameter (default: true).

Step 3 — Disconnect when done:

curl -X POST https://midnight-mainnet.blockfrost.io/api/v0 \
  -H "project_id: YOUR_PROJECT_ID" \
  -H "Content-Type: application/json" \
  -d '{"query": "mutation { disconnect(sessionId: \"SESSION_ID_HEX\") }"}'

Besides blocks and shieldedTransactions, the following subscriptions are available:

• contractActions(address: HexEncoded!, offset: BlockOffset) — real-time contract events (deploys, calls, updates) for a specific contract address
• unshieldedTransactions(address: UnshieldedAddress!, transactionId: Int) — unshielded transaction events for an address, with optional resume from a specific transaction ID
• dustLedgerEvents(id: Int) — DUST ledger state changes (initial UTXOs, generation time updates, spend processing, parameter changes)
• zswapLedgerEvents(id: Int) — zswap ledger state changes

For more information about the Midnight Indexer API, see the official Midnight documentation.