Skip to content

Commit d8a3466

Browse files
slowbackspaceslowbackspace
committed
chore: keep only short midnight section on openapi side
1 parent 8a94f09 commit d8a3466

6 files changed

Lines changed: 187 additions & 1916 deletions

File tree

‎blockfrost-openapi.yaml‎

Lines changed: 6 additions & 353 deletions
Original file line numberDiff line numberDiff line change
@@ -232,365 +232,18 @@ info:
232232
## Midnight API
233233
234234
235-
The Midnight Indexer API exposes a GraphQL API that enables clients to query and subscribe to blockchain data—blocks, transactions, contracts, and wallet-related events—indexed from the Midnight blockchain.
236-
237-
The deployed version of the Midnight Indexer API is **v4**.
238-
239-
[![Open Midnight GraphQL API Reference](https://img.shields.io/badge/Open_Midnight_GraphQL_API_Reference_→-0033AD?style=for-the-badge)](./midnight/)
240-
241-
For the raw GraphQL schema specification, see the [Midnight Indexer GraphQL Schema](midnight/midnight-indexer-api.graphql).
242-
243-
### Quick Start
244-
245-
Create a Midnight project on [blockfrost.io](https://blockfrost.io) and make your first API call:
246-
247-
```bash
248-
curl -X POST https://midnight-mainnet.blockfrost.io/api/v0 \
249-
-H "project_id: YOUR_PROJECT_ID" \
250-
-H "Content-Type: application/json" \
251-
-d '{"query": "{ block { hash height timestamp } }"}'
252-
```
253-
254-
Response:
255-
```json
256-
{
257-
"data": {
258-
"block": {
259-
"hash": "d193b2686197789ace64962eb3049c5b94c4bbf9b07da04bef034cd75d83afc4",
260-
"height": 192998,
261-
"timestamp": 1770787800000
262-
}
263-
}
264-
}
265-
```
266-
267-
### Endpoints
268-
269-
Blockfrost exposes Midnight Indexer API and Midnight Node RPC endpoints:
235+
The Midnight Indexer API exposes a GraphQL API that enables clients to query and subscribe to blockchain data — blocks, transactions, contracts, and wallet-related events — indexed from the Midnight blockchain.
270236
271237
| Service | URL | Protocol |
272238
|---------|-----|----------|
273-
| **Midnight Indexer HTTP API** | `https://midnight-mainnet.blockfrost.io/api/v0` | HTTP POST (GraphQL) |
274-
| **Midnight Indexer Subscriptions API** | `wss://midnight-mainnet.blockfrost.io/api/v0/ws` | WebSocket |
275-
| **Midnight Node RPC** | `https://rpc.midnight-mainnet.blockfrost.io` | JSON-RPC |
276-
277-
278-
The **Node RPC** endpoint exposes direct connection to the Midnight Node RPC for low-level runtime access, wallet providers, and transaction submission — use it with libraries like [midnight.js](https://github.com/midnightntwrk/midnight-js) that need a node connection.
279-
280-
### Request Format
281-
282-
Send a POST request with a JSON body containing:
283-
* `query` (required): The GraphQL query, mutation, or subscription string
284-
* `variables` (optional): Variables for the GraphQL operation
285-
286-
Example request:
287-
```json
288-
{
289-
"query": "query GetBlock($offset: BlockOffset) { block(offset: $offset) { hash height } }",
290-
"variables": { "offset": { "height": 100 } }
291-
}
292-
```
293-
294-
or without variables:
295-
```json
296-
{
297-
"query": "query { block(offset: { height: 100 }) { hash height } }"
298-
}
299-
```
300-
301-
### Response Format
302-
303-
Responses follow the standard GraphQL format:
304-
```json
305-
{
306-
"data": {
307-
"block": {
308-
"hash": "d193b2686197789ace64962eb3049c5b94c4bbf9b07da04bef034cd75d83afc4",
309-
"height": 192998,
310-
"timestamp": 1770787800000
311-
}
312-
}
313-
}
314-
```
315-
316-
On error:
317-
```json
318-
{
319-
"data": null,
320-
"errors": [
321-
{
322-
"message": "Invalid value for argument \"offset.height\" expected type \"Int\"",
323-
"locations": [{ "line": 1, "column": 15 }],
324-
"path": ["block"]
325-
}
326-
]
327-
}
328-
```
329-
330-
### Authentication
331-
332-
Include your project ID as the `project_id` HTTP header:
333-
334-
```bash
335-
curl -X POST https://midnight-mainnet.blockfrost.io/api/v0 \
336-
-H "project_id: YOUR_PROJECT_ID" \
337-
-H "Content-Type: application/json" \
338-
-d '{"query": "{ block { hash height } }"}'
339-
```
340-
341-
Alternatively, you can use **HTTP Basic Auth** directly in the endpoint URL. The username is the network prefix and the password is your project ID:
342-
343-
**Midnight Indexer API:**
344-
```
345-
https://nightmainnet:YOUR_PROJECT_ID@midnight-mainnet.blockfrost.io/api/v0
346-
```
347-
348-
**Midnight Node RPC:**
349-
```
350-
https://nightmainnet:YOUR_PROJECT_ID@rpc.midnight-mainnet.blockfrost.io
351-
```
352-
353-
When using WebSocket in the browser (which doesn't support custom headers), include your project ID as a subprotocol by prefixing it with `project_id_`:
354-
```javascript
355-
new WebSocket("wss://midnight-mainnet.blockfrost.io/api/v0/ws", [
356-
"graphql-transport-ws",
357-
"project_id_YOUR_PROJECT_ID"
358-
]);
359-
```
360-
361-
### HTTP Query Examples
362-
363-
**Query the latest block:**
364-
```bash
365-
curl -X POST https://midnight-mainnet.blockfrost.io/api/v0 \
366-
-H "project_id: YOUR_PROJECT_ID" \
367-
-H "Content-Type: application/json" \
368-
-d '{"query": "{ block { hash height timestamp author transactions { hash } } }"}'
369-
```
370-
371-
**Query a block by height:**
372-
```bash
373-
curl -X POST https://midnight-mainnet.blockfrost.io/api/v0 \
374-
-H "project_id: YOUR_PROJECT_ID" \
375-
-H "Content-Type: application/json" \
376-
-d '{"query": "{ block(offset: { height: 3 }) { hash height protocolVersion timestamp transactions { hash } } }"}'
377-
```
378-
379-
**Query transactions by hash:**
380-
```bash
381-
curl -X POST https://midnight-mainnet.blockfrost.io/api/v0 \
382-
-H "project_id: YOUR_PROJECT_ID" \
383-
-H "Content-Type: application/json" \
384-
-d '{"query": "{ transactions(offset: { hash: \"YOUR_TX_HASH\" }) { hash protocolVersion fees { paidFees estimatedFees } block { height hash } } }"}'
385-
```
386-
387-
**Query DUST generation status:**
388-
```bash
389-
curl -X POST https://midnight-mainnet.blockfrost.io/api/v0 \
390-
-H "project_id: YOUR_PROJECT_ID" \
391-
-H "Content-Type: application/json" \
392-
-d '{"query": "{ dustGenerationStatus(cardanoRewardAddresses: [\"YOUR_CARDANO_REWARD_ADDRESS\"]) { cardanoRewardAddress dustAddress registered nightBalance generationRate currentCapacity } }"}'
393-
```
394-
395-
**Query contract actions:**
396-
```bash
397-
curl -X POST https://midnight-mainnet.blockfrost.io/api/v0 \
398-
-H "project_id: YOUR_PROJECT_ID" \
399-
-H "Content-Type: application/json" \
400-
-d '{"query": "{ contractAction(address: \"YOUR_CONTRACT_ADDRESS\") { address state transaction { hash } unshieldedBalances { tokenType amount } } }"}'
401-
```
402-
403-
### WebSocket Subscriptions
239+
| **Indexer HTTP API** | `https://midnight-mainnet.blockfrost.io/api/v0` | HTTP POST (GraphQL) |
240+
| **Indexer Subscriptions API** | `wss://midnight-mainnet.blockfrost.io/api/v0/ws` | WebSocket |
241+
| **Node RPC** | `https://rpc.midnight-mainnet.blockfrost.io` | JSON-RPC |
404242
405-
Subscriptions use a WebSocket connection following the GraphQL over WebSocket protocol.
406243
407-
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.
244+
For the full documentation — queries, mutations, subscriptions, authentication options, and examples — see the Midnight GraphQL API Reference:
408245
409-
**Connecting with `websocat`:**
410-
```bash
411-
websocat wss://midnight-mainnet.blockfrost.io/api/v0/ws \
412-
--protocol "graphql-transport-ws" \
413-
-H "project_id: YOUR_PROJECT_ID"
414-
```
415-
416-
**Step 1 — Initialize the connection:**
417-
418-
After connecting, send a `connection_init` message:
419-
```json
420-
{"type": "connection_init"}
421-
```
422-
423-
The server responds with:
424-
```json
425-
{"type": "connection_ack"}
426-
```
427-
428-
**Step 2 — Send a subscription:**
429-
430-
Once acknowledged, send a `subscribe` message with your GraphQL subscription query:
431-
```json
432-
{
433-
"id": "1",
434-
"type": "subscribe",
435-
"payload": {
436-
"query": "subscription { blocks { hash height timestamp transactions { hash } } }"
437-
}
438-
}
439-
```
440-
441-
**Step 3 — Receive events:**
442-
443-
The server pushes `next` messages whenever new data is available:
444-
```json
445-
{
446-
"id": "1",
447-
"type": "next",
448-
"payload": {
449-
"data": {
450-
"blocks": {
451-
"hash": "d193b2686197789ace64962eb3049c5b94c4bbf9b07da04bef034cd75d83afc4",
452-
"height": 192998,
453-
"timestamp": 1770787800000,
454-
"transactions": []
455-
}
456-
}
457-
}
458-
}
459-
```
460-
461-
**Connecting from JavaScript:**
462-
```javascript
463-
const ws = new WebSocket(
464-
"wss://midnight-mainnet.blockfrost.io/api/v0/ws",
465-
["graphql-transport-ws", "project_id_YOUR_PROJECT_ID"]
466-
);
467-
468-
ws.onopen = () => {
469-
ws.send(JSON.stringify({ type: "connection_init" }));
470-
};
471-
472-
ws.onmessage = (event) => {
473-
const msg = JSON.parse(event.data);
474-
if (msg.type === "connection_ack") {
475-
ws.send(JSON.stringify({
476-
id: "1",
477-
type: "subscribe",
478-
payload: {
479-
query: "subscription { blocks { hash height timestamp } }"
480-
}
481-
}));
482-
}
483-
if (msg.type === "next") {
484-
console.log("New block:", msg.payload.data);
485-
}
486-
};
487-
```
488-
489-
### Query Limits
490-
491-
The server may apply limitations to queries:
492-
* `max-depth`: Maximum nesting depth
493-
* `max-fields`: Maximum number of fields
494-
* `timeout`: Query execution timeout
495-
* `complexity`: Query complexity cost
496-
497-
Requests exceeding limits return errors:
498-
```json
499-
{
500-
"data": null,
501-
"errors": [{ "message": "Query has too many fields: 20. Max fields: 10." }]
502-
}
503-
```
504-
505-
### Pagination with Offsets
506-
507-
Many queries support offsets for pagination:
508-
509-
**BlockOffset** (oneOf — provide exactly one):
510-
* `hash`: Hex-encoded block hash
511-
* `height`: Block height number
512-
513-
**TransactionOffset** (oneOf — provide exactly one):
514-
* `hash`: Hex-encoded transaction hash
515-
* `identifier`: Hex-encoded transaction identifier
516-
517-
**ContractActionOffset** (oneOf — provide exactly one):
518-
* `blockOffset`: A BlockOffset
519-
* `transactionOffset`: A TransactionOffset
520-
521-
If no offset is provided, the latest result is returned.
522-
523-
### Shielded Transactions
524-
525-
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.
526-
527-
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.
528-
529-
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.
530-
531-
**Step 1 — Connect with a viewing key:**
532-
```bash
533-
curl -X POST https://midnight-mainnet.blockfrost.io/api/v0 \
534-
-H "project_id: YOUR_PROJECT_ID" \
535-
-H "Content-Type: application/json" \
536-
-d '{"query": "mutation { connect(viewingKey: \"YOUR_VIEWING_KEY\") }"}'
537-
```
538-
539-
Response:
540-
```json
541-
{
542-
"data": {
543-
"connect": "SESSION_ID_HEX"
544-
}
545-
}
546-
```
547-
548-
The viewing key can be in Bech32m format (preferred, e.g. `mn_shield-esk1...`) or hex.
549-
550-
**Step 2 — Subscribe to shielded transactions:**
551-
552-
Using the session ID from the `connect` mutation, subscribe via WebSocket:
553-
```json
554-
{
555-
"id": "1",
556-
"type": "subscribe",
557-
"payload": {
558-
"query": "subscription($sid: HexEncoded!) { shieldedTransactions(sessionId: $sid, sendProgressUpdates: true) { ... on ViewingUpdate { index update { ... on RelevantTransaction { transaction { hash } } } } ... on ShieldedTransactionsProgress { highestIndex highestRelevantIndex highestRelevantWalletIndex } } }",
559-
"variables": { "sid": "SESSION_ID_HEX" }
560-
}
561-
}
562-
```
563-
564-
The subscription emits two event types:
565-
* `ViewingUpdate` — contains relevant transactions and Merkle tree updates for the wallet
566-
* `ShieldedTransactionsProgress` — reports sync progress (`highestIndex`, `highestRelevantIndex`, `highestRelevantWalletIndex`), useful for showing progress in a UI. Controlled by the `sendProgressUpdates` parameter (default: `true`).
567-
568-
**Step 3 — Disconnect when done:**
569-
```bash
570-
curl -X POST https://midnight-mainnet.blockfrost.io/api/v0 \
571-
-H "project_id: YOUR_PROJECT_ID" \
572-
-H "Content-Type: application/json" \
573-
-d '{"query": "mutation { disconnect(sessionId: \"SESSION_ID_HEX\") }"}'
574-
```
575-
576-
### Available Operations
577-
578-
The following links will redirect you to the Midnight GraphQL API Reference:
579-
580-
* [**Queries**](midnight/#group-Operations-Queries): Fetch blockchain data (blocks, transactions, contracts, DUST generation status)
581-
* [**Mutations**](midnight/#group-Operations-Mutations): Wallet session management (`connect`/`disconnect`)
582-
* [**Subscriptions**](midnight/#group-Operations-Subscriptions): Real-time updates via WebSocket:
583-
* `blocks` — new blocks
584-
* `contractActions` — contract events for a specific address
585-
* `shieldedTransactions` — shielded transaction events for a wallet session (requires `connect`)
586-
* `unshieldedTransactions` — unshielded transaction events for an address
587-
* `dustLedgerEvents` — DUST ledger state changes
588-
* `zswapLedgerEvents` — zswap ledger state changes
589-
590-
591-
For the full list of available queries, mutations, subscriptions and types, see
592-
593-
[![GraphQL API Reference →](https://img.shields.io/badge/Midnight_GraphQL_Reference_→-0033AD?style=for-the-badge)](./midnight/)
246+
[![Open Midnight GraphQL API Reference](https://img.shields.io/badge/Open_Midnight_GraphQL_API_Reference_→-0033AD?style=for-the-badge)](./midnight/)
594247
servers:
595248
- url: https://cardano-mainnet.blockfrost.io/api/v0
596249
description: Cardano Mainnet network

0 commit comments

Comments
 (0)