API Reference Overview

Complete reference for all Nacho API methods

Nacho API provides access to Cardano blockchain data through Ogmios JSON-RPC methods.

Base URLs

Mainnet (Production)

Protocol	Endpoint
HTTP/HTTPS	`https://api.nacho.builders/v1/ogmios`
WebSocket	`wss://api.nacho.builders/v1/ogmios`
Submit API	`https://api.nacho.builders/v1/submit`
GraphQL	`https://api.nacho.builders/v1/graphql`

Preprod Testnet (Development)

Protocol	Endpoint
HTTP/HTTPS	`https://api.nacho.builders/v1/preprod/ogmios`
WebSocket	`wss://api.nacho.builders/v1/preprod/ogmios`
Submit API	`https://api.nacho.builders/v1/preprod/submit`
GraphQL	`https://api.nacho.builders/v1/preprod/graphql`

Your API key works on both networks. Switch between Mainnet and Preprod by changing the URL path from /v1/ogmios to /v1/preprod/ogmios.

Request Format

All requests use JSON-RPC 2.0:

{
  "jsonrpc": "2.0",
  "method": "methodName",
  "params": { },
  "id": "optional-id"
}

Available APIs

GraphQL API

Flexible queries for blockchain data using GraphQL. Best for complex queries with filtering and relationships.

Feature	Description
`GraphQL API Overview`	Query blocks, transactions, UTxOs, pools with flexible GraphQL

Ledger State Queries (Ogmios)

Query the current ledger state for blockchain data.

Method	Description
`queryLedgerState/epoch`	Current epoch number
`queryLedgerState/protocolParameters`	Protocol parameters
`queryLedgerState/utxo`	UTxO set by address or reference
`queryLedgerState/stakePools`	Registered stake pools
`queryLedgerState/tip`	Current ledger tip
`queryLedgerState/eraStart`	Current era start info
`queryLedgerState/eraSummaries`	Era bounds and slot parameters
`queryLedgerState/liveStakeDistribution`	Stake distribution
`queryLedgerState/rewardAccountSummaries`	Reward account info

Network Queries

Query network-level information (available even during sync).

Method	Description
`queryNetwork/blockHeight`	Current block height
`queryNetwork/genesisConfiguration`	Genesis config by era
`queryNetwork/startTime`	Chain start time
`queryNetwork/tip`	Network tip

Transaction Methods

Submit and evaluate transactions.

Method	Description
`submitTransaction`	Submit a signed transaction
`evaluateTransaction`	Evaluate script execution costs

Chain Synchronization

Follow the chain in real-time (WebSocket only).

Method	Description
`findIntersection`	Find chain intersection point
`nextBlock`	Get next block or rollback

Chain synchronization requires a persistent WebSocket connection. See the Chain Synchronization Guide.

Response Format

Success Response

{
  "jsonrpc": "2.0",
  "method": "queryLedgerState/epoch",
  "result": 523,
  "id": "request-123"
}

Error Response

{
  "jsonrpc": "2.0",
  "error": {
    "code": -32601,
    "message": "Method not found",
    "data": { "method": "invalidMethod" }
  },
  "id": "request-123"
}

Error Codes

Code	Meaning
`-32700`	Parse error - Invalid JSON
`-32600`	Invalid request - Missing required fields
`-32601`	Method not found
`-32602`	Invalid params
`-32603`	Internal error
`3000-3999`	Transaction submission errors

HTTP vs WebSocket

Feature	HTTP	WebSocket
One-off queries	Yes	Yes
Chain sync	No	Yes
Connection overhead	Per request	Once
Pipelining	No	Yes

Use HTTP for:

Simple queries
Serverless functions
One-off requests

Use WebSocket for:

Chain synchronization
High-frequency queries
Real-time applications

Full Ogmios API Specification

Was this page helpful?