First Request

Let's make a real API request and understand what comes back.

Choosing a Network

All examples in this guide use Mainnet endpoints. To use Preprod Testnet instead, simply add /preprod to the path:

Your API key works on both networks.

Understanding JSON-RPC

Nacho API uses the JSON-RPC 2.0 protocol. Every request has this structure:

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

Query the Current Epoch

Let's query the current Cardano epoch:

curl -X POST https://api.nacho.builders/v1/ogmios \
-H "Content-Type: application/json" \
-H "apikey: YOUR_API_KEY" \
-d '{
  "jsonrpc": "2.0",
  "method": "queryLedgerState/epoch",
  "id": "my-first-request"
}'

Try It Live

Understanding the Response

A successful response looks like:

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

Error Responses

If something goes wrong, you'll get an error object instead of result:

{
  "jsonrpc": "2.0",
  "error": {
    "code": -32600,
    "message": "Invalid request",
    "data": { "reason": "Missing 'method' field" }
  },
  "id": null
}

Common error codes:

Query with Parameters

Some methods require parameters. Let's query protocol parameters:

curl -X POST https://api.nacho.builders/v1/ogmios \
-H "Content-Type: application/json" \
-H "apikey: YOUR_API_KEY" \
-d '{
  "jsonrpc": "2.0",
  "method": "queryLedgerState/protocolParameters"
}'

What's Next?

Now that you understand the basics:

• Explore all Ledger State Queries
• Learn about WebSocket connections for real-time data
• Try Submitting Transactions